@specific.dev/spectest 0.21.0 → 0.23.0

package/src/browser.ts

@@ -37,6 +37,18 @@ import { generateId } from "./ids.js";
 import { recordBrowser, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
+import {
+  DEFAULT_ACTION_TIMEOUT_MS,
+  desktopStrategy,
+  makeLocator,
+  mobileStrategy,
+} from "./locator.js";
+import type {
+  ActionStrategy,
+  GetByRoleOptions,
+  GetByTextOptions,
+  Locator,
+} from "./locator.js";
 
 import { chromium } from "playwright-core";
 import type {
@@ -66,6 +78,16 @@ export interface BrowserOptions {
   frame?: "browser" | "mobile";
   /** Initial URL to navigate to before the constructor returns. */
   url?: string;
+  /**
+   * Script installed (before the session's first navigation) to run in every
+   * document loaded from now on, BEFORE the document's own scripts — the
+   * deterministic way to plant shims (reduced-motion, `Notification`, …) that
+   * must beat the app bundle. Unlike installing one after the session is
+   * handed back, this wins the race on the FIRST document too, so no relaunch
+   * is needed. Rides snapshots into `dependsOn` children. For a mobile app,
+   * declare it once on the handle instead — `expo({ initScript })`.
+   */
+  initScript?: string;
   /**
    * Sink that receives rrweb event chunks. Each Browser op (navigate,
    * click, …) calls `recordStep` with the events that landed in
@@ -112,7 +134,7 @@ export interface BrowserSessionRecorder {
   readonly sessionId: string;
   /** Called for each drained chunk of rrweb events. */
   recordStep(step: BrowserSessionStep): void;
-  /** Optional: called whenever `Browser.navigate(url)` is invoked. */
+  /** Optional: called whenever `Browser.goto(url)` is invoked. */
   noteNavigation?(url: string): void;
   /**
    * Optional: register a captured artifact (screenshot bytes) for upload.
@@ -130,126 +152,128 @@ export interface BrowserSessionRecorder {
   }): void;
 }
 
+/** The page keyboard — Playwright's `page.keyboard`. Each method records one
+ *  browser event. */
+export interface Keyboard {
+  /** Press a key or chord by name (`"Enter"`, `"Tab"`, `"Control+A"`). */
+  press(key: string): Promise<void>;
+  /** Type character-by-character (fires keydown/keyup per char). */
+  type(text: string): Promise<void>;
+  /** Insert text in one shot (no per-char keydown — the paste path). */
+  insertText(text: string): Promise<void>;
+}
+
+/** The page mouse — Playwright's `page.mouse`. Coordinates are viewport CSS
+ *  pixels. Prefer locators; use these only for canvas/coordinate targets. */
+export interface Mouse {
+  click(x: number, y: number, opts?: { button?: "left" | "right" | "middle"; clickCount?: number }): Promise<void>;
+  dblclick(x: number, y: number): Promise<void>;
+  move(x: number, y: number): Promise<void>;
+  /** Wheel-scroll by a pixel delta. */
+  wheel(dx: number, dy: number): Promise<void>;
+}
+
 /**
- * Headless browser handle. Drive operations sequentially per view — the
- * recorder assumes op-at-a-time semantics (each op's rrweb drain is
- * attributed to it). For parallel browsing open multiple views.
+ * Headless browser session — Playwright `Page`-shaped. Select elements with
+ * the `getBy*`/`locator` roots (returning a {@link Locator}) and act on them;
+ * drive raw input via `keyboard`/`mouse`. Operations are sequential per
+ * session — the recorder attributes each op's rrweb drain to it — so for
+ * parallel browsing open multiple sessions.
  */
 export interface Browser {
-  /** Last-navigated URL (updated on navigate completion). */
-  readonly url: string;
-  /** Current page `<title>`. */
-  readonly title: string;
+  /** Current page URL (Playwright's synchronous `page.url()`). */
+  url(): string;
+  /** Current page `<title>` (async, like Playwright's `page.title()`). */
+  title(): Promise<string>;
   /** Navigate to a URL; resolves when the main frame's load completes. */
-  navigate(url: string): Promise<void>;
-  /**
-   * Evaluate JS in the page and return the JSON-deserialised result.
-   * Accepts a single expression or a statement body (`const x = …;
-   * return x;`) — statement bodies are auto-wrapped in an async IIFE, so
-   * `return` and `await` work without manual wrapping.
-   *
-   * `description` is a short human-readable label for what the
-   * snippet is doing ("read rendered todo list"); it surfaces in the
-   * test event log so the step list isn't a wall of minified code.
-   */
-  evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
+  goto(url: string): Promise<void>;
+  /** Navigate back in session history. */
+  goBack(): Promise<void>;
+  /** Navigate forward in session history. */
+  goForward(): Promise<void>;
+  /** Reload the current page. */
+  reload(): Promise<void>;
+
+  readonly keyboard: Keyboard;
+  readonly mouse: Mouse;
+
+  /** Root CSS query. */
+  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;
+
   /**
-   * Install a script that runs in every document loaded from now on, BEFORE
-   * any of the document's own scripts execute (CDP
-   * `Page.addScriptToEvaluateOnNewDocument` — the Playwright `addInitScript`
-   * equivalent). The deterministic way to plant shims and instrumentation
-   * (`fetch`/`XMLHttpRequest` wrappers, clock stubs, feature flags): unlike an
-   * `evaluate` racing the app bundle after a navigation, an init script is
-   * guaranteed to win.
-   *
-   * Does NOT run in the *current* document — call it before the `navigate`
-   * (or in-page `location.assign`) whose document needs it. Installed
-   * scripts persist for the browser session's lifetime, which for the
-   * persistent `ctx.browser()`/`ctx.mobile()` sessions means they ride
-   * snapshots into `dependsOn` children like the rest of the session state.
+   * Evaluate JS in the page and return the JSON-deserialised, provenance-
+   * wrapped result. `fn` is a real function (serialized by Playwright, with an
+   * optional serializable `arg`) or a string expression / statement body
+   * (auto-wrapped in an async IIFE, so `return`/`await` work).
    *
-   * `description` labels the step in the test event log.
+   * `description` is a short human label ("read rendered todo list") surfaced
+   * in the timeline so the step list isn't a wall of minified code — spectest
+   * keeps it (the one deviation from Playwright's bare `evaluate`).
    */
-  addInitScript(description: string, source: string): Promise<void>;
+  evaluate<T = unknown>(
+    description: string,
+    fn: string | ((arg?: unknown) => T | Promise<T>),
+    arg?: unknown,
+  ): Promise<Wrapped<T>>;
   /**
-   * Poll `expression` in the page until it returns a truthy value
-   * (the returned value is what `waitFor` resolves with). Useful for
-   * UI assertions that need to wait for an async render — instead of
-   * a manual `while (Date.now() < deadline) await evaluate(...)` loop
-   * which clutters the test log with one event per poll, this records
-   * a single `waitFor` event with the total wait time and how many
-   * attempts it took.
-   *
-   * Express the predicate as "return the data if ready, else falsy":
-   *
-   * ```ts
-   * const items = await browser.waitFor<string[]>(
-   *   "todo appears",
-   *   "(() => { const xs = [...document.querySelectorAll('li')].map(l => l.textContent); return xs.includes('hi') ? xs : null; })()",
-   * );
-   * ```
-   *
-   * Defaults: 5 s total timeout, 100 ms between polls.
+   * Poll `fn` in the page until it returns a truthy value (Playwright's
+   * `page.waitForFunction`), recorded as ONE step with the total wait + poll
+   * count. `fn` is a function (with optional `arg`) or a string expression.
+   * `description` labels the step. Defaults: 5 s timeout, 100 ms polling.
    */
-  waitFor<T = unknown>(
+  waitForFunction<T = unknown>(
     description: string,
-    expression: string,
-    options?: { timeoutMs?: number; intervalMs?: number },
+    fn: string | ((arg?: unknown) => T),
+    arg?: unknown,
+    options?: { timeout?: number; polling?: number },
   ): Promise<Wrapped<T>>;
-  /** Wait for `selector` to be actionable and click its center. */
-  click(selector: string): Promise<void>;
-  /** Click at the given viewport coordinates. */
-  clickAt(x: number, y: number): Promise<void>;
-  /** Insert text into the focused element (no `keydown` — same path as paste). */
-  type(text: string): Promise<void>;
-  /** Press a named key (`"Enter"`, `"Tab"`, …) or single character. */
-  press(key: string): Promise<void>;
-  /** Scroll the viewport by the given pixel delta. */
-  scroll(dx: number, dy: number): Promise<void>;
-  /** Wait for `selector` to exist and scroll it into view. */
-  scrollTo(selector: string): Promise<void>;
-  /** Navigate back in session history. */
-  back(): Promise<void>;
-  /** Navigate forward in session history. */
-  forward(): Promise<void>;
-  /** Reload the current page. */
-  reload(): Promise<void>;
   /**
-   * Capture a PNG screenshot of the viewport and upload it as a
-   * downloadable **artifact**. Resolves to the artifact's `art_…` id —
-   * fetch the image locally with `spectest artifact download <id>`.
-   * Only available inside an eval (`spectest_eval` / `spectest env eval`);
-   * throws with a clear message during test runs.
+   * Capture a PNG screenshot of the viewport and upload it as a downloadable
+   * **artifact**. Resolves to the artifact's `art_…` id — fetch it locally
+   * with `spectest artifact download <id>`. Eval-only (`spectest_eval` /
+   * `spectest env eval`); throws with a clear message during test runs.
    */
   screenshot(): Promise<string>;
   /**
-   * Destroy the underlying view. Idempotent; drains any pending rrweb
-   * events first. For the persistent session behind `ctx.browser()` /
-   * `ctx.mobile()` this is the escape hatch to a FRESH browser — the
-   * shared instance is discarded and the next call creates a new one.
-   * Don't call it for routine cleanup: the daemon detaches recording at
-   * test end automatically and deliberately keeps the browser alive so
-   * dependent tests inherit its state.
+   * Destroy the underlying view. Idempotent; drains pending rrweb events
+   * first. For the persistent session behind `ctx.browser()`/`ctx.mobile()`
+   * this is the escape hatch to a FRESH browser — the shared instance is
+   * discarded and the next call creates a new one. Don't call it for routine
+   * cleanup: the daemon detaches recording at test end and keeps the browser
+   * alive so dependent tests inherit its state.
    */
   close(): Promise<void>;
 }
 
+/** The touchscreen — Playwright's `page.touchscreen`, but with the press
+ *  dwell RN Pressables need. Mobile sessions only. */
+export interface Touchscreen {
+  /** Touch-tap at viewport CSS coordinates. `duration` overrides the dwell. */
+  tap(x: number, y: number, opts?: { duration?: number }): Promise<void>;
+}
+
 /**
- * A {@link Browser} with the lower-level touch primitives the mobile
- * (`ctx.mobile`) facade is built on. Not exposed to test authors directly —
- * `sdk/src/mobile.ts` wraps it in the ergonomic locator/gesture API. The
- * touch ops dispatch real `Input.dispatchTouchEvent` sequences (so RN-Web's
- * responder system sees genuine touches) and ride the same recorder + rrweb
- * drain as the desktop verbs.
+ * The internal impl type `buildBackend` returns — the {@link Browser} surface
+ * plus the mobile extensions and the low-level primitives the locator layer
+ * composes on. `ctx.browser()` exposes the narrower {@link Browser} view;
+ * `ctx.mobile()` the {@link import("./mobile.js").Mobile} view (adds
+ * `touchscreen`/`swipe`). The extras below are never in a public type.
  */
 export interface MobileBackend extends Browser {
-  /** Safe-area insets emulated on this view (`null` on desktop views or
-   *  when the CDP override is unavailable). The daemon stamps these onto
-   *  the session record for the dashboard's replay. */
+  /** Safe-area insets emulated on this view (`null` on desktop views or when
+   *  the CDP override is unavailable). Stamped onto the session record. */
   readonly safeAreaInsets: SafeAreaInsets | null;
-  /** Touch-tap at viewport CSS coordinates (touchStart → short dwell →
-   *  touchEnd; `durationMs` overrides the dwell). */
-  tapAt(x: number, y: number, opts?: { durationMs?: number }): Promise<void>;
+  readonly touchscreen: Touchscreen;
+  /** Swipe the screen (a touch drag from the center). Mobile extension —
+   *  Playwright has no swipe. */
+  swipe(direction: "up" | "down" | "left" | "right", opts?: { distance?: number }): Promise<void>;
   /** Touch-drag from (x,y) by (dx,dy) over a short move sequence. */
   swipeBy(x: number, y: number, dx: number, dy: number): Promise<void>;
   /**
@@ -258,24 +282,47 @@ export interface MobileBackend extends Browser {
    * drains it.
    */
   probe<T = unknown>(expression: string): Promise<T>;
+  /**
+   * Run `fn` against the live page WITHOUT recording an event or draining
+   * rrweb — the poll path for `expect(locator)` matchers (one browser event
+   * per retry would flood the timeline).
+   */
+  silentRead<T>(fn: (page: Page) => Promise<T>): Promise<T>;
   /**
    * Run `fn` against the live playwright {@link Page}, recorded as a single
-   * `action` event (with the usual rrweb drain). The locator layer's hook:
-   * one author-facing locator action = one recorded event, however many
-   * playwright calls it composes. `evaluate`/`waitFor` actions get their
-   * return value provenance-wrapped like the first-class verbs.
+   * event (with the usual rrweb drain). The locator layer's hook: one
+   * author-facing action = one recorded event, however many playwright calls
+   * it composes. When `opts.wrap` the return value is provenance-wrapped
+   * (reads), so a later `expect(...)` nests under the step.
    */
   pageOp<T>(
     action: BrowserAction,
     fields: Partial<RecordableFields>,
     fn: (page: Page) => Promise<T>,
+    opts?: { wrap?: boolean },
   ): Promise<T>;
   /**
    * Unrecorded CDP touch tap (touchStart → dwell → touchEnd). The locator
    * layer composes it inside a {@link pageOp} so a locator `tap()` stays a
-   * single recorded event; `tapAt` is the recorded public twin.
+   * single recorded event; `touchscreen.tap` is the recorded public twin.
    */
   rawTap(x: number, y: number, durationMs?: number): Promise<void>;
+  /**
+   * Record ONE settled browser event for an `expect(locator)` web-first
+   * matcher and return its seq. The matcher already read the value by polling
+   * {@link silentRead} (one event per retry would flood the timeline); this
+   * emits the single timeline step — the locator label + the session seek
+   * point (`sessionTimestamp`) to the settled frame — so the assertion the
+   * caller records next nests under it via `sourceSeq`, exactly as
+   * `expect(await loc.isVisible())` does. Drains rrweb like any recorded op.
+   * Returns `undefined` when nothing is recording.
+   */
+  recordSettled(
+    action: BrowserAction,
+    fields: Partial<RecordableFields>,
+    waitedMs: number,
+    error?: string,
+  ): Promise<number | undefined>;
 }
 
 // Default extra flags for headless Chromium inside a Firecracker microVM.
@@ -300,14 +347,12 @@ const CHROME_ARGV = [
   "--dns-over-https-mode=off",
 ];
 
-/** Default touchStart→touchEnd dwell for `tapAt` — see the comment there. */
+/** Default touchStart→touchEnd dwell for touch taps — see `rawTap`. */
 const TAP_DWELL_MS = 60;
 
-/** Default deadline for element-targeting ops (click/scrollTo and the mobile
- *  locator actions). Playwright's own default is 30 s — far too slow-failing
- *  for tests; 5 s matches the pre-Playwright behavior. Navigations keep a
- *  longer 30 s deadline (cold app servers). */
-const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+/** Navigations keep a longer deadline than locator actions (cold app
+ *  servers). The action default lives in `locator.ts`
+ *  ({@link DEFAULT_ACTION_TIMEOUT_MS}) since the locator layer owns it. */
 const NAVIGATION_TIMEOUT_MS = 30_000;
 
 // ────────────────────────────────────────────────────────────────────────
@@ -926,8 +971,9 @@ interface ViewHolder {
    *  views or when the CDP override is unavailable). Stamped onto the
    *  session record so the replay can mirror them. */
   safeAreaInsets: SafeAreaInsets | null;
-  /** User scripts installed via `addInitScript`, kept so the DNS-recovery
-   *  rebuild can re-install them on the replacement page. */
+  /** Declared init scripts installed on this session (via
+   *  `BrowserOptions.initScript` / a mobile app's `initScript`), kept so the
+   *  DNS-recovery rebuild can re-install them on the replacement page. */
   initScripts: string[];
 }
 
@@ -1067,8 +1113,9 @@ export async function openMobileBackend(
   // We deliberately don't forward `opts.url` to the constructor — going
   // through our own `navigate()` keeps the recorder log uniform (one
   // event per navigation, with timing) and drains rrweb after the load.
+  if (opts.initScript !== undefined) await installInitScript(holder, opts.initScript);
   if (opts.url !== undefined) {
-    await backend.navigate(opts.url);
+    await backend.goto(opts.url);
   }
   return backend;
 }
@@ -1112,6 +1159,20 @@ async function newHolder(
   return holder;
 }
 
+/**
+ * Install a declared init script (from `BrowserOptions.initScript` / a mobile
+ * app's `initScript`) on a fresh holder's page: it runs before every document
+ * loaded from now on, ahead of the document's own scripts. Called BEFORE the
+ * session's first navigation, so it wins the race on the first document too.
+ * Recorded via `holder.initScripts` so a DNS-recovery page rebuild
+ * (`rebuildView`) re-installs it. Declared config, not a test action, so it
+ * emits no timeline event.
+ */
+async function installInitScript(holder: ViewHolder, source: string): Promise<void> {
+  await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source });
+  holder.initScripts.push(source);
+}
+
 /**
  * What acquiring a persistent session returns. `detach` is the test-end
  * hook (final rrweb drain, stop writing to this test's recorder, keep the
@@ -1182,7 +1243,13 @@ export async function acquirePersistentBrowser(
       if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
     },
   });
-  if (!attached && opts.url !== undefined) await backend.navigate(opts.url);
+  // Fresh session only: an attached view already carries the init script on
+  // its (forked) holder, and first-call-wins means a later call's options
+  // don't retroactively apply.
+  if (!attached && opts.initScript !== undefined) {
+    await installInitScript(holder, opts.initScript);
+  }
+  if (!attached && opts.url !== undefined) await backend.goto(opts.url);
   return { browser: backend, attached, detach };
 }
 
@@ -1193,6 +1260,7 @@ export async function acquirePersistentBrowser(
 export async function acquirePersistentMobileBackend(
   url: string,
   recorder: BrowserSessionRecorder | null,
+  initScript?: string,
 ): Promise<PersistentBrowser> {
   const existing = SHARED_MOBILE.get(url);
   const holder =
@@ -1213,7 +1281,12 @@ export async function acquirePersistentMobileBackend(
       if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(url);
     },
   });
-  if (!existing) await backend.navigate(url);
+  if (!existing) {
+    // Fresh session: install the app's init script before the first
+    // navigation so its first document already has the shims.
+    if (initScript !== undefined) await installInitScript(holder, initScript);
+    await backend.goto(url);
+  }
   return { browser: backend, attached: existing !== undefined, detach };
 }
 
@@ -1322,6 +1395,7 @@ function buildBackend(
     action: BrowserAction,
     fields: Partial<RecordableFields>,
     fn: () => Promise<T>,
+    opts?: { wrap?: boolean },
   ): Promise<T> {
     const t = Date.now();
     const resv = reserveEvent();
@@ -1348,10 +1422,10 @@ function buildBackend(
         durationMs: endT - t,
       }, resv);
       await drain(action);
-      // Only `evaluate` and `waitFor` return user-visible JS values
-      // that someone is likely to assert on. Other actions return void
-      // or browser internals; leave them raw to avoid Proxy surprises.
-      if (seq !== undefined && (action === "evaluate" || action === "waitFor")) {
+      // Reads (`opts.wrap`) return user-visible JS values someone is likely to
+      // assert on — provenance-wrap so `expect(...)` nests under this step.
+      // Actions return void/internals; leave them raw to avoid Proxy surprises.
+      if (seq !== undefined && opts?.wrap) {
         return wrap(result, seq) as T;
       }
       return result;
@@ -1381,19 +1455,70 @@ function buildBackend(
     recordingEnded = true;
   }
 
+  const strategy: ActionStrategy = holder.device ? mobileStrategy : desktopStrategy;
+
+  const keyboard: Keyboard = {
+    press(key) {
+      return instrumented("press", { key }, () => holder.page.keyboard.press(key));
+    },
+    type(text) {
+      const t = truncateUtf8(text);
+      return instrumented("type", { text: t.value, textTruncated: t.truncated }, () =>
+        holder.page.keyboard.type(text),
+      );
+    },
+    insertText(text) {
+      // insertText path (no per-char keydown) — the paste path.
+      const t = truncateUtf8(text);
+      return instrumented("type", { text: t.value, textTruncated: t.truncated }, () =>
+        holder.page.keyboard.insertText(text),
+      );
+    },
+  };
+
+  const mouse: Mouse = {
+    click(x, y, opts) {
+      return instrumented("click", { x, y }, () => holder.page.mouse.click(x, y, opts));
+    },
+    dblclick(x, y) {
+      return instrumented("dblclick", { x, y }, () => holder.page.mouse.dblclick(x, y));
+    },
+    move(x, y) {
+      return instrumented("mouse.move", { x, y }, () => holder.page.mouse.move(x, y));
+    },
+    wheel(dx, dy) {
+      return instrumented("scroll", { dx, dy }, () => holder.page.mouse.wheel(dx, dy));
+    },
+  };
+
+  const touchscreen: Touchscreen = {
+    tap(x, y, opts) {
+      // Recorded as "tap"; the CDP touch (with dwell) fires RN-Web responders.
+      return instrumented("tap", { x, y }, () => backend.rawTap(x, y, opts?.duration));
+    },
+  };
+
   const backend: MobileBackend = {
-    get url() {
+    url() {
       return holder.page.url();
     },
-    get title() {
+    async title() {
+      try {
+        holder.lastTitle = await holder.page.title();
+      } catch {
+        /* page mid-navigation or closed — return the last cached title */
+      }
       return holder.lastTitle;
     },
     get safeAreaInsets() {
       return holder.safeAreaInsets;
     },
-    navigate(url) {
+    keyboard,
+    mouse,
+    touchscreen,
+    goto(url) {
       recorder?.noteNavigation?.(url);
-      return instrumented("navigate", { url }, async () => {
+      return instrumented("goto", { url }, async () => {
         try {
           await holder.page.goto(url, { waitUntil: "load" });
         } catch (err) {
@@ -1409,137 +1534,112 @@ function buildBackend(
         }
       });
     },
+    goBack() {
+      return instrumented("goBack", {}, async () => {
+        await holder.page.goBack();
+      });
+    },
+    goForward() {
+      return instrumented("goForward", {}, async () => {
+        await holder.page.goForward();
+      });
+    },
+    reload() {
+      return instrumented("reload", {}, async () => {
+        await holder.page.reload();
+      });
+    },
+
+    locator: (css) => makeLocator(backend, strategy, { steps: [{ m: "locator", args: [css] }] }),
+    getByRole: (role, opts) =>
+      makeLocator(backend, strategy, { steps: [{ m: "getByRole", args: [role, opts] }] }),
+    getByText: (text, opts) =>
+      makeLocator(backend, strategy, { steps: [{ m: "getByText", args: [text, opts] }] }),
+    getByLabel: (text, opts) =>
+      makeLocator(backend, strategy, { steps: [{ m: "getByLabel", args: [text, opts] }] }),
+    getByPlaceholder: (text, opts) =>
+      makeLocator(backend, strategy, { steps: [{ m: "getByPlaceholder", args: [text, opts] }] }),
+    getByAltText: (text, opts) =>
+      makeLocator(backend, strategy, { steps: [{ m: "getByAltText", args: [text, opts] }] }),
+    getByTitle: (text, opts) =>
+      makeLocator(backend, strategy, { steps: [{ m: "getByTitle", args: [text, opts] }] }),
+    getByTestId: (id) =>
+      makeLocator(backend, strategy, { steps: [{ m: "getByTestId", args: [id] }] }),
+
     async evaluate<T = unknown>(
       description: string,
-      script: string,
+      fn: string | ((arg?: unknown) => T | Promise<T>),
+      arg?: unknown,
     ): Promise<Wrapped<T>> {
-      const truncatedScript = truncateUtf8(script);
-      // `instrumented` wraps the result for evaluate/waitFor (see line ~622),
-      // so the value is a `Wrapped<T>` at runtime; the cast matches the type.
+      const src = typeof fn === "string" ? fn : fn.toString();
+      const t = truncateUtf8(src);
       return instrumented<T>(
         "evaluate",
-        {
-          description,
-          script: truncatedScript.value,
-          scriptTruncated: truncatedScript.truncated,
-        },
+        { description, script: t.value, scriptTruncated: t.truncated },
         async () => {
-          const v = (await holder.page.evaluate(toEvaluable(script))) as T;
-          return v;
+          if (typeof fn === "string") {
+            return (await holder.page.evaluate(toEvaluable(fn))) as T;
+          }
+          return (await holder.page.evaluate(fn as never, arg)) as T;
         },
+        { wrap: true },
       ) as Promise<Wrapped<T>>;
     },
-    addInitScript(description: string, source: string): Promise<void> {
-      const truncated = truncateUtf8(source);
-      return instrumented(
-        "addInitScript",
-        {
-          description,
-          script: truncated.value,
-          scriptTruncated: truncated.truncated,
-        },
-        async () => {
-          // Raw CDP (not context.addInitScript) so the script stays scoped
-          // to THIS page — the desktop context is shared across views.
-          await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
-            source,
-          });
-          // Remember it so a DNS-recovery page rebuild re-installs it.
-          holder.initScripts.push(source);
-        },
-      );
-    },
-    async waitFor<T = unknown>(
+    async waitForFunction<T = unknown>(
       description: string,
-      expression: string,
-      options: { timeoutMs?: number; intervalMs?: number } = {},
+      fn: string | ((arg?: unknown) => T),
+      arg?: unknown,
+      options: { timeout?: number; polling?: number } = {},
     ): Promise<Wrapped<T>> {
-      const timeoutMs = options.timeoutMs ?? 5_000;
-      const intervalMs = options.intervalMs ?? 100;
-      const truncatedScript = truncateUtf8(expression);
+      const timeoutMs = options.timeout ?? 5_000;
+      const intervalMs = options.polling ?? 100;
+      const src = typeof fn === "string" ? fn : fn.toString();
+      const t = truncateUtf8(src);
       // Pass `fields` by reference so the loop can stamp the final
       // attempt count onto the event before instrumented records it.
       const fields: Partial<RecordableFields> = {
         description,
-        script: truncatedScript.value,
-        scriptTruncated: truncatedScript.truncated,
+        script: t.value,
+        scriptTruncated: t.truncated,
         attempts: 0,
       };
-      // Normalised once up front — see `toEvaluable` (statement bodies work).
-      const evaluable = toEvaluable(expression);
-      return instrumented<T>("waitFor", fields, async () => {
-        const deadline = Date.now() + timeoutMs;
-        // (return value wrapped by `instrumented`; cast below matches.)
-        // The polling loop calls `view.evaluate` directly (not the
-        // wrapped `evaluate`) so it doesn't fan out into N events in
-        // the log or N rrweb drains. rrweb keeps buffering page-side
-        // throughout the wait; the wrapper's single drain at the end
-        // collects everything.
-        for (;;) {
-          fields.attempts = (fields.attempts ?? 0) + 1;
-          let v: unknown;
-          try {
-            v = await holder.page.evaluate(evaluable);
-          } catch (err) {
-            if (Date.now() >= deadline) throw err;
+      // Normalised once up front — string bodies go through `toEvaluable`
+      // (statement bodies work); functions run with `arg`.
+      const evaluable = typeof fn === "string" ? toEvaluable(fn) : null;
+      const evalOnce = (): Promise<unknown> =>
+        evaluable !== null
+          ? holder.page.evaluate(evaluable)
+          : holder.page.evaluate(fn as never, arg);
+      return instrumented<T>(
+        "waitForFunction",
+        fields,
+        async () => {
+          const deadline = Date.now() + timeoutMs;
+          // The polling loop calls `page.evaluate` directly (not the wrapped
+          // `evaluate`) so it doesn't fan out into N events or N rrweb drains.
+          // rrweb keeps buffering page-side; the wrapper's single drain at the
+          // end collects everything.
+          for (;;) {
+            fields.attempts = (fields.attempts ?? 0) + 1;
+            let v: unknown;
+            try {
+              v = await evalOnce();
+            } catch (err) {
+              if (Date.now() >= deadline) throw err;
+              await new Promise((r) => setTimeout(r, intervalMs));
+              continue;
+            }
+            if (v) return v as T;
+            if (Date.now() >= deadline) {
+              throw new Error(
+                `waitForFunction ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${fields.attempts} attempts)`,
+              );
+            }
             await new Promise((r) => setTimeout(r, intervalMs));
-            continue;
-          }
-          if (v) return v as T;
-          if (Date.now() >= deadline) {
-            throw new Error(
-              `waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${fields.attempts} attempts)`,
-            );
           }
-          await new Promise((r) => setTimeout(r, intervalMs));
-        }
-      }) as Promise<Wrapped<T>>;
-    },
-    click(selector) {
-      return instrumented("click", { selector }, () =>
-        holder.page.click(selector, { timeout: DEFAULT_ACTION_TIMEOUT_MS }),
-      );
-    },
-    clickAt(x, y) {
-      return instrumented("click", { x, y }, () => holder.page.mouse.click(x, y));
-    },
-    type(text) {
-      // insertText path (no per-char keydown) — same semantics as before.
-      const t = truncateUtf8(text);
-      return instrumented(
-        "type",
-        { text: t.value, textTruncated: t.truncated },
-        () => holder.page.keyboard.insertText(text),
-      );
-    },
-    press(key) {
-      return instrumented("press", { key }, () => holder.page.keyboard.press(key));
-    },
-    scroll(dx, dy) {
-      return instrumented("scroll", { dx, dy }, () => holder.page.mouse.wheel(dx, dy));
-    },
-    scrollTo(selector) {
-      return instrumented("scrollTo", { selector }, () =>
-        holder.page
-          .locator(selector)
-          .first()
-          .scrollIntoViewIfNeeded({ timeout: DEFAULT_ACTION_TIMEOUT_MS }),
-      );
-    },
-    back() {
-      return instrumented("back", {}, async () => {
-        await holder.page.goBack();
-      });
-    },
-    forward() {
-      return instrumented("forward", {}, async () => {
-        await holder.page.goForward();
-      });
-    },
-    reload() {
-      return instrumented("reload", {}, async () => {
-        await holder.page.reload();
-      });
+        },
+        { wrap: true },
+      ) as Promise<Wrapped<T>>;
     },
     async screenshot() {
       const fields: Partial<RecordableFields> = { format: "png" };
@@ -1619,10 +1719,17 @@ function buildBackend(
         touchPoints: [],
       });
     },
-    tapAt(x, y, opts) {
-      // Recorded as a "click" (the event schema stays desktop-shaped; the
-      // mobile facade owns the author-facing "tap" vocabulary).
-      return instrumented("click", { x, y }, () => backend.rawTap(x, y, opts?.durationMs));
+    async swipe(direction, opts) {
+      const vp = await backend.probe<{ w: number; h: number }>(
+        "({ w: window.innerWidth, h: window.innerHeight })",
+      );
+      const cx = vp.w / 2;
+      const cy = vp.h / 2;
+      const horiz = direction === "left" || direction === "right";
+      const dist = opts?.distance ?? Math.round((horiz ? vp.w : vp.h) * 0.5);
+      const dx = direction === "left" ? -dist : direction === "right" ? dist : 0;
+      const dy = direction === "up" ? -dist : direction === "down" ? dist : 0;
+      await backend.swipeBy(cx, cy, dx, dy);
     },
     swipeBy(x, y, dx, dy) {
       return instrumented("scroll", { dx, dy }, async () => {
@@ -1646,18 +1753,42 @@ function buildBackend(
     probe<T = unknown>(expression: string): Promise<T> {
       return holder.page.evaluate(expression) as Promise<T>;
     },
+    silentRead<T>(fn: (page: Page) => Promise<T>): Promise<T> {
+      return fn(holder.page);
+    },
+    async recordSettled(action, fields, waitedMs, error) {
+      // No page work — the matcher already read the value via silentRead. We
+      // only mint the timeline anchor: the seq the assertion nests under, plus
+      // `sessionTimestamp` (post-settle wall clock) so the dashboard seeks the
+      // replay to the frame the assertion observed.
+      const endT = Date.now();
+      const seq = recordBrowser({
+        action,
+        ...fields,
+        ...(recorder
+          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
+          : {}),
+        durationMs: waitedMs,
+        ...(error ? { error } : {}),
+      });
+      // Drain the rrweb the page buffered while the matcher waited into this
+      // step's chunk, so `settledTarget` has bounds to seek into.
+      await drain(action);
+      return seq;
+    },
     pageOp<T>(
       action: BrowserAction,
       fields: Partial<RecordableFields>,
       fn: (page: Page) => Promise<T>,
+      opts?: { wrap?: boolean },
     ): Promise<T> {
-      return instrumented(action, fields, () => fn(holder.page));
+      return instrumented(action, fields, () => fn(holder.page), opts);
     },
   };
   return { backend, detach: endRecording };
 }
 
-interface RecordableFields {
+export interface RecordableFields {
   url: string;
   selector: string;
   description: string;