/**
 * The wire vocabulary of the ACTIVE-DOCUMENT probe — the scoped editor-chrome
 * door (`packages/editor/src/editor-document-probe.ts` implements it,
 * `@vgai/live`'s `editor.document` binds it, and that module's header carries
 * the design decision and the scope contract).
 *
 * Deliberately NOT a page-automation vocabulary: there is no navigation, no
 * waiting, no frame/window addressing and no selector rooted anywhere but the
 * active document's own container. Five actions, each one a gesture or a read
 * an agent cannot otherwise perform through the product.
 */

/** One element as the probe reports it — everything a caller needs to assert
 *  on, and nothing that requires a second round trip. */
export interface ProbedElement {
  /** Position within the match list this element came from. */
  index: number;
  tag: string;
  /** `innerText`, trimmed and capped. */
  text: string;
  attributes: Record<string, string>;
  rect: { x: number; y: number; width: number; height: number };
  /** Present for form controls. */
  value?: string;
  checked?: boolean;
  disabled?: boolean;
}

export interface DocumentProbeResult {
  /** The scope the step ran in — echoed so a transcript proves WHICH document
   *  was driven, not merely that something was. */
  document: { id: string; title: string };
  /** Total matches inside the scope, before any `limit`. */
  matched: number;
  elements: ProbedElement[];
}

/** Read what the active document rendered. */
export interface DocumentQueryStep {
  action: 'query';
  selector: string;
  /** Cap on returned elements (default 25); `matched` still reports the total. */
  limit?: number;
}

/** A real pointer gesture on one matched element. */
export interface DocumentClickStep {
  action: 'click';
  selector: string;
  /** Which match (default 0). */
  index?: number;
}

/**
 * A real pointer DRAG across one matched element: `pointerdown` at `from`,
 * `steps` `pointermove`s along the way, `pointerup` at `to` — the sequence a
 * mouse produces, so a canvas that begins a gesture on press and previews on
 * move (an Asset Lab document's direct manipulation) sees the whole gesture.
 * `from`/`to` are FRACTIONS of the element's box (`[0.5, 0.5]` is its
 * center), so a caller reasons in the element's own space, not the screen's.
 * A zero-length drag is a click at that fraction.
 */
export interface DocumentDragStep {
  action: 'drag';
  selector: string;
  /** Which match (default 0). */
  index?: number;
  from: [number, number];
  to: [number, number];
  /** Waypoints the pointer passes through between `from` and `to`, in
   *  order — what a lasso or a knife stroke needs, since a straight drag
   *  encloses nothing. Each leg gets `steps` moves. */
  via?: [number, number][];
  /** Intermediate `pointermove`s between consecutive points (default 8). */
  steps?: number;
  /** Modifier keys held for the whole gesture (a Shift-extend, an Alt-click). */
  altKey?: boolean;
  ctrlKey?: boolean;
  metaKey?: boolean;
  shiftKey?: boolean;
}

/** A real key on the explicit target, else whatever inside the document has focus. */
export interface DocumentKeyStep {
  action: 'key';
  key: string;
  code?: string;
  selector?: string;
  index?: number;
  ctrlKey?: boolean;
  metaKey?: boolean;
  shiftKey?: boolean;
  altKey?: boolean;
}

/** A real `ClipboardEvent` carrying `text/plain` — the only way to exercise a
 *  paste handler, and the gesture the Sheets build could not verify. */
export interface DocumentPasteStep {
  action: 'paste';
  text: string;
  selector?: string;
  index?: number;
}

/**
 * Choose a value on a `<select>` — the gesture `click` cannot make.
 *
 * A native dropdown's option list is rendered by the OS, not by the DOM, so
 * there is nothing inside the document's container for a pointer gesture to
 * resolve against: `click` on the `<select>` opens a menu no synthetic event
 * can reach. Assigning `element.value` is equally useless on a React
 * controlled component — React caches the last value it wrote on the node, so
 * a direct write is not seen as a change and the next render puts the old
 * value straight back. The implementation goes through the prototype's own
 * value setter and then dispatches `input`/`change`, which is the ONE spelling
 * React's synthetic-event layer honours.
 */
export interface DocumentSelectStep {
  action: 'select';
  selector: string;
  /** The option's `value` (not its label). */
  value: string;
  /** Which match (default 0). */
  index?: number;
}

export type DocumentProbeStep =
  | DocumentQueryStep
  | DocumentClickStep
  | DocumentDragStep
  | DocumentKeyStep
  | DocumentPasteStep
  | DocumentSelectStep;