sea_pen.mojom | Explore in Territory

// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module ash.personalization_app.mojom;

import "ash/webui/common/mojom/sea_pen_generated.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "url/mojom/url.mojom";


// Encapsulates metadata for a thumbnail image, which can be displayed as an
// image tile in the SeaPen search result page.
struct SeaPenThumbnail {
    // Data url to display the image.
    url.mojom.Url image;

    // An id that uniquely identifies the image.
    uint32 id;
};

// The query information that was recently used to search for SeaPen images
// including the visible prompt text and template title from the UI.
// The strings were translated based on the localization that the user was in
// when they ran the query.
struct SeaPenUserVisibleQuery {
  // The user visible prompt used to search for images.
  string text;

  // The visible title of the selected template used to search for images.
  string template_title;
};

// The information needed to send a template query. The possible `id` and
// `options` values are defined in cs/ChromeOsWallpaperQueryProcessor.kt. They
// are not controlled by the renderer. The browser is responsible for validating
// the values.
struct SeaPenTemplateQuery {
  // A unique template ID.
  SeaPenTemplateId id;

  // The chips and their selected options.
  map<SeaPenTemplateChip, SeaPenTemplateOption> options;

  // The visible template query information including the prompt and template
  // title that the user selected, saved in the localization that the user
  // was in when they ran the query.
  SeaPenUserVisibleQuery user_visible_query;
};

// The metadata for the feedback dialog
struct SeaPenFeedbackMetadata {
  bool is_positive;
  string log_id;

  // This is the generation seed from the Manta Service to identify a
  // SeaPenThumbnail.
  uint32 generation_seed;
};

// A text or template query for constructing a Manta request.
union SeaPenQuery {
  // Set if the query is from text input.
  string text_query;

  // Set if the query is from template input.
  SeaPenTemplateQuery template_query;
};

// The information of a recent SeaPen image including the query information
// and its creation time.
struct RecentSeaPenImageInfo {
  // The SeaPen query that the user used to generate the recent image.
  SeaPenQuery query;

  // Human-readable string representation of the date the image was
  // created, e.g., "Dec 30, 2023", translated into the user's current
  // locale. `creation_time` is null if its data has invalid time format.
  mojo_base.mojom.String16? creation_time;
};

// The thumbnail data includes the `url` and the image information `image_info`
// for the recent Sea Pen image.
// `image_info` is null if the image metadata has missing or invalid data.
struct RecentSeaPenThumbnailData {
  url.mojom.Url url;
  RecentSeaPenImageInfo? image_info;
};

// Represents a single entry of text query history.
struct TextQueryHistoryEntry {
  string query;

  array<SeaPenThumbnail> thumbnails;
};

// Maximum allowable query text length, in bytes.
// When validating length in Javascript, be careful of the difference between
// UTF-16 (Javascript) length and UTF-8 length.
const uint32 kMaximumGetSeaPenThumbnailsTextBytes = 3000;

// Should match the associated enum in components/manta/manta_status.h
enum MantaStatusCode {
  kOk = 0,
  kGenericError = 1,
  kInvalidInput = 2,
  kResourceExhausted = 3,
  kBackendFailure = 4,
  kMalformedResponse = 5,
  kNoInternetConnection = 6,
  kUnsupportedLanguage = 7,
  kBlockedOutputs = 8,
  kRestrictedCountry = 9,
  kNoIdentityManager = 10,
  kPerUserQuotaExceeded = 11,
  kMax = kPerUserQuotaExceeded,
};

// An interface to provide SeaPen updates to the renderer process, e.g. when the
// browser process has changed wallpaper.
interface SeaPenObserver {
  // Called to update the renderer process when the active SeaPen image has
  // changed. Called with null when SeaPen image is unset/removed, e.g. a
  // different type of wallpaper has been set.
  OnSelectedSeaPenImageChanged(uint32? id);

  // Called whenever there is a change to the text query history.
  OnTextQueryHistoryChanged(array<TextQueryHistoryEntry>? entries);
};

// Provides APIs to get thumbnails and full size images. Uses APIs in
// `manta.proto` to send requests to a google owned server.
// Implemented in the browser process, and called by the ChromeOS
// Personalization App (chrome://personalization) in a renderer process.
interface SeaPenProvider {

    // Binds a listener to start receiving updates on SeaPen status changes.
    SetSeaPenObserver(pending_remote<SeaPenObserver> observer);

    // Given a user text input, return a set of matching thumbnails.
    // `thumbnails` will be null in case of an unrecoverable error, such as
    // network failure.
    // `thumbnails` will be empty array when the request succeeded, but no
    // matching thumbnails were returned.
    // If `query` is of type string, it must be smaller than
    // `kMaximumGetSeaPenThumbnailsTextBytes` bytes.
    GetSeaPenThumbnails(SeaPenQuery query) =>
        (array<SeaPenThumbnail>? thumbnails, MantaStatusCode statusCode);

    // Select a thumbnail for the current user.
    // `id` must be a valid id from a previous call to `GetSeaPenThumbnails`.
    SelectSeaPenThumbnail(uint32 id, bool preview_mode) => (bool success);

    // Gets the available previously selected SeaPen images. `ids` will be
    // empty if no thumbnails have been previously selected, or in case of disk
    // or other failure.
    GetRecentSeaPenImageIds() => (array<uint32> ids);

    // Sets the given SeaPen image id as the user's background. Must be a valid
    // id from a previous call to `GetRecentSeaPenImageIds`.
    SelectRecentSeaPenImage(uint32 id, bool preview_mode) => (bool success);

    // Fetches the thumbnail data for the given recent Sea Pen image `id`.
    // `id` must be a valid id from a previous call to
    // `GetRecentSeaPenImageIds`.
    // `thumbnail_data` is null if the `id` is invalid or the image fails to
    // decode.
    GetRecentSeaPenImageThumbnail(uint32 id) =>
        (RecentSeaPenThumbnailData? thumbnail_data);

    // Deletes the selected SeaPen image from SeaPen directory. `id` must be a
    // valid id from a previous call to `GetRecentSeaPenImageIds`.
    DeleteRecentSeaPenImage(uint32 id) => (bool success);

    // Pops up a feedback dialog when user clicks feedback buttons.
    OpenFeedbackDialog(SeaPenFeedbackMetadata metadata);

    // Determines whether to show the SeaPen introduction dialog.
    ShouldShowSeaPenIntroductionDialog() => (bool should_show_dialog);

    // Called when the user close the introduction dialog for SeaPen feature.
    HandleSeaPenIntroductionDialogClosed();

    // Indicates whether the device is in tablet mode.
    IsInTabletMode() => (bool tablet_mode);

    // Called to force the browser window to make the native views transparent
    // so that the user can see wallpaper in fullscreen on their desktop. Safe
    // to call multiple times.
    MakeTransparent();
};
chromium/ash/webui/common/mojom/sea_pen.mojom
