components/surface_embed/common/surface_embed.mojom

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

module surface_embed.mojom;

import "mojo/public/mojom/base/unguessable_token.mojom";
import "services/viz/public/mojom/compositing/frame_sink_id.mojom";
import "services/viz/public/mojom/compositing/local_surface_id.mojom";
import "third_party/blink/public/mojom/frame/frame_visual_properties.mojom";
import "third_party/blink/public/mojom/input/focus_type.mojom";

// Implemented by SurfaceEmbedWebPlugin in the render process.
// The browser uses this interface to embed the surface of a child WebContents
// in an <embed> element on the embedder page.
interface SurfaceEmbed {
  // Embeds a surface by its FrameSinkId. When `allow_paint_holding` is true,
  // the old surface will be used as a fallback until the new surface produces
  // its first frame (or a timeout expires), preventing a visual flash during
  // navigation.
  // The `allow_paint_holding` is decided in Navigator::DidNavigate(). See
  // crbug.com/40942531 for why we cannot always enable paint holding.
  SetFrameSinkId(viz.mojom.FrameSinkId frame_sink_id,
                 bool allow_paint_holding);

  // Called when the child frame initiates a LocalSurfaceId update.
  // This typically happens when an auto-resized child frame has a new
  // intrinsic size. However, this has also been observed on non-auto-resized
  // frames (e.g., www.nytimes.com) due to an unclear triggering condition.
  UpdateLocalSurfaceIdFromChild(viz.mojom.LocalSurfaceId local_surface_id);

  // Called when the browser detects that the renderer process hosting the
  // child this is embedding has crashed.
  ChildProcessGone();

  // Requests focus for the <embed> element. Returns when the focus request
  // has completed.
  // SurfaceEmbedHost uses this completion callback to track pending focus
  // requests so that OnEmbedElementFocused() can ignore focus events triggered
  // by RequestFocusOnEmbedElement(). This prevents an incorrect call to
  // WebContents::Focus() in multi-level embedding setups (e.g., root -> parent
  // embed -> child embed when clicking on the child embed).
  RequestFocusOnEmbedElement() => ();

  // Requests to advance focus from the <embed> element in the embedder page.
  // When `reverse` is true, advances backward (e.g. Shift+Tab), otherwise
  // advances forward (e.g. Tab).
  AdvanceFocusFromEmbedElement(bool reverse);
};

// Represents the render throttling status of an embedded frame.
// Uses the same set of parameters as RemoteFrame::UpdateRenderThrottlingStatus.
// TODO(crbug.com/532190467): Make this a shared struct across RemoteFrame,
// FrameWidget, and SurfaceEmbedHost.
struct RenderThrottlingStatus {
  bool is_throttled;
  bool subtree_throttled;
  bool display_locked;
};

// Implemented by SurfaceEmbedHost in the browser process.
// The render process will use this interface to initiate the child WebContents
// attachment and synchronize with the browser about the visual properties of
// the <embed> element.
interface SurfaceEmbedHost {
  // Sets the SurfaceEmbed interface for communication with the renderer. This
  // must be called before other methods on SurfaceEmbedHost.
  SetSurfaceEmbed(pending_associated_remote<SurfaceEmbed> surface_embed);

  // Attaches the child content identified by `content_id` to the parent.
  // `is_embed_element_focused` indicates whether the <embed> element currently
  // has focus in the parent document.
  // `allow_pinch_zoom` indicates whether touchscreen pinch gestures should
  // scale the child WebContents instead of the embedding WebContents.
  AttachConnector(mojo_base.mojom.UnguessableToken content_id,
                  bool is_embed_element_focused,
                  bool allow_pinch_zoom);

  // Updates whether future touchscreen pinch gestures should scale the child
  // WebContents. A pinch sequence already in progress keeps its current target.
  SetAllowPinchZoom(bool allow_pinch_zoom);

  // Detaches the currently attached child content, if any.
  DetachConnector();

  // Synchronizes the visual properties of the <embed> element.
  // `is_visible` reports visibility with respect to "visibility:" CSS property;
  // This does not cover the case of "display:none", in which the plugin will
  // be destroyed.
  SynchronizeVisualProperties(
      blink.mojom.FrameVisualProperties visual_properties,
      bool is_visible);

  // Notifies the browser that the embed element inside the parent document
  // gained or lost focus.
  // SurfaceEmbedHost ignores this notification if there is a pending
  // RequestFocusOnEmbedElement() call to avoid incorrectly calling
  // WebContents::Focus() on the embedded WebContents in multi-level embedding
  // setups.
  OnEmbedElementFocused(bool focused, blink.mojom.FocusType focus_type);

  // Called when the render throttling status of the <embed> element changes.
  // `SurfaceEmbedHost` will decide how this state is applied to the child
  // WebContents (e.g. it may reject throttling when the child WebContents is
  // being screen-captured).
  OnEmbedElementThrottlingStatusChanged(RenderThrottlingStatus status);

  // Sends the parent HTML element accessibility node ID from the render process
  // to the browser process to stitch together accessibility trees in the
  // browser process. This may happen during creation or later
  // if accessibility is not yet enabled.
  SetParentAccessibilityInfo(int32 ax_node_id);
};