// 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 record_replay.mojom;

// Uniquely identifies a DOM element in a document.
struct DomNodeId {
  int64 id;
};

// Identify a DOM element. Unlike DomNodeId, a selector is not guaranteed to
// be unique but attempts to be stable across page loads.
struct Selector {
  string selector;
};

// The value of a form control element or contenteditable.
struct FieldValue {
  string value;
};

// There is one instance of this interface per RenderFrame in the render
// process. The events are initiated by the browser process.
//
// Beware that data sent from the renderer to the browser is not to be trusted.
// In particular, element selectors shall not be parsed in the browser process.
interface RecordReplayAgent {
  // Instructs the renderer to send events to the RecordReplayDriver.
  StartRecording();

  // Instructs the renderer to stop sending events to the RecordReplayDriver.
  StopRecording();

  // Determines a selector for a given DOM element.
  // If unsuccessful, `element_selector` is the empty string.
  // TDOO(b/476101114): Generalize to multiple selectors.
  GetElementSelector(DomNodeId dom_node_id) => (Selector element_selector);

  // Determines all elements that match the given selector. The response is a
  // list of DOM node IDs.
  GetMatchingElements(Selector element_selector) => (array<DomNodeId> elements);

  // Dispatches a click event on the given DOM element.
  DoClick(DomNodeId dom_node_id) => (bool success);

  // Dispatches a paste event into the given form control element element which
  // replaces its content with `text`.
  DoPaste(DomNodeId dom_node_id, FieldValue text) => (bool success);

  // Selects the first option of the given select element that has the given
  // `value`.
  DoSelect(DomNodeId dom_node_id, FieldValue value) => (bool success);

  // Determines all elements matching a selector and retrieves their values.
  GetValuesOfMatchingElements(Selector element_selector) => (array<FieldValue> values);
};

// There is one instance of this interface per RenderFrameHost in the browser
// process. The events are initiated by the renderer process.
//
// Elements are identified in two ways:
// - The DOM node ID uniquely identifieds the element for the lifetime of the
//   HTML document. It is not stable across documents.
// - The selector string is not guaranteed to uniquely identify the element, but
//   attempts to be and is ideally stable across page load.
//   Currently this is a CSS selector, but the browser should make no
//   assumptions about the format.
//   TODO(b/476101114): Generalize to multiple selectors.
//
// Beware that data sent from the renderer to the browser is not to be trusted.
// In particular, element selectors shall not be parsed in the browser process.
interface RecordReplayDriver {
  // Fired when a left-click or tap on the given element happens.
  OnClick(DomNodeId dom_node_id, Selector element_selector);

  // Fired when the value of a select element changes.
  OnSelectChanged(DomNodeId dom_node_id,
                  Selector element_selector,
                  FieldValue value);

  // Fired when the text value of a text form control element changes.
  OnTextChange(DomNodeId dom_node_id,
               Selector element_selector,
               FieldValue text);
};