@specific.dev/spectest 0.26.0 → 0.27.0

package/dist/locator.d.ts

@@ -0,0 +1,260 @@
+import type { Page, Locator as PWLocator } from "playwright-core";
+import type { RecordableFields } from "./browser.js";
+import type { Wrapped } from "./inspect.js";
+/** Default deadline for a locator action/read's target to become actionable.
+ *  Playwright's own default is 30s — far too slow-failing for tests; 5s
+ *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
+ *  `undefined` falls through to the context default (also set to this in
+ *  browser.ts's `contextFor`). Navigations keep a longer deadline. */
+export declare const DEFAULT_ACTION_TIMEOUT_MS = 5000;
+export interface GetByTextOptions {
+    /** Whole-string, case-sensitive match instead of the default
+     *  case-insensitive substring. Ignored when the query is a RegExp. */
+    exact?: boolean;
+}
+export interface GetByRoleOptions {
+    /** Match by accessible name. */
+    name?: string | RegExp;
+    /** Whole-string, case-sensitive name match. */
+    exact?: boolean;
+}
+export interface FilterOptions {
+    /** Keep only elements whose subtree contains this text. */
+    hasText?: string | RegExp;
+    /** Drop elements whose subtree contains this text. */
+    hasNotText?: string | RegExp;
+    /** Keep only elements that contain a match for this locator. */
+    has?: Locator;
+    /** Drop elements that contain a match for this locator. */
+    hasNot?: Locator;
+}
+export interface ClickOptions {
+    timeout?: number;
+    force?: boolean;
+    button?: "left" | "right" | "middle";
+    clickCount?: number;
+    delay?: number;
+    position?: {
+        x: number;
+        y: number;
+    };
+    modifiers?: Array<"Alt" | "Control" | "Meta" | "Shift">;
+}
+export interface TimeoutOption {
+    timeout?: number;
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type WaitForState = "attached" | "detached" | "visible" | "hidden";
+type Step = {
+    m: "locator";
+    args: [string];
+} | {
+    m: "getByRole";
+    args: [string, GetByRoleOptions?];
+} | {
+    m: "getByText";
+    args: [string | RegExp, GetByTextOptions?];
+} | {
+    m: "getByLabel";
+    args: [string | RegExp, GetByTextOptions?];
+} | {
+    m: "getByPlaceholder";
+    args: [string | RegExp, GetByTextOptions?];
+} | {
+    m: "getByAltText";
+    args: [string | RegExp, GetByTextOptions?];
+} | {
+    m: "getByTitle";
+    args: [string | RegExp, GetByTextOptions?];
+} | {
+    m: "getByTestId";
+    args: [string];
+} | {
+    m: "filter";
+    args: [FilterOptions];
+} | {
+    m: "and";
+    args: [Locator];
+} | {
+    m: "or";
+    args: [Locator];
+} | {
+    m: "first";
+    args: [];
+} | {
+    m: "last";
+    args: [];
+} | {
+    m: "nth";
+    args: [number];
+};
+interface Chain {
+    steps: Step[];
+}
+/** True if `x` is a spectest {@link Locator}. */
+export declare function isLocator(x: unknown): x is Locator;
+/** Fold a chain onto a live page, producing a throwaway playwright Locator.
+ *  Nested spectest locators (`filter({has})`, `and`, `or`) are lowered
+ *  recursively against the same page. */
+export declare function lower(page: Page, chain: Chain): PWLocator;
+/** Short human label for a chain, e.g.
+ *  `role button "15" ‹ filter(has: text "July 2026") ‹ css .calendar`.
+ *  Root first; narrowing steps appended in reading order. */
+export declare function chainLabel(chain: Chain): string;
+/** The slice of the browser backend a locator needs. `pageOp` records one
+ *  browser event and (when `wrap`) provenance-wraps the result so a later
+ *  `expect(...)` nests under the step. `silentRead` runs a lowered read with
+ *  NO recording/drain — the poll path for `expect(locator)` matchers, which
+ *  must not emit one browser event per retry. */
+export interface LocatorBackend {
+    pageOp<T>(action: string, fields: Partial<RecordableFields>, fn: (page: Page) => Promise<T>, opts?: {
+        wrap?: boolean;
+    }): Promise<T>;
+    silentRead<T>(fn: (page: Page) => Promise<T>): Promise<T>;
+    /** CDP touch tap with press dwell (mobile only). */
+    rawTap(x: number, y: number, durationMs?: number): Promise<void>;
+    /** Record ONE settled browser event for an `expect(locator)` matcher (label
+     *  + session seek point) and return its seq, so the assertion nests under it.
+     *  See {@link "./browser".MobileBackend.recordSettled}. */
+    recordSettled(action: string, fields: Partial<RecordableFields>, waitedMs: number, error?: string): Promise<number | undefined>;
+}
+/** Silent (non-recorded) reads a locator exposes for `expect(...)` matchers to
+ *  poll. See {@link getLocatorProbe}. */
+export interface LocatorProbe {
+    /** Human label of the locator (for failure messages). */
+    readonly label: string;
+    isVisible(): Promise<boolean>;
+    textContent(timeout?: number): Promise<string | null>;
+    inputValue(timeout?: number): Promise<string>;
+    count(): Promise<number>;
+    isEnabled(timeout?: number): Promise<boolean>;
+    isChecked(timeout?: number): Promise<boolean>;
+    /** After the silent poll settles, emit the single settled browser step this
+     *  locator's `expect(...)` matcher assertion nests under, and return its seq
+     *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
+     *  poll time, `error` marks the step failed on a timed-out matcher. Returns
+     *  `undefined` when nothing is recording. */
+    settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
+}
+/** The silent-read probe for a locator — the seam `expect(locator)` matchers
+ *  poll (in index.ts) without pulling playwright types or the backend into
+ *  that module. */
+export declare function getLocatorProbe(loc: Locator): LocatorProbe;
+/** Per-session flavor of the `tap()` gesture. Desktop and mobile differ only
+ *  here; every other locator method is platform-agnostic. */
+export interface ActionStrategy {
+    /** Whether this session supports touch. Desktop → `tap()` throws. */
+    readonly touch: boolean;
+    /** Perform a touch tap on the resolved element (mobile only). */
+    tap(backend: LocatorBackend, loc: PWLocator, opts?: {
+        timeout?: number;
+        duration?: number;
+    }): Promise<void>;
+}
+/** Desktop: no touchscreen. `tap()` is a mobile gesture — steer authors to
+ *  `click()`. */
+export declare const desktopStrategy: ActionStrategy;
+/** Mobile: resolve the element's center and dispatch a real CDP touch with
+ *  the press dwell RN Pressables need (playwright's `tap()` has no dwell). */
+export declare const mobileStrategy: ActionStrategy;
+/**
+ * A lazy reference to element(s), resolved with auto-waiting at the moment an
+ * action runs. Mirrors playwright-core's `Locator`: STRICT by default — a
+ * locator resolving to multiple elements throws a strict-mode violation at
+ * action time rather than silently acting on one. Narrow with `exact: true`,
+ * a testid, `filter(...)`, or the explicit `first()`/`last()`/`nth(i)`
+ * opt-outs.
+ */
+export interface Locator {
+    /** Descendant CSS query, scoped to this locator's subtree. */
+    locator(css: string): Locator;
+    getByRole(role: string, opts?: GetByRoleOptions): Locator;
+    getByText(text: string | RegExp, opts?: GetByTextOptions): Locator;
+    getByLabel(text: string | RegExp, opts?: GetByTextOptions): Locator;
+    getByPlaceholder(text: string | RegExp, opts?: GetByTextOptions): Locator;
+    getByAltText(text: string | RegExp, opts?: GetByTextOptions): Locator;
+    getByTitle(text: string | RegExp, opts?: GetByTextOptions): Locator;
+    getByTestId(testId: string): Locator;
+    /** Narrow the current match set by content or by a descendant locator. */
+    filter(opts: FilterOptions): Locator;
+    /** Intersect with another locator (both must match the same element). */
+    and(other: Locator): Locator;
+    /** Union with another locator (either may match). */
+    or(other: Locator): Locator;
+    /** Explicit strict-mode opt-out: the first resolved element. */
+    first(): Locator;
+    /** Explicit strict-mode opt-out: the last resolved element. */
+    last(): Locator;
+    /** Explicit strict-mode opt-out: the i-th resolved element (0-based). */
+    nth(index: number): Locator;
+    click(opts?: ClickOptions): Promise<void>;
+    dblclick(opts?: ClickOptions): Promise<void>;
+    /** Touch-tap (mobile sessions only; throws on desktop). `duration`
+     *  overrides the press dwell. */
+    tap(opts?: {
+        timeout?: number;
+        duration?: number;
+    }): Promise<void>;
+    /** Set an input/textarea's value (React-safe: native setter + input event). */
+    fill(value: string, opts?: TimeoutOption): Promise<void>;
+    /** Clear an input's value (`fill("")`). */
+    clear(opts?: TimeoutOption): Promise<void>;
+    /** Focus and press a single key or chord (`"Enter"`, `"Control+A"`). */
+    press(key: string, opts?: TimeoutOption): Promise<void>;
+    /** Focus and type character-by-character (fires keydown/keyup per char). */
+    pressSequentially(text: string, opts?: {
+        timeout?: number;
+        delay?: number;
+    }): Promise<void>;
+    check(opts?: TimeoutOption): Promise<void>;
+    uncheck(opts?: TimeoutOption): Promise<void>;
+    setChecked(checked: boolean, opts?: TimeoutOption): Promise<void>;
+    /** Select `<option>`(s) by value/label/index; returns the selected values,
+     *  provenance-wrapped so `expect(...)` on them nests under this step. */
+    selectOption(values: string | string[] | {
+        label?: string;
+        value?: string;
+        index?: number;
+    }, opts?: TimeoutOption): Promise<Wrapped<string[]>>;
+    hover(opts?: TimeoutOption): Promise<void>;
+    focus(opts?: TimeoutOption): Promise<void>;
+    blur(opts?: TimeoutOption): Promise<void>;
+    scrollIntoViewIfNeeded(opts?: TimeoutOption): Promise<void>;
+    dragTo(target: Locator, opts?: TimeoutOption): Promise<void>;
+    textContent(opts?: TimeoutOption): Promise<Wrapped<string | null>>;
+    innerText(opts?: TimeoutOption): Promise<Wrapped<string>>;
+    innerHTML(opts?: TimeoutOption): Promise<Wrapped<string>>;
+    inputValue(opts?: TimeoutOption): Promise<Wrapped<string>>;
+    getAttribute(name: string, opts?: TimeoutOption): Promise<Wrapped<string | null>>;
+    isVisible(): Promise<Wrapped<boolean>>;
+    isHidden(): Promise<Wrapped<boolean>>;
+    isEnabled(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+    isDisabled(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+    isChecked(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+    isEditable(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+    count(): Promise<Wrapped<number>>;
+    /** Resolve to one locator per current match (handle-free — each is pinned
+     *  with `nth(i)`). One recorded event. */
+    all(): Promise<Locator[]>;
+    allTextContents(): Promise<Wrapped<string[]>>;
+    allInnerTexts(): Promise<Wrapped<string[]>>;
+    boundingBox(opts?: TimeoutOption): Promise<Wrapped<BoundingBox | null>>;
+    /** Evaluate a function against the resolved element. `description` labels
+     *  the step in the timeline (spectest keeps it for readability). */
+    evaluate<T = unknown>(description: string, fn: string | ((el: Element, arg?: unknown) => T), arg?: unknown): Promise<Wrapped<T>>;
+    /** Wait until the element reaches `state` (default `"visible"`). */
+    waitFor(opts?: {
+        state?: WaitForState;
+        timeout?: number;
+    }): Promise<void>;
+}
+/** Build a lazy {@link Locator} over `chain`. `backend`/`strategy` are the
+ *  session seams; composition methods extend the chain, terminal methods run
+ *  through `backend.pageOp`. */
+export declare function makeLocator(backend: LocatorBackend, strategy: ActionStrategy, chain: Chain): Locator;
+export {};

package/dist/locator.js

@@ -0,0 +1,293 @@
+// Playwright-native locators for the browser/mobile test surface.
+//
+// A `Locator` mirrors playwright-core's `Locator` shape — the same method
+// names, arguments, and semantics (STRICT mode included) — but it is our own
+// type, not playwright's, so we control exactly what's exposed. Everything
+// here is recordable in the dashboard timeline; playwright methods that bypass
+// the recorder (`elementHandle()`, `page()`, `contentFrame()`) are
+// deliberately absent.
+//
+// The implementation is a **lazy call-chain**. A locator carries a list of
+// `Step`s (getByRole → filter → nth …) and never touches a page until an
+// action runs. At action time `lower(page, chain)` folds the steps onto the
+// live playwright `Page`, producing a real playwright `Locator` that is used
+// once and discarded. This is load-bearing: the persistent browser session
+// swaps its underlying `page` on DNS-recovery (`rebuildView` in browser.ts),
+// so a locator must re-resolve against the *current* page every time — it can
+// never pin a playwright `Locator`/`Page` at creation.
+//
+// Composition (`locator`, `getBy*`, `filter`, `and`, `or`, `first`/`last`/
+// `nth`) returns a new lazy `Locator` with an extended chain. Terminal methods
+// (actions, reads, `waitFor`) run inside `backend.pageOp`, so each
+// author-facing call is exactly one recorded browser event (with its rrweb
+// drain), whatever playwright work it composes underneath.
+import { truncateUtf8 } from "./recorder.js";
+/** Default deadline for a locator action/read's target to become actionable.
+ *  Playwright's own default is 30s — far too slow-failing for tests; 5s
+ *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
+ *  `undefined` falls through to the context default (also set to this in
+ *  browser.ts's `contextFor`). Navigations keep a longer deadline. */
+export const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+// Brand + chain carrier. Both are `Symbol.for` keys so `JSON.stringify` drops
+// them (locators are never serialized) while runtime code can still detect a
+// locator and read a nested one's chain during lowering.
+const LOCATOR_BRAND = Symbol.for("spectest.locator");
+const CHAIN = Symbol.for("spectest.locatorChain");
+/** True if `x` is a spectest {@link Locator}. */
+export function isLocator(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        x[LOCATOR_BRAND] === true);
+}
+function chainOf(loc) {
+    return loc[CHAIN];
+}
+// ────────────────────────────────────────────────────────────────────────
+// Lowering: chain → live playwright Locator
+// ────────────────────────────────────────────────────────────────────────
+/** Fold a chain onto a live page, producing a throwaway playwright Locator.
+ *  Nested spectest locators (`filter({has})`, `and`, `or`) are lowered
+ *  recursively against the same page. */
+export function lower(page, chain) {
+    let cur = page;
+    for (const step of chain.steps) {
+        cur = applyStep(page, cur, step);
+    }
+    return cur;
+}
+function applyStep(page, cur, step) {
+    switch (step.m) {
+        case "locator":
+            return cur.locator(step.args[0]);
+        case "getByRole":
+            return cur.getByRole(step.args[0], step.args[1]);
+        case "getByText":
+            return cur.getByText(step.args[0], step.args[1]);
+        case "getByLabel":
+            return cur.getByLabel(step.args[0], step.args[1]);
+        case "getByPlaceholder":
+            return cur.getByPlaceholder(step.args[0], step.args[1]);
+        case "getByAltText":
+            return cur.getByAltText(step.args[0], step.args[1]);
+        case "getByTitle":
+            return cur.getByTitle(step.args[0], step.args[1]);
+        case "getByTestId":
+            return cur.getByTestId(step.args[0]);
+        case "filter": {
+            const o = step.args[0];
+            return cur.filter({
+                hasText: o.hasText,
+                hasNotText: o.hasNotText,
+                has: o.has ? lower(page, chainOf(o.has)) : undefined,
+                hasNot: o.hasNot ? lower(page, chainOf(o.hasNot)) : undefined,
+            });
+        }
+        case "and":
+            return cur.and(lower(page, chainOf(step.args[0])));
+        case "or":
+            return cur.or(lower(page, chainOf(step.args[0])));
+        case "first":
+            return cur.first();
+        case "last":
+            return cur.last();
+        case "nth":
+            return cur.nth(step.args[0]);
+    }
+}
+// ────────────────────────────────────────────────────────────────────────
+// Human labels (event `selector` field / dashboard timeline)
+// ────────────────────────────────────────────────────────────────────────
+function textArg(v) {
+    return v instanceof RegExp ? `/${v.source}/${v.flags}` : JSON.stringify(v);
+}
+function stepLabel(step) {
+    switch (step.m) {
+        case "locator":
+            return `css ${JSON.stringify(step.args[0])}`;
+        case "getByRole": {
+            const name = step.args[1]?.name;
+            return name !== undefined
+                ? `role ${step.args[0]} ${textArg(name)}`
+                : `role ${step.args[0]}`;
+        }
+        case "getByText":
+            return `text ${textArg(step.args[0])}`;
+        case "getByLabel":
+            return `label ${textArg(step.args[0])}`;
+        case "getByPlaceholder":
+            return `placeholder ${textArg(step.args[0])}`;
+        case "getByAltText":
+            return `alt ${textArg(step.args[0])}`;
+        case "getByTitle":
+            return `title ${textArg(step.args[0])}`;
+        case "getByTestId":
+            return `testid ${JSON.stringify(step.args[0])}`;
+        case "filter": {
+            const o = step.args[0];
+            if (o.has)
+                return `filter(has: ${chainLabel(chainOf(o.has))})`;
+            if (o.hasNot)
+                return `filter(hasNot: ${chainLabel(chainOf(o.hasNot))})`;
+            if (o.hasText !== undefined)
+                return `filter(hasText: ${textArg(o.hasText)})`;
+            if (o.hasNotText !== undefined)
+                return `filter(hasNotText: ${textArg(o.hasNotText)})`;
+            return "filter()";
+        }
+        case "and":
+            return `and(${chainLabel(chainOf(step.args[0]))})`;
+        case "or":
+            return `or(${chainLabel(chainOf(step.args[0]))})`;
+        case "first":
+            return ".first()";
+        case "last":
+            return ".last()";
+        case "nth":
+            return `.nth(${step.args[0]})`;
+    }
+}
+/** Short human label for a chain, e.g.
+ *  `role button "15" ‹ filter(has: text "July 2026") ‹ css .calendar`.
+ *  Root first; narrowing steps appended in reading order. */
+export function chainLabel(chain) {
+    const [root, ...rest] = chain.steps;
+    if (!root)
+        return "<empty>";
+    let out = stepLabel(root);
+    for (const s of rest) {
+        // first/last/nth read naturally appended ("… .first()"); the rest are
+        // narrowing relations, joined with a left-arrow.
+        out += s.m === "first" || s.m === "last" || s.m === "nth"
+            ? ` ${stepLabel(s)}`
+            : ` ‹ ${stepLabel(s)}`;
+    }
+    return out;
+}
+const PROBE = Symbol.for("spectest.locatorProbe");
+/** The silent-read probe for a locator — the seam `expect(locator)` matchers
+ *  poll (in index.ts) without pulling playwright types or the backend into
+ *  that module. */
+export function getLocatorProbe(loc) {
+    return loc[PROBE];
+}
+/** Desktop: no touchscreen. `tap()` is a mobile gesture — steer authors to
+ *  `click()`. */
+export const desktopStrategy = {
+    touch: false,
+    async tap() {
+        throw new Error("tap() is a mobile-session gesture (ctx.mobile). On a desktop ctx.browser() session use click().");
+    },
+};
+/** Mobile: resolve the element's center and dispatch a real CDP touch with
+ *  the press dwell RN Pressables need (playwright's `tap()` has no dwell). */
+export const mobileStrategy = {
+    touch: true,
+    async tap(backend, loc, opts) {
+        await loc.waitFor({ state: "visible", timeout: opts?.timeout });
+        await loc.scrollIntoViewIfNeeded({ timeout: opts?.timeout });
+        const box = await loc.boundingBox();
+        if (!box)
+            throw new Error("tap: element vanished before it could be tapped");
+        await backend.rawTap(box.x + box.width / 2, box.y + box.height / 2, opts?.duration);
+    },
+};
+// ────────────────────────────────────────────────────────────────────────
+// Factory
+// ────────────────────────────────────────────────────────────────────────
+/** Build a lazy {@link Locator} over `chain`. `backend`/`strategy` are the
+ *  session seams; composition methods extend the chain, terminal methods run
+ *  through `backend.pageOp`. */
+export function makeLocator(backend, strategy, chain) {
+    const label = chainLabel(chain);
+    const extend = (step) => makeLocator(backend, strategy, { steps: [...chain.steps, step] });
+    // One recorded event, result NOT wrapped (void/action).
+    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain), page));
+    // One recorded event, result provenance-wrapped for expect().
+    const read = (action, fn) => backend.pageOp(action, { selector: label }, (page) => fn(lower(page, chain)), {
+        wrap: true,
+    });
+    // Silent, non-recorded reads for expect(locator) matchers to poll.
+    const probe = {
+        label,
+        isVisible: () => backend.silentRead((page) => lower(page, chain).isVisible()),
+        textContent: (timeout) => backend.silentRead((page) => lower(page, chain).textContent({ timeout })),
+        inputValue: (timeout) => backend.silentRead((page) => lower(page, chain).inputValue({ timeout })),
+        count: () => backend.silentRead((page) => lower(page, chain).count()),
+        isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
+        isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
+        settle: (action, waitedMs, error) => backend.recordSettled(action, { selector: label }, waitedMs, error),
+    };
+    const loc = {
+        [LOCATOR_BRAND]: true,
+        [CHAIN]: chain,
+        // composition
+        locator: (css) => extend({ m: "locator", args: [css] }),
+        getByRole: (role, opts) => extend({ m: "getByRole", args: [role, opts] }),
+        getByText: (text, opts) => extend({ m: "getByText", args: [text, opts] }),
+        getByLabel: (text, opts) => extend({ m: "getByLabel", args: [text, opts] }),
+        getByPlaceholder: (text, opts) => extend({ m: "getByPlaceholder", args: [text, opts] }),
+        getByAltText: (text, opts) => extend({ m: "getByAltText", args: [text, opts] }),
+        getByTitle: (text, opts) => extend({ m: "getByTitle", args: [text, opts] }),
+        getByTestId: (id) => extend({ m: "getByTestId", args: [id] }),
+        filter: (opts) => extend({ m: "filter", args: [opts] }),
+        and: (other) => extend({ m: "and", args: [other] }),
+        or: (other) => extend({ m: "or", args: [other] }),
+        first: () => extend({ m: "first", args: [] }),
+        last: () => extend({ m: "last", args: [] }),
+        nth: (i) => extend({ m: "nth", args: [i] }),
+        // actions
+        click: (opts) => act("click", {}, (l) => l.click(opts)),
+        dblclick: (opts) => act("dblclick", {}, (l) => l.dblclick(opts)),
+        tap: (opts) => act("tap", {}, (l) => strategy.tap(backend, l, opts)),
+        fill: (value, opts) => {
+            const t = truncateUtf8(value);
+            return act("fill", { text: t.value, textTruncated: t.truncated }, (l) => l.fill(value, { timeout: opts?.timeout }));
+        },
+        clear: (opts) => act("clear", {}, (l) => l.clear({ timeout: opts?.timeout })),
+        press: (key, opts) => act("press", { key }, (l) => l.press(key, { timeout: opts?.timeout })),
+        pressSequentially: (text, opts) => {
+            const t = truncateUtf8(text);
+            return act("pressSequentially", { text: t.value, textTruncated: t.truncated }, (l) => l.pressSequentially(text, { timeout: opts?.timeout, delay: opts?.delay }));
+        },
+        check: (opts) => act("check", {}, (l) => l.check({ timeout: opts?.timeout })),
+        uncheck: (opts) => act("uncheck", {}, (l) => l.uncheck({ timeout: opts?.timeout })),
+        setChecked: (checked, opts) => act("setChecked", {}, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
+        selectOption: (values, opts) => read("selectOption", (l) => l.selectOption(values, { timeout: opts?.timeout })),
+        hover: (opts) => act("hover", {}, (l) => l.hover({ timeout: opts?.timeout })),
+        focus: (opts) => act("focus", {}, (l) => l.focus({ timeout: opts?.timeout })),
+        blur: (opts) => act("blur", {}, (l) => l.blur({ timeout: opts?.timeout })),
+        scrollIntoViewIfNeeded: (opts) => act("scrollIntoViewIfNeeded", {}, (l) => l.scrollIntoViewIfNeeded({ timeout: opts?.timeout })),
+        dragTo: (target, opts) => act("dragTo", {}, (l, page) => l.dragTo(lower(page, chainOf(target)), { timeout: opts?.timeout })),
+        // reads
+        textContent: (opts) => read("textContent", (l) => l.textContent({ timeout: opts?.timeout })),
+        innerText: (opts) => read("innerText", (l) => l.innerText({ timeout: opts?.timeout })),
+        innerHTML: (opts) => read("innerHTML", (l) => l.innerHTML({ timeout: opts?.timeout })),
+        inputValue: (opts) => read("inputValue", (l) => l.inputValue({ timeout: opts?.timeout })),
+        getAttribute: (name, opts) => read("getAttribute", (l) => l.getAttribute(name, { timeout: opts?.timeout })),
+        isVisible: () => read("isVisible", (l) => l.isVisible()),
+        isHidden: () => read("isHidden", (l) => l.isHidden()),
+        isEnabled: (opts) => read("isEnabled", (l) => l.isEnabled({ timeout: opts?.timeout })),
+        isDisabled: (opts) => read("isDisabled", (l) => l.isDisabled({ timeout: opts?.timeout })),
+        isChecked: (opts) => read("isChecked", (l) => l.isChecked({ timeout: opts?.timeout })),
+        isEditable: (opts) => read("isEditable", (l) => l.isEditable({ timeout: opts?.timeout })),
+        count: () => read("count", (l) => l.count()),
+        allTextContents: () => read("allTextContents", (l) => l.allTextContents()),
+        allInnerTexts: () => read("allInnerTexts", (l) => l.allInnerTexts()),
+        boundingBox: (opts) => read("boundingBox", (l) => l.boundingBox({ timeout: opts?.timeout })),
+        async all() {
+            // count() lowered once (one event), then one child locator per match,
+            // each pinned with nth(i). Stays lazy + handle-free.
+            const n = await act("all", {}, (l) => l.count());
+            const out = [];
+            for (let i = 0; i < n; i++)
+                out.push(extend({ m: "nth", args: [i] }));
+            return out;
+        },
+        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => lower(page, chain).evaluate(fn, arg), { wrap: true }),
+        waitFor: (opts) => act("waitFor", {}, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
+    };
+    // Attach the silent-read probe under its symbol (kept off the typed literal
+    // so declaration order stays simple).
+    loc[PROBE] = probe;
+    return loc;
+}

package/dist/mobile.d.ts

@@ -0,0 +1,71 @@
+import type { Browser, BrowserSessionRecorder, SafeAreaInsets, Touchscreen } from "./browser.js";
+/** Branded handle a mobile-app component (e.g. `expo()`) exposes on
+ *  `ctx.svc.<name>`. The brand is a `Symbol.for` key so `JSON.stringify`
+ *  drops it (wire-invisible) while `ctx.mobile(...)` can still type-check
+ *  against it. */
+export declare const MOBILE_APP: unique symbol;
+/** What `ctx.mobile(...)` accepts — produced by a mobile-app component's
+ *  `helpers` factory. Carries the in-VM URL the session auto-navigates to. */
+export interface MobileApp {
+    readonly [MOBILE_APP]: true;
+    /** Resolved in-VM URL of the app's web build (e.g. `http://app.internal:8081`). */
+    readonly url: string;
+    /** Optional script installed before the session's first navigation, so it
+     *  runs ahead of the app bundle on the very first document (no relaunch) —
+     *  the place to plant reduced-motion / `Notification` shims once for every
+     *  `ctx.mobile(app)` call. Set via `expo({ initScript })`. */
+    readonly initScript?: string;
+}
+/** True if `x` is a {@link MobileApp} handle. */
+export declare function isMobileApp(x: unknown): x is MobileApp;
+/** Build a {@link MobileApp} handle from a resolved URL (and an optional
+ *  init script installed before the session's first navigation). */
+export declare function mobileApp(url: string, initScript?: string): MobileApp;
+/**
+ * A phone-emulated app session. The full {@link Browser} surface (locators,
+ * `keyboard`/`mouse`, `evaluate`, …) plus a `touchscreen` and `swipe`. Opened
+ * via `ctx.mobile(app)` already on the app.
+ *
+ * The device is fixed (latest iPhone: viewport, DPR, mobile UA, touch). A
+ * locator's `tap()` on this session uses a real CDP touch with the RN press
+ * dwell; `getByTestId` targets `testID`, `getByLabel` targets
+ * `accessibilityLabel`.
+ */
+export interface Mobile extends Browser {
+    /** Coordinate touch taps (mobile escape hatch — prefer locator `tap()`). */
+    readonly touchscreen: Touchscreen;
+    /** Swipe the screen in a direction (a touch drag from the center). */
+    swipe(direction: "up" | "down" | "left" | "right", opts?: {
+        distance?: number;
+    }): Promise<void>;
+}
+/**
+ * Open an EPHEMERAL phone-emulated session pointed at `url` (`close()`
+ * destroys it). Library callers only — the daemon's `ctx.mobile(app)` goes
+ * through {@link openPersistentMobile} so sessions survive across tests.
+ */
+export declare function openMobile(opts: {
+    url?: string;
+    recorder: BrowserSessionRecorder | null;
+}): Promise<Mobile>;
+/**
+ * Acquire the persistent phone-emulated session for an app (one per app URL,
+ * created on first use). The daemon calls this from `ctx.mobile(app)` with a
+ * per-test rrweb recorder; the resulting record carries `frame: "mobile"` so
+ * the dashboard renders a phone bezel. `detach` is the test-end hook;
+ * `mobile.close()` destroys the session for real.
+ */
+export declare function openPersistentMobile(opts: {
+    url: string;
+    recorder: BrowserSessionRecorder | null;
+    /** Installed before the fresh session's first navigation (ignored on an
+     *  attached session, which already carries it on the forked holder). */
+    initScript?: string;
+}): Promise<{
+    mobile: Mobile;
+    attached: boolean;
+    detach(): Promise<void>;
+    /** Safe-area insets emulated on the view (`null` when the CDP override
+     *  is unavailable) — the daemon stamps them onto the session record. */
+    safeAreaInsets: SafeAreaInsets | null;
+}>;