@ghia/native 0.0.0 → 0.11.0

package/dist/testing.js

@@ -0,0 +1,1187 @@
+/// GPUIX TestRenderer — thin wrapper over the native TestGpuixRenderer.
+///
+/// All state lives in Rust's RetainedTree. All mutations go directly to
+/// the native renderer via napi. Inspection methods (findByType, getAllText,
+/// toJSON, etc.) query the Rust tree via napi — no JS-side shadow copy.
+///
+/// All event simulation goes through the native GPUI pipeline (coordinate-based
+/// hit testing, GPUI dispatch, emit_event_full). The nativeSimulate* methods
+/// flush the tree, dispatch through GPUI, drain events, and feed them into
+/// the injected framework event dispatcher.
+import { hasTestGpuixRenderer, TestGpuixRenderer, measureMotionAnimation, validateKeyframes, } from "../index.js";
+import { bindClipboard } from "./clipboard.js";
+import { forgetElementSource, forgetWindowSource } from "./events/window-target.js";
+import { matchableText } from "./text-match.js";
+import { flushPendingMutations } from "./bounds.js";
+import { closeWebAnimations } from "./web-animations.js";
+import { flushObservations, settleObservations } from "./observers.js";
+import { readFontFiles } from "./fonts.js";
+import { registerKeyframesHost, unregisterKeyframesHost, registerKeyframesValidator, } from "./keyframes.js";
+import { registerAnimationMeasurer } from "./motion-value.js";
+import { createRendererState, reportSyncErrors } from "./renderer-state.js";
+export { applyMacCpuThrottleFromEnv, MAC_CPU_THROTTLES, readMacCpuThrottle, } from "./cpu-throttle.js";
+// The Linux stub has no test methods; the native availability check guards the full API.
+function hasNativeTestRendererClass(renderer) {
+    return hasTestGpuixRenderer();
+}
+const NativeTestRenderer = hasNativeTestRendererClass(TestGpuixRenderer) ? TestGpuixRenderer : null;
+/** Whether the native TestGpuixRenderer is available (for conditional test registration). */
+export const hasNativeTestRenderer = NativeTestRenderer != null;
+registerKeyframesValidator(validateKeyframes);
+registerAnimationMeasurer((from, target, transition) => {
+    const length = measureMotionAnimation(from, target, transition ?? null);
+    return { duration: length.duration, iterationDuration: length.iterationDuration };
+});
+// ── TestRenderer ─────────────────────────────────────────────────────
+/** The test window is one per thread: making a renderer tears down the one before it. */
+let latestRenderer;
+/** Throws if a replayed frame of this window differed from a build of it, or if gpuix's own
+ *  check found an element judged unchanged that built differently, and prints the counters when
+ *  GPUIX_RETAIN_VERIFY_REPORT is set. The gpuix findings are read from the window's list, not
+ *  from `retainMismatches`, which is one count per thread that only `resetBuildCounters` clears. */
+function reportRetentionMismatches(native) {
+    const counters = native.getRetainedCounters();
+    const findings = native.getRetainMismatches();
+    if (process.env.GPUIX_RETAIN_VERIFY_REPORT !== undefined) {
+        console.log(`[retain-verify] verified=${counters.verified} mismatches=${counters.mismatches} gpuix-mismatches=${findings.length} replays=${counters.replays} ` +
+            `hits=${counters.hits} builds=${counters.builds} lazy=${counters.lazyBuilds} non-reusable=${counters.nonReusable}`);
+    }
+    if (counters.mismatches > 0) {
+        throw new Error(`${counters.mismatches} replayed frames differed from a build:\n${native.getRetentionMismatches().join('\n')}`);
+    }
+    if (findings.length > 0) {
+        throw new Error(`${findings.length} elements were judged unchanged and built differently:\n${findings.join('\n')}`);
+    }
+}
+export class TestRenderer {
+    /** Native TestGpuixRenderer — all state lives here in Rust's RetainedTree. */
+    native;
+    applyBatch;
+    focusNext;
+    focusPrevious;
+    promptForPaths;
+    /** The test window's own clipboard. It never touches the system's. */
+    writeClipboardText;
+    readClipboardText;
+    setWindowSelectionChange;
+    setWindowAppearanceChange;
+    setWindowMediaChange;
+    getMediaFeatures;
+    setWindowKeyEvents;
+    setWindowEventListeners;
+    dispatchEvent;
+    dispatchSyncEvent;
+    onError;
+    constructor(options = {}) {
+        if (!NativeTestRenderer) {
+            throw new Error("TestGpuixRenderer is macOS and Windows only. Linux builds have no test-support because wgpu cannot read a rendered image back yet. GpuixRenderer still works on Linux.");
+        }
+        const fonts = readFontFiles(options.fonts);
+        this.native = new NativeTestRenderer(options, options.scaleFactor);
+        if (latestRenderer) {
+            // The native side keeps one window per thread and this constructor replaced it, so the
+            // earlier renderer is as dead as a disposed one: it would reach the new window's state, and
+            // throw once that is disposed.
+            forgetWindowSource(latestRenderer);
+            unregisterKeyframesHost(latestRenderer.native);
+            closeWebAnimations(latestRenderer);
+        }
+        latestRenderer = this;
+        for (const font of fonts)
+            this.native.registerFont(font);
+        registerKeyframesHost(this.native);
+        this.applyBatch = this.native.applyBatch.bind(this.native);
+        this.focusNext = this.native.focusNext.bind(this.native);
+        this.focusPrevious = this.native.focusPrevious.bind(this.native);
+        this.promptForPaths = this.native.promptForPaths.bind(this.native);
+        this.writeClipboardText = this.native.writeClipboardText.bind(this.native);
+        this.readClipboardText = this.native.readClipboardText.bind(this.native);
+        this.setWindowKeyEvents = this.native.setWindowKeyEvents.bind(this.native);
+        this.setWindowEventListeners = this.native.setWindowEventListeners.bind(this.native);
+        this.setWindowSelectionChange = this.native.setWindowSelectionChange.bind(this.native);
+        this.setWindowAppearanceChange = this.native.setWindowAppearanceChange.bind(this.native);
+        this.onError = options.onError;
+        this.setWindowMediaChange = this.native.setWindowMediaChange.bind(this.native);
+        this.getMediaFeatures = this.native.getMediaFeatures.bind(this.native);
+        this.dispatchEvent = options.dispatchEvent ?? ((event) => {
+            createRendererState(this).dispatch(event);
+        });
+        const state = createRendererState(this);
+        state.setErrorHandler(options.onError);
+        this.dispatchSyncEvent = reportSyncErrors(options.dispatchSyncEvent ?? ((event) => state.dispatchSync(event)), (error) => state.reportError(error));
+        this.native.setSyncEventHandler((event) => this.dispatchSyncEvent(event));
+        bindClipboard(this);
+    }
+    /** 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() {
+        // A run under GPUIX_RETAIN_VERIFY fails at the window that showed a replayed frame that a
+        // build would have shown differently, and says which test's window it was.
+        if (process.env.GPUIX_RETAIN_VERIFY !== undefined)
+            reportRetentionMismatches(this.native);
+        forgetElementSource(this);
+        unregisterKeyframesHost(this.native);
+        closeWebAnimations(this);
+        this.native.setSyncEventHandler(null);
+        this.native.dispose();
+    }
+    // ── GPUI pipeline methods ───────────────────────────────────────
+    /** Trigger the real GPUI rendering pipeline (GpuixView::render() →
+     *  build_element() → apply_styles() → layout). */
+    flush() {
+        this.native.flush();
+    }
+    /** Drain events collected by the native GPUI event handlers. */
+    drainEvents() {
+        return this.native.drainEvents();
+    }
+    // ── Frame loop ──────────────────────────────────────────────────
+    // The surface `startFrameLoop` drives, so the wake path can be checked without a live window.
+    // The test window draws no frames: a tick delivers the input AppKit has queued for it.
+    /** Wakes `callback` when the main run loop has work, as `GpuixRenderer.setFrameWakeCallback`
+     *  does. Returns true on macOS. Pass null to clear. */
+    setFrameWakeCallback(callback) {
+        return this.native.setFrameWakeCallback(callback);
+    }
+    /** Whether `startFrameLoop` must tick this renderer: true on macOS. */
+    requiresTick() {
+        return this.native.requiresTick();
+    }
+    /** 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() {
+        const running = this.native.tick();
+        this.dispatchNativeEvents();
+        return running;
+    }
+    /** 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, x, y) {
+        this.native.postNativeEvent(kind, x, y);
+    }
+    // ── Native end-to-end simulation ────────────────────────────────
+    // These methods go through the full GPUI pipeline:
+    //   native simulate → GPUI dispatch → hit test → event handler →
+    //   emit_event_full → drainEvents → framework event handler
+    /** 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() {
+        // The probe draws, and its reports are what the loop below drains.
+        settleObservations(this);
+        for (;;) {
+            const events = this.native.drainEvents();
+            if (events.length === 0)
+                break;
+            for (const event of events) {
+                try {
+                    this.dispatchEvent(event);
+                }
+                catch (error) {
+                    if (!this.onError)
+                        throw error;
+                    this.onError(error);
+                }
+            }
+        }
+        // Nothing else would run the observers' batch in a synchronous test.
+        flushObservations(this);
+    }
+    /** 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) {
+        this.native.flushIfDirty();
+        // Events already queued reach JS before a key does, as on a live window.
+        // Delivered after it, they would undo what the key's own synchronous focus
+        // events did.
+        this.dispatchNativeEvents();
+        this.native.simulateKeystrokes(keystrokes);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    /** 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, keystrokes) {
+        this.native.flushIfDirty();
+        this.native.focusElement(elementId);
+        // Focus events are queued but a key is delivered synchronously: let the
+        // focus handlers run first, as in a browser.
+        this.dispatchNativeEvents();
+        this.native.simulateKeystrokes(keystrokes);
+        this.dispatchNativeEvents();
+    }
+    /** 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, keystroke, isHeld) {
+        this.native.flushIfDirty();
+        this.native.focusElement(elementId);
+        // Focus events are queued but a key is delivered synchronously: let the
+        // focus handlers run first, as in a browser.
+        this.dispatchNativeEvents();
+        this.native.simulateKeyDown(keystroke, isHeld);
+        this.dispatchNativeEvents();
+    }
+    /** 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, keystroke) {
+        this.native.flushIfDirty();
+        this.native.focusElement(elementId);
+        // Focus events are queued but a key is delivered synchronously: let the
+        // focus handlers run first, as in a browser.
+        this.dispatchNativeEvents();
+        this.native.simulateKeyUp(keystroke);
+        this.dispatchNativeEvents();
+    }
+    /** 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, steps) {
+        this.native.flushIfDirty();
+        this.native.focusElement(elementId);
+        // Focus events are queued but a key is delivered synchronously: let the
+        // focus handlers run first, as in a browser.
+        this.dispatchNativeEvents();
+        for (const step of steps) {
+            this.native.simulateImeKeyDown(step.key, step.action, step.action === "unmark" ? undefined : step.text);
+            // The edit's events are queued behind the keydown, and a browser fires
+            // them before the keyup.
+            this.dispatchNativeEvents();
+            this.native.simulateKeyUp(step.key);
+            this.dispatchNativeEvents();
+        }
+        this.native.flushIfDirty();
+    }
+    /** End-to-end: simulate a click through GPUI hit testing →
+     *  dispatch resulting events to the framework. */
+    nativeSimulateClick(x, y, button, modifiers) {
+        this.native.flushIfDirty();
+        // Two inputs, not `native.simulateClick`: whatever the press queued must
+        // reach JS before the release, as it does when a person lets go later.
+        this.native.simulateMouseDown(x, y, button ?? 0, modifiers);
+        this.dispatchNativeEvents();
+        this.native.simulateMouseUp(x, y, button ?? 0, modifiers);
+        this.dispatchNativeEvents();
+        // Flush again after framework state updates so the Rust RetainedTree
+        // is fully rebuilt and GPUI has re-laid-out before any screenshot.
+        this.native.flushIfDirty();
+    }
+    /** 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, y, deltaX, deltaY, modifiers, phase) {
+        this.native.flushIfDirty();
+        this.native.simulateScrollWheel(x, y, deltaX, deltaY, modifiers, phase);
+        this.dispatchNativeEvents();
+    }
+    /** 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, y, deltaX, deltaY, modifiers, phase) {
+        this.native.simulateScrollWheel(x, y, deltaX, deltaY, modifiers, phase);
+        this.dispatchNativeEvents();
+    }
+    /** 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, y, modifiers, movement) {
+        this.native.simulateMouseMove(x, y, modifiers, movement?.x, movement?.y);
+        this.dispatchNativeEvents();
+    }
+    /** 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, y, modifiers, movement) {
+        this.native.flushIfDirty();
+        this.native.simulateMouseMove(x, y, modifiers, movement?.x, movement?.y);
+        this.dispatchNativeEvents();
+        // Flush again after framework state updates so hover styles are applied
+        // and the Rust tree is current before any screenshot.
+        this.native.flushIfDirty();
+    }
+    /** 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, y) {
+        this.native.flushIfDirty();
+        this.native.simulateMouseExit(x, y);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    /** 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) {
+        this.native.simulateLostMouseUp(button);
+    }
+    /** 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, y, button, modifiers, clickCount) {
+        this.native.flushIfDirty();
+        this.native.simulateMouseDown(x, y, button ?? 0, modifiers, clickCount);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    /** 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, y, button, modifiers, clickCount) {
+        this.native.flushIfDirty();
+        this.native.simulateMouseUp(x, y, button ?? 0, modifiers, clickCount);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    /**
+     * 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, y, paths) {
+        this.native.flushIfDirty();
+        const operation = this.native.simulateFileDragEnter(x, y, paths);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+        return operation;
+    }
+    /** End-to-end: the dragged files move to `x`, `y`. Returns the operation, as `nativeSimulateFileDragEnter` does. */
+    nativeSimulateFileDragMove(x, y) {
+        this.native.flushIfDirty();
+        const operation = this.native.simulateFileDragMove(x, y);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+        return operation;
+    }
+    /** End-to-end: the dragged files are released at `x`, `y`. */
+    nativeSimulateFileDragSubmit(x, y) {
+        this.native.flushIfDirty();
+        this.native.simulateFileDragSubmit(x, y);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    /** End-to-end: the dragged files leave the window. */
+    nativeSimulateFileDragExit() {
+        this.native.flushIfDirty();
+        this.native.simulateFileDragExit();
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    /** End-to-end: the platform's drag session ends. */
+    nativeSimulateFileDragEnd() {
+        this.native.flushIfDirty();
+        this.native.simulateFileDragEnd();
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    /** End-to-end: a whole Finder-style drop at `x`, `y`, as the platform sends it: enter, submit, exit, end. */
+    nativeSimulateFileDrop(x, y, paths) {
+        this.native.flushIfDirty();
+        this.native.simulateFileDrop(x, y, paths);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    // ── Tree inspection (queries Rust RetainedTree via napi) ────────
+    /** Build a flat map of TestElements from the native tree JSON.
+     *  One FFI call to get the full tree, then parse into TestElement objects. */
+    buildElementMap() {
+        const json = JSON.parse(this.native.getTreeJson());
+        const map = new Map();
+        const walk = (node, parentId) => {
+            if (!node)
+                return;
+            map.set(node.id, {
+                id: node.id,
+                type: node.type,
+                style: node.style ?? {},
+                text: node.text ?? null,
+                events: new Set(node.events ?? []),
+                children: (node.children ?? []).map((c) => c.id),
+                parentId,
+                ...(node.testId ? { testId: node.testId } : {}),
+                ...(node.customProps ? { customProps: node.customProps } : {}),
+            });
+            for (const child of node.children ?? []) {
+                walk(child, node.id);
+            }
+        };
+        walk(json, null);
+        return map;
+    }
+    /** Get the root element. */
+    getRoot() {
+        const rootId = this.native.getRootId();
+        if (rootId == null)
+            return undefined;
+        return this.buildElementMap().get(rootId);
+    }
+    /** Get an element by ID. */
+    getElement(id) {
+        return this.buildElementMap().get(id);
+    }
+    /** Find elements by type (e.g. "div", "text"). */
+    findByType(type) {
+        return [...this.buildElementMap().values()].filter((el) => el.type === type);
+    }
+    /** Find the first text element containing the given string. */
+    findByText(text) {
+        const wanted = matchableText(text);
+        return [...this.buildElementMap().values()].find((el) => el.text != null && matchableText(el.text).includes(wanted));
+    }
+    findByTestId(testId) {
+        return [...this.buildElementMap().values()].find((el) => el.testId === testId);
+    }
+    /** Get all text content in the tree (depth-first). */
+    getAllText() {
+        return this.native.getAllText();
+    }
+    /** Print the tree structure for debugging. Only includes non-empty fields. */
+    toJSON() {
+        return JSON.parse(this.native.getTreeJson());
+    }
+    /** GPUI accessibility dump from the last painted frame. */
+    getA11yTree() {
+        return JSON.parse(this.native.getA11yTree());
+    }
+    getAutomationTree() {
+        return this.native.getAutomationTree();
+    }
+    /** 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() {
+        return this.native.getRetainedElementCount();
+    }
+    /** 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() {
+        return this.native.getBuildCounters();
+    }
+    /** 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() {
+        return this.native.getRetainedCounters();
+    }
+    /** 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() {
+        return this.native.getFrameWorkCounters();
+    }
+    /** How the frames compared under `setRetainVerify` differed from a whole build. */
+    getRetentionMismatches() {
+        return this.native.getRetentionMismatches();
+    }
+    /** 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() {
+        return this.native.getLayoutCounters();
+    }
+    resetBuildCounters() {
+        this.native.resetBuildCounters();
+    }
+    /** 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) {
+        this.native.setRetainVerify(verify);
+    }
+    /** 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) {
+        this.native.setRetainPlanning(planning);
+    }
+    /** 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) {
+        this.native.setRetainEnabled(enabled);
+    }
+    /** 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) {
+        this.native.setPatchEnabled(enabled);
+    }
+    /** 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() {
+        return this.native.getPatchCounters();
+    }
+    /** Counts as if these exclusions (`svg`, `overflow-hidden`, `custom-element`, ...) were lifted,
+     *  to see which are worth lifting first. Nothing is reused. */
+    setRetainLift(names) {
+        this.native.setRetainLift(names);
+    }
+    /** The elements counted in `retainMismatches`, one line each. */
+    getRetainMismatches() {
+        return this.native.getRetainMismatches();
+    }
+    /** 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() {
+        return this.native.getPaintedFrameCount();
+    }
+    /** 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) {
+        this.native.setInlineDraws(enabled);
+    }
+    /** One display-link frame: deliver the queued frame callbacks, then draw a
+     *  pending change once. Pairs with `setInlineDraws(false)`. */
+    drawFrame() {
+        this.native.drawFrame();
+    }
+    /** 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() {
+        return this.native.getLayoutPassCount();
+    }
+    /** Pretends a screen reader is connected, as the test window starts out,
+     *  or not. Without one no accessibility tree is built. */
+    setA11yActive(active) {
+        this.native.setA11yActive(active);
+    }
+    /** Subtrees the window has skipped as lying outside their clip, over its
+     *  life. Compare before and after a frame. */
+    getCulledSubtreeCount() {
+        return this.native.getCulledSubtreeCount();
+    }
+    getElementBounds(elementId) {
+        flushPendingMutations(this);
+        return this.native.getElementBounds(elementId);
+    }
+    /** `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) {
+        flushPendingMutations(this);
+        return this.native.probeElementBounds(elementId);
+    }
+    /** 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) {
+        flushPendingMutations(this);
+        return this.native.getBuiltElementBounds(elementId);
+    }
+    /** Ids of the elements under the window point, topmost first. */
+    getElementsAt(x, y) {
+        flushPendingMutations(this);
+        return this.native.getElementsAt(x, y);
+    }
+    clockPause() {
+        return this.native.clockPause();
+    }
+    clockSet(nowMs) {
+        return this.native.clockSet(nowMs);
+    }
+    clockFastForward(deltaMs) {
+        return this.native.clockFastForward(deltaMs);
+    }
+    /** `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) {
+        return this.native.clockAdvance(deltaMs);
+    }
+    clockResume() {
+        return this.native.clockResume();
+    }
+    // ── Motion values ───────────────────────────────────────────────
+    createMotionValue(...args) {
+        this.native.createMotionValue(...args);
+    }
+    createMotionTransform(...args) {
+        this.native.createMotionTransform(...args);
+    }
+    createMotionFollower(...args) {
+        this.native.createMotionFollower(...args);
+    }
+    createMotionSpring(...args) {
+        this.native.createMotionSpring(...args);
+    }
+    disposeMotionValue(id) {
+        return this.native.disposeMotionValue(id);
+    }
+    getMotionValue(id) {
+        return this.native.getMotionValue(id);
+    }
+    getMotionValueVelocity(id) {
+        return this.native.getMotionValueVelocity(id);
+    }
+    isMotionValueAnimating(id) {
+        return this.native.isMotionValueAnimating(id);
+    }
+    setMotionValue(id, value) {
+        this.native.setMotionValue(id, value);
+    }
+    jumpMotionValue(id, value) {
+        this.native.jumpMotionValue(id, value);
+    }
+    animateMotionValue(id, target, transition) {
+        this.native.animateMotionValue(id, target, transition);
+    }
+    stopMotionValue(id) {
+        this.native.stopMotionValue(id);
+    }
+    pauseMotionValue(id) {
+        this.native.pauseMotionValue(id);
+    }
+    playMotionValue(id) {
+        this.native.playMotionValue(id);
+    }
+    seekMotionValue(id, seconds) {
+        this.native.seekMotionValue(id, seconds);
+    }
+    setMotionValueSpeed(id, speed) {
+        this.native.setMotionValueSpeed(id, speed);
+    }
+    completeMotionValue(id) {
+        this.native.completeMotionValue(id);
+    }
+    detachMotionValueClock(id) {
+        this.native.detachMotionValueClock(id);
+    }
+    getMotionValuePlayback(id) {
+        return this.native.getMotionValuePlayback(id);
+    }
+    setMotionValueListener(id, change, animation) {
+        this.native.setMotionValueListener(id, change, animation);
+    }
+    /** 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) {
+        this.native.advanceTime(milliseconds);
+        this.dispatchNativeEvents();
+    }
+    focusElement(elementId) {
+        this.native.flushIfDirty();
+        this.native.focusElement(elementId);
+        this.dispatchNativeEvents();
+    }
+    blurElement(elementId) {
+        this.native.flushIfDirty();
+        this.native.blurElement(elementId);
+        this.dispatchNativeEvents();
+    }
+    matchesFocus(elementId, selector) {
+        this.native.flushIfDirty();
+        const matches = this.native.matchesFocus(elementId, selector);
+        this.dispatchNativeEvents();
+        return matches;
+    }
+    getFocusedElementId() {
+        this.native.flushIfDirty();
+        return this.native.getFocusedElementId();
+    }
+    /** Makes the offscreen window key (`true`, the default) or not, as when the user switches apps. */
+    setWindowActive(active) {
+        this.native.setWindowActive(active);
+        this.native.flushIfDirty();
+        this.dispatchNativeEvents();
+    }
+    focusNextWithin(elementId) {
+        this.native.flushIfDirty();
+        this.native.focusNextWithin(elementId);
+        this.dispatchNativeEvents();
+    }
+    focusPreviousWithin(elementId) {
+        this.native.flushIfDirty();
+        this.native.focusPreviousWithin(elementId);
+        this.dispatchNativeEvents();
+    }
+    /** The offscreen window size, so `useWindowSize()` works under test. */
+    getWindowSize() {
+        return this.native.getWindowSize();
+    }
+    /** `"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) {
+        this.native.flush();
+        this.native.setAppearance(appearance);
+        this.native.flush();
+        this.dispatchNativeEvents();
+    }
+    /** `"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) {
+        this.native.flush();
+        this.native.setScrollbarStyle(style);
+        this.native.flush();
+    }
+    /** The window's title, as the platform window has it: the `title` option, or `"GPUIX"`. */
+    getWindowTitle() {
+        this.native.flush();
+        return this.native.getWindowTitle();
+    }
+    /** The window's effective appearance, `"light"` or `"dark"`. */
+    getAppearance() {
+        this.native.flush();
+        return this.native.getAppearance();
+    }
+    /** 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) {
+        this.native.setMediaFeatures(features.reducedMotion, features.increasedContrast, features.forcedColors);
+        this.dispatchNativeEvents();
+    }
+    /** 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, height) {
+        this.native.setWindowSize(width, height);
+        this.dispatchNativeEvents();
+    }
+    /** 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) {
+        this.native.setWindowScaleFactor(scaleFactor);
+    }
+    // ── Scroll API ──────────────────────────────────────────────────
+    /** 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, left, top, behavior) {
+        this.native.scrollTo(elementId, left, top, behavior);
+    }
+    /** 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, index, offsetInItem) {
+        this.native.flush();
+        this.native.scrollToItem(elementId, index, offsetInItem);
+        this.dispatchNativeEvents();
+        this.native.flush();
+    }
+    /** The DOM's `scrollIntoView`: every scrollable ancestor scrolls until the element sits
+     *  where `block` (default `"start"`) and `inline` (default `"nearest"`) ask. */
+    scrollIntoView(elementId, block, inline, behavior) {
+        this.native.flush();
+        this.native.scrollIntoView(elementId, block, inline, behavior);
+        this.dispatchNativeEvents();
+        this.native.flush();
+    }
+    /** Applies from the next simulated pointer input. See `PointerCaptureMethods`. */
+    setPointerCapture(elementId, pointerId) {
+        this.native.setPointerCapture(elementId, pointerId);
+    }
+    releasePointerCapture(elementId, pointerId) {
+        this.native.releasePointerCapture(elementId, pointerId);
+    }
+    hasPointerCapture(elementId, pointerId) {
+        return this.native.hasPointerCapture(elementId, pointerId);
+    }
+    clickElement(elementId) {
+        this.native.clickElement(elementId);
+    }
+    getAnimations(elementId) {
+        return this.native.getAnimations(elementId);
+    }
+    getSubtreeAnimations(elementId) {
+        return this.native.getSubtreeAnimations(elementId);
+    }
+    getDocumentAnimations() {
+        return this.native.getDocumentAnimations();
+    }
+    /**
+     * 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) {
+        return this.native.getSvgMarkup(elementId);
+    }
+    getAnimation(animationId) {
+        return this.native.getAnimation(animationId);
+    }
+    releaseAnimation(animationId) {
+        this.native.releaseAnimation(animationId);
+    }
+    forgetAnimation(animationId) {
+        this.native.forgetAnimation(animationId);
+    }
+    getAnimationEffect(animationId) {
+        return this.native.getAnimationEffect(animationId);
+    }
+    getAnimationKeyframes(animationId) {
+        return this.native.getAnimationKeyframes(animationId);
+    }
+    updateAnimationTiming(animationId, timing) {
+        this.native.updateAnimationTiming(animationId, timing);
+    }
+    pauseAnimation(animationId) {
+        this.native.pauseAnimation(animationId);
+    }
+    playAnimation(animationId) {
+        this.native.playAnimation(animationId);
+    }
+    setAnimationCurrentTime(animationId, milliseconds) {
+        this.native.setAnimationCurrentTime(animationId, milliseconds);
+    }
+    setAnimationPlaybackRate(animationId, rate) {
+        this.native.setAnimationPlaybackRate(animationId, rate);
+    }
+    cancelAnimation(animationId) {
+        this.native.cancelAnimation(animationId);
+    }
+    finishAnimation(animationId) {
+        this.native.finishAnimation(animationId);
+    }
+    reverseAnimation(animationId) {
+        this.native.reverseAnimation(animationId);
+    }
+    updateAnimationPlaybackRate(animationId, rate) {
+        this.native.updateAnimationPlaybackRate(animationId, rate);
+    }
+    setAnimationStartTime(animationId, startTime) {
+        this.native.setAnimationStartTime(animationId, startTime);
+    }
+    getAnimationTimelineTime() {
+        return this.native.getAnimationTimelineTime();
+    }
+    /** Applies from the next simulated pointer input. */
+    cancelDrag() {
+        this.native.cancelDrag();
+    }
+    /** The frame it asks for is drawn here, so `pointerlockchange` or
+     *  `pointerlockerror` has reached its listeners when this returns. */
+    requestPointerLock(elementId) {
+        this.native.requestPointerLock(elementId);
+        this.dispatchNativeEvents();
+    }
+    exitPointerLock() {
+        this.native.exitPointerLock();
+        this.dispatchNativeEvents();
+    }
+    pointerLockElement() {
+        return this.native.pointerLockElement();
+    }
+    /** 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) {
+        this.native.simulatePointerLockGranting(granting);
+    }
+    /** The platform drops the lock, as when the window deactivates. */
+    simulatePointerLockLost() {
+        this.native.simulatePointerLockLost();
+        this.dispatchNativeEvents();
+    }
+    /** 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() {
+        return this.native.takeSimulatedWindowActions();
+    }
+    /** The default action of a scrolling key. See `scrollByKey` on the native renderer. */
+    scrollByKey(key, shift) {
+        this.native.flush();
+        this.native.scrollByKey(key, shift);
+        this.dispatchNativeEvents();
+        this.native.flush();
+    }
+    /** `[scrollLeft, scrollTop, scrollWidth, scrollHeight, clientWidth, clientHeight]`, or
+     *  null for an element that has not been painted. */
+    getScrollMetrics(elementId) {
+        return this.native.getScrollMetrics(elementId);
+    }
+    setImage(elementId, bytes) {
+        this.native.flush();
+        this.native.setImage(elementId, bytes);
+        this.native.flush();
+    }
+    setStyleImage(url, bytes) {
+        this.native.flush();
+        this.native.setStyleImage(url, bytes);
+        this.native.flush();
+    }
+    failStyleImage(url, message) {
+        this.native.flush();
+        this.native.failStyleImage(url, message);
+        this.native.flush();
+    }
+    selectText(elementId) {
+        this.native.flush();
+        this.native.selectText(elementId);
+        this.native.flush();
+    }
+    setSelectionRange(elementId, start, end, direction) {
+        this.native.flush();
+        this.native.setSelectionRange(elementId, start, end, direction);
+        this.native.flush();
+    }
+    getTextSelection(elementId) {
+        this.native.flush();
+        return this.native.getTextSelection(elementId);
+    }
+    requestSubmit(elementId) {
+        this.native.flushIfDirty();
+        this.native.requestSubmit(elementId);
+        this.dispatchNativeEvents();
+        this.native.flushIfDirty();
+    }
+    registerFont(bytes) {
+        this.native.registerFont(bytes);
+        this.native.flush();
+    }
+    // ── <webview> ───────────────────────────────────────────────────
+    // The page of a webview is made when the element is first painted, so these draw first.
+    // The engine is a scripted page: it answers from what these set, and reports what they make it.
+    webviewCommand(elementId, command, argument) {
+        this.native.flush();
+        this.native.webviewCommand(elementId, command, argument);
+    }
+    webviewState(elementId) {
+        this.native.flush();
+        return this.native.webviewState(elementId);
+    }
+    webviewExecuteJavascript(elementId, code) {
+        this.native.flush();
+        return this.native.webviewExecuteJavascript(elementId, code);
+    }
+    /** What the page of the `<webview>` was asked to do, in order. */
+    getWebviewCommands(elementId) {
+        this.native.flush();
+        return this.native.getWebviewCommands(elementId);
+    }
+    /** The page starts loading: `did-start-loading`. */
+    simulateWebviewStartLoading(elementId) {
+        this.native.flush();
+        this.native.simulateWebviewStartLoading(elementId);
+        this.dispatchNativeEvents();
+    }
+    /** The page stops loading: `did-stop-loading`. */
+    simulateWebviewStopLoading(elementId) {
+        this.native.flush();
+        this.native.simulateWebviewStopLoading(elementId);
+        this.dispatchNativeEvents();
+    }
+    /** The page commits `url`: `did-navigate`, and `getURL()` answers it. */
+    simulateWebviewNavigate(elementId, url) {
+        this.native.flush();
+        this.native.simulateWebviewNavigate(elementId, url);
+        this.dispatchNativeEvents();
+    }
+    /** 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, backwards = false) {
+        this.native.flush();
+        this.native.simulateWebviewTabOut(elementId, backwards);
+        this.dispatchNativeEvents();
+    }
+    /** The page gets a title: `page-title-updated`, and `getTitle()` answers it. */
+    simulateWebviewTitle(elementId, title, explicitSet = true) {
+        this.native.flush();
+        this.native.simulateWebviewTitle(elementId, title, explicitSet);
+        this.dispatchNativeEvents();
+    }
+    /** A load fails: `did-fail-load`, with an `NSURLError` code. */
+    simulateWebviewFail(elementId, errorCode, errorDescription, validatedUrl) {
+        this.native.flush();
+        this.native.simulateWebviewFail(elementId, errorCode, errorDescription, validatedUrl);
+        this.dispatchNativeEvents();
+    }
+    /** What `canGoBack()` and `canGoForward()` answer. */
+    setWebviewHistory(elementId, canGoBack, canGoForward) {
+        this.native.flush();
+        this.native.setWebviewHistory(elementId, canGoBack, canGoForward);
+    }
+    /** 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, outcome) {
+        this.native.flush();
+        this.native.settleWebviewScript(elementId, outcome.result === undefined ? undefined : JSON.stringify(outcome.result), outcome.error);
+    }
+    /** Where the last frame put the surface of the `<webview>`; null while it has none. */
+    getWebviewSurface(elementId) {
+        this.native.flush();
+        return this.native.getWebviewSurface(elementId);
+    }
+    /** The layers of the last composed frame, bottom to top. */
+    getCompositionLayers() {
+        this.native.flush();
+        return this.native.getCompositionLayers();
+    }
+    /** The views AppKit holds for the `<webview>`, with the placement the last frame applied. */
+    getWebviewNativeView(elementId) {
+        this.native.flush();
+        return this.native.getWebviewNativeView(elementId);
+    }
+    // ── <nativeview> ────────────────────────────────────────────────
+    // The surface of a nativeview is made when its element is first painted.
+    /** 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) {
+        this.native.flush();
+        return this.native.getNativeviewSurface(elementId);
+    }
+    /** 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() {
+        this.native.flush();
+        return this.native.getNativeSurfaceEvents();
+    }
+    /** How many warnings the `<nativeview>` has issued: one when the platform cannot make its
+     *  surface, however many frames are drawn. */
+    getNativeviewWarnings(elementId) {
+        this.native.flush();
+        return this.native.getNativeviewWarnings(elementId);
+    }
+    /** `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) {
+        this.native.flush();
+        this.native.setNativeSurfacesAvailable(available);
+    }
+    setImagePixels(elementId, width, height, pixels, format) {
+        this.native.flush();
+        this.native.setImagePixels(elementId, width, height, pixels, format);
+        this.native.flush();
+    }
+    /** 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) {
+        this.native.flush();
+        const result = this.native.getScrollOffset(elementId);
+        if (!result)
+            return null;
+        return [result[0], result[1]];
+    }
+    /** 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() {
+        this.native.flush();
+        return this.native.getCursor();
+    }
+    /** 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) {
+        this.native.flush();
+        const result = this.native.getListScrollTop(elementId);
+        if (!result)
+            return null;
+        return [result[0], result[1], result[2]];
+    }
+    // ── Selection API ───────────────────────────────────────────────
+    /** 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, y1, x2, y2) {
+        this.native.dragSelect(x1, y1, x2, y2);
+        return this.native.getSelectedText();
+    }
+    /** The current selection joined in document order, or null. */
+    getSelectedText() {
+        return this.native.getSelectedText();
+    }
+    /** 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() {
+        return this.native.getPaintedText();
+    }
+    /** 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() {
+        return this.native.getPaintedHighlights();
+    }
+    /** Syntax-cache counters as `[hits, misses, documents]`. */
+    getSyntaxCacheStats() {
+        const [hits, misses, documents] = this.native.getSyntaxCacheStats();
+        return [hits, misses, documents];
+    }
+    clearSelection() {
+        this.native.clearSelection();
+        this.native.flush();
+    }
+    setDebugFrameOverlay(mode) {
+        return this.native.setDebugFrameOverlay(mode);
+    }
+    getDebugFrameOverlay() {
+        return this.native.getDebugFrameOverlay();
+    }
+    cycleDebugFrameOverlay() {
+        return this.native.cycleDebugFrameOverlay();
+    }
+    resetDebugFrameOverlayStats() {
+        this.native.resetDebugFrameOverlayStats();
+    }
+    getDebugFrameOverlayStats() {
+        return this.native.getDebugFrameOverlayStats();
+    }
+    /** Capture the current Metal or DirectX frame and save it as a PNG. */
+    captureScreenshot(path) {
+        this.native.flush();
+        this.native.captureScreenshot(path);
+    }
+    /** Whether the native GPUI test renderer is available. Always true. */
+    get hasNative() {
+        return true;
+    }
+}
+//# sourceMappingURL=testing.js.map