@ghia/native 0.0.0-stage → 0.11.0

package/dist/testing.d.ts

@@ -0,0 +1,811 @@
+import { type ElementWebAnimationInfo, type EventPayload, type MediaFeatures, type MotionValuePlayback, type PatchCounters, type WebAnimationEffectInfo, type WebAnimationInfo, type WebAnimationKeyframeInfo, type WebAnimationTimingUpdate, type WindowOptions } from "../index.js";
+import type { DebugFrameOverlayMode, DebugFrameOverlayStats, ElementBounds, HighlightMatch, ImagePixelFormat, MotionValueHost, NativeRenderer, WindowKeyEventHandlers } from "./host.js";
+import type { HostDropEffect } from "./events/types.js";
+import { type WindowFontsOption } from "./fonts.js";
+import { type SyncDispatchResult } from "./renderer-state.js";
+export { applyMacCpuThrottleFromEnv, MAC_CPU_THROTTLES, readMacCpuThrottle, } from "./cpu-throttle.js";
+export type { MacCpuThrottle } from "./cpu-throttle.js";
+export interface BuildCounters {
+    elementsBuilt: number;
+    elementsSkipped: number;
+    styleDescClones: number;
+    inheritedClones: number;
+    retainableRoots: number;
+    retainableElements: number;
+    retainableElementsLarge: number;
+    retainMismatches: number;
+    unitsBuilt: number;
+    unitsOversized: number;
+    motionsSynced: number;
+    motionValuesSampled: number;
+    retainReasons: string;
+}
+export interface FrameWorkCounters {
+    prepainted: number;
+    culledPrepainted: number;
+    painted: number;
+    culledPainted: number;
+    paintedPrimitives: number;
+    replayedPrimitives: number;
+    boundsInserts: number;
+    rasterizedGlyphs: number;
+    dormantTicks: number;
+}
+export interface LayoutCounters {
+    nodesCreated: number;
+    nodesReused: number;
+    nodesRemoved: number;
+    stylesSet: number;
+    childrenSet: number;
+    passes: number;
+    measures: number;
+    nodesLaidOut: number;
+    nodesSized: number;
+    relationVisits: number;
+    shapes: number;
+    wrappedLayouts: number;
+    lineLayoutHits: number;
+    shapeCacheHits: number;
+    extentWalks: number;
+    overflowWalks: number;
+    unsnappedOverflowWalks: number;
+}
+/** What the page of a `<webview>` was asked to do. */
+export interface WebviewCommand {
+    /** `loadURL`, `reload`, `stop`, `goBack`, `goForward`, `executeJavaScript` or
+     *  `setFirstResponder`. */
+    name: string;
+    /** The URL, the code, or for `setFirstResponder` `"true"`, `"false"`, `"forward"` (Tab) or
+     *  `"backward"` (Shift+Tab). */
+    argument?: string | null;
+}
+/** Where the last composed frame put the surface of a `<webview>`, in window pixels. */
+export interface WebviewSurface {
+    /** Painted, and not clipped away entirely. */
+    visible: boolean;
+    /** The whole surface, uncut. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** What shows of it: the surface cut by the clip of the content around it. */
+    clipX: number;
+    clipY: number;
+    clipWidth: number;
+    clipHeight: number;
+    opacity: number;
+    cornerRadius: number;
+    /** The position among the layers of the frame, bottom to top. */
+    layer: number;
+}
+/** A layer of the last composed frame, bottom to top: the window's GPUI layer, native surfaces and
+ *  the GPUI layers between and above them. */
+export interface CompositionLayer {
+    kind: "gpui" | "native";
+    /** The window's own GPUI layer. */
+    isBase: boolean;
+    /** GPUI layers: how many primitives of the scene it draws. */
+    primitives: number;
+    /** Native layers: the element of its `<webview>`. */
+    webview?: number | null;
+    /** Native layers: the element of its `<nativeview>`. */
+    nativeview?: number | null;
+    visible: boolean;
+}
+export interface NativeviewRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Where the last composed frame put the native view of a `<nativeview>`, in window pixels. */
+export interface NativeviewSurface {
+    /** The content view `onAttach` got, as a decimal string: the address of the `NSView` of the
+     *  test renderer's offscreen window, a large number like `"516333569280"` that differs per run.
+     *  Compare it with the `attach` handle, do not expect a fixed value. */
+    handle: string;
+    /** The whole surface: the padding box of the element. */
+    bounds: NativeviewRect;
+    /** What shows of it. For an element that does not clip it is the content mask around the
+     *  element, which can be larger than `bounds`. */
+    clip: NativeviewRect;
+    opacity: number;
+    /** The radius the view is cut to: the inner radius of an element that clips, else 0. */
+    cornerRadius: number;
+    /** The view takes the pointer events over its box. */
+    capturesPointer: boolean;
+}
+/** A native surface made or dropped by a `<nativeview>`, in order. */
+export interface NativeSurfaceEvent {
+    kind: "created" | "removed";
+    /** The content view of the surface, the `handle` of `onAttach`. */
+    handle: string;
+}
+/** The container view AppKit holds for a `<webview>` surface, in window points from the top
+ *  left: the placement that was applied, not only recorded. */
+export interface WebviewNativeView {
+    hidden: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** The content view the page lives in, relative to the container: whole size, cut by it. */
+    contentX: number;
+    contentY: number;
+    contentWidth: number;
+    contentHeight: number;
+    opacity: number;
+    /** A corner radius is cut into it. */
+    masked: boolean;
+}
+export interface RetainedCounters {
+    hits: number;
+    replays: number;
+    lazyBuilds: number;
+    builds: number;
+    layoutFallbacks: number;
+    layoutSkips: number;
+    layoutReplays: number;
+    layoutBuilds: number;
+    layoutTranslations: number;
+    layoutRecords: number;
+    verified: number;
+    mismatches: number;
+    nonReusable: string;
+    relocations: number;
+    nonRelocatable: string;
+    relocationMisses: string;
+}
+/**
+ * The options a live window takes (`WindowOptions`), applied to the offscreen test window by
+ * the same translation, plus the fonts option and the test hooks below. The size defaults to
+ * 1280x800 and `focus` to false, since the window is offscreen and must not take the OS's
+ * keyboard. `fullscreen`, `appId`, `appName` and `layerShell` have no effect on it; the
+ * docs/reference.md's Testing section lists what each option does there.
+ */
+export interface TestRendererOptions extends WindowOptions, WindowFontsOption {
+    /**
+     * Device pixels per CSS px the offscreen test window opens with, `1` when unset (headless
+     * Chrome's own), whatever display the machine has. `TestRenderer` only: a live window takes
+     * its display's scale.
+     */
+    scaleFactor?: number;
+    /** Framework scheduling boundary for events drained from native. */
+    dispatchEvent?: (event: EventPayload) => void;
+    /**
+     * Framework boundary for the events native waits on: `keydown` and `keyup`,
+     * which run inside the simulate call. Must return what the handlers decided.
+     */
+    dispatchSyncEvent?: (event: EventPayload) => SyncDispatchResult;
+    /**
+     * Receives an error thrown by an event handler, as `onError` does for a live
+     * renderer, and the dispatch carries on with the remaining handlers. Without
+     * it the error is reported as uncaught (`reportError`), never thrown from the
+     * simulate call that delivered the event. A test that expects the error
+     * passes `onError`.
+     */
+    onError?: (error: unknown) => void;
+}
+/** The motion a simulated mouse move reports, in logical pixels. */
+/**
+ * One key an input method consumes, and what the input method then does with
+ * it. `key` is a press in the `simulateKeystrokes` grammar.
+ */
+export type CompositionStep = 
+/** The composition becomes `text`: `compositionstart` on the first, then `compositionupdate`. */
+{
+    key: string;
+    action: "mark";
+    text: string;
+}
+/** The composition ends with `text` as the final text: `compositionend`. */
+ | {
+    key: string;
+    action: "commit";
+    text: string;
+}
+/** The composition ends with the text it has: `compositionend`. */
+ | {
+    key: string;
+    action: "unmark";
+};
+export interface MouseMovement {
+    x: number;
+    y: number;
+}
+/** Where a simulated wheel event sits in a gesture. A call that names none starts a
+ *  gesture of its own; the scroller that took a gesture's first delta keeps the rest of
+ *  it, so continue one with `"moved"`. */
+export type ScrollGesturePhase = "started" | "moved" | "ended" | "cancelled";
+export type TestWindowOptions = TestRendererOptions & WindowKeyEventHandlers;
+/** Whether the native TestGpuixRenderer is available (for conditional test registration). */
+export declare const hasNativeTestRenderer: boolean;
+export interface TestElement {
+    id: number;
+    type: string;
+    style: Record<string, unknown>;
+    text: string | null;
+    events: Set<string>;
+    children: number[];
+    parentId: number | null;
+    testId?: string;
+    customProps?: Record<string, unknown>;
+}
+/** GPUI `debug_a11y_tree_json` dump. Node keys are ephemeral (`a`, `b`, …). */
+export interface A11yTreeNode {
+    /** In device pixels from the window's content origin: clipped and off-screen
+     *  nodes are in the tree, with the box they have. */
+    bounds?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    aria?: {
+        role?: string;
+        label?: string;
+        description?: string;
+        value?: string;
+        author_id?: string;
+        keyboard_shortcut?: string;
+        placeholder?: string;
+        role_description?: string;
+        braille_label?: string;
+        braille_role_description?: string;
+        row_index_text?: string;
+        column_index_text?: string;
+        expanded?: boolean;
+        selected?: boolean;
+        toggled?: "False" | "True" | "Mixed";
+        hidden?: boolean;
+        disabled?: boolean;
+        required?: boolean;
+        read_only?: boolean;
+        multiselectable?: boolean;
+        busy?: boolean;
+        live_atomic?: boolean;
+        modal?: boolean;
+        invalid?: "True" | "Grammar" | "Spelling";
+        live?: "Off" | "Polite" | "Assertive";
+        aria_current?: string;
+        has_popup?: string;
+        orientation?: "Horizontal" | "Vertical";
+        sort_direction?: "Ascending" | "Descending" | "Other";
+        auto_complete?: "Inline" | "List" | "Both";
+        numeric_value?: number;
+        min_numeric_value?: number;
+        max_numeric_value?: number;
+        level?: number;
+        position_in_set?: number;
+        size_of_set?: number;
+        row_index?: number;
+        column_index?: number;
+        row_count?: number;
+        column_count?: number;
+        row_span?: number;
+        column_span?: number;
+        /** Relations hold the dump's ephemeral node keys; see `A11yTreeDump.nodes`. */
+        labelled_by?: string[];
+        described_by?: string[];
+        controls?: string[];
+        owns?: string[];
+        details?: string[];
+        flow_to?: string[];
+        error_message?: string;
+        active_descendant?: string;
+        on_action?: string[];
+    };
+}
+export interface A11yTreeDump {
+    root?: string;
+    /** Null when the window has no focused node. */
+    gpui_focus?: string | null;
+    /** Null when no active descendant is claimed. */
+    active_descendant_focus?: string | null;
+    /** Absent only when the dump is the empty `{}` fallback (no a11y tree yet). */
+    frame?: {
+        rendered_at: string;
+        frame_number: number;
+        window_title: string | null;
+        node_count: number;
+        tab_stop_count: number;
+        viewport_size: {
+            width: number;
+            height: number;
+        };
+        scale_factor: number;
+    };
+    nodes?: Record<string, A11yTreeNode>;
+}
+export declare class TestRenderer implements NativeRenderer {
+    /** Native TestGpuixRenderer — all state lives here in Rust's RetainedTree. */
+    private native;
+    readonly applyBatch: NativeRenderer["applyBatch"];
+    readonly focusNext: () => void;
+    readonly focusPrevious: () => void;
+    readonly promptForPaths: NonNullable<NativeRenderer["promptForPaths"]>;
+    /** The test window's own clipboard. It never touches the system's. */
+    readonly writeClipboardText: NonNullable<NativeRenderer["writeClipboardText"]>;
+    readonly readClipboardText: NonNullable<NativeRenderer["readClipboardText"]>;
+    readonly setWindowSelectionChange: NonNullable<NativeRenderer["setWindowSelectionChange"]>;
+    readonly setWindowAppearanceChange: NonNullable<NativeRenderer["setWindowAppearanceChange"]>;
+    readonly setWindowMediaChange: NonNullable<NativeRenderer["setWindowMediaChange"]>;
+    readonly getMediaFeatures: NonNullable<NativeRenderer["getMediaFeatures"]>;
+    readonly setWindowKeyEvents: NonNullable<NativeRenderer["setWindowKeyEvents"]>;
+    readonly setWindowEventListeners: NonNullable<NativeRenderer["setWindowEventListeners"]>;
+    private readonly dispatchEvent;
+    private readonly dispatchSyncEvent;
+    private readonly onError;
+    constructor(options?: TestRendererOptions);
+    /** Releases the sync event handler, which captures this renderer, and tears the native
+     *  window down. Call it after the root is unmounted. Native calls that need the window
+     *  throw afterwards; the retained tree stays readable. Without it the window is leaked
+     *  when the thread exits. */
+    dispose(): void;
+    /** Trigger the real GPUI rendering pipeline (GpuixView::render() →
+     *  build_element() → apply_styles() → layout). */
+    flush(): void;
+    /** Drain events collected by the native GPUI event handlers. */
+    drainEvents(): EventPayload[];
+    /** Wakes `callback` when the main run loop has work, as `GpuixRenderer.setFrameWakeCallback`
+     *  does. Returns true on macOS. Pass null to clear. */
+    setFrameWakeCallback(callback?: (() => void) | null): boolean;
+    /** Whether `startFrameLoop` must tick this renderer: true on macOS. */
+    requiresTick(): boolean;
+    /** One frame-loop step: hands the input AppKit queued for the test window (see
+     *  `postNativeEvent`) to it, then to the JS handlers, as `dispatchNativeEvents` does. Draws
+     *  nothing: frames stay `flush` and `drawFrame`. */
+    tick(): boolean;
+    /** Posts a real NSEvent for the test window from `com.apple.NSEventThread`, the way AppKit
+     *  receives input, so an idle `startFrameLoop(testRenderer)` is woken by it. `kind` is
+     *  `"keyDown"` (the key `a`), `"mouseMove"`, `"click"` or `"scroll"` (3 lines down); the last
+     *  three need `x` and `y` in logical pixels from the window's top left. The window is neither
+     *  made key nor shown, and nothing reaches the OS. `tick()` delivers the event. */
+    postNativeEvent(kind: string, x?: number, y?: number): void;
+    /** Drain events from the native GPUI pipeline and feed them into the
+     *  framework event registry, triggering state updates synchronously.
+     *  Loops until no more events are produced — handles re-entrant events
+     *  that may be generated during framework state updates. */
+    dispatchNativeEvents(): void;
+    /** Press keys on whatever currently holds focus, in Playwright's
+     *  `keyboard.press` grammar. A press is a DOM `key` value (`"Enter"`, `"a"`,
+     *  `"A"`, `"ArrowDown"`, `"Escape"`, `"Tab"`, `"F2"`) or a `code` name
+     *  (`"Space"`, `"KeyA"`, `"Digit1"`), with modifiers joined by `+`
+     *  (`"Shift+Tab"`, `"Meta+a"`, `"Alt+ArrowLeft"`, `"ControlOrMeta+Shift+P"`;
+     *  `ControlOrMeta` is Meta on macOS). `keystrokes` is a sequence of presses
+     *  separated by spaces: `"a Shift+b Enter"`. Each press is a `keydown` then a
+     *  `keyup`, and a typed key inserts its character into a focused input.
+     *  Names are case-sensitive and an unknown one throws before anything is
+     *  pressed.
+     *
+     *  Unlike `nativeSimulateKeystrokes`, this focuses nothing first, which is
+     *  the only way to test that `autoFocus` (or a click) actually moved focus. */
+    simulateKeystrokes(keystrokes: string): void;
+    /** Focus an element, then press keys on it (the `simulateKeystrokes` grammar).
+     *  @param elementId - element to focus
+     *  @param keystrokes - space-separated presses, e.g. `"h i Enter Shift+Tab"` */
+    nativeSimulateKeystrokes(elementId: number, keystrokes: string): void;
+    /** Focus an element, then send one `keydown` for one press (the
+     *  `simulateKeystrokes` grammar), with no `keyup` after it. Pairs with
+     *  `nativeSimulateKeyUp`.
+     *  @param elementId - element to focus
+     *  @param keystroke - one press, e.g. `"a"`, `"Enter"`, `"Meta+s"`
+     *  @param isHeld - whether this is a key-repeat event (default: false)
+     */
+    nativeSimulateKeyDown(elementId: number, keystroke: string, isHeld?: boolean): void;
+    /** Focus an element, then send one `keyup` for one press (the
+     *  `simulateKeystrokes` grammar). Pairs with `nativeSimulateKeyDown`.
+     *  @param elementId - element to focus
+     *  @param keystroke - one press, e.g. `"a"`, `"Enter"`, `"Meta+s"`
+     */
+    nativeSimulateKeyUp(elementId: number, keystroke: string): void;
+    /** Focus a text input, then run an input method composition in it, one step
+     *  per key. Each step is what macOS does for a key the input method takes: a
+     *  `keydown` with `key` `"Process"`, the composition events and the `change`
+     *  of the edit, then the `keyup` of that key. A text input is the only element
+     *  that composes, so `elementId` must be one.
+     *  @param elementId - the `<input>` or `<textarea>` to compose in
+     *  @param steps - the keys the input method consumes, in order */
+    simulateComposition(elementId: number, steps: readonly CompositionStep[]): void;
+    /** End-to-end: simulate a click through GPUI hit testing →
+     *  dispatch resulting events to the framework. */
+    nativeSimulateClick(x: number, y: number, button?: number, modifiers?: string): void;
+    /** End-to-end: simulate scroll wheel through GPUI →
+     *  dispatch resulting events to the framework. Deltas have the DOM's sign, like
+     *  `WheelEvent.deltaY`: positive `deltaY` scrolls down (the content moves up),
+     *  positive `deltaX` scrolls right. */
+    nativeSimulateScrollWheel(x: number, y: number, deltaX: number, deltaY: number, modifiers?: string, phase?: ScrollGesturePhase): void;
+    /** Dispatch a wheel without the surrounding flushes, for perf sampling. Deltas
+     *  have the DOM's sign: positive `deltaY` scrolls down.
+     *  Call `flush()` yourself, or the sample is the framework update only and
+     *  none of the GPUI build, layout and paint that follows. */
+    dispatchScrollWheel(x: number, y: number, deltaX: number, deltaY: number, modifiers?: string, phase?: ScrollGesturePhase): void;
+    /** Dispatch a move without the surrounding flushes, for perf sampling.
+     *  `nativeSimulateMouseMove` draws a pending change before and after the move, so a
+     *  drag timed with it includes the paint and a wheel timed with `dispatchScrollWheel`
+     *  does not. */
+    dispatchMouseMove(x: number, y: number, modifiers?: string, movement?: MouseMovement): void;
+    /** End-to-end: simulate mouse move through GPUI →
+     *  dispatch resulting events to the framework. The move reports the buttons held by
+     *  `nativeSimulateMouseDown` and not yet released by `nativeSimulateMouseUp`, as a real
+     *  OS does on every move, so a drag is a down, moves, an up.
+     *  @param movement - what the platform reports as this move's motion, which becomes
+     *    `movementX`/`movementY`. A real platform reports the delta from the last position;
+     *    the simulation reports `{ x: 0, y: 0 }` unless told otherwise. */
+    nativeSimulateMouseMove(x: number, y: number, modifiers?: string, movement?: MouseMovement): void;
+    /** End-to-end: the pointer leaves the window at (x, y), the way the platform
+     *  reports it, with no mouse move after the last position inside. */
+    nativeSimulateMouseExit(x: number, y: number): void;
+    /** The OS ate the release of `button` (0=left, the default, 1=middle, 2=right): the
+     *  renderer forgets it as held and dispatches nothing. The next move reports no button,
+     *  which is how a page sees a release it never got (the pointer let go outside the
+     *  window), and the press is cancelled. */
+    simulateLostMouseUp(button?: number): void;
+    /** End-to-end: simulate mouse down through GPUI hit testing →
+     *  dispatch resulting events to the framework.
+     *  @param button - 0=left (default), 1=middle, 2=right
+     *  @param clickCount - the platform's count: 2 for the second press of a double click */
+    nativeSimulateMouseDown(x: number, y: number, button?: number, modifiers?: string, clickCount?: number): void;
+    /** End-to-end: simulate mouse up through GPUI hit testing →
+     *  dispatch resulting events to the framework.
+     *  @param button - 0=left (default), 1=middle, 2=right
+     *  @param clickCount - the platform's count: 2 for the release of a double click */
+    nativeSimulateMouseUp(x: number, y: number, button?: number, modifiers?: string, clickCount?: number): void;
+    /**
+     * End-to-end: files from the OS enter the window at `x`, `y`. Returns the operation the
+     * window answered the OS drag with, as macOS would see it: the `dropEffect` the `dragover`
+     * ended with (`"none"` when no handler cancelled it), or `null` when native picked none.
+     */
+    nativeSimulateFileDragEnter(x: number, y: number, paths: string[]): HostDropEffect | null;
+    /** End-to-end: the dragged files move to `x`, `y`. Returns the operation, as `nativeSimulateFileDragEnter` does. */
+    nativeSimulateFileDragMove(x: number, y: number): HostDropEffect | null;
+    /** End-to-end: the dragged files are released at `x`, `y`. */
+    nativeSimulateFileDragSubmit(x: number, y: number): void;
+    /** End-to-end: the dragged files leave the window. */
+    nativeSimulateFileDragExit(): void;
+    /** End-to-end: the platform's drag session ends. */
+    nativeSimulateFileDragEnd(): void;
+    /** End-to-end: a whole Finder-style drop at `x`, `y`, as the platform sends it: enter, submit, exit, end. */
+    nativeSimulateFileDrop(x: number, y: number, paths: string[]): void;
+    /** Build a flat map of TestElements from the native tree JSON.
+     *  One FFI call to get the full tree, then parse into TestElement objects. */
+    private buildElementMap;
+    /** Get the root element. */
+    getRoot(): TestElement | undefined;
+    /** Get an element by ID. */
+    getElement(id: number): TestElement | undefined;
+    /** Find elements by type (e.g. "div", "text"). */
+    findByType(type: string): TestElement[];
+    /** Find the first text element containing the given string. */
+    findByText(text: string): TestElement | undefined;
+    findByTestId(testId: string): TestElement | undefined;
+    /** Get all text content in the tree (depth-first). */
+    getAllText(): string[];
+    /** Print the tree structure for debugging. Only includes non-empty fields. */
+    toJSON(): unknown;
+    /** GPUI accessibility dump from the last painted frame. */
+    getA11yTree(): A11yTreeDump;
+    getAutomationTree(): string;
+    /** Every element the native tree holds, reachable or not. `toJSON()` walks
+     *  from the root, so only this can see a node that was detached and leaked. */
+    getRetainedElementCount(): number;
+    /** What the element build has done since the last `resetBuildCounters()`:
+     *  elements built and `StyleDesc` / `Inherited` clones. A draw builds every
+     *  element, so divide by the frames drawn for the per-frame figure. */
+    getBuildCounters(): BuildCounters;
+    /** What the retained subtrees did since the window was made: subtrees not built, replayed,
+     *  built late, and frames compared with a whole build under `setRetainVerify`. */
+    getRetainedCounters(): RetainedCounters;
+    /** What building and drawing the elements did since the window was made: elements prepainted and
+     *  painted (those in a culled subtree apart), and the scene primitives painting inserted against
+     *  the ones a replay inserted again. A replayed subtree prepaints and paints none of its
+     *  elements; its replays are `getRetainedCounters().replays`. */
+    getFrameWorkCounters(): FrameWorkCounters;
+    /** How the frames compared under `setRetainVerify` differed from a whole build. */
+    getRetentionMismatches(): string[];
+    /** Layout nodes made, found again and freed, styles and child lists set, text measured and
+     *  shaped, and the subtrees whose extent and overflow were walked again, by the window's layout
+     *  engine since the window was made. */
+    getLayoutCounters(): LayoutCounters;
+    resetBuildCounters(): void;
+    /** Hashes what every element builds, and counts in `retainMismatches` an element the
+     *  retain key judged unchanged that built differently since the last build. Costs a
+     *  formatted style per element: leave it off to time a frame. */
+    setRetainVerify(verify: boolean): void;
+    /** Turns the skipping of unchanged subtrees on or off (on by default): off, every frame
+     *  builds every element, the way `GPUIX_RETAIN_OFF` makes it for the whole run. */
+    setRetainPlanning(planning: boolean): void;
+    /** Whether a frame records what it builds at all (on by default): off, a frame costs what it did
+     *  before retention, as `GPUIX_RETAIN_OFF` makes it for the whole run. Turning it on starts
+     *  from a frame that builds everything. */
+    setRetainEnabled(enabled: boolean): void;
+    /** Whether a tick of animations that only change what they paint is drawn by painting the roots
+     *  they change again in the frame before it (on by default, as `GPUIX_PATCH_OFF` turns off for the
+     *  whole run). It is never patched while the retention is off. */
+    setPatchEnabled(enabled: boolean): void;
+    /** How ticks were drawn by patching since the window was made: the frames and roots patched, the
+     *  ticks gpui drew whole after the patch was tried (`declines`, by reason, as JSON) and the ones
+     *  gpuix did not try to patch (`unpatchable`, by kind, as JSON). */
+    getPatchCounters(): PatchCounters;
+    /** Counts as if these exclusions (`svg`, `overflow-hidden`, `custom-element`, ...) were lifted,
+     *  to see which are worth lifting first. Nothing is reused. */
+    setRetainLift(names: string[]): void;
+    /** The elements counted in `retainMismatches`, one line each. */
+    getRetainMismatches(): string[];
+    /** Frames the window has painted. A test compares it before and after to
+     *  count the draws a read caused: a bounds or scroll read paints nothing. */
+    getPaintedFrameCount(): number;
+    /** Draw a dirty window when an update or a simulated input flushes (the
+     *  default), or leave that to `drawFrame`, as a real window leaves it to its
+     *  display link. A test that counts draws per frame turns it off. */
+    setInlineDraws(enabled: boolean): void;
+    /** One display-link frame: deliver the queued frame callbacks, then draw a
+     *  pending change once. Pairs with `setInlineDraws(false)`. */
+    drawFrame(): void;
+    /** Layout-only passes the window has run. A read of bounds or scroll metrics
+     *  on a dirty window is one, in place of a draw, and the next frame draws
+     *  once regardless. */
+    getLayoutPassCount(): number;
+    /** Pretends a screen reader is connected, as the test window starts out,
+     *  or not. Without one no accessibility tree is built. */
+    setA11yActive(active: boolean): void;
+    /** Subtrees the window has skipped as lying outside their clip, over its
+     *  life. Compare before and after a frame. */
+    getCulledSubtreeCount(): number;
+    getElementBounds(elementId: number): ElementBounds | null;
+    /** `getElementBounds` for the first report of an observer: it lays out as that does, but not the content
+     *  of a skipped `content-visibility` ancestor, and an element inside it has no box (null). */
+    probeElementBounds(elementId: number): ElementBounds | null;
+    /** The box the last layout gave an element, or null if it was not built. Unlike `getElementBounds`
+     *  it does not lay out the content of a skipped `content-visibility` ancestor to answer, so it
+     *  tells whether that content is built. */
+    getBuiltElementBounds(elementId: number): ElementBounds | null;
+    /** Ids of the elements under the window point, topmost first. */
+    getElementsAt(x: number, y: number): number[];
+    clockPause(): number;
+    clockSet(nowMs: number): number;
+    clockFastForward(deltaMs: number): number;
+    /** `clockFastForward` without telling the window, as time passing does in a live one: the frame
+     *  after it is a tick, which patches the frame before it when only paint-only animations ran. */
+    clockAdvance(deltaMs: number): number;
+    clockResume(): number;
+    createMotionValue(...args: Parameters<MotionValueHost["createMotionValue"]>): void;
+    createMotionTransform(...args: Parameters<MotionValueHost["createMotionTransform"]>): void;
+    createMotionFollower(...args: Parameters<MotionValueHost["createMotionFollower"]>): void;
+    createMotionSpring(...args: Parameters<MotionValueHost["createMotionSpring"]>): void;
+    disposeMotionValue(id: number): boolean;
+    getMotionValue(id: number): unknown;
+    getMotionValueVelocity(id: number): number;
+    isMotionValueAnimating(id: number): boolean;
+    setMotionValue(id: number, value: unknown): void;
+    jumpMotionValue(id: number, value: unknown): void;
+    animateMotionValue(id: number, target: unknown, transition?: unknown): void;
+    stopMotionValue(id: number): void;
+    pauseMotionValue(id: number): void;
+    playMotionValue(id: number): void;
+    seekMotionValue(id: number, seconds: number): void;
+    setMotionValueSpeed(id: number, speed: number): void;
+    completeMotionValue(id: number): void;
+    detachMotionValueClock(id: number): void;
+    getMotionValuePlayback(id: number): MotionValuePlayback | null;
+    setMotionValueListener(id: number, change: boolean, animation: boolean): void;
+    /** Advance GPUI's test dispatcher and run due timers.
+     *  This is not `clockFastForward`. That moves the motion clock only.
+     *  Use this for caret blink, input drag autoscroll, and list edge scroll. */
+    advanceTime(milliseconds: number): void;
+    focusElement(elementId: number): void;
+    blurElement(elementId: number): void;
+    matchesFocus(elementId: number, selector: string): boolean;
+    getFocusedElementId(): number | null;
+    /** Makes the offscreen window key (`true`, the default) or not, as when the user switches apps. */
+    setWindowActive(active: boolean): void;
+    focusNextWithin(elementId: number): void;
+    focusPreviousWithin(elementId: number): void;
+    /** The offscreen window size, so `useWindowSize()` works under test. */
+    getWindowSize(): {
+        width: number;
+        height: number;
+    };
+    /** `"system"` | `"light"` | `"dark"`, as on the live renderer: the window's appearance
+     *  follows (`getAppearance`, `light-dark()`, `prefers-color-scheme`) and `appearanceChange`
+     *  is delivered. `"system"` returns to the platform's own. */
+    setAppearance(appearance: string): void;
+    /** `"overlay"` (macOS "Show scroll bars" Automatically or When scrolling, which the test
+     *  window starts with) or `"classic"` (Always, which macOS also picks while a mouse is
+     *  attached). Classic bars are always drawn and take 15px (11 with `scrollbarWidth: "thin"`)
+     *  out of the container, so its `clientWidth` and content box shrink by it. The test window
+     *  never hears from the OS, so this is how a test flips the setting. */
+    setScrollbarStyle(style: "overlay" | "classic"): void;
+    /** The window's title, as the platform window has it: the `title` option, or `"GPUIX"`. */
+    getWindowTitle(): string;
+    /** The window's effective appearance, `"light"` or `"dark"`. */
+    getAppearance(): string;
+    /** Set the OS accessibility preferences this window reports (all start as
+     *  "no preference") and deliver the resulting `mediaChange` event. The test
+     *  window never hears from the OS, so this is how a test flips reduced motion. */
+    setMediaFeatures(features: Partial<MediaFeatures>): void;
+    /** Resize the offscreen window's content, as dragging its edge would: `getWindowSize()`
+     *  and the size queries of `matchMedia` see the new size, and their `change` events are
+     *  delivered. */
+    setWindowSize(width: number, height: number): void;
+    /** Give the offscreen window the scale factor of a display of another density (`2` is a
+     *  retina one), as a window dragged to it has: the next frame lays out and paints at it, and
+     *  a screenshot is the window's size times it. The factor stays until it is set again:
+     *  resizing the window does not reset it. The window starts at 1 (`scaleFactor` option). */
+    setWindowScaleFactor(scaleFactor: number): void;
+    /** Scroll an element (overflow: "scroll", or a `<virtual-list>`) to a DOM scroll
+     *  position: `left` and `top` are `scrollLeft` and `scrollTop`, zero or more, so
+     *  scrolling down is a larger `top`. Like a browser's, the write forces a layout only if
+     *  one is pending, and the window draws the new offset with its next frame. */
+    scrollTo(elementId: number, left: number, top: number, behavior?: string): void;
+    /** Scroll a child into view by its index in the children list.
+     *
+     *  `offsetInItem` is in pixels. A negative value anchors the viewport top
+     *  above the item, resolved against measured row heights at layout time, so
+     *  a row stays pixel-stable while unmeasured rows are spliced in above it. */
+    scrollToItem(elementId: number, index: number, offsetInItem?: number): void;
+    /** The DOM's `scrollIntoView`: every scrollable ancestor scrolls until the element sits
+     *  where `block` (default `"start"`) and `inline` (default `"nearest"`) ask. */
+    scrollIntoView(elementId: number, block?: string, inline?: string, behavior?: string): void;
+    /** Applies from the next simulated pointer input. See `PointerCaptureMethods`. */
+    setPointerCapture(elementId: number, pointerId: number): void;
+    releasePointerCapture(elementId: number, pointerId: number): void;
+    hasPointerCapture(elementId: number, pointerId: number): boolean;
+    clickElement(elementId: number): void;
+    getAnimations(elementId: number): WebAnimationInfo[];
+    getSubtreeAnimations(elementId: number): ElementWebAnimationInfo[];
+    getDocumentAnimations(): ElementWebAnimationInfo[];
+    /**
+     * The XML the `<svg>` painted from its shape children in the last frame, with
+     * animated attributes as that frame had them, or `null` when it painted none.
+     */
+    getSvgMarkup(elementId: number): string | null;
+    getAnimation(animationId: number): WebAnimationInfo;
+    releaseAnimation(animationId: number): void;
+    forgetAnimation(animationId: number): void;
+    getAnimationEffect(animationId: number): WebAnimationEffectInfo;
+    getAnimationKeyframes(animationId: number): WebAnimationKeyframeInfo[];
+    updateAnimationTiming(animationId: number, timing: WebAnimationTimingUpdate): void;
+    pauseAnimation(animationId: number): void;
+    playAnimation(animationId: number): void;
+    setAnimationCurrentTime(animationId: number, milliseconds: number): void;
+    setAnimationPlaybackRate(animationId: number, rate: number): void;
+    cancelAnimation(animationId: number): void;
+    finishAnimation(animationId: number): void;
+    reverseAnimation(animationId: number): void;
+    updateAnimationPlaybackRate(animationId: number, rate: number): void;
+    setAnimationStartTime(animationId: number, startTime: number | null): void;
+    getAnimationTimelineTime(): number;
+    /** Applies from the next simulated pointer input. */
+    cancelDrag(): void;
+    /** The frame it asks for is drawn here, so `pointerlockchange` or
+     *  `pointerlockerror` has reached its listeners when this returns. */
+    requestPointerLock(elementId: number): void;
+    exitPointerLock(): void;
+    pointerLockElement(): number | null;
+    /** Whether the simulated platform grants lock requests. The offscreen test
+     *  window is never key, so a real GPUI lock would always be refused; this
+     *  stands in for a platform that can lock, and off, for one that refuses. */
+    simulatePointerLockGranting(granting: boolean): void;
+    /** The platform drops the lock, as when the window deactivates. */
+    simulatePointerLockLost(): void;
+    /** What the window was asked to do by presses in `appRegion: "drag"` boxes since the last
+     *  call, oldest first: `"move"`, `"titlebarDoubleClick"` (macOS), `"zoom"` or `"showMenu"`
+     *  (Linux). The offscreen window cannot start a real move, so the test window records
+     *  instead. Every test window is frameless, so `appRegion` always applies. */
+    takeSimulatedWindowActions(): string[];
+    /** The default action of a scrolling key. See `scrollByKey` on the native renderer. */
+    scrollByKey(key: string, shift: boolean): void;
+    /** `[scrollLeft, scrollTop, scrollWidth, scrollHeight, clientWidth, clientHeight]`, or
+     *  null for an element that has not been painted. */
+    getScrollMetrics(elementId: number): number[] | null;
+    setImage(elementId: number, bytes: Buffer | Uint8Array): void;
+    setStyleImage(url: string, bytes: Buffer | Uint8Array): void;
+    failStyleImage(url: string, message: string): void;
+    selectText(elementId: number): void;
+    setSelectionRange(elementId: number, start: number, end: number, direction?: string): void;
+    getTextSelection(elementId: number): {
+        start: number;
+        end: number;
+        direction: string;
+    };
+    requestSubmit(elementId: number): void;
+    registerFont(bytes: Buffer | Uint8Array): void;
+    webviewCommand(elementId: number, command: string, argument?: string): void;
+    webviewState(elementId: number): {
+        url: string;
+        title: string;
+        canGoBack: boolean;
+        canGoForward: boolean;
+    };
+    webviewExecuteJavascript(elementId: number, code: string): Promise<string | null>;
+    /** What the page of the `<webview>` was asked to do, in order. */
+    getWebviewCommands(elementId: number): WebviewCommand[];
+    /** The page starts loading: `did-start-loading`. */
+    simulateWebviewStartLoading(elementId: number): void;
+    /** The page stops loading: `did-stop-loading`. */
+    simulateWebviewStopLoading(elementId: number): void;
+    /** The page commits `url`: `did-navigate`, and `getURL()` answers it. */
+    simulateWebviewNavigate(elementId: number, url: string): void;
+    /** The page hands the keyboard on, as it does when Tab leaves its last tabbable element
+     *  (`backwards`: Shift+Tab leaves its first): focus moves to the next (previous) tab stop. */
+    simulateWebviewTabOut(elementId: number, backwards?: boolean): void;
+    /** The page gets a title: `page-title-updated`, and `getTitle()` answers it. */
+    simulateWebviewTitle(elementId: number, title: string, explicitSet?: boolean): void;
+    /** A load fails: `did-fail-load`, with an `NSURLError` code. */
+    simulateWebviewFail(elementId: number, errorCode: number, errorDescription: string, validatedUrl?: string): void;
+    /** What `canGoBack()` and `canGoForward()` answer. */
+    setWebviewHistory(elementId: number, canGoBack: boolean, canGoForward: boolean): void;
+    /** Settles the oldest `executeJavaScript` of the `<webview>` that waits: resolves it with
+     *  `result` (anything JSON holds; `undefined` for `undefined`), or rejects it with `error`. */
+    settleWebviewScript(elementId: number, outcome: {
+        result?: unknown;
+        error?: string;
+    }): void;
+    /** Where the last frame put the surface of the `<webview>`; null while it has none. */
+    getWebviewSurface(elementId: number): WebviewSurface | null;
+    /** The layers of the last composed frame, bottom to top. */
+    getCompositionLayers(): CompositionLayer[];
+    /** The views AppKit holds for the `<webview>`, with the placement the last frame applied. */
+    getWebviewNativeView(elementId: number): WebviewNativeView;
+    /** Where the last frame put the native view of the `<nativeview>`; null while it has no
+     *  surface or the frame did not place it (`display: none`, `visibility: hidden`, culled). */
+    getNativeviewSurface(elementId: number): NativeviewSurface | null;
+    /** The native surfaces the `<nativeview>` elements made and dropped, in order. `"removed"` is
+     *  when the element drops the surface (after `detach`); its view leaves the window with the
+     *  next frame. */
+    getNativeSurfaceEvents(): NativeSurfaceEvent[];
+    /** How many warnings the `<nativeview>` has issued: one when the platform cannot make its
+     *  surface, however many frames are drawn. */
+    getNativeviewWarnings(elementId: number): number;
+    /** `false` makes the window refuse native surfaces, as a platform that cannot compose does:
+     *  call it before the first frame that paints a `<nativeview>`. */
+    setNativeSurfacesAvailable(available: boolean): void;
+    setImagePixels(elementId: number, width: number, height: number, pixels: Buffer | Uint8Array, format?: ImagePixelFormat): void;
+    /** The DOM scroll position `[scrollLeft, scrollTop]` (zero or more, like `element.scrollLeft`
+     *  and the `onScroll` event), or null if the element is not scrollable. */
+    getScrollOffset(elementId: number): [number, number] | null;
+    /** The CSS keyword of the cursor the window asks the platform for where the pointer last
+     *  was (`"default"` when nothing asks). A mouse move updates it, a draw keeps it current.
+     *  Keywords that name one cursor read back as the first of them: `"pointer"`, `"grabbing"`,
+     *  `"nwse-resize"`, `"nesw-resize"`, `"not-allowed"`. */
+    getCursor(): string;
+    /** The logical scroll anchor of a `<virtual-list>`:
+     *  `[itemIndex, offsetInItemPx, viewportHeightPx]`, or null for anything
+     *  else. `itemIndex == item count` is gpui's at-end sentinel. Exact even
+     *  while row heights are still estimates, because it is the anchor gpui
+     *  itself scrolls by. */
+    getListScrollTop(elementId: number): [number, number, number] | null;
+    /** Drag-select from (x1,y1) to (x2,y2) and return the selected text.
+     *
+     *  Selection listeners are registered during **paint**, so the native helper
+     *  flushes between every step. Calling simulateMouseDown/Move/Up by hand
+     *  without those flushes selects nothing. */
+    dragSelect(x1: number, y1: number, x2: number, y2: number): string | null;
+    /** The current selection joined in document order, or null. */
+    getSelectedText(): string | null;
+    /** Every string painted in the last frame, in paint order.
+     *
+     *  `getAllText()` only sees `<text>` nodes in the retained tree. Native
+     *  elements like `<code>` and `<diff>` paint their text inside GPUI, so this
+     *  is the only way to assert on what they rendered. */
+    getPaintedText(): string[];
+    /** Every highlight wash painted in the last frame, in paint order.
+     *
+     *  A quad never lands in `getPaintedText()`, and a soft-wrapped match must
+     *  draw one box per visual row, so each entry carries its `rects`. */
+    getPaintedHighlights(): HighlightMatch[];
+    /** Syntax-cache counters as `[hits, misses, documents]`. */
+    getSyntaxCacheStats(): [number, number, number];
+    clearSelection(): void;
+    setDebugFrameOverlay(mode: DebugFrameOverlayMode): string;
+    getDebugFrameOverlay(): string;
+    cycleDebugFrameOverlay(): string;
+    resetDebugFrameOverlayStats(): void;
+    getDebugFrameOverlayStats(): DebugFrameOverlayStats;
+    /** Capture the current Metal or DirectX frame and save it as a PNG. */
+    captureScreenshot(path: string): void;
+    /** Whether the native GPUI test renderer is available. Always true. */
+    get hasNative(): boolean;
+}
+//# sourceMappingURL=testing.d.ts.map