@delacour/warden-e2e 0.0.0-stage → 0.1.1

package/types/e2e/src/screen/locator.d.ts

@@ -0,0 +1,233 @@
+import type { KeyName, Modifier, Point, Rect } from "../driver/driver.types";
+import { type Momentum, type SwipeDirection } from "./actions";
+import type { Observed, Runtime } from "./context";
+import type { NodeEntry } from "./nodes";
+import { type RoleOptions, type TestIdOptions, type TextQueryOptions } from "./queries";
+import { type LocatorExpression } from "./query";
+import type { QueryRole } from "./roles";
+import { type TextMatch } from "./text";
+export type ActionOptions = {
+    timeout?: number;
+};
+/** What `locator.read()` saw in one look: no match is just `{ visible: false }`. */
+export type LocatorReading = {
+    visible: boolean;
+    /** what `text()` returns; absent when nothing matched */
+    text?: string;
+    /** what `value()` returns; absent when nothing matched */
+    value?: string;
+    /** only for a node that can be checked (a switch, a checkbox) */
+    checked?: boolean;
+};
+/** What shows a tap landed: a locator that becomes visible, or a check that resolves true. */
+export type TapUntil = Locator | (() => Promise<boolean>);
+export type TapOptions = ActionOptions & {
+    position?: Point;
+    /**
+     * Tap again when this does not show up. A locator counts once it is visible; a function once it resolves true (its
+     * reads share one snapshot per check). After the tap and after each re-tap the wait is `windowMs`, except that the
+     * last re-tap is not waited on: like a hand-rolled tap-and-check helper, `tap` returns and the next assertion says
+     * whether it landed. With a locator, the screen is also compared with the one the press aimed from: once it
+     * changed (a spinner, a disabled button, the target gone) the press landed and is never sent again, however late
+     * `until` is; a screen that has not changed at all is pressed again from 750 ms on, without waiting out `windowMs`.
+     */
+    until?: TapUntil;
+    /** extra taps when `until` has not shown within `windowMs` of the previous tap. Default 2. Needs `until`. */
+    retries?: number;
+    /** how long each tap gets to show `until`. Default 4000 ms. Needs `until`. */
+    windowMs?: number;
+    /** gap between checks of `until`. Default 250 ms. Needs `until`. */
+    pollMs?: number;
+};
+export type LongPressOptions = ActionOptions & {
+    durationMs?: number;
+};
+export type PressOptions = ActionOptions & {
+    modifiers?: readonly Modifier[];
+};
+export type LocatorSwipeOptions = ActionOptions & {
+    direction: SwipeDirection;
+    momentum?: Momentum;
+};
+/** A pinch or rotate: `radius` is each finger's distance from the centre at the start, in points. */
+export type PinchOptions = ActionOptions & {
+    durationMs?: number;
+    radius?: number;
+};
+export type RotateOptions = PinchOptions;
+export type ScrollOptions = ActionOptions & {
+    direction?: SwipeDirection;
+    momentum?: Momentum;
+    maxSwipes?: number;
+};
+export type WaitState = "attached" | "detached" | "visible" | "hidden";
+export type WaitForOptions = ActionOptions & {
+    state?: WaitState;
+};
+declare const LOCATOR_BRAND: unique symbol;
+/** Whether `value` is a `Locator` (also across duplicated copies of this module, e.g. the bundled entry and the preload). */
+export declare function isLocator(value: unknown): value is Locator;
+export declare class Locator {
+    readonly expr: LocatorExpression;
+    private readonly rt;
+    readonly [LOCATOR_BRAND] = true;
+    constructor(expr: LocatorExpression, rt: Runtime);
+    toString(): string;
+    private scoped;
+    getByTestId(id: TextMatch, options?: TestIdOptions): Locator;
+    getByText(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByLabel(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByPlaceholder(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByValue(value: TextMatch, options?: TextQueryOptions): Locator;
+    getByRole(role: QueryRole, nameOrOptions?: TextMatch | RoleOptions, options?: Omit<RoleOptions, "name">): Locator;
+    locator(selector: string): Locator;
+    filter(options: {
+        hasText?: TextMatch;
+        has?: Locator;
+    }): Locator;
+    first(): Locator;
+    last(): Locator;
+    nth(index: number): Locator;
+    /** The runtime (host, timeouts, clock) this locator runs on; the `expect` matchers poll through it. */
+    get runtime(): Runtime;
+    /** One look at the screen: every current match and the snapshot they came from. Never waits. */
+    look(options?: {
+        reuse?: boolean;
+    }): Promise<{
+        entries: NodeEntry[];
+        observed: Observed;
+    }>;
+    private matches;
+    private single;
+    /** Components of the React tree that this locator names, when it is a plain `getByTestId` and the app has devtools. */
+    private reactCandidates;
+    private exactlyOne;
+    /** One read as a trace-only `read.<name>` span naming this locator; reads that call another read are not wrapped twice. */
+    private traced;
+    count(): Promise<number>;
+    all(): Promise<Locator[]>;
+    text(): Promise<string>;
+    allTexts(): Promise<string[]>;
+    value(): Promise<string>;
+    isVisible(): Promise<boolean>;
+    /**
+     * Visibility, text, value and checked state from ONE look at the screen: where `isVisible()` then `text()` read the
+     * screen for each (sharing a snapshot only when nothing was pressed in between and it is still young), this is one
+     * read by construction. No match is `{ visible: false }` and never waits; several matches fail like `text()`.
+     * `text` is what `text()` returns, `value` what `value()` returns, `checked` is there only for a node that can be
+     * checked (a switch, a checkbox).
+     */
+    read(): Promise<LocatorReading>;
+    /** Whether this locator's one match is visible in `observed`; no match is not visible, several matches throw. */
+    visibleIn(observed: Observed): boolean;
+    isHidden(): Promise<boolean>;
+    isEnabled(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    /** Always a new snapshot: a frame is for aiming at, and one from a screen that was still moving is wrong. */
+    boundingBox(): Promise<Rect>;
+    /** Polls until the locator is `visible` (default), `hidden`, `attached` or `detached`; else `TIMEOUT`. */
+    waitFor(options?: WaitForOptions): Promise<void>;
+    private waitForState;
+    private act;
+    /**
+     * Waits for exactly one visible (and, per `spec`, enabled, on-screen) match. Several matches fail at once.
+     * With `allowReact` a component that only the React tree knows (a plain `getByTestId`) counts as a match.
+     * Every look here is a new snapshot, never the one a read or an `expect` kept: the action goes to where the element
+     * is now, and a snapshot taken while the screen was still sliding in has it somewhere else. (A plain `tap` on a
+     * driver with a cheap hit-test first tries `aimFromKept`, which checks the kept snapshot with a hit-test instead.)
+     * A fresh snapshot can also be of a screen still moving, so a match is taken only once its frame held still across
+     * two looks with no input between them (Playwright's "stable"): the look a read or an `expect` kept, when there is
+     * one, costs nothing; with none, a look less than `STABLE_INPUT_GAP_MS` after an input is checked by one more. An
+     * element that never stops moving is taken after `MAX_STABILITY_LOOKS` extra looks.
+     */
+    private actionable;
+    /** One look of `actionable`: done, not yet, or `moving` (the match has not held still yet; look again at once). */
+    private actionableLook;
+    /**
+     * Whether `entry`'s frame, to 1 pt, is where the look before this one had this locator's one match. Without that look:
+     * still unless an input ended less than `STABLE_INPUT_GAP_MS` before this one. No observation cache = still (no history).
+     */
+    private heldStill;
+    /**
+     * Where a hit-test is cheap (`capabilities.cheapHitTest`, iOS), the tap after an assertion need not take a second
+     * snapshot: when the observation cache holds one it would still reuse (younger than `OBSERVATION_MAX_AGE_MS` for the
+     * platform) with no input since, its one
+     * actionable match is hit-tested at the tap point, and the match is taken as is when the hit is that element (same
+     * role, identifier, label, enabled state and frame to 1 pt). That hit is also the second look of the stable-frame
+     * rule: the element is where the snapshot had it. Anything else (no such snapshot, an alert on it, several or no
+     * matches, a blocked match, a hit on a child or a neighbour, a failed hit-test) is undefined: `actionable` looks again.
+     * Never with system alerts answered (`answerSystemAlert`, `test.use({ systemAlerts })`): an alert that came up after
+     * the kept snapshot sits outside the app, where the app-scoped hit-test may not see it, and the fresh look answers it.
+     */
+    private aimFromKept;
+    /**
+     * Taps the one visible, enabled match. With `until` it is also the retrying tap: the press on a tab bar or a list row
+     * right after a navigation is sometimes dropped with nothing on screen to tell, so it checks that `until` shows
+     * within `windowMs` and presses again, up to `retries` more times.
+     */
+    tap(options?: TapOptions): Promise<void>;
+    /**
+     * One press; resolves to the snapshot it aimed from (the screen just before the press). A plain tap may aim from the
+     * kept snapshot (`aimFromKept`); a tap with `until` takes a fresh look, since the screen it aimed from is what the
+     * checks compare against to tell the press landed, and an older one could differ only because it was older.
+     */
+    private tapOnce;
+    /**
+     * Polls `plan.until` for `plan.windowMs`, one look at the screen per check. A locator is checked on the snapshot of
+     * the poll itself, which is also compared with `pressedOn` (the hash of the screen the press aimed from): once the
+     * screen changed the press landed, so it is never sent again (`landed`, even when `until` is late); a screen still
+     * unchanged on `UNCHANGED_CHECKS` checks in a row from `UNCHANGED_AFTER_MS` on is pressed again at once. A function
+     * is called with the kept snapshot forgotten (after the first check), so its own reads take one new snapshot
+     * between them rather than the previous check's; it gets the whole window.
+     */
+    private arrivedWithin;
+    /** One check of a locator `until`: shown, the press looks dropped (`press-again`), or not yet (noting whether the screen moved). */
+    private checkLocatorUntil;
+    longPress(options?: LongPressOptions): Promise<void>;
+    /**
+     * Replaces the content of a text field: focus with the caret at the end, empty it (select all and type over the selection when
+     * the driver can, nothing for a field that is empty or shows a placeholder), type, then poll until the field holds
+     * the text on consecutive reads (the accessibility value lags the keys). A mismatch is retried once with one Backspace
+     * per character and a retype (a field that refuses select-all). Secure fields cannot be read back, so they are not
+     * verified.
+     */
+    fill(text: string, options?: ActionOptions): Promise<void>;
+    /** Empties a text field (select all and one Backspace when the driver can), then checks it is empty (one more pass of counted Backspaces when it is not). */
+    clear(options?: ActionOptions): Promise<void>;
+    /** Types at the caret; the field is tapped (caret to the end) first unless it already has focus. */
+    type(text: string, options?: ActionOptions): Promise<void>;
+    press(key: KeyName, options?: PressOptions): Promise<void>;
+    /** A scroll gesture on this one node, in the direction the content moves. */
+    swipe(options: LocatorSwipeOptions): Promise<void>;
+    /**
+     * A two-finger pinch centred on this node's visible part: `scale` above 1 spreads the fingers (zoom in), below 1
+     * brings them together. `INVALID_ARGUMENT` for a scale outside 0.1-10 or exactly 1, or on a driver without pinch.
+     */
+    pinch(scale: number, options?: PinchOptions): Promise<void>;
+    /** A two-finger rotation about this node's visible centre; positive `degrees` turn clockwise. */
+    rotate(degrees: number, options?: RotateOptions): Promise<void>;
+    /** Scrolls the screen until this locator is on screen. */
+    scrollTo(options?: ScrollOptions): Promise<void>;
+    /** One poll step when the accessibility tree has no match: ask the React tree (plain `getByTestId` only). */
+    private reactStep;
+    private focus;
+    private focusAndClear;
+    /** Sleeps on the runtime's clock (a fake one in tests), ending early when the attempt aborts. */
+    private readonly pause;
+    /**
+     * Polls until the field holds `text` on consecutive reads. Each read is a hit-test at the field's centre (a full
+     * snapshot with the keyboard up takes 300-1000 ms and slows the app that is digesting the keys), falling back to a
+     * scoped re-query when the hit-test cannot tell. The deadline is `VERIFY_MS`, extended while the value changes.
+     */
+    private confirm;
+}
+/** The strict one-match rule; the error carries the rendered screen, which is only built when there is an error. */
+export declare function pickOne(rt: Runtime, expr: LocatorExpression, entries: readonly NodeEntry[], observed: Observed): NodeEntry;
+/** Display text: the accessible name, else the text of everything inside. */
+export declare function textOf(entry: NodeEntry): string;
+/**
+ * Swipes the screen in `direction` (the way the content moves) until `target` has exactly one match that is on screen.
+ * Gives up after `maxSwipes` swipes or the action timeout.
+ */
+export declare function scrollUntilVisible(rt: Runtime, target: Locator, options?: ScrollOptions): Promise<void>;
+export {};

package/types/e2e/src/screen/nodes.d.ts

@@ -0,0 +1,53 @@
+import type { Element, ScreenInfo, Snapshot } from "../driver/driver.types";
+import { type QueryRole } from "./roles";
+export type NodeStates = {
+    /** undefined when the node is not checkable */
+    checked: boolean | undefined;
+    expanded: boolean | undefined;
+    disabled: boolean;
+    selected: boolean;
+    focused: boolean;
+    /** the driver's `hidden` flag, inherited from ancestors; queries use this, `visible` adds geometry */
+    hidden: boolean;
+};
+/** One accessibility node with everything queries need derived once per snapshot. */
+export type NodeEntry = {
+    /** index into `NodeIndex.entries` (document order) */
+    position: number;
+    element: Element;
+    depth: number;
+    parent: NodeEntry | undefined;
+    children: NodeEntry[];
+    role: QueryRole;
+    /** accessible name: label, else text */
+    name: string | undefined;
+    /** displayed value with React Native role prefixes removed; never set for secure fields */
+    value: string | undefined;
+    states: NodeStates;
+    secure: boolean;
+    /** not hidden, non-empty frame, intersecting the screen */
+    visible: boolean;
+    /**
+     * Normalised label/text/value of this node and its descendants, echoes removed, in document order. Worked out on the
+     * first read (and kept), because indexing every node's subtree costs nodes x depth and most reads never ask.
+     */
+    readonly fragments: readonly string[];
+    /** `fragments` joined with a space; also worked out on first read */
+    readonly subtreeText: string;
+};
+export type NodeIndex = {
+    entries: readonly NodeEntry[];
+    byId: ReadonlyMap<string, NodeEntry>;
+    screen: ScreenInfo;
+};
+/**
+ * Flattens a snapshot into document-order entries with parent/child links and derived state. Subtree text is not built
+ * here: `fragments` and `subtreeText` compute on first read.
+ */
+export declare function indexSnapshot(snapshot: Snapshot): NodeIndex;
+/** True when `entry` is a strict descendant of `ancestor`. */
+export declare function isWithin(entry: NodeEntry, ancestor: NodeEntry): boolean;
+/** Strict descendants of any of `ancestors` among `universe`, in the universe's order. */
+export declare function descendantsOf(universe: readonly NodeEntry[], ancestors: readonly NodeEntry[]): NodeEntry[];
+/** The snapshot entry of one element (its role, name, value and secure flag), for rules that need more than the `Element`. */
+export declare function entryOfElement(element: Element, template: Pick<Snapshot, "platform">): NodeEntry | undefined;

package/types/e2e/src/screen/poll.d.ts

@@ -0,0 +1,57 @@
+/** Time source for polling; tests inject `fakeClock()` so nothing really waits. */
+export type Clock = {
+    now(): number;
+    /** resolves after `ms`, or early when `signal` aborts */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+};
+export declare const systemClock: Clock;
+export declare const DEFAULT_POLL_INTERVAL_MS = 100;
+/**
+ * Gap between attempts: `fastMs` while the poll is younger than `fastForMs`, `slowMs` after. Every attempt is a read of
+ * the device (a full accessibility walk inside the app, or a 1.9 s `uiautomator dump` on Android), so a wait that has
+ * not been satisfied for a second is not worth 10 reads a second.
+ */
+export type PollSchedule = {
+    fastMs: number;
+    fastForMs: number;
+    slowMs: number;
+};
+export declare const DEFAULT_POLL_SCHEDULE: PollSchedule;
+/** One attempt: finished with a value, or not yet (with whatever the caller wants to report if time runs out). */
+export type PollStep<T, S> = {
+    done: true;
+    value: T;
+} | {
+    done: false;
+    state: S;
+    /** wake no later than this many ms from now, even when the schedule says to wait longer (a hold window ending) */
+    maxWaitMs?: number;
+};
+export type PollResult<T, S> = {
+    status: "done";
+    value: T;
+    attempts: number;
+} | {
+    status: "timeout";
+    last: S | undefined;
+    attempts: number;
+} | {
+    status: "aborted";
+    attempts: number;
+};
+export type PollOptions = {
+    /** a fixed gap between attempts, with no back-off; wins over `schedule` */
+    intervalMs?: number;
+    /** default `DEFAULT_POLL_SCHEDULE`: 100 ms for the first second, then 250 ms */
+    schedule?: PollSchedule;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    now?: Clock["now"];
+    sleep?: Clock["sleep"];
+};
+/**
+ * Runs `step` until it is done, `timeoutMs` pass, or `signal` aborts. Always tries at least once (unless already
+ * aborted); never sleeps past the deadline, so the last attempt is at the deadline. The gap follows `intervalMs`, else
+ * `schedule` measured on the clock (a slow step reaches the slow gap sooner). Errors thrown by `step` end the poll.
+ */
+export declare function poll<T, S = undefined>(step: (attempt: number) => Promise<PollStep<T, S>> | PollStep<T, S>, options: PollOptions): Promise<PollResult<T, S>>;

package/types/e2e/src/screen/queries.d.ts

@@ -0,0 +1,34 @@
+import type { LocatorExpression, Query, RoleQuery } from "./query";
+import { type QueryRole } from "./roles";
+import type { TextMatch } from "./text";
+/** Pure constructors for the `getBy*` family, shared by `screen` and `Locator` (which scopes them to its subtree). */
+export type TextQueryOptions = {
+    exact?: boolean;
+    visible?: boolean;
+};
+export type TestIdOptions = {
+    visible?: boolean;
+};
+export type RoleOptions = {
+    name?: TextMatch;
+    exact?: boolean;
+    checked?: boolean;
+    disabled?: boolean;
+    selected?: boolean;
+    visible?: boolean;
+};
+export declare function testIdQuery(id: TextMatch, options?: TestIdOptions): Query;
+declare const METHOD: {
+    readonly text: "getByText";
+    readonly label: "getByLabel";
+    readonly placeholder: "getByPlaceholder";
+    readonly value: "getByValue";
+};
+export declare function textQuery(kind: keyof typeof METHOD, value: TextMatch, options?: TextQueryOptions): Query;
+/** `getByRole("button", "Save", { checked })` and `getByRole("button", { name: "Save", checked })` are the same query. */
+export declare function roleQuery(role: QueryRole, nameOrOptions?: TextMatch | RoleOptions, options?: Omit<RoleOptions, "name">): RoleQuery;
+/** `locator("id=x role=button")`: the agent-CLI selector grammar as a locator expression. */
+export declare function selectorExpression(text: string): LocatorExpression;
+/** Runs `expr` inside the subtree(s) of `scope` (below any scope `expr` already has). */
+export declare function withScope(expr: LocatorExpression, scope: LocatorExpression): LocatorExpression;
+export {};

package/types/e2e/src/screen/query.d.ts

@@ -0,0 +1,60 @@
+import { type Result } from "../../../types/src/result";
+import { type E2eError } from "../errors";
+import { type NodeEntry, type NodeIndex } from "./nodes";
+import type { QueryRole } from "./roles";
+import { type ParsedSelector } from "./selector";
+import { type TextMatch } from "./text";
+/** Every query accepts `visible: true`, which drops hidden nodes before the exactly-one rule runs. */
+type Visibility = {
+    visible?: boolean;
+};
+export type RoleQuery = {
+    kind: "role";
+    role: QueryRole;
+    name?: TextMatch;
+    exact?: boolean;
+    checked?: boolean;
+    disabled?: boolean;
+    selected?: boolean;
+} & Visibility;
+export type Query = ({
+    kind: "testId";
+    value: TextMatch;
+} & Visibility) | ({
+    kind: "text" | "label" | "placeholder" | "value";
+    value: TextMatch;
+    exact?: boolean;
+} & Visibility) | RoleQuery | ({
+    kind: "selector";
+    selector: ParsedSelector;
+} & Visibility);
+/**
+ * A lazy locator: what to look for, never where it is. Evaluated against one `NodeIndex` by `resolve`.
+ * `query` optionally runs inside the subtree(s) of `scope`; `filter` refines; `index` picks one.
+ */
+export type LocatorExpression = {
+    kind: "query";
+    query: Query;
+    scope?: LocatorExpression;
+} | {
+    kind: "filter";
+    source: LocatorExpression;
+    hasText?: TextMatch;
+    has?: LocatorExpression;
+} | {
+    kind: "index";
+    source: LocatorExpression;
+    index: "first" | "last" | number;
+};
+/** Every node the expression currently matches, in document order. One immediate pass: no waiting, no strictness. */
+export declare function resolve(expr: LocatorExpression, index: NodeIndex): NodeEntry[];
+/**
+ * The strict one-match rule for actions and reads: zero matches is `LOCATOR_NOT_FOUND`, several is `LOCATOR_AMBIGUOUS`.
+ * `options.screen` is attached to the error (the rendered tree helps a failure report).
+ */
+export declare function exactlyOne(expr: LocatorExpression, matches: readonly NodeEntry[], options?: {
+    screen?: string;
+}): Result<NodeEntry, E2eError>;
+/** A spec-API style description of the expression (`getByRole("button", "Save").first()`), for error messages. */
+export declare function describeExpression(expr: LocatorExpression): string;
+export {};

package/types/e2e/src/screen/react-locator.d.ts

@@ -0,0 +1,30 @@
+import type { DevtoolsFacet } from "../devtools/devtools.types";
+import type { Platform, Point, Rect, ScreenInfo } from "../driver/driver.types";
+import { type TextMatch } from "./text";
+/** A component found by `testID` in the React tree, where the accessibility tree had nothing. */
+export type ReactMatch = {
+    /** window rect in the driver's pixels */
+    frame: Rect;
+    /** centre of `frame` */
+    tapPoint: Point;
+    source: "react";
+    testId: string;
+    /** the component's name (`View`, `Button`, ...) */
+    name: string;
+};
+export type ReactView = {
+    platform: Platform;
+    screen: ScreenInfo;
+};
+/**
+ * Components of the running app whose `testID` matches, with rects in the driver's pixels. This is the fallback for
+ * `getByTestId` when the platform hides the view from accessibility (React Native only exposes `testID` to
+ * accessibility on some views). Any devtools failure means "nothing found", so callers keep their own not-found
+ * error. Android measures in dp but the driver taps in px: `view.screen.scale` converts.
+ */
+export declare function locateByTestIdViaReact(facet: Pick<DevtoolsFacet, "tree">, testId: TextMatch, view: ReactView, options?: {
+    screenName?: string;
+    timeoutMs?: number;
+}): Promise<ReactMatch[]>;
+/** Where a tap on `match` lands: `position` is an offset from the frame's top-left corner, else the centre. */
+export declare function reactTapPoint(match: ReactMatch, position?: Point): Point;

package/types/e2e/src/screen/render.d.ts

@@ -0,0 +1,42 @@
+import type { Snapshot } from "../driver/driver.types";
+import { type NodeEntry } from "./nodes";
+export type RenderOptions = {
+    /** keep interactive roles plus any element with an identifier; hidden elements are dropped, no indentation */
+    interactiveOnly: boolean;
+    /** element id -> `@eN`; elements without an entry print without a ref */
+    refs: ReadonlyMap<string, string>;
+    /** cap on element lines; a `… N more (use --all)` line follows when cut */
+    maxLines?: number;
+};
+export type RenderedSnapshot = {
+    lines: string[];
+    /** element lines printed */
+    shown: number;
+    /** elements in the snapshot */
+    total: number;
+    /** elements cut by `maxLines` */
+    omitted: number;
+};
+/** `[button] "Sign in" id=sign-in-submit`: enough to tell matches apart in an error message. */
+export declare function describeEntry(entry: NodeEntry): string;
+/** `@e3 [button] "Sign in" id=sign-in-submit value="…" enabled hittable (24,332 345×48)`; `indent` is in levels. */
+export declare function renderEntryLine(entry: NodeEntry, options?: {
+    ref?: string;
+    indent?: number;
+}): string;
+/** The entries `interactiveOnly` lists: visible ones that are interactive or carry a testID. */
+export declare function isListed(entry: NodeEntry): boolean;
+/** The `warden ui snapshot` body: one line per element in document order. */
+export declare function renderSnapshot(snapshot: Snapshot, options: RenderOptions): RenderedSnapshot;
+/**
+ * `# ios axbridge 390×844@3x gen 12 · 5 of 8 elements (interactive)` for spec failure artifacts; with `style: "cli"`
+ * the `warden ui snapshot` line, `generation 4 · axbridge · 393×852@3x · 5 of 41 elements` (`, truncated` at the end,
+ * the count is `41 elements` when nothing was cut).
+ */
+export declare function renderHeader(input: {
+    snapshot: Snapshot;
+    rendered: RenderedSnapshot;
+    interactiveOnly: boolean;
+    generation?: number;
+    style?: "spec" | "cli";
+}): string;

package/types/e2e/src/screen/roles.d.ts

@@ -0,0 +1,24 @@
+import type { Element } from "../driver/driver.types";
+/** The role vocabulary `getByRole` and `role=` selectors speak. */
+export declare const QUERY_ROLES: readonly ["button", "link", "textbox", "searchbox", "checkbox", "radio", "switch", "slider", "image", "heading", "text", "tab", "tablist", "menu", "menuitem", "list", "listitem", "row", "alert", "dialog", "navigation", "group", "other"];
+export type QueryRole = (typeof QUERY_ROLES)[number];
+export declare function isQueryRole(value: string): value is QueryRole;
+/** Roles `snapshot -i` keeps: things a user can act on. */
+export declare function isInteractiveRole(role: QueryRole): boolean;
+export type SpelledValue = {
+    checked?: boolean;
+    expanded?: boolean;
+    role: QueryRole;
+    value: string | undefined;
+};
+/** Reads `<role description>[, <state>…][, <value>]` back; undefined for any value that does not start with a role. */
+export declare function parseSpelledValue(value: string | undefined): SpelledValue | undefined;
+export type ResolvedRole = {
+    role: QueryRole;
+    spelled?: SpelledValue;
+};
+/**
+ * The query role for one driver element. `parent` lets iOS tab bar items (reported as plain buttons) answer `tab`.
+ * Precedence: React Native spelled value on an `Other`, Android class, driver role, then trait upgrades.
+ */
+export declare function resolveRole(element: Element, parent?: Element): ResolvedRole;

package/types/e2e/src/screen/screen.d.ts

@@ -0,0 +1,61 @@
+import type { Point } from "../driver/driver.types";
+import { type Momentum, type SwipeDirection } from "./actions";
+import { type ScreenHost } from "./context";
+import { type ActionOptions, Locator, type ScrollOptions } from "./locator";
+import { type RoleOptions, type TestIdOptions, type TextQueryOptions } from "./queries";
+import type { QueryRole } from "./roles";
+import type { TextMatch } from "./text";
+export type ScreenSwipeOptions = {
+    direction: SwipeDirection;
+    momentum?: Momentum;
+} | {
+    from: Point;
+    to: Point;
+    durationMs?: number;
+};
+export type ScreenPinchOptions = {
+    scale: number;
+    center?: Point;
+    radius?: number;
+    durationMs?: number;
+};
+export type ScreenRotateOptions = {
+    degrees: number;
+    center?: Point;
+    radius?: number;
+    durationMs?: number;
+};
+/**
+ * `paths` are 1-2 fingers' routes in screen points, each with at least one finite point (give two or more for a
+ * real path; a single point is a held touch). More fingers than the driver's `capabilities.maxPointers` is `INVALID_ARGUMENT`.
+ */
+export type ScreenPathOptions = {
+    paths: readonly (readonly Point[])[];
+    durationMs?: number;
+};
+/** Viewport-level gestures; `screen.swipe` is the same as `screen.gesture.swipe`. */
+export type ScreenGestures = {
+    /** pinch about the screen centre (or `center`); `scale` above 1 zooms in */
+    pinch(options: ScreenPinchOptions): Promise<void>;
+    /** rotate about the screen centre (or `center`); positive `degrees` turn clockwise */
+    rotate(options: ScreenRotateOptions): Promise<void>;
+    /** replay 1-2 finger paths on one timeline; no observation, coordinates are used as given */
+    path(options: ScreenPathOptions): Promise<void>;
+    swipe(options: ScreenSwipeOptions): Promise<void>;
+};
+/** The `screen` of the spec API: lazy queries over the device, plus viewport-level gestures. */
+export type Screen = {
+    getByTestId(id: TextMatch, options?: TestIdOptions): Locator;
+    getByText(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByLabel(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByPlaceholder(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByValue(value: TextMatch, options?: TextQueryOptions): Locator;
+    getByRole(role: QueryRole, nameOrOptions?: TextMatch | RoleOptions, options?: Omit<RoleOptions, "name">): Locator;
+    /** the agent-CLI selector grammar: `locator("id=sign-in role=button nth=1")` */
+    locator(selector: string): Locator;
+    tapAt(point: Point, options?: ActionOptions): Promise<void>;
+    swipe(options: ScreenSwipeOptions): Promise<void>;
+    gesture: ScreenGestures;
+    scrollUntilVisible(target: Locator, options?: ScrollOptions): Promise<void>;
+};
+export declare function createScreen(host: ScreenHost): Screen;

package/types/e2e/src/screen/selector.d.ts

@@ -0,0 +1,38 @@
+import { type Result } from "../../../types/src/result";
+import type { NodeEntry } from "./nodes";
+import type { LocatorExpression } from "./query";
+/** A selector value: literal text (bare or quoted on the wire) or a regular expression. */
+export type SelectorValue = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "regex";
+    source: string;
+    flags: string;
+};
+/**
+ * The agent-CLI selector grammar: `id=<v> label=<v> text=<v> role=<v> value=<v> editable=true|false nth=<i>`.
+ * `id` is exact; `label`, `text` and `value` are case-insensitive substrings; a regex is applied as written.
+ */
+export type ParsedSelector = {
+    id?: SelectorValue;
+    label?: SelectorValue;
+    text?: SelectorValue;
+    role?: SelectorValue;
+    value?: SelectorValue;
+    editable?: boolean;
+    nth?: number;
+};
+/** Parses `id=x label="Sign in" text=/regex/i role=button editable=true nth=1`. */
+export declare function parseSelector(input: string): Result<ParsedSelector>;
+/** The canonical text for a selector; `parseSelector(formatSelector(s))` equals `s`. */
+export declare function formatSelector(selector: ParsedSelector): string;
+/** The expression a selector stands for: one selector query, wrapped in `nth` when given. */
+export declare function selectorToQuery(selector: ParsedSelector): LocatorExpression;
+/** One node against one parsed selector (`nth` is not part of matching; see `selectorToQuery`). */
+export declare function matchesSelector(entry: NodeEntry, selector: ParsedSelector): boolean;
+/**
+ * Picks the target of an action among several matches: visible first, then the most exact text terms, then the smallest
+ * frame, then reading order.
+ */
+export declare function pickMostSpecific(matches: readonly NodeEntry[], selector: ParsedSelector): NodeEntry | undefined;

package/types/e2e/src/screen/text.d.ts

@@ -0,0 +1,13 @@
+/** A string (whole-text, or substring with `exact:false`) or a RegExp applied as written. */
+export type TextMatch = string | RegExp;
+export type TextMatchOptions = {
+    exact?: boolean;
+};
+/** Collapses every whitespace run (including no-break spaces) to one space and trims. */
+export declare function normalizeText(text: string): string;
+/**
+ * Whether `value` satisfies `match`. A string must equal the whole text after whitespace normalisation (case-sensitive);
+ * `exact:false` turns it into a case-insensitive substring. A RegExp is tested as written against the normalised value
+ * (its `g`/`y` flags are dropped so repeated calls are not stateful).
+ */
+export declare function matchesText(value: string, match: TextMatch, options?: TextMatchOptions): boolean;