@pixui-dev/inflight-test 0.0.7

package/dist/index.d.ts

@@ -0,0 +1,1679 @@
+import { A as TestArtifact, C as joinPath, D as SuiteCollector, E as SuiteAPI, F as beforeEach, I as onTestFailed, L as onTestFinished, M as afterAll, N as afterEach, O as Test, P as beforeAll, S as createRunId, T as FileSpecification, _ as ProgressSurface, a as StartOptions, b as QuickjsReportIo, c as start, d as CaptureScreenRequest, f as CaptureScreenResult, g as ConsoleProgressSurface, h as CollectingProgressSurface, i as RunProgressEvent, j as VitestRunner, k as TestAPI, l as ActivityBridge, m as PROTOCOL_CAPTURE_SCREEN_CALLBACK, n as InflightRunResult, o as TestFileSpec, p as PROTOCOL_CAPTURE_SCREEN, r as InflightVitestRunner, s as run, t as InflightRunOptions, u as CaptureRect, v as MemoryReportIo, w as File, x as ReportIo, y as QuickjsOs } from "./run-tests-DoriyCYM.js";
+
+//#region src/vendored/runtime/runner/suite.d.ts
+/**
+ * Creates a suite of tests, allowing for grouping and hierarchical organization of tests.
+ * Suites can contain both tests and other suites, enabling complex test structures.
+ *
+ * @param {string} name - The name of the suite, used for identification and reporting.
+ * @param {Function} fn - A function that defines the tests and suites within this suite.
+ * @example
+ * ```ts
+ * // Define a suite with two tests
+ * suite('Math operations', () => {
+ *   test('should add two numbers', () => {
+ *     expect(add(1, 2)).toBe(3);
+ *   });
+ *
+ *   test('should subtract two numbers', () => {
+ *     expect(subtract(5, 2)).toBe(3);
+ *   });
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Define nested suites
+ * suite('String operations', () => {
+ *   suite('Trimming', () => {
+ *     test('should trim whitespace from start and end', () => {
+ *       expect('  hello  '.trim()).toBe('hello');
+ *     });
+ *   });
+ *
+ *   suite('Concatenation', () => {
+ *     test('should concatenate two strings', () => {
+ *       expect('hello' + ' ' + 'world').toBe('hello world');
+ *     });
+ *   });
+ * });
+ * ```
+ */
+declare const suite: SuiteAPI;
+/**
+ * Defines a test case with a given name and test function. The test function can optionally be configured with test options.
+ *
+ * @param {string | Function} name - The name of the test or a function that will be used as a test name.
+ * @param {TestOptions | TestFunction} [optionsOrFn] - Optional. The test options or the test function if no explicit name is provided.
+ * @param {number | TestOptions | TestFunction} [optionsOrTest] - Optional. The test function or options, depending on the previous parameters.
+ * @throws {Error} If called inside another test function.
+ * @example
+ * ```ts
+ * // Define a simple test
+ * test('should add two numbers', () => {
+ *   expect(add(1, 2)).toBe(3);
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Define a test with options
+ * test('should subtract two numbers', { retry: 3 }, () => {
+ *   expect(subtract(5, 2)).toBe(3);
+ * });
+ * ```
+ */
+declare const test: TestAPI;
+/**
+ * Creates a suite of tests, allowing for grouping and hierarchical organization of tests.
+ * Suites can contain both tests and other suites, enabling complex test structures.
+ *
+ * @param {string} name - The name of the suite, used for identification and reporting.
+ * @param {Function} fn - A function that defines the tests and suites within this suite.
+ * @example
+ * ```ts
+ * // Define a suite with two tests
+ * describe('Math operations', () => {
+ *   test('should add two numbers', () => {
+ *     expect(add(1, 2)).toBe(3);
+ *   });
+ *
+ *   test('should subtract two numbers', () => {
+ *     expect(subtract(5, 2)).toBe(3);
+ *   });
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Define nested suites
+ * describe('String operations', () => {
+ *   describe('Trimming', () => {
+ *     test('should trim whitespace from start and end', () => {
+ *       expect('  hello  '.trim()).toBe('hello');
+ *     });
+ *   });
+ *
+ *   describe('Concatenation', () => {
+ *     test('should concatenate two strings', () => {
+ *       expect('hello' + ' ' + 'world').toBe('hello world');
+ *     });
+ *   });
+ * });
+ * ```
+ */
+declare const describe: SuiteAPI;
+/**
+ * Defines a test case with a given name and test function. The test function can optionally be configured with test options.
+ *
+ * @param {string | Function} name - The name of the test or a function that will be used as a test name.
+ * @param {TestOptions | TestFunction} [optionsOrFn] - Optional. The test options or the test function if no explicit name is provided.
+ * @param {number | TestOptions | TestFunction} [optionsOrTest] - Optional. The test function or options, depending on the previous parameters.
+ * @throws {Error} If called inside another test function.
+ * @example
+ * ```ts
+ * // Define a simple test
+ * it('adds two numbers', () => {
+ *   expect(add(1, 2)).toBe(3);
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Define a test with options
+ * it('subtracts two numbers', { retry: 3 }, () => {
+ *   expect(subtract(5, 2)).toBe(3);
+ * });
+ * ```
+ */
+declare const it: TestAPI;
+declare function getRunner(): VitestRunner;
+declare function getCurrentSuite<ExtraContext = object>(): SuiteCollector<ExtraContext>;
+//#endregion
+//#region src/vendored/runtime/runner/artifact.d.ts
+/**
+ * @experimental
+ * @advanced
+ *
+ * Records a custom test artifact during test execution.
+ *
+ * This function allows you to attach structured data, files, or metadata to a test.
+ *
+ * Vitest automatically injects the source location where the artifact was created and manages any attachments you include.
+ *
+ * **Note:** artifacts must be recorded before the task is reported. Any artifacts recorded after that will not be included in the task.
+ *
+ * @param task - The test task context, typically accessed via `this.task` in custom matchers or `context.task` in tests
+ * @param artifact - The artifact to record. Must extend {@linkcode TestArtifactBase}
+ *
+ * @returns A promise that resolves to the recorded artifact with location injected
+ *
+ * @throws {Error} If the test runner doesn't support artifacts
+ *
+ * @example
+ * ```ts
+ * // In a custom assertion
+ * async function toHaveValidSchema(this: MatcherState, actual: unknown) {
+ *   const validation = validateSchema(actual)
+ *
+ *   await recordArtifact(this.task, {
+ *     type: 'my-plugin:schema-validation',
+ *     passed: validation.valid,
+ *     errors: validation.errors,
+ *   })
+ *
+ *   return { pass: validation.valid, message: () => '...' }
+ * }
+ * ```
+ */
+declare function recordArtifact<Artifact extends TestArtifact>(task: Test, artifact: Artifact): Promise<Artifact>;
+//#endregion
+//#region src/vendored/runtime/runner/run.d.ts
+declare function startTests(specs: string[] | FileSpecification[], runner: VitestRunner): Promise<File[]>;
+//#endregion
+//#region src/vendored/runtime/runner/collect.d.ts
+declare function collectTests(specs: string[] | FileSpecification[], runner: VitestRunner): Promise<File[]>;
+//#endregion
+//#region src/expect.d.ts
+/**
+ * `expect` assembled from the pure-JS `@vitest/expect` package.
+ *
+ * Per req 1.2 we reuse vitest's matcher implementations rather than rolling
+ * our own: chai is augmented with `JestExtend` (enables `expect.extend`) and
+ * `JestChaiExpect` (the `toBe` / `toEqual` / `toThrow` / … matcher set), then
+ * we expose chai's `expect` entry point.
+ *
+ * NOTE (v1 scope): asymmetric matchers (`expect.any`, …), `expect.soft`,
+ * `expect.poll` and snapshot matchers are not wired up yet — they can be
+ * layered on by porting vitest's `createExpect` once the core run loop is in
+ * place.
+ */
+declare const expect: Chai.ExpectStatic;
+//#endregion
+//#region src/reporter/blob-report.d.ts
+interface BlobReportInput {
+  /** The runner task tree (`File[]` returned by `startTests`). */
+  files: unknown[];
+  /** Unhandled errors collected during the run. */
+  errors?: unknown[];
+  /** Total wall-clock execution time, ms. */
+  executionTime: number;
+}
+/**
+ * Serialize a blob report payload, byte-for-byte compatible with what
+ * Vitest's own BlobReporter would write (modulo the empty coverage / module
+ * graph fields described above).
+ */
+declare function serializeBlobReport(input: BlobReportInput): string;
+interface WriteBlobReportOptions extends BlobReportInput {
+  /** Report root, e.g. `<external.writeablePath>/inflight-test-report`. */
+  reportRoot: string;
+  /** Pre-computed run id; defaults to a fresh local-time id. */
+  runId?: string;
+}
+interface WrittenReport {
+  /** Absolute path of this run's directory. */
+  runDir: string;
+  /** Absolute path of the written `report.blob`. */
+  blobPath: string;
+  runId: string;
+}
+/**
+ * Write `<reportRoot>/<run-id>/report.blob` via the injected {@link ReportIo}.
+ * Returns the resolved paths (the run dir is surfaced to the user on the
+ * end-of-run summary — req 4.3).
+ */
+declare function writeBlobReport(io: ReportIo, options: WriteBlobReportOptions): WrittenReport;
+//#endregion
+//#region src/page/screenshot.d.ts
+interface CaptureScreenshotOptions {
+  bridge: ActivityBridge;
+  io: ReportIo;
+  /** Absolute run directory; screenshots land in `<runDir>/screenshots/`. */
+  runDir: string;
+  /** File name within `screenshots/`, e.g. `<test-id>__<name>.png`. */
+  fileName: string;
+  /** Region to capture; defaults to the full `window.screen`. */
+  clip?: CaptureRect;
+  timeoutMs?: number;
+}
+interface CapturedScreenshot {
+  /** Path relative to the run directory — stored on the artifact (req 5.5). */
+  relativePath: string;
+  /** Absolute path written. */
+  absolutePath: string;
+  /** The PNG bytes. */
+  bytes: Uint8Array;
+}
+declare function captureScreenshot(options: CaptureScreenshotOptions): Promise<CapturedScreenshot>;
+//#endregion
+//#region src/page/simulated-bridge.d.ts
+/** A minimal valid 1×1 transparent PNG, used as the default rendered frame. */
+declare const TINY_PNG: Uint8Array;
+interface SimulatedScreenshotHostOptions {
+  /** Produce PNG bytes for a capture request. Default: {@link TINY_PNG}. */
+  render?: (req: CaptureScreenRequest) => Uint8Array;
+  /**
+   * The host writes its PNG into this ReportIo and replies with its `savePath`
+   * (exercising the os.read copy path). Pass the SAME ReportIo the screenshot
+   * reader uses so the round-trip closes. Required for a successful capture.
+   */
+  io?: ReportIo;
+  /** Temp directory the host writes into (with `io`). Default `/pandora-capture-tmp`. */
+  tempDir?: string;
+  /** Simulate a failed capture — reply with an empty `savePath`. */
+  fail?: boolean;
+  /** Reply latency in ms (default 0 — replies on a microtask). */
+  latencyMs?: number;
+}
+type Handler = (payload: unknown) => void;
+declare class SimulatedActivityBridge implements ActivityBridge {
+  private readonly _handlers;
+  private readonly _host;
+  private _seq;
+  /** Records every callGame for assertions. */
+  readonly calls: {
+    protocol: string;
+    payload: unknown;
+  }[];
+  constructor(host?: SimulatedScreenshotHostOptions);
+  callGame(protocol: string, payload: unknown): void;
+  onSDKMessage(protocol: string, handler: Handler): () => void;
+  /** Emit a host → activity message to all current subscribers. */
+  emit(protocol: string, payload: unknown): void;
+  private _handleCapture;
+}
+//#endregion
+//#region ../shared-client/dist/create-page-api-BxBu-Q5N.d.ts
+type TypedArrayKind = 'i8' | 'ui8' | 'ui8c' | 'i16' | 'ui16' | 'i32' | 'ui32' | 'f32' | 'f64' | 'bi64' | 'bui64';
+//#endregion
+//#region src/serialized-value.d.ts
+/**
+ * Tagged union for serialized values.
+ *
+ * Primitives (boolean, number, string) pass through as-is since they're
+ * already JSON-safe. Special types get a discriminated wrapper object.
+ *
+ * @see Playwright SerializedValue in utilityScriptSerializers.ts
+ */
+type SerializedValue = undefined | boolean | number | string | {
+  v: 'null' | 'undefined' | 'NaN' | 'Infinity' | '-Infinity' | '-0';
+} | {
+  d: string;
+} | {
+  u: string;
+} | {
+  bi: string;
+} | {
+  e: {
+    n: string;
+    m: string;
+    s: string;
+  };
+} | {
+  r: {
+    p: string;
+    f: string;
+  };
+} | {
+  a: SerializedValue[];
+  id: number;
+} | {
+  o: {
+    k: string;
+    v: SerializedValue;
+  }[];
+  id: number;
+} | {
+  ref: number;
+} | {
+  h: number;
+} | {
+  ta: {
+    b: string;
+    k: TypedArrayKind;
+  };
+} | {
+  ab: {
+    b: string;
+  };
+};
+/**
+ * Optional transform applied to Error `.stack` strings during deserialization.
+ *
+ * On the Node.js side, this is used to normalize PixUI engine stack traces
+ * to V8-compatible format with source map resolution — the same transform
+ * applied to `ConsoleMessage.origin` and `SerializedError.stack`.
+ */
+//#endregion
+//#region src/evaluate-args.d.ts
+/**
+ * Evaluate-arg payload travelling across the RPC boundary.
+ *
+ * Ship both fields as ordinary birpc arguments — the `SerializedValue` tree
+ * is already JSON-safe, so birpc's own serialiser passes it through
+ * symmetrically on both sides.
+ */
+interface EvaluateArg {
+  /** Tagged-union tree with `{ h: N }` slots standing in for handles. */
+  readonly value: SerializedValue;
+  /** Ordered handle IDs: `value`'s `{ h: N }` slots index into this array. */
+  readonly handles: readonly string[];
+}
+/** An empty payload, for call-sites that pass no argument at all. */
+/**
+ * Minimal element reference returned by selector queries.
+ *
+ * Playwright has `ElementHandle` — a behavior-carrying class with 30+
+ * DOM methods (click, fill, getAttribute, boundingBox, etc.). The
+ * Locator resolves a selector → ElementHandle, then delegates to the
+ * handle's methods. However, Playwright themselves now **discourage**
+ * ElementHandle in favor of the Locator-first API.
+ *
+ * We skip the ElementHandle layer entirely. Our Locator directly calls
+ * bridge RPC methods with element ID strings — there is no intermediate
+ * behavior-carrying object. This is a deliberate design choice aligned
+ * with Playwright's Locator-first direction, not a technical limitation.
+ *
+ * `ResolvedElement` is a plain DTO carrying the element's ID (from the
+ * client-side element map) plus `isVisible` — the one property needed
+ * for the Locator's pre-filtering (visibility) and strict mode checks,
+ * avoiding an extra RPC round-trip per element during selector resolution.
+ *
+ * @see Playwright dom.ts ElementHandle — deprecated in favor of Locator
+ * @see Playwright frames.ts _callOnElementOnceMatches
+ */
+interface ResolvedElement {
+  id: string;
+  isVisible: boolean;
+}
+/** Actionability states, matching Playwright's ElementState. */
+type ElementState = 'visible' | 'stable' | 'enabled' | 'editable' | 'receivesEvents';
+/**
+ * Encoded string-or-regex expectation, mirroring Playwright's
+ * `channels.ExpectedTextValue`. Regex instances are never sent over the
+ * wire; they are decomposed into `regexSource` + `regexFlags` and
+ * reconstructed on the client side.
+ *
+ * @see Playwright packages/isomorphic/expectUtils.ts serializeExpectedTextValues
+ */
+interface ExpectedTextValue {
+  string?: string | undefined;
+  regexSource?: string | undefined;
+  regexFlags?: string | undefined;
+  /** Match a substring of the received value instead of the whole value. */
+  matchSubstring?: boolean | undefined;
+  /** Collapse runs of whitespace before comparing (used by `toHaveText`). */
+  normalizeWhiteSpace?: boolean | undefined;
+  ignoreCase?: boolean | undefined;
+}
+/**
+ * All supported expect expressions. Exactly mirrors the subset of
+ * Playwright's `FrameExpectParams.expression` values that the PixUI
+ * DOM subset can implement.
+ *
+ * @see Playwright packages/injected/src/injectedScript.ts expectSingleElement
+ */
+type ExpectExpression = 'to.be.attached' | 'to.be.detached' | 'to.be.visible' | 'to.be.hidden' | 'to.be.enabled' | 'to.be.disabled' | 'to.be.editable' | 'to.be.readonly' | 'to.be.empty' | 'to.be.checked' | 'to.be.focused' | 'to.have.attribute' | 'to.have.attribute.value' | 'to.have.class' | 'to.have.count' | 'to.have.css' | 'to.have.id' | 'to.have.property' | 'to.have.text' | 'to.have.value';
+/**
+ * Parameters for a single `pageExpect` RPC call.
+ *
+ * The client runs one assertion tick per call and returns the result;
+ * the host-side polling loop (`src/expect-runner.ts`) decides whether
+ * to retry.
+ *
+ * @see Playwright packages/playwright-core/src/client/types.ts FrameExpectParams
+ */
+interface ExpectParams {
+  expression: ExpectExpression;
+  /** Inverted match — mirrors Playwright's `options.isNot`. */
+  isNot: boolean;
+  /**
+   * Extra identifier for the attribute / CSS property / JS property
+   * being checked (e.g. `"href"` for `to.have.attribute.value`).
+   */
+  expressionArg?: string | undefined;
+  /** Encoded string/regex expectation(s) — array for text-like matchers. */
+  expectedText?: ExpectedTextValue[] | undefined;
+  /** Numeric expectation — used by `to.have.count`. */
+  expectedNumber?: number | undefined;
+  /** Arbitrary JSON-serializable expectation — used by `to.have.property`. */
+  expectedValue?: unknown;
+  /**
+   * Optional nth-index to slice the resolved element list after selector
+   * resolution — mirrors `Locator.first()/.last()/.nth(n)`. `null` means
+   * strict mode: exactly one element must match (matchers targeting
+   * element arrays like `to.have.count` always ignore this).
+   */
+  nthIndex?: number | null | undefined;
+}
+/**
+ * Result of a single `pageExpect` tick.
+ *
+ * - `matches`: whether the condition held on this tick.
+ * - `received`: the actual value observed (e.g. the element's text, a
+ *   CSS property value, or a count) — used by the host-side matcher for
+ *   the failure diff.
+ * - `log`: human-readable breadcrumbs from the client tick, echoed into
+ *   the final matcher error.
+ * - `errorMessage`: a message for unrecoverable failures (e.g. strict
+ *   mode violation). When set, the host matcher stops polling immediately.
+ * - `missingReceived`: true when the element was not found — so the
+ *   matcher can distinguish "element gone" from "element present but
+ *   value mismatched" in the failure message.
+ */
+interface ExpectResult {
+  matches: boolean;
+  received?: unknown;
+  log?: string[] | undefined;
+  errorMessage?: string | undefined;
+  missingReceived?: boolean | undefined;
+}
+/** Functions exposed by __pxemu on the client side (callable via bridge RPC from the host) */
+interface PageFunctions {
+  querySelectorCustom(selector: string, testIdAttribute: string): ResolvedElement[];
+  querySelectorAll(selector: string): ResolvedElement[];
+  querySelector(selector: string): ResolvedElement | null;
+  getBoundingRect(elementId: string): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null;
+  isElementVisible(elementId: string): boolean;
+  isElementEnabled(elementId: string): boolean;
+  isElementEditable(elementId: string): boolean;
+  getElementAttribute(elementId: string, name: string): string | null;
+  getElementTextContent(elementId: string): string | null;
+  getElementInnerHTML(elementId: string): string;
+  getElementTag(elementId: string): string | null;
+  isElementChecked(elementId: string): boolean;
+  focusElement(elementId: string): 'done' | 'error:notconnected';
+  blurElement(elementId: string): 'done' | 'error:notconnected';
+  getDomTree(): ResolvedElement[];
+  configure(config: {
+    testIdAttribute?: string;
+  }): boolean;
+  /**
+   * Evaluate a function (or plain expression) in the page context and
+   * return its value by JSON-serialization.
+   *
+   * If the evaluation returns a Promise, it is awaited.
+   *
+   * @see shared/evaluate-args.ts
+   * @see Playwright Frame.evaluateExpression
+   */
+  evaluate(expression: string, arg: EvaluateArg): unknown;
+  /**
+   * Evaluate a function against all matching elements and return the
+   * result. The function's first argument is an array of the resolved
+   * Elements; the extra `arg` follows the same handle-aware serialization
+   * protocol as `evaluate`.
+   *
+   * @see Playwright Frame.$$eval
+   */
+  evaluateAll(expression: string, elementIds: string[], arg: EvaluateArg): unknown;
+  /**
+   * Evaluate a function in the page context and return a handle descriptor
+   * for the result, matching Playwright's `evaluateHandle`. The `arg`
+   * follows the same handle-aware serialization protocol as `evaluate`.
+   *
+   * Returns `null` when the value is null/undefined — the host wraps it
+   * in a local null-handle rather than wasting an entry in the handle map.
+   *
+   * @see Playwright Frame.evaluateExpressionHandle
+   */
+  evaluateHandle(expression: string, arg: EvaluateArg): {
+    id: string;
+    type: string;
+  } | null;
+  /**
+   * Evaluate a function against a single resolved element, matching
+   * Playwright's `Frame.evalOnSelector`. The resolved element is passed
+   * as the first positional argument to the function; the `arg` payload
+   * follows the same handle-aware protocol as `evaluate`.
+   *
+   * Returns `'error:notconnected'` when the element has detached so
+   * `Locator._retryWithSelectorResolution` can re-resolve.
+   *
+   * @see Playwright Frame.evalOnSelector
+   */
+  evalOnSelector(elementId: string, expression: string, arg: EvaluateArg): unknown;
+  /**
+   * Evaluate a function against a single resolved element and return a
+   * handle descriptor, matching Playwright's `Frame.evalOnSelectorHandle`.
+   *
+   * @see Playwright Frame.evalOnSelectorHandle
+   */
+  evalOnSelectorHandle(elementId: string, expression: string, arg: EvaluateArg): {
+    id: string;
+    type: string;
+  } | null | 'error:notconnected';
+  /**
+   * Evaluate a function with a handle's target value as its first argument.
+   * Returns the result by value. The `arg` payload follows the same
+   * handle-aware protocol as `evaluate`.
+   *
+   * @see Playwright JSHandleChannel.evaluateExpression
+   */
+  handleEvaluate(handleId: string, expression: string, arg: EvaluateArg): unknown;
+  /**
+   * Evaluate a function with a handle's target value as its first argument.
+   * Returns a new handle descriptor (or `null` for nullish results).
+   *
+   * @see Playwright JSHandleChannel.evaluateExpressionHandle
+   */
+  handleEvaluateHandle(handleId: string, expression: string, arg: EvaluateArg): {
+    id: string;
+    type: string;
+  } | null;
+  /**
+   * Get the JSON-serializable value of a handle.
+   *
+   * @see Playwright JSHandleChannel.jsonValue
+   * @see vitest-playwright-bridge BridgeHandleServerMethods.jsonValue
+   */
+  handleJsonValue(handleId: string): unknown;
+  /**
+   * Get a handle to a named property of a handle's value.
+   *
+   * @see Playwright JSHandleChannel.getProperty
+   * @see vitest-playwright-bridge BridgeHandleServerMethods.getProperty
+   */
+  handleGetProperty(handleId: string, propertyName: string): {
+    id: string;
+    type: string;
+  } | null;
+  /**
+   * Get handles to all enumerable own properties of a handle's value.
+   * Returns an array of {key, id, type} entries.
+   *
+   * @see Playwright JSHandleChannel.getPropertyList
+   * @see vitest-playwright-bridge BridgeHandleServerMethods.getProperties
+   */
+  handleGetProperties(handleId: string): Array<{
+    key: string;
+    id: string;
+    type: string;
+  }>;
+  /**
+   * Release a handle, removing it from the client-side handle map.
+   * The referenced JS value becomes eligible for garbage collection.
+   *
+   * @see Playwright JSHandleChannel.dispose
+   * @see vitest-playwright-bridge BridgeHandleServerMethods.dispose
+   */
+  handleDispose(handleId: string): void;
+  /**
+   * Run one tick of a Playwright-style auto-retrying assertion entirely
+   * in the page context. The host calls this method repeatedly on a
+   * backoff schedule until either the condition is met or the deadline
+   * passes — see `src/expect-runner.ts` for the polling loop.
+   *
+   * Rationale: executing the DOM assertion in the page avoids a round
+   * trip per observed value (faster convergence) and gives each matcher
+   * access to the full DOM API (`HTMLInputElement.value`,
+   * `document.activeElement`, `getComputedStyle`, …) with native
+   * TypeScript DOM types at author time — see `client/page-expect.ts`.
+   *
+   * @see Playwright packages/playwright-core/src/server/frames.ts Frame.expect
+   */
+  pageExpect(selector: string | null, testIdAttribute: string, params: ExpectParams): ExpectResult;
+  /**
+   * Check actionability states on an element entirely in the page context.
+   *
+   * This mirrors Playwright's injectedScript.checkElementStates().
+   * Stable uses real requestAnimationFrame. All checks operate on the
+   * same element instance, avoiding the race condition of re-resolving
+   * elements between RPC round-trips.
+   *
+   * @returns `{ passed: true }` if all states pass, or `{ missingState }` for
+   *          the first state that failed.
+   */
+  checkElementStates(elementId: string, states: ElementState[]): Promise<{
+    passed: true;
+  } | {
+    missingState: ElementState;
+  }>;
+  /**
+   * Scroll the element into the visible area of the viewport if needed.
+   *
+   * This mirrors Playwright's scroll-into-view step performed between
+   * actionability checks and the actual input action.
+   *
+   * @see https://playwright.dev/docs/api/class-locator#locator-scroll-into-view-if-needed
+   */
+  scrollIntoViewIfNeeded(elementId: string): 'done' | 'error:notconnected';
+  /**
+   * Release element references by ID, allowing GC on the client side.
+   *
+   * This is for the element map (DOM elements resolved by selectors).
+   * For arbitrary JS value handles, use `handleDispose()` instead.
+   *
+   * @see Playwright Runtime.releaseObject (WebKit) / Runtime.disposeObject (Firefox)
+   */
+  releaseElements(elementIds: string[]): void;
+  /**
+   * Prune detached elements from the client-side element map and enforce
+   * a max-size cap. Returns the number of entries removed.
+   *
+   * Mirrors Playwright's dispatcher GC-bucket overflow protection
+   * (maybeDisposeStaleDispatchers) which caps ElementHandle dispatchers
+   * at 100k and evicts the oldest 10% on overflow.
+   *
+   * Called automatically before each querySelectorCustom on the client,
+   * but can also be called explicitly from the host for manual cleanup.
+   */
+  pruneDetachedElements(): number;
+  /**
+   * Prepare the page for a deterministic screenshot.
+   *
+   * Applies temporary visual changes (e.g. hiding carets) and stores
+   * a cleanup function so `restoreScreenshot()` can undo them.
+   *
+   * Ported from Playwright's `Screenshotter._preparePageForScreenshot()`.
+   */
+  prepareScreenshot(options: {
+    hideCaret: boolean;
+  }): void;
+  /**
+   * Undo visual changes applied by `prepareScreenshot()`.
+   *
+   * Ported from Playwright's `Screenshotter._restorePageAfterScreenshot()`.
+   */
+  restoreScreenshot(): void;
+  /** Append a log entry for navigation replay. */
+  clockLog(type: string, time: number, param?: number): void;
+  /** Inject fake clock infrastructure without setting time. */
+  clockInject(): void;
+  /** Install fake clock and set initial time. */
+  clockInstall(timeMs: number): void;
+  /** Advance clock, firing all due timers. */
+  clockRunFor(ticksMs: number): Promise<void>;
+  /** Jump forward in time, firing due timers at most once. */
+  clockFastForward(ticksMs: number): Promise<void>;
+  /** Jump to a specific time and pause. */
+  clockPauseAt(timeMs: number): Promise<number>;
+  /** Resume real-time progression. */
+  clockResume(): void;
+  /** Set a fixed time for Date.now() / new Date(). */
+  clockSetFixedTime(timeMs: number): void;
+  /** Set system time without triggering timers. */
+  clockSetSystemTime(timeMs: number): void;
+  /** Uninstall fake clock, restoring native globals. */
+  clockUninstall(): void;
+}
+/**
+ * Shared interface for bridge RPC callers.
+ *
+ * Both `DevtoolsBridge` (server-side, direct birpc) and `ControlClient`
+ * (worker-side, proxied via control channel) implement this interface.
+ * Consumers like `JSHandle` and `Locator` depend on this interface
+ * instead of a concrete class, so they work in both server and worker
+ * contexts.
+ *
+ * @see DevtoolsBridge.call — server-side implementation
+ * @see ControlClient.call — worker-side proxy implementation
+ */
+interface BridgeClient {
+  /** Whether both devtools + bridge channels are connected. */
+  readonly connected: boolean;
+  /** Type-safe RPC call to a page function. */
+  call<M extends keyof PageFunctions>(method: M, ...args: Parameters<PageFunctions[M]>): Promise<ReturnType<PageFunctions[M]>>;
+}
+/** Functions exposed by the host to the client (callable via birpc from the page) */
+//#endregion
+//#region ../shared-client/dist/index.d.ts
+//#endregion
+//#region src/options.d.ts
+/** Timeout option accepted by most Locator methods. Matches Playwright's TimeoutOptions. */
+interface TimeoutOptions {
+  timeout?: number | undefined;
+}
+interface ClickOptions {
+  button?: string | undefined;
+  clickCount?: number | undefined;
+  delay?: number | undefined;
+  /** Skip actionability checks. */
+  force?: boolean | undefined;
+  /** Maximum time in milliseconds. Pass `0` to disable timeout. */
+  timeout?: number | undefined;
+  /** Click at a specific position relative to the element's top-left corner. */
+  position?: {
+    x: number;
+    y: number;
+  } | undefined;
+  /** Perform all actionability checks but skip the actual action. */
+  trial?: boolean | undefined;
+}
+interface HoverOptions {
+  /** Skip actionability checks. */
+  force?: boolean | undefined;
+  /** Maximum time in milliseconds. Pass `0` to disable timeout. */
+  timeout?: number | undefined;
+  /** Hover at a specific position relative to the element's top-left corner. */
+  position?: {
+    x: number;
+    y: number;
+  } | undefined;
+  /** Perform all actionability checks but skip the actual action. */
+  trial?: boolean | undefined;
+}
+interface MouseOptions {
+  button?: string | undefined;
+  isDown?: boolean | undefined;
+}
+interface DragOptions {
+  steps?: number | undefined;
+  stepDelay?: number | undefined;
+  /** Skip actionability checks. */
+  force?: boolean | undefined;
+  /** Maximum time in milliseconds. */
+  timeout?: number | undefined;
+  /** Perform all actionability checks but skip the actual action. */
+  trial?: boolean | undefined;
+}
+interface TapOptions {
+  delay?: number | undefined;
+  /** Skip actionability checks. */
+  force?: boolean | undefined;
+  /** Maximum time in milliseconds. */
+  timeout?: number | undefined;
+  /** Click at a specific position relative to the element's top-left corner. */
+  position?: {
+    x: number;
+    y: number;
+  } | undefined;
+  /** Perform all actionability checks but skip the actual action. */
+  trial?: boolean | undefined;
+}
+interface SwipeOptions {
+  steps?: number | undefined;
+  stepDelay?: number | undefined;
+  /** Skip actionability checks. */
+  force?: boolean | undefined;
+  /** Maximum time in milliseconds. */
+  timeout?: number | undefined;
+}
+interface LongPressOptions {
+  duration?: number | undefined;
+  /** Skip actionability checks. */
+  force?: boolean | undefined;
+  /** Maximum time in milliseconds. */
+  timeout?: number | undefined;
+  /** Press at a specific position relative to the element's top-left corner. */
+  position?: {
+    x: number;
+    y: number;
+  } | undefined;
+}
+interface PressOptions {
+  delay?: number | undefined;
+}
+interface TypeOptions {
+  delay?: number | undefined;
+}
+interface ScreenshotOptions {
+  path?: string | undefined;
+  timeout?: number | undefined;
+  /**
+   * Clip the screenshot to a specific region of the viewport.
+   *
+   * Coordinates are in CSS pixels relative to the top-left corner of the
+   * viewport.  Typically obtained from an element's `boundingRect` (via
+   * `locator.boundingBox()`).
+   */
+  clip?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | undefined;
+  /**
+   * Whether to hide the text input caret during the screenshot.
+   *
+   * - `'hide'` (default): set `caret-color: transparent !important` on all
+   *   `input` and `textarea` elements before capture,
+   *   then restore original values.
+   * - `'initial'`: leave carets as-is.
+   */
+  caret?: 'hide' | 'initial' | undefined;
+}
+interface FillOptions {
+  /** Skip actionability checks. */
+  force?: boolean | undefined;
+  /** Maximum time in milliseconds. */
+  timeout?: number | undefined;
+} //#endregion
+//#region src/progress.d.ts
+/**
+ * Progress — Port of Playwright's Progress/ProgressController.
+ *
+ * Provides centralized timeout management, cooperative cancellation,
+ * and structured call logging for all retry loops (selector resolution,
+ * action retries, waitFor).
+ *
+ * Lives in shared-client because the Locator retry loops depend on it and
+ * must run unchanged in both the Node (emulator) and QuickJS (inflight)
+ * runtimes. It is pure async-control logic — `AbortController`, `setTimeout`,
+ * and Promises — with no Node builtins.
+ *
+ * @see Playwright packages/playwright-core/src/server/progress.ts
+ * @see Playwright packages/playwright-core/src/server/callLog.ts
+ */
+/**
+ * A progress token passed to retry loops and action callbacks.
+ *
+ * Each method that takes a Progress must result in one of three outcomes:
+ *   - It finishes successfully, returning a value, before the Progress is aborted.
+ *   - It throws some error, before the Progress is aborted.
+ *   - It throws the Progress's aborted error, because the Progress was aborted
+ *     before the method could finish.
+ *
+ * @see Playwright Progress interface in packages/protocol/src/progress.d.ts
+ */
+//#endregion
+//#region src/evaluate-types.d.ts
+/**
+ * Evaluate-family type system (runtime-agnostic, type-only).
+ *
+ * These types describe the `evaluate` / `evaluateHandle` argument and return
+ * shapes shared by the host driver (`Locator`) and the emulator's `JSHandle`.
+ * They carry ZERO runtime code, so the shared barrel that re-exports them has
+ * no module-load side effects — which is exactly what lets the in-page IIFE
+ * and the inflight bundle import from the package root without dragging in the
+ * emulator-only `JSHandle` (whose `FinalizationRegistry` the PixUI QuickJS
+ * runtime cannot construct).
+ *
+ * The concrete `JSHandle` class lives in `@pixui-dev/emulator-core` (it is an
+ * emulator-only host feature). `JSHandleLike` is the structural surface the
+ * shared `Locator.evaluateHandle` returns and that `Unboxed` uses to see
+ * through handles passed as `evaluate` arguments.
+ *
+ * @see Playwright packages/playwright-core/types/structs.d.ts (Unboxed, PageFunctionOn)
+ */
+/**
+ * Structural surface of a host-side JS handle.
+ *
+ * The emulator's `JSHandle` satisfies this shape; the shared `Locator` returns
+ * it from `evaluateHandle` (constructed via the injected `PageHost.wrapHandle`
+ * seam) without importing the concrete class. Deliberately omits
+ * `getProperty`/`getProperties` (which return the concrete handle on the
+ * emulator) so the interface stays a clean structural supertype of `JSHandle`
+ * — avoiding `Map` invariance pitfalls — while still typing the members
+ * callers actually use on a locator-derived handle.
+ *
+ * @see Playwright JSHandle (client-side)
+ */
+interface JSHandleLike<T = unknown> {
+  /** Brand used by {@link Unboxed} to recognise handles in argument positions. */
+  readonly __brand: '@pixui-dev/emulator JSHandle';
+  /** JS `typeof` the referenced value (for debugging/preview). */
+  readonly type: string;
+  /** Whether this handle has been disposed. */
+  readonly disposed: boolean;
+  /** Evaluate a function with this handle's value as the first argument. */
+  evaluate<R, Arg, O extends T = T>(pageFunction: PageFunctionOn<O, Arg, R>, arg: Arg): Promise<R>;
+  evaluate<R, O extends T = T>(pageFunction: PageFunctionOn<O, void, R>, arg?: unknown): Promise<R>;
+  /** Evaluate a function with this handle's value, returning a new handle. */
+  evaluateHandle<R, Arg, O extends T = T>(pageFunction: PageFunctionOn<O, Arg, R>, arg: Arg): Promise<JSHandleLike<R>>;
+  evaluateHandle<R, O extends T = T>(pageFunction: PageFunctionOn<O, void, R>, arg?: unknown): Promise<JSHandleLike<R>>;
+  /** Get the JSON-serializable value of this handle. */
+  jsonValue(): Promise<T>;
+  /** Explicitly release this handle. */
+  dispose(): Promise<void>;
+}
+/**
+ * Recursively unwrap `JSHandleLike<T>` → `T` in type positions.
+ *
+ * This is the core of the Box/Unbox type system, letting
+ * `handle.evaluate((el, arg) => ...)` infer the in-page types for `el`/`arg`:
+ *   - `JSHandleLike<Element>` → `Element`
+ *   - `{ foo: JSHandleLike<string> }` → `{ foo: string }`
+ *   - `[JSHandleLike<number>, string]` → `[number, string]`
+ *   - Plain types pass through unchanged
+ *
+ * Simplified from Playwright's `Unboxed` (no ElementHandle, no 4-tuple cases) —
+ * we only have one handle kind.
+ *
+ * @see Playwright structs.d.ts Unboxed
+ */
+type Unboxed<Arg> = Arg extends JSHandleLike<infer T> ? T : Arg extends [infer A0, ...infer Rest] ? [Unboxed<A0>, ...{ [K in keyof Rest]: Unboxed<Rest[K]> }] : Arg extends Array<infer T> ? Array<Unboxed<T>> : Arg extends object ? { [Key in keyof Arg]: Unboxed<Arg[Key]> } : Arg;
+/**
+ * Function type for `evaluate` / `evaluateHandle` on a handle or element.
+ *
+ * `On` is the type of the target value (first argument). `Arg` is the extra
+ * argument (second argument), unwrapped via {@link Unboxed}. `R` is the return
+ * type. Accepts either a string expression or a function.
+ *
+ * @see Playwright structs.d.ts PageFunctionOn
+ */
+type PageFunctionOn<On, Arg, R> = string | ((on: On, arg: Unboxed<Arg>) => R | Promise<R>);
+/**
+ * Function type for page-level `evaluate` (no "on" target).
+ *
+ * @see Playwright structs.d.ts PageFunction
+ */
+//#endregion
+//#region src/input-backend.d.ts
+interface InputBackend {
+  click(x: number, y: number, options?: ClickOptions): Promise<void>;
+  move(x: number, y: number, options?: MouseOptions): Promise<void>;
+  down(x: number, y: number, options?: MouseOptions): Promise<void>;
+  up(x: number, y: number, options?: MouseOptions): Promise<void>;
+  wheel(x: number, y: number, deltaY: number, deltaX: number): Promise<void>;
+  tap(x: number, y: number, options?: TapOptions): Promise<void>;
+  swipe(fromX: number, fromY: number, toX: number, toY: number, options?: SwipeOptions): Promise<void>;
+  longPress(x: number, y: number, options?: LongPressOptions): Promise<void>;
+  press(key: string, options?: PressOptions): Promise<void>;
+  keyDown(key: string): Promise<void>;
+  keyUp(key: string): Promise<void>;
+  typeText(text: string, options?: TypeOptions): Promise<void>;
+} //#endregion
+//#region src/input.d.ts
+/**
+ * Context object passed to input classes, providing the atomic input
+ * backend plus the two page-level hooks the devices need (closed-state
+ * assertion and post-action frame settling).
+ */
+interface InputContext {
+  backend: InputBackend;
+  assertNotClosed(): void;
+  waitForFrame(): Promise<unknown>;
+}
+declare class Mouse {
+  /** @internal */
+  readonly _ctx: InputContext;
+  constructor(ctx: InputContext);
+  click(x: number, y: number, options?: ClickOptions): Promise<void>;
+  dblclick(x: number, y: number, options?: ClickOptions): Promise<void>;
+  move(x: number, y: number, options?: MouseOptions): Promise<void>;
+  down(x: number, y: number, options?: MouseOptions): Promise<void>;
+  up(x: number, y: number, options?: MouseOptions): Promise<void>;
+  wheel(x: number, y: number, deltaY: number, deltaX?: number): Promise<void>;
+}
+declare class Touchscreen {
+  /** @internal */
+  readonly _ctx: InputContext;
+  constructor(ctx: InputContext);
+  tap(x: number, y: number, options?: TapOptions): Promise<void>;
+  /** PixUI extension: swipe gesture. */
+  swipe(fromX: number, fromY: number, toX: number, toY: number, options?: SwipeOptions): Promise<void>;
+  /** PixUI extension: long press gesture. */
+  longPress(x: number, y: number, options?: LongPressOptions): Promise<void>;
+}
+declare class Keyboard {
+  /** @internal */
+  readonly _ctx: InputContext;
+  constructor(ctx: InputContext);
+  press(key: string, options?: PressOptions): Promise<void>;
+  down(key: string): Promise<void>;
+  up(key: string): Promise<void>;
+  type(text: string, options?: TypeOptions): Promise<void>;
+  insertText(text: string): Promise<void>;
+} //#endregion
+//#region src/page-host.d.ts
+interface PageHost {
+  /** Bridge for DOM introspection RPCs, or `null` when not connected. */
+  readonly devtoolsBridge: BridgeClient | null;
+  /** The configured test ID attribute name (e.g. `data-testid`). */
+  readonly testIdAttribute: string;
+  /** Mouse input device. */
+  readonly mouse: Mouse;
+  /** Touchscreen input device. */
+  readonly touchscreen: Touchscreen;
+  /** Keyboard input device. */
+  readonly keyboard: Keyboard;
+  /** Whether the page has been closed via `window.close()`. */
+  isClosed(): boolean;
+  /** Whether the page has been disposed. */
+  isDisposed(): boolean;
+  /** Sleep helper used by the action retry loops. */
+  waitForTimeout(ms: number): Promise<void>;
+  /**
+   * Capture a screenshot of the current frame. Returns the encoded PNG
+   * bytes. (The emulator returns a Node `Buffer`, which is a `Uint8Array`;
+   * the inflight backend returns the bytes it read back from the host.)
+   */
+  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+  /**
+   * Subscribe to the page `close` event (window.close()). Returns an
+   * unsubscribe function. Used by Locator to fail fast on close instead of
+   * waiting out the full timeout — without coupling Locator to a concrete
+   * EventEmitter.
+   */
+  onClose(handler: () => void): () => void;
+  /**
+   * Subscribe to the page `disposed` event. Returns an unsubscribe function.
+   */
+  onDisposed(handler: () => void): () => void;
+  /**
+   * Wrap an `evalOnSelectorHandle` RPC result into a host-side JS handle.
+   *
+   * Optional seam: JS handles are an emulator-only feature (the concrete
+   * `JSHandle` class with its `FinalizationRegistry` lives in
+   * `@pixui-dev/emulator-core`, not in this runtime-agnostic layer). The
+   * emulator's `SimulatorPage` implements this; backends without handle
+   * support — notably inflight-test, which runs inside QuickJS and has no
+   * `eval` — omit it, so `Locator.evaluateHandle` throws a clear error there.
+   *
+   * @param result The handle descriptor from the page, or `null` for a
+   *   null/undefined result (wrapped as a host-side null-handle).
+   */
+  wrapHandle?(result: {
+    id: string;
+    type: string;
+  } | null): JSHandleLike<unknown>;
+} //#endregion
+//#region src/locator.d.ts
+/** Options for text-based locator queries. */
+/** Filter options for narrowing locator matches */
+interface LocatorFilterOptions {
+  /** Filter by text content */
+  hasText?: string | RegExp | undefined;
+  /** Filter by NOT having text content */
+  hasNotText?: string | RegExp | undefined;
+}
+interface SwipeTarget {
+  x: number;
+  y: number;
+}
+interface WaitForOptions {
+  /** Timeout in milliseconds (default: 30000) */
+  timeout?: number | undefined;
+  /** Wait for element to reach this state (default: 'visible') */
+  state?: 'attached' | 'detached' | 'visible' | 'hidden' | undefined;
+}
+/**
+ * Defines how a locator resolves its target elements.
+ * The selector is a custom selector string resolved by the bridge client.
+ */
+type LocatorSource = {
+  kind: 'selector';
+  selector: string;
+};
+/**
+ * A Locator represents a way to find one or more elements on the PixUI page.
+ *
+ * Locators are the core primitive for interacting with the page. They are:
+ * - **Lazy**: Elements are resolved at interaction time.
+ * - **Auto-waiting**: Actions automatically wait for elements to appear.
+ * - **Auto-retrying**: Assertions retry until timeout.
+ * - **Strict**: Actions throw if the locator matches more than one element
+ *   (configurable via .first(), .last(), .nth()).
+ */
+declare class Locator {
+  private _page;
+  private _source;
+  private _nthIndex;
+  private _offsetX;
+  private _offsetY;
+  /** Timeout for auto-waiting (ms) */
+  private _timeout;
+  constructor(page: PageHost, source: LocatorSource);
+  /**
+   * The raw selector string.
+   */
+  get selector(): string | null;
+  /**
+   * Create a locator from a CSS selector string.
+   */
+  static fromSelector(page: PageHost, selector: string): Locator;
+  /**
+   * Create a locator by text content.
+   */
+  static fromText(page: PageHost, text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  /**
+   * Create a locator by alt text.
+   */
+  static fromAltText(page: PageHost, text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  /**
+   * Create a locator by label text.
+   */
+  static fromLabelText(page: PageHost, text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  /**
+   * Create a locator by placeholder.
+   */
+  static fromPlaceholder(page: PageHost, text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  /**
+   * Create a locator by title attribute.
+   */
+  static fromTitle(page: PageHost, text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  /**
+   * Create a locator by data-testid attribute.
+   */
+  static fromTestId(page: PageHost, testId: string | RegExp): Locator;
+  /**
+   * Human-readable description of this locator (for error messages).
+   */
+  private get _description();
+  /**
+   * Raw selector query — no retry, no waiting.
+   *
+   * Returns all matching elements, or null if the bridge is not available.
+   * This is the low-level building block used by _retryWithSelectorResolution.
+   *
+   * @see Playwright frames.ts: resolved.injected.evaluateHandle(injected.querySelectorAll)
+   */
+  private _resolveSelector;
+  /**
+   * Run a Playwright-style auto-retrying assertion against this locator.
+   *
+   * The host side is a thin polling loop: it fires `pageExpect` RPCs on
+   * exponential intervals (`[100, 250, 500, 1000]`) until either the
+   * condition holds (`matches !== isNot`) or the deadline passes.
+   * Each tick performs the full selector resolution + DOM check inside
+   * the page, so re-renders between ticks are observed naturally.
+   *
+   * This method is internal — matchers in the vitest plugin call it via
+   * the public barrel export. Not for end-user consumption.
+   *
+   * @see Playwright server/frames.ts Frame.expect — the same two-phase
+   *      (one-shot + retry-with-backoff) loop.
+   * @internal
+   */
+  _expect(params: Omit<ExpectParams, 'nthIndex'>, timeout: number): Promise<ExpectResult>;
+  /**
+   * Pick a single element from the resolved list, applying nth/strict mode.
+   *
+   * Returns the element, or null if no match (caller should retry),
+   * or throws on strict mode violation (non-recoverable).
+   *
+   * @see Playwright frames.ts _retryWithProgressIfNotConnected: strict mode check
+   */
+  private _pickElement;
+  /**
+   * Run a ProgressController task with page close/dispose detection.
+   *
+   * Listens for the page's 'close' and 'disposed' events and aborts the
+   * controller immediately, so pending locator operations fail fast with
+   * a descriptive error instead of waiting for the full timeout.
+   */
+  private _runWithCloseDetection;
+  /**
+   * Outermost retry loop — resolves the selector and passes the element
+   * to an action callback. Re-resolves on 'error:notconnected'.
+   *
+   * This is our equivalent of Playwright's Frame._retryWithProgressIfNotConnected.
+   *
+   * The retry loop uses progressive backoff: [0, 20, 100, 100, 500]ms,
+   * matching Playwright's retryWithProgressAndTimeouts.
+   *
+   * @param action - Callback receiving the resolved element. Must return
+   *                 'error:notconnected' to trigger re-resolution, or any
+   *                 other value as the final result.
+   * @param options - timeout, force (skip visibility pre-filter)
+   * @returns The action's return value (excluding 'error:notconnected')
+   *
+   * @see Playwright frames.ts _retryWithProgressIfNotConnected
+   * @see Playwright frames.ts retryWithProgressAndTimeouts
+   */
+  private _retryWithSelectorResolution;
+  /**
+   * Generic retry wrapper for actions, matching Playwright's `_retryAction`.
+   *
+   * Retries the action callback when it returns a recoverable error code.
+   * Uses progressive backoff: [0, 20, 100, 100, 500]ms between retries.
+   *
+   * Returns 'error:notconnected' to the caller so the outer loop
+   * (_retryWithSelectorResolution) can re-resolve the selector.
+   *
+   * @see Playwright dom.ts ElementHandle._retryAction
+   */
+  private _retryAction;
+  /**
+   * Retry wrapper for pointer actions, matching Playwright's `_retryPointerAction`.
+   *
+   * Wraps `_retryAction` and adds pointer-specific retry logic:
+   * - Cycles through different scroll alignments on each retry to handle
+   *   position:sticky elements that overlay the target.
+   *
+   * Returns 'error:notconnected' to bubble up to _retryWithSelectorResolution.
+   *
+   * @see Playwright dom.ts ElementHandle._retryPointerAction
+   */
+  private _retryPointerAction;
+  /**
+   * Perform a single pointer action attempt. Returns error codes instead
+   * of throwing, letting the retry layers decide.
+   *
+   * Follows Playwright's exact sequence:
+   *   1. Check element states (visible, stable, enabled) — unless force
+   *   2. Scroll into view if needed
+   *   3. Compute action point via _clickablePoint() or _offsetPoint()
+   *   4. Hit target check — PixUI placeholder (always passes)
+   *   5. Perform action — unless trial
+   *
+   * Note: Element resolution is NOT done here — it's done by
+   * _retryWithSelectorResolution, which passes the element ID.
+   *
+   * @see Playwright dom.ts ElementHandle._performPointerAction
+   */
+  private _performPointerAction;
+  /**
+   * Compute the clickable point (center) of an element.
+   * @see Playwright dom.ts ElementHandle._clickablePoint
+   */
+  private _clickablePoint;
+  /**
+   * Compute a point at a specific offset from the element's top-left corner.
+   *
+   * Note: Playwright computes offset relative to the padding box (adds
+   * border width). PixUI uses border-box for all elements, so we compute
+   * relative to the bounding box directly.
+   *
+   * @see Playwright dom.ts ElementHandle._offsetPoint
+   */
+  private _offsetPoint;
+  /**
+   * Fetch a fresh bounding rect for an element from the client side.
+   * @see Playwright dom.ts ElementHandle.boundingBox / getContentQuads
+   */
+  private _getBoundingRect;
+  /**
+   * Scroll the element (or a sub-rect of it) into the visible viewport area.
+   * @see Playwright dom.ts ElementHandle._scrollRectIntoViewIfNeeded
+   */
+  private _scrollRectIntoViewIfNeeded;
+  /**
+   * Resolve the click-target position for this locator.
+   * Public API for getting the element's action point.
+   *
+   * @see Playwright dom.ts _clickablePoint / _offsetPoint
+   */
+  position(relativePosition?: {
+    x: number;
+    y: number;
+  }, options?: TimeoutOptions): Promise<{
+    x: number;
+    y: number;
+  }>;
+  first(): Locator;
+  last(): Locator;
+  nth(index: number): Locator;
+  and(locator: Locator): Locator;
+  or(locator: Locator): Locator;
+  filter(options: LocatorFilterOptions): Locator;
+  locator(selector: string): Locator;
+  getByText(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByAltText(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByLabel(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByPlaceholder(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByTitle(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByTestId(testId: string | RegExp): Locator;
+  offset(dx: number, dy: number): Locator;
+  /**
+   * Click on this locator's element.
+   *
+   * Call chain (matching Playwright):
+   *   Frame._retryWithProgressIfNotConnected(selector, handle => handle._click())
+   *     → ElementHandle._click → _retryPointerAction → _retryAction → _performPointerAction
+   *
+   * Our equivalent:
+   *   _retryWithSelectorResolution(element =>
+   *     _retryPointerAction(element.id, ...) → _retryAction → _performPointerAction)
+   *
+   * @see Playwright frames.ts Frame.click
+   * @see Playwright dom.ts ElementHandle._click
+   */
+  click(options?: ClickOptions): Promise<void>;
+  /**
+   * Double-click on this locator's element.
+   * @see Playwright frames.ts Frame.dblclick
+   * @see Playwright dom.ts ElementHandle._dblclick
+   */
+  dblclick(options?: ClickOptions): Promise<void>;
+  /**
+   * Hover over this locator's element (move mouse to element center).
+   *
+   * @see Playwright dom.ts ElementHandle._hover
+   */
+  hover(options?: HoverOptions): Promise<void>;
+  /**
+   * Scroll the mouse wheel at this locator's element position.
+   */
+  wheel(deltaY: number, deltaX?: number): Promise<void>;
+  /**
+   * Drag from this locator to a target position or locator.
+   * @see Playwright frames.ts Frame.dragAndDrop
+   */
+  dragTo(target: SwipeTarget | Locator, options?: DragOptions): Promise<void>;
+  /**
+   * Tap on this locator's element.
+   * @see Playwright frames.ts Frame.tap
+   * @see Playwright dom.ts ElementHandle._tap
+   */
+  tap(options?: TapOptions): Promise<void>;
+  /**
+   * Swipe from this locator to a target position or locator.
+   * (PixUI extension — not in Playwright; follows dragTo's pattern.)
+   */
+  swipeTo(target: SwipeTarget | Locator, options?: SwipeOptions): Promise<void>;
+  /**
+   * Long press on this locator's element.
+   * (PixUI extension — not in Playwright; follows click's pattern.)
+   */
+  longPress(options?: LongPressOptions): Promise<void>;
+  /**
+   * Click this locator's element, then type text.
+   */
+  type(text: string, options?: TypeOptions): Promise<void>;
+  /**
+   * Click, select all, then insert text (or delete if empty).
+   *
+   * Playwright's fill uses DOM selection APIs (input.select(), Range) to
+   * select existing content, then keyboard.insertText() to replace it.
+   * PixUI lacks DOM selection APIs, so we use Control+A as a fallback.
+   *
+   * @see Playwright dom.ts ElementHandle._fill
+   */
+  fill(text: string, options?: FillOptions): Promise<void>;
+  /**
+   * Click this locator's element, then press a key or key combo.
+   */
+  press(key: string, options?: PressOptions & TimeoutOptions): Promise<void>;
+  /**
+   * Type characters one by one into the element.
+   * Alias for `type()`, matching Playwright's naming.
+   *
+   * @see Playwright Locator.pressSequentially
+   */
+  pressSequentially(text: string, options?: TypeOptions): Promise<void>;
+  /**
+   * Clear the input field.
+   *
+   * @see Playwright Locator.clear
+   */
+  clear(options?: FillOptions): Promise<void>;
+  /**
+   * Focus the element.
+   *
+   * @see Playwright Locator.focus → Frame.focus → ElementHandle._focus
+   */
+  focus(options?: TimeoutOptions): Promise<void>;
+  /**
+   * Remove focus from the element.
+   *
+   * @see Playwright Locator.blur → Frame.blur → ElementHandle._blur
+   */
+  blur(options?: TimeoutOptions): Promise<void>;
+  /**
+   * Returns the number of elements matching this locator.
+   */
+  count(): Promise<number>;
+  /**
+   * Returns all matching elements' serialized data.
+   */
+  all(): Promise<ResolvedElement[]>;
+  /**
+   * Returns an array of all matching elements' `innerText` values.
+   *
+   * @see Playwright Locator.allInnerTexts → $$eval(ee => ee.map(e => e.innerText))
+   */
+  allInnerTexts(): Promise<string[]>;
+  /**
+   * Returns an array of all matching elements' `textContent` values.
+   *
+   * @see Playwright Locator.allTextContents → $$eval(ee => ee.map(e => e.textContent || ''))
+   */
+  allTextContents(): Promise<string[]>;
+  /**
+   * Check if this locator matches any visible element.
+   */
+  isVisible(options?: TimeoutOptions): Promise<boolean>;
+  /**
+   * Check if this locator's element is hidden.
+   */
+  isHidden(options?: TimeoutOptions): Promise<boolean>;
+  /**
+   * Check if this locator's element is enabled.
+   *
+   * @see Playwright frames.ts Frame.isEnabled → _callOnElementOnceMatches
+   */
+  isEnabled(options?: TimeoutOptions): Promise<boolean>;
+  /**
+   * Check if this locator's element is disabled.
+   */
+  isDisabled(options?: TimeoutOptions): Promise<boolean>;
+  /**
+   * Check if this locator's element is editable.
+   */
+  isEditable(options?: TimeoutOptions): Promise<boolean>;
+  /**
+   * Check if this locator's element is checked (for checkboxes/radios).
+   */
+  isChecked(options?: TimeoutOptions): Promise<boolean>;
+  /**
+   * Get the text content of this locator's element.
+   *
+   * @see Playwright frames.ts Frame.textContent → _callOnElementOnceMatches
+   */
+  textContent(options?: TimeoutOptions): Promise<string | null>;
+  /**
+   * Get the inner text of this locator's element.
+   */
+  innerText(options?: TimeoutOptions): Promise<string>;
+  /**
+   * Get the inner HTML of this locator's element.
+   *
+   * @see Playwright frames.ts Frame.innerHTML → _callOnElementOnceMatches
+   */
+  innerHTML(options?: TimeoutOptions): Promise<string>;
+  /**
+   * Get an attribute value from this locator's element.
+   *
+   * @see Playwright frames.ts Frame.getAttribute → _callOnElementOnceMatches
+   */
+  getAttribute(name: string, options?: TimeoutOptions): Promise<string | null>;
+  /**
+   * Returns the bounding box of the element, or `null` if the element is not visible.
+   */
+  boundingBox(options?: TimeoutOptions): Promise<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null>;
+  /**
+   * Wait for this locator's element to reach a certain state.
+   *
+   * Matches Playwright's Frame.waitForSelector which uses
+   * retryWithProgressAndTimeouts with the same backoff pattern.
+   *
+   * @see Playwright frames.ts Frame.waitForSelector
+   */
+  waitFor(options?: WaitForOptions): Promise<void>;
+  /**
+   * Scroll the element into the visible viewport area if needed.
+   *
+   * Uses _retryWithSelectorResolution → _retryAction, matching Playwright's
+   * ElementHandle._waitAndScrollIntoViewIfNeeded → _retryAction.
+   *
+   * @see Playwright dom.ts ElementHandle.scrollIntoViewIfNeeded → _waitAndScrollIntoViewIfNeeded
+   */
+  scrollIntoViewIfNeeded(options?: TimeoutOptions): Promise<void>;
+  /**
+   * Take a screenshot clipped to this element's bounding box.
+   *
+   * Uses _retryWithSelectorResolution → _retryAction, matching Playwright's
+   * Frame.rafrafTimeoutScreenshotElementWithProgress → _retryWithProgressIfNotConnected.
+   *
+   * @see Playwright frames.ts Frame.rafrafTimeoutScreenshotElementWithProgress
+   * @see Playwright dom.ts ElementHandle.screenshot
+   */
+  screenshot(options?: Omit<ScreenshotOptions, 'clip'>): Promise<Uint8Array>;
+  /**
+   * Evaluate a function in the page context with this element as the
+   * first argument.
+   *
+   * The expression is sent to the client-side bridge as a string and
+   * parsed there (matching Playwright's `normalizeEvaluationExpression`
+   * + vitest-playwright-bridge's `parseExpression` pattern). The resolved
+   * element is passed as the function's argument.
+   *
+   * Usage:
+   *   // Arrow function — element is the first arg
+   *   const text = await locator.evaluate<string>('(el) => el.textContent');
+   *
+   *   // With extra arg — [element, arg] is passed
+   *   const attr = await locator.evaluate<string>(
+   *     '([el, name]) => el.getAttribute(name)',
+   *     'data-value',
+   *   );
+   *
+   * @see Playwright Locator.evaluate → Frame.evalOnSelector
+   * @see vitest-playwright-bridge HostHandle.evaluate
+   */
+  evaluate<R, Arg, E extends HTMLElement = HTMLElement>(expression: PageFunctionOn<E, Arg, R>, arg: Arg): Promise<R>;
+  evaluate<R, E extends HTMLElement = HTMLElement>(expression: PageFunctionOn<E, void, R>, arg?: unknown): Promise<R>;
+  /**
+   * Evaluate a function against all matching elements.
+   *
+   * The function receives an array of all matching HTMLElements as its
+   * first argument, and the optional `arg` as its second argument.
+   *
+   * @see Playwright Locator.evaluateAll → Frame.$$eval
+   */
+  evaluateAll<R, Arg, E extends HTMLElement = HTMLElement>(expression: PageFunctionOn<E[], Arg, R>, arg: Arg): Promise<R>;
+  evaluateAll<R, E extends HTMLElement = HTMLElement>(expression: PageFunctionOn<E[], void, R>, arg?: unknown): Promise<R>;
+  /**
+   * Evaluate a function in the page context and return a handle to the result
+   * instead of the serialized value.
+   *
+   * The handle can be used in subsequent `handle.evaluate()` calls or released
+   * via `handle.dispose()`. This is useful for non-serializable values (DOM
+   * elements, functions, etc.).
+   *
+   * JS handles are an emulator-only host feature: the concrete `JSHandle`
+   * class (with `FinalizationRegistry` auto-dispose) lives in
+   * `@pixui-dev/emulator-core`, not in this runtime-agnostic layer. The page
+   * backend supplies it through {@link PageHost.wrapHandle}; backends that do
+   * not support handles (e.g. inflight-test, which runs inside QuickJS and has
+   * no `eval`) simply omit `wrapHandle`, and this method throws.
+   *
+   * @see Playwright Locator.evaluateHandle → Frame.evalOnSelectorHandle
+   */
+  evaluateHandle<R, Arg, E extends HTMLElement = HTMLElement>(expression: PageFunctionOn<E, Arg, R>, arg: Arg): Promise<JSHandleLike<R>>;
+  evaluateHandle<R, E extends HTMLElement = HTMLElement>(expression: PageFunctionOn<E, void, R>, arg?: unknown): Promise<JSHandleLike<R>>;
+  private _clone;
+  setTimeout(timeout: number): Locator;
+  toString(): string;
+} //#endregion
+//#region src/local-bridge.d.ts
+//#endregion
+//#region src/page/inflight-page.d.ts
+interface InflightPageOptions {
+  /** Test-id attribute for `getByTestId`. Default `data-testid`. */
+  testIdAttribute?: string;
+  /** Activity ⇄ host bridge — required for `page.screenshot`. */
+  activityBridge?: ActivityBridge;
+  /** Filesystem writer — required for `page.screenshot`. */
+  io?: ReportIo;
+  /** Run directory screenshots are written under (`<run-dir>/screenshots/`). */
+  reportRunDir?: string;
+  /** Override the page API (default: `createPageApi()` over the live DOM). */
+  api?: PageFunctions;
+  /** Override the input backend (default: {@link DomInputBackend}). */
+  input?: InputBackend;
+}
+declare class InflightPage implements PageHost {
+  readonly devtoolsBridge: BridgeClient;
+  readonly mouse: Mouse;
+  readonly keyboard: Keyboard;
+  readonly touchscreen: Touchscreen;
+  readonly testIdAttribute: string;
+  private _closed;
+  private _disposed;
+  private readonly _closeHandlers;
+  private readonly _disposedHandlers;
+  private readonly _activityBridge;
+  private readonly _io;
+  private readonly _reportRunDir;
+  constructor(options?: InflightPageOptions);
+  isClosed(): boolean;
+  isDisposed(): boolean;
+  waitForTimeout(ms: number): Promise<void>;
+  onClose(handler: () => void): () => void;
+  onDisposed(handler: () => void): () => void;
+  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+  locator(selector: string, options?: LocatorFilterOptions): Locator;
+  getByText(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByAltText(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByLabel(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByPlaceholder(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByTitle(text: string | RegExp, options?: {
+    exact?: boolean;
+  }): Locator;
+  getByTestId(testId: string | RegExp): Locator;
+  /** Mark the page closed (window.close()-style) and notify listeners. */
+  close(): void;
+  /** Dispose the page and notify listeners. */
+  dispose(): void;
+  private _assertNotClosed;
+  private _screenshotFileName;
+}
+//#endregion
+//#region src/page/page-singleton.d.ts
+/**
+ * Configure the lazily-created {@link page} singleton. Called by `run()` before
+ * tests execute so `page.screenshot()` etc. have their host wiring. Resets any
+ * existing instance so the next access rebuilds with the new config; safe
+ * because configuration always happens before tests create locators.
+ */
+declare function configureInflightPage(options: InflightPageOptions): void;
+/** The live {@link InflightPage} instance, created on first access. */
+declare function getInflightPage(): InflightPage;
+/** Drop the current instance + config (test isolation). */
+declare function resetInflightPage(): void;
+/**
+ * The shared page. Every access forwards to the lazily-created
+ * {@link InflightPage}; methods are bound so destructuring
+ * (`const { getByTestId } = page`) keeps working.
+ */
+declare const page: InflightPage;
+//#endregion
+//#region src/page/dom-input-backend.d.ts
+declare class DomInputBackend implements InputBackend {
+  click(x: number, y: number, options?: ClickOptions): Promise<void>;
+  move(x: number, y: number): Promise<void>;
+  down(x: number, y: number, options?: MouseOptions): Promise<void>;
+  up(x: number, y: number, options?: MouseOptions): Promise<void>;
+  wheel(x: number, y: number, deltaY: number, deltaX?: number): Promise<void>;
+  tap(x: number, y: number, options?: TapOptions): Promise<void>;
+  swipe(fromX: number, fromY: number, toX: number, toY: number, options?: SwipeOptions): Promise<void>;
+  longPress(x: number, y: number, options?: LongPressOptions): Promise<void>;
+  press(key: string, options?: PressOptions): Promise<void>;
+  keyDown(key: string): Promise<void>;
+  keyUp(key: string): Promise<void>;
+  typeText(text: string, options?: TypeOptions): Promise<void>;
+}
+//#endregion
+//#region src/vendored/version.d.ts
+declare const VENDORED_VITEST_VERSION = "5.0.0-beta.5";
+//#endregion
+export { type ActivityBridge, type BlobReportInput, type CaptureRect, type CaptureScreenRequest, type CaptureScreenResult, type CaptureScreenshotOptions, type CapturedScreenshot, CollectingProgressSurface, ConsoleProgressSurface, DomInputBackend, InflightPage, type InflightPageOptions, type InflightRunOptions, type InflightRunResult, InflightVitestRunner, MemoryReportIo, PROTOCOL_CAPTURE_SCREEN, PROTOCOL_CAPTURE_SCREEN_CALLBACK, type ProgressSurface, type QuickjsOs, QuickjsReportIo, type ReportIo, type RunProgressEvent, SimulatedActivityBridge, type SimulatedScreenshotHostOptions, type StartOptions, TINY_PNG, type TestFileSpec, VENDORED_VITEST_VERSION, type VitestRunner, type WriteBlobReportOptions, type WrittenReport, afterAll, afterEach, beforeAll, beforeEach, captureScreenshot, collectTests, configureInflightPage, createRunId, describe, expect, getCurrentSuite, getInflightPage, getRunner, it, joinPath, onTestFailed, onTestFinished, page, recordArtifact, resetInflightPage, run, serializeBlobReport, start, startTests, suite, test, writeBlobReport };
+//# sourceMappingURL=index.d.ts.map