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

module lens.mojom;

import "chrome/browser/lens/core/mojom/geometry.mojom";
import "chrome/browser/lens/core/mojom/overlay_object.mojom";
import "chrome/browser/lens/core/mojom/page_content_type.mojom";
import "chrome/browser/lens/core/mojom/text.mojom";
import "chrome/browser/lens/core/mojom/translate.mojom";
import "mojo/public/mojom/base/big_string.mojom";
import "skia/public/mojom/bitmap.mojom";
import "skia/public/mojom/skcolor.mojom";
import "ui/base/mojom/window_open_disposition.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";

// Enumerates the user interactions with the Lens Overlay.
//
// This enum must match the numbering for LensOverlayUserAction in enums.xml.
//
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
// LINT.IfChange(UserAction)
enum UserAction {
  kRegionSelection = 0,
  kRegionSelectionChange = 1,
  kTextSelection = 2,
  kObjectClick = 3,
  kTranslateText = 4,
  kCopyText = 5,
  kMyActivity = 6,
  kLearnMore = 7,
  kSendFeedback = 8,
  kTapRegionSelection = 9,
  kTranslateButtonEnableAction = 10,
  kTranslateButtonDisableAction = 11,
  kTranslateSourceLanguageChanged = 12,
  kTranslateTargetLanguageChanged = 13,
  kTranslateTextSelection = 14,
  kCopyAsImage = 15,
  kSaveAsImage = 16,
  kMathSelection = 17,
  kFullScreenshotRegionSelection = 18,
};

// LINT.ThenChange(//tools/metrics/histograms/metadata/lens/enums.xml:LensOverlayUserAction)

// Enumerates the semantic events that can be logged by the Lens Overlay.
enum SemanticEvent {
  kTextGleamsViewStart = 0,
  kTextGleamsViewEnd = 1,
};

// Factory method for creating a new WebUI page handler for lens overlay.
interface LensPageHandlerFactory {
  // The WebUI calls this method when the page is first initialized.
  CreatePageHandler(pending_receiver<LensPageHandler> handler,
                    pending_remote<LensPage> page);
};


// Browser-side handler for requests from WebUI page. (TypeScript -> C++)
interface LensPageHandler {
  // When this method is called, the C++ coordinator will open the link to the
  // My Activity page in a new tab.
  ActivityRequestedByOverlay(ui.mojom.ClickModifiers click_modifiers);

  // WebUI calls this when the user wants to dismiss the lens overlay using
  // the close button.
  CloseRequestedByOverlayCloseButton();

  // Like above, but when dismissed by clicking on the overlay background.
  CloseRequestedByOverlayBackgroundClick();

  // This method is called to notify the C++ coordinator that the overlay has
  // content that will fill the viewport.
  NotifyOverlayInitialized();

  // When this method is called, the C++ coordinator will add a blur to the
  // tab contents.
  AddBackgroundBlur();

  // Enables/disables the live blurring of the background
  SetLiveBlur(bool enabled);

  // When this method is called, the C++ coordinator will show the feedback
  // dialog.
  FeedbackRequestedByOverlay();

  // Returns the Lens Overlay entry point, used in the WebUI for metrics
  // sliced by entry point. Requested by WebUI to eliminate need to wait
  // for page to be bound on browser side.
  GetOverlayInvocationSource() => (string invocation_source);

  // When this method is called, the C++ coordinator will open the link to the
  // Help Center article in a new tab.
  InfoRequestedByOverlay(ui.mojom.ClickModifiers click_modifiers);

  // When this method is called, the C++ coordinator sends a Lens request with
  // the given bounding region to the Lens servers and display results in the
  // Chrome side panel. The region should be normalized between 0 and 1.
  // The click flag should be set if the region was created using a click
  // (i.e. not a dragged-out region) and is used for logging only.
  // TODO(b/329262670): Verify normalization does not cause off-by-1 pixel
  // errors.
  IssueLensRegionRequest(CenterRotatedBox region, bool is_click);

  // When this method is called, the C++ coordinator sends a Lens request with
  // the given bounding region to the Lens servers and display results in the
  // Chrome side panel. The region should be normalized between 0 and 1.
  // The mask click flag is used for logging only.
  // TODO(b/329262670): Verify normalization does not cause off-by-1 pixel
  // errors.
  IssueLensObjectRequest(CenterRotatedBox region, bool is_mask_click);

  // When this method is called, the C++ coordinator issues a SRP request with
  // given text string in the side panel. This function also passes selection
  // indices into a list of words maintained in the WebUI and are passed to the
  // browser-side UI solely for the purposes of maintaining a history stack.
  // They do not and will not be used to be indexed into anything in the
  // browser; when the user traverses history, the indices may be passed back to
  // the WebUI. The function also passed an `is_translate` boolean for logging
  // purposes but it does not change any functionality.
  IssueTextSelectionRequest(string query,
                            int32 selection_start_index,
                            int32 selection_end_index,
                            bool is_translate);

  // Similar to IssueTextSelectionRequest(), but requests that the selected
  // text be translated.
  IssueTranslateSelectionRequest(string query,
                                 string content_language,
                                 int32 selection_start_index,
                                 int32 selection_end_index);

  // Similar to IssueTextSelectionRequest(), but adds a math formula.
  IssueMathSelectionRequest(string query,
                            string formula,
                            int32 selection_start_index,
                            int32 selection_end_index);

  // When this method is called, the C++ coordinator issues another full image
  // request with appropriate parameters to return a response with text on the
  // screenshot translated from `source_language` to `target_language`. This
  // differs from IssueTranslateSelectionRequest() as this is a request to
  // translate the entire screenshot, rather than a translation of selected
  // text.
  IssueTranslateFullPageRequest(
      string source_language, string target_language);

  // When this method is called, the C++ coordinator issues another full image
  // request with the auto filter, which is necessary to update the overlay
  // state to the default non-translate mode.
  IssueEndTranslateModeRequest();

  // Copies the given text to the users clipboard using the browser process.
  // This is different than using navigator.clipboard.writeText since
  // navigator.clipboard.writeText requires explicet user activation on the web
  // contents to work. Since the focus leaves the overlay web contents when the
  // user opens side panel, we cannot guarantee the overlay webcontents will
  // still have explicit user activation. Therefore, we use this method instead.
  CopyText(string text);

  // Copies the given region of the current screenshot to the user's clipboard
  // using the browser process. Rationale for using this method is the same as
  // for CopyText.
  CopyImage(CenterRotatedBox region);

  // Crops the current screenshot to the given region and downloads it as a PNG
  // file.
  SaveAsImage(CenterRotatedBox region);

  // When called, the C++ coordinator closes the preselection toast bubble.
  ClosePreselectionBubble();

  // Records UKM metrics and task completion for lens overlay interactions.
  RecordUkmAndTaskCompletionForLensOverlayInteraction(
      UserAction user_action);

  // Records a semantic event for the lens overlay.
  RecordLensOverlaySemanticEvent(SemanticEvent event);

  // Requests to show a feature promo on the translate button. This is a no-op
  // if the promo show fails for reasons listed out at
  // //components/user_education/common/feature_promo/feature_promo_result.h.
  // The most common
  // failures are due to the anchor not being visible or it has already been
  // shown and dismissed.
  MaybeShowTranslateFeaturePromo();

  // Requests to close the feature promo on the translate button with a
  // parameter denoting whether the feature was engaged. A no-op if no promo is
  // showing.
  MaybeCloseTranslateFeaturePromo(bool feature_engaged);

  // Requests to fetch the supported languages from the translate server.
  // Returns the supported source and target languages to translate from and to.
  // Also returns the browser locale as that determines the browser UI language.
  // This can't be retrieved from the `navigator.language` call in TS because
  // the user's browser UI language can differ from the language used for web
  // content.
  FetchSupportedLanguages() => (string browser_locale,
                                array<Language> source_languages,
                                array<Language> target_languages);

  // Notifies the browser that the overlay WebUI is ready to be reshown so it
  // can reshow the blur with the appropriate live page screenshot.
  FinishReshowOverlay();

  // Notifies the browser that the user has accepted the privacy notice in the
  // overlay.
  AcceptPrivacyNotice();

  // Notifies the browser that the user has dismissed the privacy notice in the
  // overlay.
  DismissPrivacyNotice();
};

// WebUI page handler for request from Browser side. (C++ -> TypeScript)
interface LensPage {
  // Pass screenshot data to WebUI and a parameter indicating whether the
  // side panel is already open in order to update the UI.
  ScreenshotDataReceived(
      skia.mojom.BitmapMappedFromTrustedProcess screenshot_data,
      bool is_side_panel_open);

  // Notifies the WebUI that the handshake to the Lens backend is complete.
  NotifyHandshakeComplete();

  // Notifies the WebUI that our results panel is currently opening.
  NotifyResultsPanelOpened();

  // Notifies the WebUI that a close has been triggered and the overlay will
  // soon be hidden.
  NotifyOverlayClosing();

  // Passes objects received from Lens to WebUI for rendering.
  ObjectsReceived(array<OverlayObject> objects);

  // Passes Text received from Lens to WebUI for rendering.
  TextReceived(Text text);

  // Passes region text received from Lens to WebUI for rendering. Also
  // indicates whether the text was received for an injected image. An injected
  // image is a preselected region that was sent to the Lens overlay on open.
  // It differs from a regular region search because the image bytes are not
  // cropped from the page screenshot.
  RegionTextReceived(Text text, bool is_injected_image);


  // Sets whether the contextual searchbox should be shown to the user.
  ShouldShowContextualSearchBox(bool should_show);

  // Notifies the contextual searchbox that the page content type has changed.
  // `new_page_content_type` is the new type of the page.
  PageContentTypeChanged(PageContentType new_page_content_type);

  // Sets a post selection region to be rendered as selected on the page.
  SetPostRegionSelection(CenterRotatedBox region);

  // Sets text to be rendered as selected on the page.
  SetTextSelection(int32 selection_start_index, int32 selection_end_index);

  // Sets the overlay to translate mode with the specified languages.
  SetTranslateMode(string source_language, string target_language);

  // Clears any post region selection on the page. No-op if none selected.
  ClearRegionSelection();

  // Clears any text selection on the page. No-op if none selected.
  ClearTextSelection();

  // Clears any text or post region selection on the page. No-op if none
  // selected.
  ClearAllSelections();

  // Copies the currently selected text or image to the users clipboard and
  // displays the relevant copied toast.
  OnCopyCommand();

  // Suppress the ghost loader when tab is foregrounded.
  SuppressGhostLoader();

  // Notifies the WebUI that the overlay is being reshown.
  OnOverlayReshown(skia.mojom.BitmapMappedFromTrustedProcess screenshot_data);
};