@specific.dev/spectest 0.39.0 → 0.43.0

package/src/browser.ts

@@ -0,0 +1,2095 @@
+// Headless browser handle for tests. Thin wrapper around playwright-core
+// driving the guest's system Chromium (pipe transport — `chromium.launch`
+// with an explicit `executablePath`; `connectOverCDP` is off-limits, its
+// bundled `ws` client hangs under Bun). The wrapper keeps the public
+// surface stable (we swapped from Bun.WebView to Playwright without
+// changing tests) and routes every call through the recorder so browser
+// actions show up in a test's event log alongside exec/fetch/assertion
+// events. Playwright's client state (browser/context/page objects, the
+// launched Chromium) lives in daemon memory + the VM, so the whole pair
+// forks with snapshots like everything else — validated 2026-07-14.
+//
+// On top of the per-op event recording, every Browser also captures an
+// rrweb session: rrweb-record is injected into every document via CDP
+// `Page.addScriptToEvaluateOnNewDocument`, the page buffers events on
+// `window.__spectestRrwebEvents`, and we drain that buffer after every
+// Browser op (and a final time on close). Drained chunks are tagged
+// with the op that triggered the drain — that's the per-step structure
+// the persistence layer stores so the dashboard can correlate replay
+// timeline with the test's browser actions.
+//
+// Headless-Linux specifics live here: we force the chrome backend, add
+// `--no-sandbox` (Chrome refuses to run as root otherwise) and
+// `--disable-dev-shm-usage` (Firecracker's /dev/shm is tiny).
+//
+// Sessions are PERSISTENT by default: `ctx.browser()` always hands back the
+// one shared desktop browser and `ctx.mobile(app)` the one session for that
+// app, kept alive across tests so snapshots capture the live Chromium and
+// dependsOn children resume exactly where the parent left off (signed-in
+// SPA state included). See the "Persistent sessions" section below.
+
+import { promises as dns } from "node:dns";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { generateId } from "./ids.js";
+import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import type { UrlPattern } from "./url-match.js";
+export type { UrlPattern } from "./url-match.js";
+import {
+  attachBrowserProbe,
+  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 {
+  Browser as PlaywrightBrowser,
+  BrowserContext,
+  CDPSession,
+  Page,
+} from "playwright-core";
+
+// Minimal declaration of the one Bun global we use (executable lookup), so
+// the SDK type-checks in projects that don't install `@types/bun`.
+declare const Bun: { which(bin: string): string | null };
+
+export interface BrowserOptions {
+  /** Viewport width in pixels. Default 1280. Ignored when `frame: "mobile"`
+   * (the device preset's viewport wins). */
+  width?: number;
+  /** Viewport height in pixels. Default 720. Ignored when `frame: "mobile"`. */
+  height?: number;
+  /**
+   * Which device frame this session represents. `"browser"` (default) is a
+   * desktop viewport rendered as a browser window in the replay; `"mobile"`
+   * emulates a phone (viewport + DPR + mobile UA + touch via CDP) and the
+   * replay wraps the capture in a phone bezel. The mobile device is fixed
+   * (latest iPhone) and not caller-configurable — see `ctx.mobile`.
+   */
+  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
+   * `window.__spectestRrwebEvents` since the last drain. The daemon
+   * passes a per-test, per-session sink; if `null` (e.g. tests calling
+   * `openBrowser` directly without a test context), rrweb still
+   * records page-side but the buffer is discarded on close.
+   */
+  recorder?: BrowserSessionRecorder | null;
+}
+
+/** Decoded byte count of a base64 string, without decoding it. */
+function base64ByteLength(b64: string): number {
+  let padding = 0;
+  if (b64.endsWith("==")) padding = 2;
+  else if (b64.endsWith("=")) padding = 1;
+  return (b64.length * 3) / 4 - padding;
+}
+
+/** One Browser-action's worth of rrweb events, in the order rrweb emitted them. */
+export interface BrowserSessionStep {
+  /** Monotonic counter within the session. */
+  stepSeq: number;
+  /** Browser action that triggered this drain — same set as in the
+   * per-op event log, plus `"close"` for the final pre-teardown drain. */
+  action: BrowserAction | "close";
+  /** Ms since the session was opened. */
+  tOffsetMs: number;
+  /** rrweb events as emitted by `rrweb.record`'s `emit` callback. */
+  events: unknown[];
+}
+
+// The set of actions that show up in the test event log. The session
+// step type extends this with "close" for the final drain.
+import type { BrowserAction } from "./recorder.js";
+export type { BrowserAction } from "./recorder.js";
+
+/** Sink the daemon passes in to collect per-session rrweb event chunks. */
+export interface BrowserSessionRecorder {
+  /**
+   * Stable ID of this session — echoed into the per-op event log so
+   * the dashboard can link a browser event to its replay player.
+   */
+  readonly sessionId: string;
+  /**
+   * Author-given name of this session (`ctx.browser("alice")`), absent
+   * for the default unnamed one. Echoed onto every op's event so the
+   * step list can say WHICH browser acted without having to resolve the
+   * session record — which the CLI's failure detail can't do (it renders
+   * from the persisted events alone, with no replay bundle).
+   */
+  readonly sessionName?: string;
+  /** Called for each drained chunk of rrweb events. */
+  recordStep(step: BrowserSessionStep): void;
+  /** Optional: called whenever `Browser.goto(url)` is invoked. */
+  noteNavigation?(url: string): void;
+  /**
+   * Optional: register a captured artifact (screenshot bytes) for upload.
+   * Present only in eval context — the daemon wires it to the per-eval
+   * collector, and its absence is what makes `screenshot()` throw during
+   * test runs (artifacts are eval-only for now). Throws when the eval's
+   * artifact byte budget is exhausted.
+   */
+  registerArtifact?(artifact: {
+    id: string;
+    kind: "screenshot";
+    contentType: string;
+    sizeBytes: number;
+    bytesBase64: string;
+  }): 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 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 {
+  /** 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. */
+  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;
+
+  /**
+   * 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` 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`).
+   */
+  evaluate<T = unknown>(
+    description: string,
+    fn: string | ((arg?: unknown) => T | Promise<T>),
+    arg?: unknown,
+  ): Promise<Wrapped<T>>;
+  /**
+   * Wait until the page's URL matches `pattern` — Playwright's
+   * `page.waitForURL`. Resolves to the **matched URL** (provenance-wrapped,
+   * so `expect(...)` on it nests under this step), and returns immediately if
+   * the current URL already matches.
+   *
+   * This is the primitive for "the app redirected somewhere": an auth
+   * handoff, an OAuth callback, a post-login bounce. Reach for it instead of
+   * `waitForFunction("…", () => location.href.startsWith(…))` — that polls
+   * *inside* the page, so it races the navigation it's watching for (the
+   * `Execution context was destroyed` flake), misses any URL the browser only
+   * passes through between polls, and needs the destination to run JS at all.
+   * This one is driven by frame-navigation events, so it sees every commit.
+   *
+   * ```ts
+   * const url = await browser.waitForURL("https://api.workos.com/**");
+   * expect(url).toContain("code=");
+   * ```
+   *
+   * `waitUntil` defaults to **`"commit"`**, not Playwright's `"load"`: the
+   * destination is usually somewhere the hermetic VM can't fully load, and
+   * waiting for its load event would time out on exactly the case this
+   * exists for. Pass `"load"`/`"domcontentloaded"` when you own the page and
+   * intend to keep driving it. Timeout defaults to 5 s.
+   */
+  waitForURL(
+    pattern: UrlPattern,
+    options?: {
+      timeout?: number;
+      waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
+    },
+  ): Promise<Wrapped<string>>;
+  /**
+   * 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.
+   *
+   * For "wait until the page navigates somewhere" use {@link waitForURL} —
+   * an in-page poll is the wrong tool for watching a navigation.
+   */
+  waitForFunction<T = unknown>(
+    description: string,
+    fn: string | ((arg?: unknown) => T),
+    arg?: unknown,
+    options?: { timeout?: number; polling?: number },
+  ): Promise<Wrapped<T>>;
+  /**
+   * 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 env eval`);
+   * throws with a clear message during test runs.
+   */
+  screenshot(): Promise<string>;
+  /**
+   * 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>;
+}
+
+/**
+ * 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). Stamped onto the session record. */
+  readonly safeAreaInsets: SafeAreaInsets | null;
+  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>;
+  /**
+   * Evaluate a JS expression in the page WITHOUT recording an event or
+   * draining rrweb. rrweb keeps buffering page-side; the next recorded op
+   * 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
+   * 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; `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.
+// --no-sandbox: Chrome refuses to launch as root otherwise (no user
+//   namespaces in the guest).
+// --disable-dev-shm-usage: /dev/shm in the microVM defaults to ~64MB,
+//   which Chromium will exhaust on non-trivial pages.
+// --disable-features=AsyncDns,DnsOverHttps + --dns-over-https-mode=off:
+//   force Chromium onto glibc getaddrinfo for name resolution — the exact
+//   path `fetch()` uses (→ /etc/resolv.conf → 127.0.0.53 → spectest-resolver).
+//   Chromium's built-in async DNS client (and DoH auto-upgrade) bypass the
+//   loopback nameserver in /etc/resolv.conf and query public DNS directly,
+//   which has never heard of our service names (`dashboard`, `web`,
+//   `api.todos.local`, …). On a cold first navigate in a fresh fork that
+//   surfaces as an intermittent `net::ERR_NAME_NOT_RESOLVED`. getaddrinfo
+//   reads resolv.conf synchronously per lookup, so it has no startup race
+//   and always reaches the resolver. See run 878d0054 (dashboard:3000).
+//
+// The two media flags below make `getUserMedia` work at all. The microVM
+// has no camera and no sound card, so without them a page that asks for one
+// fails on `NotFoundError: Requested device not found` — an app that gates
+// its UI on microphone access can't be driven past that point.
+//
+// What the app gets is Chromium's own synthetic devices: the microphone is a
+// generated beep pattern (a live, real MediaStreamTrack — MediaRecorder,
+// WebRTC and AudioContext analysis all work on it), the camera a rolling
+// test pattern at 640x480. There is deliberately NO way to feed a recording
+// in; this is device availability, not audio fixtures.
+//
+// --use-fake-device-for-media-stream: the synthetic camera + microphone.
+//   Also what makes `enumerateDevices()` return anything at all.
+// --use-fake-ui-for-media-stream: auto-accept the permission prompt.
+//   Headless has no UI to accept it with, so without this `getUserMedia`
+//   fails on `NotAllowedError` even when the fake devices are present.
+//
+// `--autoplay-policy=no-user-gesture-required` is deliberately NOT here.
+// WebAudio over the captured stream works without it: holding a live
+// getUserMedia stream is itself one of the conditions under which Chromium
+// lets an AudioContext start, so an app's level meter or VAD reads the fake
+// device fine (measured). Adding it would also un-block ordinary media
+// autoplay, which is a behaviour change in the app under test, not in us.
+const CHROME_ARGV = [
+  "--no-sandbox",
+  "--disable-dev-shm-usage",
+  "--disable-features=AsyncDns,DnsOverHttps",
+  "--dns-over-https-mode=off",
+  "--use-fake-device-for-media-stream",
+  "--use-fake-ui-for-media-stream",
+];
+
+/** Default touchStart→touchEnd dwell for touch taps — see `rawTap`. */
+const TAP_DWELL_MS = 60;
+
+/** 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;
+
+// ────────────────────────────────────────────────────────────────────────
+// Shared Chromium (playwright-core)
+// ────────────────────────────────────────────────────────────────────────
+
+// One Chromium per daemon, launched lazily on first view creation and kept
+// for the daemon's lifetime. It rides snapshots: the process, playwright's
+// pipe connection to it, and every open page freeze into the VM snapshot
+// and resume in each fork (like dockerd and the daemon itself). Profile
+// state — cookies, localStorage — is per-Chromium, and the in-VM CA trust
+// comes from the HOME-scoped NSS user DB, so neither cares that playwright
+// runs a temp --user-data-dir.
+let PW_BROWSER: PlaywrightBrowser | null = null;
+// Every view gets its OWN context, desktop included. A context is the cookie
+// jar + storage, so one-context-per-view is what makes `close()` mean what
+// the docs promise: the browsing session is destroyed and the next
+// `ctx.browser()` starts signed out. Desktop views used to share one context
+// (mirroring the old one-Chrome-profile model), which left `close()` closing
+// the page only — cookies survived and the next session was still
+// authenticated.
+
+function chromiumPath(): string {
+  return (
+    Bun.which("chromium") ??
+    Bun.which("chromium-browser") ??
+    Bun.which("google-chrome") ??
+    "/usr/bin/chromium"
+  );
+}
+
+async function ensurePlaywrightBrowser(): Promise<PlaywrightBrowser> {
+  if (PW_BROWSER?.isConnected()) return PW_BROWSER;
+  PW_BROWSER = await chromium.launch({
+    executablePath: chromiumPath(),
+    headless: true,
+    args: CHROME_ARGV,
+  });
+  return PW_BROWSER;
+}
+
+/** Context options for the mobile device preset — playwright's native
+ *  emulation (viewport/DPR/UA/touch are context-scoped). Safe-area insets
+ *  have no context option; they stay a raw-CDP override per page. */
+function deviceContextOptions(d: DevicePreset) {
+  return {
+    viewport: { width: d.viewport.width, height: d.viewport.height },
+    deviceScaleFactor: d.deviceScaleFactor,
+    isMobile: d.isMobile,
+    hasTouch: d.hasTouch,
+    userAgent: d.userAgent,
+    // Emulate `prefers-reduced-motion: reduce` for replay fidelity — an app
+    // that honors it skips entrance animations/transitions, so rrweb's
+    // per-op FullSnapshot captures the settled DOM instead of a mid-fade
+    // (opacity 0) frame that a paused seek would freeze on. Applied at every
+    // newContext site below so all sessions record the same way.
+    reducedMotion: "reduce" as const,
+  };
+}
+
+/** Create the context one view lives in — device emulation when the view is
+ *  phone-emulated, a plain viewport otherwise. */
+async function newViewContext(
+  width: number,
+  height: number,
+  device: DevicePreset | null,
+): Promise<BrowserContext> {
+  const browser = await ensurePlaywrightBrowser();
+  const context = await browser.newContext(
+    device
+      ? deviceContextOptions(device)
+      : {
+          viewport: { width, height },
+          // Reduced-motion for replay fidelity — see deviceContextOptions.
+          reducedMotion: "reduce",
+        },
+  );
+  context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
+  context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+  return context;
+}
+
+/**
+ * Make a user script evaluable by the page: Bun's `view.evaluate` accepts a
+ * single EXPRESSION (it wraps the source in `await (...)`), so a statement
+ * body (`const x = …; return x;`) is a syntax error. Rather than forcing
+ * authors to IIFE-wrap by hand, wrap it for them when it isn't an expression.
+ *
+ * The check is parse-only (`new Function` compiles without executing) and
+ * happens BEFORE the script runs — deciding by catching the page-side error
+ * and retrying would re-execute side-effecting expressions whose *runtime*
+ * error happens to look syntactic (`JSON.parse` throws SyntaxError too).
+ */
+function toEvaluable(script: string): string {
+  try {
+    new Function(`return (${script}\n);`);
+    return script;
+  } catch {
+    // Statement body — an async IIFE makes `return`, declarations, and
+    // multi-statement snippets valid, with `await` still available. The
+    // newlines keep a trailing line comment from eating the wrapper.
+    return `(async () => {\n${script}\n})()`;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Device emulation (mobile frame)
+// ────────────────────────────────────────────────────────────────────────
+
+/** A device descriptor in the shape of Playwright's `devices[...]` entries
+ *  — the subset we feed to CDP. Not caller-configurable today; a single
+ *  fixed preset (latest iPhone) backs every `ctx.mobile(...)` session. */
+interface DevicePreset {
+  name: string;
+  viewport: { width: number; height: number };
+  deviceScaleFactor: number;
+  isMobile: boolean;
+  hasTouch: boolean;
+  userAgent: string;
+  safeAreaInsets: SafeAreaInsets;
+}
+
+/** iOS safe-area insets (CSS `env(safe-area-inset-*)`), in CSS px. */
+export interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** The fixed mobile device. Logical resolution + DPR of a current iPhone;
+ *  the UA mirrors what Playwright emits for iOS so RN-Web's mobile branches
+ *  fire. We run Chromium under the hood, so the Safari UA is a deliberate
+ *  emulation lie (same as every device-emulation tool). */
+const LATEST_IPHONE: DevicePreset = {
+  name: "iPhone 15 Pro",
+  viewport: { width: 393, height: 852 },
+  deviceScaleFactor: 3,
+  isMobile: true,
+  hasTouch: true,
+  userAgent:
+    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) " +
+    "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
+  // Portrait safe area of the 393×852 iPhones (14 Pro through 16): 59pt
+  // status-bar/Dynamic-Island clearance on top, 34pt home-indicator strip
+  // at the bottom. Emulated via CDP so the app's `env(safe-area-inset-*)`
+  // padding fires exactly like on the real device.
+  safeAreaInsets: { top: 59, right: 0, bottom: 34, left: 0 },
+};
+
+/** Apply the one device-emulation piece playwright's context options can't
+ *  express: iOS safe-area insets, via raw CDP on the page's session. The
+ *  override is session-global, so it persists across the app navigation
+ *  that follows. Best-effort — Chromium < ~135 lacks the method.
+ *
+ *  Returns the insets that actually took effect (`null` when the override
+ *  failed). The caller stamps them onto the session record so the dashboard
+ *  can substitute the same values for `env(safe-area-inset-*)` in the
+ *  replayed CSS; stamping only what was really applied keeps capture layout
+ *  and replay layout in lockstep (recorded touch coordinates would
+ *  misalign otherwise). */
+async function applySafeAreaInsets(
+  cdp: CDPSession,
+  d: DevicePreset,
+): Promise<SafeAreaInsets | null> {
+  try {
+    await cdp.send(
+      // Not in playwright's Protocol types yet (Chromium ≥ ~135 method).
+      "Emulation.setSafeAreaInsetsOverride" as Parameters<CDPSession["send"]>[0],
+      { insets: { ...d.safeAreaInsets } } as never,
+    );
+    return d.safeAreaInsets;
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("[spectest] safe-area inset emulation unavailable:", err);
+    return null;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// rrweb bootstrap
+// ────────────────────────────────────────────────────────────────────────
+
+// Vendored `@rrweb/record` UMD bundle (rrweb 2.x). Its global `rrwebRecord`
+// is a module object — the record function is `rrwebRecord.record` (the
+// bootstrap resolves both this and the legacy function-shaped global). Read
+// once at module init — the SDK ships this file in the base snapshot so
+// no network fetch happens inside the VM.
+const RRWEB_BUNDLE: string = (() => {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const file = path.join(here, "vendor", "rrweb-record.min.js");
+    return readFileSync(file, "utf8");
+  } catch (err) {
+    // If the vendored bundle is missing the SDK still works — the
+    // browser just records no rrweb events. Surface a warning so the
+    // mistake is visible.
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[spectest] rrweb-record.min.js missing from SDK vendor dir; browser sessions will be empty",
+      err,
+    );
+    return "";
+  }
+})();
+
+// Vendored console-record plugin bundle (UMD, exposes
+// `rrwebPluginConsoleRecord` global). Captures the page's
+// `console.{log,info,warn,error,debug,...}` calls and uncaught errors as
+// rrweb Plugin events (`type: 6`, `data.plugin: "rrweb/console@1"`),
+// which ride in the same `emit` stream as DOM mutations. Optional —
+// missing bundle just means no console capture; the recorder still runs.
+const RRWEB_CONSOLE_PLUGIN_BUNDLE: string = (() => {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const file = path.join(here, "vendor", "rrweb-plugin-console-record.umd.js");
+    return readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+})();
+
+// Bootstrap that runs after the bundle defines `rrwebRecord`. Idempotent —
+// the same script is added with `Page.addScriptToEvaluateOnNewDocument`
+// and runs on every new document, so the `__spectestRrwebInit` guard keeps
+// us from double-starting.
+//
+// `lengthThreshold` caps per-arg serialized size (default 1000 → bumped to
+// 10 KiB so longer error stacks survive without dwarfing the event stream).
+const RRWEB_BOOTSTRAP = `
+;(function () {
+  // rrweb 2.x ships \`@rrweb/record\` whose UMD global is a module object
+  // (\`rrwebRecord.record\`); the pre-2.0 bundle exposed the record function
+  // directly. Resolve either shape so the bootstrap is version-agnostic,
+  // and stash it on \`window.__spectestRec\` for the drain/attach helpers
+  // (which run as separate injected expressions).
+  var rec = (typeof rrwebRecord === "function")
+    ? rrwebRecord
+    : (rrwebRecord && (rrwebRecord.record || rrwebRecord.default));
+  if (typeof rec !== "function") return;
+  if (window.__spectestRrwebInit) return;
+  window.__spectestRrwebInit = true;
+  window.__spectestRec = rec;
+  window.__spectestRrwebEvents = [];
+  var plugins = [];
+  try {
+    if (typeof rrwebPluginConsoleRecord === "object" &&
+        typeof rrwebPluginConsoleRecord.getRecordConsolePlugin === "function") {
+      plugins.push(rrwebPluginConsoleRecord.getRecordConsolePlugin({
+        level: ["assert", "debug", "error", "info", "log", "trace", "warn"],
+        lengthThreshold: 10000,
+        logger: window.console,
+      }));
+    }
+  } catch (e) { /* plugin init failed — keep recording DOM only. */ }
+  try {
+    rec({
+      emit: function (ev) { window.__spectestRrwebEvents.push(ev); },
+      plugins: plugins,
+      // Capture page assets into the event stream so the replay renders
+      // faithfully offline (the dashboard reconstructs the DOM with no
+      // access to the env's origin). \`inlineStylesheet\` (default, set
+      // explicitly) bakes <style>/<link> CSS into the snapshot;
+      // \`inlineImages\` turns <img> elements into data URIs — but ONLY
+      // synchronously, for images already decoded at serialize time
+      // (its late-load path patches the emitted event in place, which
+      // loses the race against our per-op drains; the image inliner
+      // below covers that case with synthetic mutation events).
+      // \`collectFonts\` only captures fonts added via the JS
+      // FontFace API — it does NOT inline static \`@font-face { src:url() }\`
+      // CSS (what next/font emits), so it's a no-op for most apps; the
+      // url()-based fonts are handled by the inliner below instead. All
+      // degrade gracefully — an asset that can't be read is skipped,
+      // never fatal to recording.
+      inlineStylesheet: true,
+      collectFonts: true,
+      inlineImages: true,
+    });
+  } catch (e) {
+    /* DOM not yet ready or rrweb mis-init — skip. */
+  }
+  // ── Inline @font-face fonts as base64 ──────────────────────────────
+  // The replay is viewed OUTSIDE this hermetic VM, so a @font-face whose
+  // src points at a same-origin URL (e.g. next/font's
+  // /_next/static/media/*.woff2) is unreachable at replay time and the
+  // page silently falls back to a system font. collectFonts above won't
+  // help (FontFace-API fonts only), so inline the bytes ourselves: fetch
+  // each url() (same-origin -> allowed, and the page already trusts the
+  // in-VM CA), rewrite the rule's src to a data:
+  // URI, then take a fresh full snapshot so the now-self-contained CSS
+  // is captured. Plain string ops, no regex — this whole script ships
+  // inside a TS template literal where regex backslashes get mangled.
+  //
+  // Do NOT start this scan from document.fonts.ready. This script runs at
+  // document-start. At that moment the font set is idle, so Chrome settles
+  // that first ready promise immediately, before the parser has registered
+  // one stylesheet. The scan then saw 0 @font-face rules, and a one-shot
+  // latch stopped it from looking again, so no font was ever inlined.
+  // (Found on run_03j0mxtvp6x0p16d9y83e: every next/font face fell back.
+  // The diagnostics were invisible too, because rrweb's console plugin
+  // only patches console at the load event.)
+  //
+  // Two triggers instead: the load event, by which all render-blocking CSS
+  // is parsed, and each \`loadingdone\` on document.fonts, which catches CSS
+  // added later by an HMR update or a client-side route change. The scan
+  // skips a rule it already inlined, so repeated triggers are cheap.
+  (function () {
+    if (window.__spectestFontInliner) return;
+    window.__spectestFontInliner = true;
+    // Diagnostics ride the console-record plugin, so they land in the
+    // recording (and state.db) — our only debugging window into the
+    // headless page. Prefix is grep-able; keep them terse.
+    function log(m) { try { console.log("[spectest-fonts] " + m); } catch (e) {} }
+    var cache = {};
+    function fetchDataUri(url) {
+      if (cache[url]) return cache[url];
+      cache[url] = fetch(url).then(function (r) {
+        if (!r.ok) throw new Error("HTTP " + r.status);
+        return r.blob();
+      }).then(function (blob) {
+        return new Promise(function (resolve, reject) {
+          var fr = new FileReader();
+          fr.onload = function () { resolve(fr.result); };
+          fr.onerror = reject;
+          fr.readAsDataURL(blob);
+        });
+      });
+      return cache[url];
+    }
+    // Extract every url() token in cssText, resolved against baseHref.
+    // CSSOM cssText keeps urls as authored — next/font emits
+    // absolute-path url(/_next/static/media/x.woff2) (no scheme), so a
+    // bare http prefix check misses them (that's why run b04cab1f / 6987
+    // saw withHttpUrl=0). Resolve against the sheet href (or the document
+    // base for inline style) before fetching. token is the raw string as
+    // it appears in cssText, used for the later string replace.
+    function urlsIn(text, baseHref) {
+      var out = [], i = 0;
+      while (true) {
+        var u = text.indexOf("url(", i);
+        if (u < 0) break;
+        var start = u + 4, end = text.indexOf(")", start);
+        if (end < 0) break;
+        var raw = text.slice(start, end).trim();
+        if (raw && (raw.charAt(0) === '"' || raw.charAt(0) === "'")) {
+          raw = raw.slice(1, raw.length - 1);
+        }
+        i = end + 1;
+        if (!raw || raw.lastIndexOf("data:", 0) === 0) continue; // already inline
+        var abs;
+        try { abs = new URL(raw, baseHref).href; } catch (e) { continue; }
+        if (abs.lastIndexOf("http", 0) !== 0) continue; // only fetchable http(s)
+        out.push({ token: raw, abs: abs });
+      }
+      return out;
+    }
+    function eachFontFace(rules, fn) {
+      for (var i = 0; i < rules.length; i++) {
+        var rule = rules[i];
+        if (rule.type === 5) fn(rule);            // CSSRule.FONT_FACE_RULE
+        else if (rule.cssRules) {                 // @media / @supports nesting
+          try { eachFontFace(rule.cssRules, fn); } catch (e) {}
+        }
+      }
+    }
+    // Every @font-face cssText this run already rewrote. A rule stays out
+    // of later scans, so an HMR update that adds one stylesheet costs one
+    // fetch, not a re-inline of the whole page.
+    var inlined = {};
+    var scans = 0, busy = false, rescan = false;
+    function collect() {
+      // Collect each @font-face's *cssText* (reliable for any CSSRule —
+      // unlike .style.setProperty('src',…), which silently no-ops on
+      // CSSFontFaceRule in Chrome) plus the http url()s inside it.
+      var faces = [], sheets = document.styleSheets, readable = 0, faceCount = 0;
+      for (var s = 0; s < sheets.length; s++) {
+        var rules;
+        try { rules = sheets[s].cssRules; } catch (e) { continue; } // cross-origin
+        if (!rules) continue;
+        readable++;
+        var base = sheets[s].href || document.baseURI;
+        eachFontFace(rules, function (rule) {
+          faceCount++;
+          var cssText = rule.cssText || "";
+          if (inlined[cssText]) return;
+          var urls = urlsIn(cssText, base);
+          if (urls.length) faces.push({ cssText: cssText, urls: urls });
+        });
+      }
+      // Log the first scan (so a page with no web fonts still says so) and
+      // every scan with work to do. A quiet re-trigger stays silent.
+      if (!scans++ || faces.length) {
+        log("sheets=" + sheets.length + " readable=" + readable +
+            " fontFaces=" + faceCount + " new=" + faces.length);
+      }
+      return faces;
+    }
+    function run() {
+      // One pass at a time. A trigger during a pass queues exactly one
+      // more, which then sees the marks the pass just wrote.
+      if (busy) { rescan = true; return; }
+      var faces = collect();
+      if (!faces.length) return;
+      busy = true;
+      var jobs = faces.map(function (face) {
+        return Promise.all(face.urls.map(function (u) {
+          return fetchDataUri(u.abs)
+            .then(function (d) { return { token: u.token, dataUri: d }; })
+            .catch(function (e) { log("fetch FAIL " + u.abs + " : " + (e && e.message)); return null; });
+        })).then(function (pairs) {
+          var text = face.cssText, changed = false;
+          for (var k = 0; k < pairs.length; k++) {
+            if (!pairs[k]) continue;
+            text = text.split(pairs[k].token).join(pairs[k].dataUri);
+            changed = true;
+          }
+          if (!changed) return null;
+          inlined[face.cssText] = true;
+          return text;
+        });
+      });
+      Promise.all(jobs).then(function (texts) {
+        var ok = texts.filter(function (t) { return t; });
+        if (!ok.length) { log("nothing inlined (all fetches failed?)"); return; }
+        // Inject the rewritten @font-face rules as a NEW <style> appended
+        // last. A later @font-face with identical descriptors wins, and a
+        // freshly-added node is captured reliably by rrweb's mutation
+        // observer (no dependence on CSSOM edits being serialized).
+        try {
+          var st = document.createElement("style");
+          st.setAttribute("data-spectest-inlined-fonts", "1");
+          st.appendChild(document.createTextNode(ok.join("\\n")));
+          (document.head || document.documentElement).appendChild(st);
+          log("injected " + ok.length + " @font-face rule(s) as data: URIs");
+        } catch (e) { log("inject FAIL " + (e && e.message)); return; }
+        try {
+          if (rec && typeof rec.takeFullSnapshot === "function") {
+            rec.takeFullSnapshot();
+            log("took full snapshot");
+          }
+        } catch (e) { log("snapshot FAIL " + (e && e.message)); }
+      }).catch(function (e) {
+        log("run FAIL " + (e && e.message));
+      }).then(function () {
+        busy = false;
+        if (rescan) { rescan = false; setTimeout(run, 0); }
+      });
+    }
+    function schedule() { setTimeout(run, 0); }
+    try {
+      if (document.readyState === "complete") schedule();
+      else window.addEventListener("load", schedule);
+      // Fires each time a batch of fonts finishes loading, including fonts
+      // pulled in by CSS that arrives after the load event.
+      if (document.fonts && document.fonts.addEventListener) {
+        document.fonts.addEventListener("loadingdone", schedule);
+      }
+    } catch (e) { log("init FAIL " + (e && e.message)); }
+  })();
+  // ── Inline late-loading <img>s as synthetic src mutations ──────────
+  // rrweb's inlineImages only bakes a data: URI in synchronously when
+  // the image is already decoded at serialize time. An image that
+  // finishes loading AFTER its node was serialized is patched by rrweb
+  // IN PLACE on the already-emitted event object — lost whenever a
+  // drain (op boundary) ships the buffer first. Classic case: a tap
+  // reveals a screen full of first-seen images; the step's drain fires
+  // right after the tap, the images decode a beat later, and the replay
+  // is left with raw in-VM URLs it can't fetch (hermetic env).
+  //
+  // Fix: listen for image loads ourselves (capture phase on document —
+  // runs BEFORE rrweb's target-phase listener) and, once the element
+  // has an id in rrweb's mirror, push a synthetic incremental mutation
+  // rewriting the img's src to a data: URI. A mutation event rides
+  // whatever drain comes next, so it survives the race even when the
+  // add event is long gone. Bytes come from a same-origin fetch of the
+  // ORIGINAL file (compact and lossless — rrweb's canvas path
+  // re-encodes JPEGs as much larger PNGs). It must be a plain \`src\`
+  // rewrite: the replayer honors \`rr_dataURL\` only when BUILDING a
+  // node; in the attribute-mutation path it just sets the literal
+  // attribute (only canvas is special-cased there).
+  (function () {
+    if (window.__spectestImgInliner) return;
+    window.__spectestImgInliner = true;
+    function log(m) { try { console.log("[spectest-img] " + m); } catch (e) {} }
+    var cache = {};
+    function fetchDataUri(url) {
+      if (cache[url]) return cache[url];
+      cache[url] = fetch(url).then(function (r) {
+        if (!r.ok) throw new Error("HTTP " + r.status);
+        return r.blob();
+      }).then(function (blob) {
+        return new Promise(function (resolve, reject) {
+          var fr = new FileReader();
+          fr.onload = function () { resolve(fr.result); };
+          fr.onerror = reject;
+          fr.readAsDataURL(blob);
+        });
+      });
+      return cache[url];
+    }
+    // The serialized-node meta when rrweb already inlined THIS src on
+    // it (rr_dataURL present and the recorded src matches — a stale
+    // bake from a previous src must not count).
+    function bakedMeta(mirror, img, src) {
+      try {
+        var meta = mirror.getMeta(img);
+        if (meta && meta.attributes && meta.attributes.rr_dataURL &&
+            meta.attributes.src === src) return meta;
+      } catch (e) {}
+      return null;
+    }
+    function onImgLoad(img, src) {
+      var mirror = rec && rec.mirror;
+      if (!mirror || typeof mirror.getId !== "function" ||
+          typeof mirror.getMeta !== "function") return;
+      // A patch visible NOW — before rrweb's own load listener has run
+      // (we're capture phase, it's target phase) — can only be the
+      // synchronous serialize-time bake, which shipped inside the event
+      // itself. Nothing to do.
+      var preId = mirror.getId(img);
+      if (preId > 0 && bakedMeta(mirror, img, src)) return;
+      var tries = 0;
+      function finish() {
+        var id = mirror.getId(img);
+        if (!(id > 0)) {
+          // Not serialized yet (mutation batch pending, or the initial
+          // full snapshot hasn't run — rrweb defers it to window load).
+          tries++;
+          if (tries < 40) setTimeout(finish, 50);
+          else log("drop (never serialized) " + src);
+          return;
+        }
+        var meta = bakedMeta(mirror, img, src);
+        if (meta && preId < 1) return; // serialized after load → sync bake
+        if (meta) {
+          // rrweb's async in-place patch landed after our capture-phase
+          // check. If the add is still in the buffer it now carries a
+          // PNG re-encode; strip it and ship ours instead (original
+          // bytes, and immune to a drain having already taken the add).
+          try { delete meta.attributes.rr_dataURL; } catch (e) {}
+        }
+        fetchDataUri(src).then(function (dataUri) {
+          var attrs = { src: dataUri };
+          // A srcset would out-rank the patched src in the replay
+          // iframe and point back at the unreachable original.
+          if (img.getAttribute && img.getAttribute("srcset")) attrs.srcset = "";
+          window.__spectestRrwebEvents.push({
+            type: 3,
+            data: { source: 0, texts: [], attributes: [{ id: id, attributes: attrs }], removes: [], adds: [] },
+            timestamp: Date.now(),
+          });
+          log("inlined id=" + id + " bytes=" + dataUri.length + " " + src);
+        }).catch(function (e) {
+          log("fetch FAIL " + src + " : " + (e && e.message));
+        });
+      }
+      // Next task, so rrweb's own load listener has run and its patch
+      // (if any) is observable above.
+      setTimeout(finish, 0);
+    }
+    try {
+      document.addEventListener("load", function (ev) {
+        var el = ev.target;
+        if (!el || !el.tagName || String(el.tagName).toLowerCase() !== "img") return;
+        var src = el.currentSrc || el.src || "";
+        if (!src || src.lastIndexOf("http", 0) !== 0) return; // data:/blob: already replayable
+        if (el.__spectestImgSrc === src) return; // this src already handled
+        el.__spectestImgSrc = src;
+        onImgLoad(el, src);
+      }, true);
+    } catch (e) { log("init FAIL " + (e && e.message)); }
+  })();
+  // ── Record form resets as synthetic Input events ───────────────────
+  // rrweb learns that a control's value changed through exactly two
+  // channels: the \`input\`/\`change\` events, and setters it hooks on the
+  // HTMLInput/TextArea/SelectElement prototypes. A **form reset** uses
+  // neither — the browser clears the controls internally — so the
+  // recording keeps the last typed value forever while the real page
+  // shows an empty field. Measured, not assumed: \`el.value = x\` IS
+  // captured (even through React's own per-node \`value\` accessor, since
+  // that delegates to the prototype descriptor we hooked first), and
+  // \`form.reset()\` is NOT. The shape is everywhere in chat/prompt UIs —
+  // shadcn/ai-elements' PromptInput resets the form on submit, as does
+  // React 19's automatic \`<form action>\` reset — where it reads as
+  // "clicking send didn't clear the box".
+  //
+  // The \`reset\` event is the hook: it fires (cancelable) BEFORE the
+  // controls are reset, for both \`form.reset()\` and a user-clicked
+  // \`type="reset"\` button. Snapshot the values there, diff on the next
+  // task, and push an Input event per control that actually moved —
+  // byte-identical in shape to what rrweb emits for a real input, so
+  // the replayer applies it the same way. A prevented or no-op reset
+  // changes nothing and therefore emits nothing. We never touch the
+  // page's DOM to provoke a recording (\`el.value = el.value\` would
+  // work, but it sets the control's dirty-value flag and would change
+  // how the app's own later attribute writes render).
+  (function () {
+    if (window.__spectestFormReset) return;
+    window.__spectestFormReset = true;
+    var INPUT_TAGS = ["INPUT", "TEXTAREA", "SELECT"];
+    function snap(form) {
+      var out = [], els;
+      try { els = form.elements; } catch (e) { return out; }
+      if (!els) return out;
+      for (var i = 0; i < els.length; i++) {
+        var el = els[i];
+        if (!el || !el.tagName) continue;
+        if (INPUT_TAGS.indexOf(String(el.tagName).toUpperCase()) < 0) continue;
+        out.push({ el: el, value: el.value, checked: !!el.checked });
+      }
+      return out;
+    }
+    function emitChanged(before) {
+      var mirror = rec && rec.mirror;
+      if (!mirror || typeof mirror.getId !== "function") return;
+      for (var i = 0; i < before.length; i++) {
+        var el = before[i].el;
+        if (el.value === before[i].value && !!el.checked === before[i].checked) continue;
+        if (el.classList && el.classList.contains("rr-ignore")) continue;
+        var id = mirror.getId(el);
+        if (!(id > 0)) continue;
+        var type = el.type ? String(el.type).toLowerCase() : "";
+        var text = String(el.value);
+        // rrweb masks password inputs by default (maskInputOptions
+        // \`{ password: true }\`, default maskInputFn = same-length '*').
+        if (type === "password") {
+          var masked = "";
+          for (var k = 0; k < text.length; k++) masked += "*";
+          text = masked;
+        }
+        window.__spectestRrwebEvents.push({
+          type: 3,
+          data: {
+            source: 5,
+            text: text,
+            isChecked: (type === "radio" || type === "checkbox") ? !!el.checked : false,
+            id: id,
+          },
+          timestamp: Date.now(),
+        });
+      }
+    }
+    try {
+      document.addEventListener("reset", function (ev) {
+        var form = ev.target;
+        if (!form || !form.tagName || String(form.tagName).toUpperCase() !== "FORM") return;
+        var before = snap(form);
+        if (!before.length) return;
+        // The controls are reset after dispatch returns — diff then.
+        setTimeout(function () { emitChanged(before); }, 0);
+      }, true);
+    } catch (e) { /* recording continues without reset capture. */ }
+  })();
+})();
+`;
+
+// The `;` between parts is load-bearing: a vendored bundle that ends
+// without a trailing semicolon (rrweb 2.1.0's UMD ends in `}))`) would
+// otherwise ASI-merge with the next part's leading `(function...` into a
+// call expression — the TypeError kills everything after the bundle, so
+// the globals define but the bootstrap never runs (zero rrweb events,
+// empty replays).
+const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
+  ? `${RRWEB_BUNDLE}\n;\n${RRWEB_CONSOLE_PLUGIN_BUNDLE}\n;\n${RRWEB_BOOTSTRAP}`
+  : "";
+
+// Page-side expression that atomically swaps in a fresh buffer and
+// returns the old one. Wrapped as a single expression so view.evaluate's
+// `await (...)` wrapper accepts it.
+//
+// `forceFullIfMissing` (inlined by `drainExpr`) guards a recovery path
+// for the most common replay failure: a post-navigation page whose full
+// snapshot never made it into the stream. rrweb defers its *initial*
+// full snapshot to the page's `load` event, but our drains fire at op
+// boundaries — `waitFor` in particular returns the instant its predicate
+// is truthy, which is usually right after `DOMContentLoaded`, *before*
+// `load`. Login/redirect chains compound this: every new document resets
+// `window.__spectestRrwebEvents`, so a partial chunk from an intermediate
+// page is discarded. The net effect is a final step that carries only a
+// `DOMContentLoaded` (type 0) and no Meta/FullSnapshot — the player then
+// has no DOM for the new page and keeps showing the previous one (e.g.
+// the auth provider's login screen instead of the post-login dashboard).
+//
+// When the caller detects the document changed since the last drain
+// (`view.url` differs) it passes `force=true`; if the outgoing buffer
+// then lacks any FullSnapshot (type 2), we call `rec.takeFullSnapshot()`
+// to synthesize one for the *current* DOM. That emits a fresh Meta
+// (with the correct href) + FullSnapshot, so the step is self-contained
+// and seeking to it shows the right page. Gating on url-change + missing
+// snapshot keeps steady-state steps (clicks/types on an unchanged page,
+// or navigations where `load` already fired) from bloating the stream
+// with redundant snapshots.
+function drainExpr(forceFullIfMissing: boolean): string {
+  return `(function () {
+  try {
+    var rec = window.__spectestRec;
+    if (${forceFullIfMissing ? "true" : "false"} &&
+        window.__spectestRrwebInit &&
+        rec && typeof rec.takeFullSnapshot === "function") {
+      var b = window.__spectestRrwebEvents || [];
+      var hasFull = false;
+      for (var i = 0; i < b.length; i++) {
+        if (b[i] && b[i].type === 2) { hasFull = true; break; }
+      }
+      if (!hasFull) rec.takeFullSnapshot();
+    }
+  } catch (e) { /* recording inactive or DOM detached — drain what's there. */ }
+  var buf = window.__spectestRrwebEvents;
+  if (!buf || !buf.length) return [];
+  window.__spectestRrwebEvents = [];
+  return buf;
+})()`;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Factory
+// ────────────────────────────────────────────────────────────────────────
+
+/** A page freshly spawned into a context: renderer up, CDP session open,
+ *  rrweb init script installed, parked on about:blank. */
+interface SpawnedPage {
+  page: Page;
+  cdp: CDPSession;
+  recordingInstalled: boolean;
+}
+
+/** A pre-opened, never-used desktop view (with the context it lives in —
+ *  one per view, handed to the holder that claims it). */
+interface PooledView extends SpawnedPage {
+  context: BrowserContext;
+}
+
+/**
+ * The unit a Browser/Mobile handle drives. `page`/`cdp` are deliberately
+ * mutable: the DNS-recovery path (see `navigate` in {@link buildBackend})
+ * replaces a broken restored renderer with a freshly-spawned page in the
+ * SAME context (cookies/localStorage survive), and every wrapper reads
+ * through the holder so the swap is transparent. `device`/`width`/`height`
+ * are kept so a rebuilt page comes back with the same emulation.
+ */
+interface ViewHolder {
+  /** Context this view lives in — its own, never shared, so `close()` can
+   *  take the cookie jar down with the page. */
+  context: BrowserContext;
+  page: Page;
+  cdp: CDPSession;
+  /** Cached page title — playwright's `title()` is async but our public
+   *  surface is a sync getter; refreshed after every recorded op. */
+  lastTitle: string;
+  recordingInstalled: boolean;
+  device: DevicePreset | null;
+  width: number;
+  height: number;
+  /** Safe-area insets actually applied to the view (`null` for desktop
+   *  views or when the CDP override is unavailable). Stamped onto the
+   *  session record so the replay can mirror them. */
+  safeAreaInsets: SafeAreaInsets | null;
+  /** 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[];
+}
+
+// Pre-opened view pool. Renderer spawn is the expensive part of
+// `ctx.browser()` — ~1.8s for the first view in a fresh Chrome and
+// (measured 2026-06-05) a constant ~1.2-1.5s per view in a Chrome that
+// lived through a snapshot restore, i.e. in every test fork. The daemon
+// fills this pool once at the end of /bootstrap; the warm-template and
+// pretest snapshots are captured after that, so EVERY fork inherits a
+// live renderer and the first `ctx.browser()` of a test skips the spawn
+// entirely. Lives in daemon memory → forks each get the pristine pool,
+// and a test consuming it never affects its siblings (same isolation as
+// fake state).
+const VIEW_POOL: PooledView[] = [];
+
+/** Spawn a page (+ CDP session + rrweb init script) into `context` — the
+ *  slow part (renderer process spawn). */
+async function spawnPage(context: BrowserContext): Promise<SpawnedPage> {
+  const page = await context.newPage();
+  const cdp = await context.newCDPSession(page);
+  // Without Page.enable the addScriptToEvaluateOnNewDocument registration
+  // silently never fires on this session (verified in the fork spike).
+  await cdp.send("Page.enable");
+
+  let recordingInstalled = false;
+  if (PAGE_INIT_SCRIPT) {
+    try {
+      await cdp.send("Page.addScriptToEvaluateOnNewDocument", {
+        source: PAGE_INIT_SCRIPT,
+      });
+      recordingInstalled = true;
+    } catch (err) {
+      // Without rrweb the browser still works; just no replay.
+      // eslint-disable-next-line no-console
+      console.warn("[spectest] failed to install rrweb recorder:", err);
+    }
+  }
+  return { page, cdp, recordingInstalled };
+}
+
+/** Create a default-desktop view (plus its context) for the pool. */
+async function createView(width: number, height: number): Promise<PooledView> {
+  const context = await newViewContext(width, height, null);
+  return { context, ...(await spawnPage(context)) };
+}
+
+/**
+ * Pre-open `n` views into the pool (called by the daemon at the end of
+ * /bootstrap, before the warm-template snapshot is captured). Only
+ * default-viewport views are pooled — `openBrowser` with a custom
+ * width/height bypasses the pool.
+ */
+export async function prewarmViewPool(n = 1): Promise<void> {
+  for (let i = 0; i < n; i++) {
+    VIEW_POOL.push(await createView(1280, 720));
+  }
+}
+
+/**
+ * Open a browser view (a page in the shared Chromium). Serves from the
+ * pre-opened pool when the caller uses the default viewport.
+ *
+ * This is the EPHEMERAL path — `close()` destroys the view. The daemon's
+ * `ctx.browser()`/`ctx.mobile()` go through {@link acquirePersistentBrowser}
+ * / {@link acquirePersistentMobileBackend} instead, which keep one view
+ * alive across tests so it rides snapshots/forks.
+ */
+export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
+  return openMobileBackend(opts);
+}
+
+/**
+ * Like {@link openBrowser} but returns the {@link MobileBackend} superset
+ * (touch + probe). When `opts.frame === "mobile"` the view is created at the
+ * fixed device viewport, bypasses the (desktop-sized) pool, and has CDP
+ * device emulation applied before the first navigation. Desktop callers go
+ * through {@link openBrowser} and get the narrower {@link Browser} view of
+ * the same object.
+ */
+export async function openMobileBackend(
+  opts: BrowserOptions = {},
+): Promise<MobileBackend> {
+  const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
+  const wantW = device ? device.viewport.width : opts.width ?? 1280;
+  const wantH = device ? device.viewport.height : opts.height ?? 720;
+  // Mobile views are never pooled — the pool holds only default-desktop
+  // views (in the shared desktop context), and a mobile view needs its own
+  // emulated context anyway.
+  const pooled =
+    !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+  let holder: ViewHolder;
+  if (pooled) {
+    holder = {
+      context: pooled.context,
+      page: pooled.page,
+      cdp: pooled.cdp,
+      lastTitle: "",
+      recordingInstalled: pooled.recordingInstalled,
+      device,
+      width: wantW,
+      height: wantH,
+      safeAreaInsets: null,
+      initScripts: [],
+    };
+  } else {
+    holder = await newHolder(wantW, wantH, device);
+  }
+
+  const { backend } = buildBackend(holder, opts.recorder ?? null, {
+    persistent: false,
+  });
+
+  // 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.goto(opts.url);
+  }
+  return backend;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Persistent sessions (the default behind ctx.browser / ctx.mobile)
+// ────────────────────────────────────────────────────────────────────────
+
+// Long-lived sessions, keyed by NAME: one desktop browser per name, one
+// mobile session per (name, app URL). The default name is `""` — what
+// `ctx.browser()` / `ctx.mobile(app)` use — so an unnamed project keeps
+// exactly the one-session-per-device behaviour it had before names
+// existed. A name is the key and nothing else: two names are two
+// BrowserContexts in the one Chromium, i.e. two independent cookie jars
+// and localStorage, which is what modelling two users needs.
+//
+// Module state lives in daemon memory, so it forks with the snapshot the
+// same way fake `state` and TEST_DATA do: a test's browsers — their live
+// pages, cookies, localStorage, in-memory SPA state — are captured in the
+// post-test snapshot and inherited by `dependsOn` children, while sibling
+// forks never see each other's sessions. That's what lets a child test
+// continue where its parent left off (e.g. already signed in) instead of
+// re-navigating and re-authenticating. The name is a plain string, so it
+// keys the same session on both sides of a fork.
+const SHARED_BROWSERS = new Map<string, ViewHolder>();
+const SHARED_MOBILE = new Map<string, ViewHolder>();
+
+/**
+ * Ceiling on live persistent sessions of one kind (desktop / mobile).
+ * Every session is a Chromium BrowserContext that rides every snapshot
+ * from here down the DAG, so a test that mints names in a loop
+ * (`ctx.browser(userId)`) would grow the VM's memory floor for the rest
+ * of the run. Failing loudly at a sane count beats a wedged guest.
+ */
+const MAX_PERSISTENT_SESSIONS = 8;
+
+/** Registry key for a named mobile session. NUL can't occur in a name or
+ *  a URL, so the two halves can never run together ambiguously. */
+export function mobileKey(name: string, url: string): string {
+  return `${name}\u0000${url}`;
+}
+
+/** Guard the session cap, naming the offender and what to do about it. */
+function checkSessionCap(kind: string, live: number, name: string): void {
+  if (live < MAX_PERSISTENT_SESSIONS) return;
+  throw new Error(
+    `too many ${kind} sessions: ${MAX_PERSISTENT_SESSIONS} are already open and "${name}" would be another. ` +
+      `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
+      `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`,
+  );
+}
+
+async function newHolder(
+  width: number,
+  height: number,
+  device: DevicePreset | null,
+): Promise<ViewHolder> {
+  const context = await newViewContext(width, height, device);
+  const spawned = await spawnPage(context);
+  const holder: ViewHolder = {
+    context,
+    page: spawned.page,
+    cdp: spawned.cdp,
+    lastTitle: "",
+    recordingInstalled: spawned.recordingInstalled,
+    device,
+    width,
+    height,
+    safeAreaInsets: null,
+    initScripts: [],
+  };
+  if (device) holder.safeAreaInsets = await applySafeAreaInsets(holder.cdp, device);
+  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
+ * view alive); `browser.close()` is the author-facing escape hatch that
+ * actually destroys the view (the next `ctx.browser()` starts fresh).
+ */
+export interface PersistentBrowser {
+  browser: MobileBackend;
+  /** True when this call attached to a view inherited from an earlier
+   *  test (possibly across a snapshot fork) rather than creating one. */
+  attached: boolean;
+  /** Final rrweb drain + detach from the current recorder. The view stays
+   *  alive so the post-test snapshot captures it. Idempotent. */
+  detach(): Promise<void>;
+}
+
+// Runs in the page when a persistent view is attached to a new test's
+// recorder: drop whatever rrweb buffered since the previous detach (idle
+// mutations; the previous test's session already drained everything it
+// owns) and emit a fresh Meta + FullSnapshot so the new session's replay
+// is self-contained from its first event.
+const ATTACH_RESET_EXPR = `(function () {
+  window.__spectestRrwebEvents = [];
+  try {
+    var rec = window.__spectestRec;
+    if (rec && typeof rec.takeFullSnapshot === "function") {
+      rec.takeFullSnapshot();
+    }
+  } catch (e) { /* recording not active on this document */ }
+  return true;
+})()`;
+
+async function attachReset(holder: ViewHolder): Promise<void> {
+  if (!holder.recordingInstalled) return;
+  try {
+    await holder.page.evaluate(ATTACH_RESET_EXPR);
+  } catch {
+    // Page mid-navigation or renderer unhappy — the first drain forces a
+    // full snapshot when one is missing (drainExpr), so replay still works.
+  }
+}
+
+/**
+ * Acquire the persistent desktop browser called `name` (creating it on
+ * first use). There is one per name — `ctx.browser()` uses the default
+ * name `""` — so a test DAG shares each named browsing session along each
+ * branch, and two names are two independent users. The first call for a
+ * name wins its options; later calls attach to the existing view as-is.
+ */
+export async function acquirePersistentBrowser(
+  name = "",
+  opts: BrowserOptions = {},
+): Promise<PersistentBrowser> {
+  const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
+  let holder = SHARED_BROWSERS.get(name);
+  const attached = holder !== undefined;
+  if (holder) {
+    await attachReset(holder);
+  } else {
+    checkSessionCap("browser", SHARED_BROWSERS.size, name);
+    holder = await newHolder(
+      device ? device.viewport.width : opts.width ?? 1280,
+      device ? device.viewport.height : opts.height ?? 720,
+      device,
+    );
+    SHARED_BROWSERS.set(name, holder);
+  }
+  const view = holder;
+  const { backend, detach } = buildBackend(view, opts.recorder ?? null, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_BROWSERS.get(name) === view) SHARED_BROWSERS.delete(name);
+    },
+  });
+  // 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(view, opts.initScript);
+  }
+  if (!attached && opts.url !== undefined) await backend.goto(opts.url);
+  return { browser: backend, attached, detach };
+}
+
+/**
+ * Acquire the persistent mobile session for an app URL under `name` (one
+ * per name per app; `ctx.mobile(app)` uses the default name `""`). A fresh
+ * session navigates to the app; an attach continues on the live page.
+ */
+export async function acquirePersistentMobileBackend(
+  url: string,
+  name: string,
+  recorder: BrowserSessionRecorder | null,
+  initScript?: string,
+): Promise<PersistentBrowser> {
+  const key = mobileKey(name, url);
+  const existing = SHARED_MOBILE.get(key);
+  if (!existing) checkSessionCap("mobile", SHARED_MOBILE.size, name);
+  const holder =
+    existing ??
+    (await newHolder(
+      LATEST_IPHONE.viewport.width,
+      LATEST_IPHONE.viewport.height,
+      LATEST_IPHONE,
+    ));
+  if (existing) {
+    await attachReset(holder);
+  } else {
+    SHARED_MOBILE.set(key, holder);
+  }
+  const { backend, detach } = buildBackend(holder, recorder, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_MOBILE.get(key) === holder) SHARED_MOBILE.delete(key);
+    },
+  });
+  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 };
+}
+
+/** True when a navigation failed on Chromium name resolution. */
+function isNameNotResolved(err: unknown): boolean {
+  return String((err as Error)?.message ?? err).includes("ERR_NAME_NOT_RESOLVED");
+}
+
+/**
+ * Whether the daemon's own resolver can look the URL's host up. Chromium
+ * runs with AsyncDns disabled (see CHROME_ARGV) so it uses the same
+ * getaddrinfo path — a host the daemon resolves but Chrome can't means
+ * the RENDERER is broken, not the name.
+ */
+async function daemonResolves(url: string): Promise<boolean> {
+  try {
+    await dns.lookup(new URL(url).hostname);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Replace a persistent holder's page with a freshly-spawned one in the SAME
+ * context. Context state — cookies, localStorage — survives; only
+ * renderer-held page state is lost, and this path only runs when that
+ * renderer already can't navigate.
+ *
+ * Known trigger: a renderer created before a snapshot fails its first
+ * post-restore navigation with `net::ERR_NAME_NOT_RESOLVED` even though a
+ * fresh page in the SAME restored Chromium resolves fine (root cause never
+ * found — see the disabled-prewarm note at the end of /bootstrap in
+ * daemon.ts). Persistent sessions walk into exactly that scenario whenever
+ * a child test navigates, so the recovery lives here: rebuild the page,
+ * retry once.
+ */
+async function rebuildView(holder: ViewHolder): Promise<void> {
+  try {
+    await holder.page.close();
+  } catch {
+    /* page may already be gone */
+  }
+  const fresh = await spawnPage(holder.context);
+  holder.page = fresh.page;
+  holder.cdp = fresh.cdp;
+  holder.recordingInstalled = fresh.recordingInstalled;
+  if (holder.device) {
+    holder.safeAreaInsets = await applySafeAreaInsets(holder.cdp, holder.device);
+  }
+  for (const source of holder.initScripts) {
+    await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source });
+  }
+}
+
+interface BackendBuildOptions {
+  /** Persistent views get the DNS-recovery navigate and a close() that
+   *  clears them out of the shared registry; ephemeral views just close. */
+  persistent: boolean;
+  /** Called when close() destroys the underlying view — the acquire
+   *  functions use it to drop the holder from the shared registry. */
+  onDestroy?: () => void;
+}
+
+function buildBackend(
+  holder: ViewHolder,
+  recorder: BrowserSessionRecorder | null,
+  buildOpts: BackendBuildOptions,
+): { backend: MobileBackend; detach(): Promise<void> } {
+  // All page access goes through `holder.page` — never capture the page in
+  // a local — because the DNS-recovery rebuild swaps it mid-wrapper.
+  // `recordingEnded` stops this wrapper's recorder writes (test end);
+  // `viewClosed` tracks actual destruction (author called close()).
+  let recordingEnded = false;
+  let viewClosed = false;
+  const sessionStart = Date.now();
+  let stepSeq = 0;
+  // URL observed at the previous drain. A change means the main frame
+  // navigated to a new document since we last looked, which is exactly
+  // when rrweb's load-deferred full snapshot is most likely to be
+  // missing from the chunk we're about to drain (see `drainExpr`).
+  let lastDrainUrl: string | null = null;
+
+  /** Session provenance stamped on every recorded op: which replay player
+   *  the step belongs to, which named browser it acted on, and where in
+   *  the player to seek (`endT`, in rrweb's clock). */
+  function sessionFields(endT: number): Record<string, unknown> {
+    if (!recorder) return {};
+    return {
+      sessionId: recorder.sessionId,
+      sessionTimestamp: endT,
+      ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
+    };
+  }
+
+  async function drain(action: BrowserAction | "close"): Promise<void> {
+    if (!holder.recordingInstalled || !recorder || recordingEnded) return;
+    try {
+      const urlChanged = holder.page.url() !== lastDrainUrl;
+      const events = (await holder.page.evaluate(drainExpr(urlChanged))) as unknown[];
+      lastDrainUrl = holder.page.url();
+      if (Array.isArray(events) && events.length > 0) {
+        recorder.recordStep({
+          stepSeq: stepSeq++,
+          action,
+          tOffsetMs: Date.now() - sessionStart,
+          events,
+        });
+      }
+    } catch {
+      // Page may be mid-navigation, detached, or the view is closing.
+      // Losing an occasional drain is acceptable — the next op picks up
+      // the rest of the buffer.
+    }
+  }
+
+  async function instrumented<T>(
+    action: BrowserAction,
+    fields: Partial<RecordableFields>,
+    fn: () => Promise<T>,
+    opts?: { wrap?: boolean },
+  ): Promise<T> {
+    const t = Date.now();
+    const resv = reserveEvent();
+    try {
+      const result = await fn();
+      // Refresh the sync title cache (playwright's title() is async).
+      try {
+        holder.lastTitle = await holder.page.title();
+      } catch {
+        /* page mid-navigation or closed — keep the stale cache */
+      }
+      // `sessionTimestamp` is the post-op wall clock — that's where we
+      // want the dashboard's seek to land, so clicking "type 'foo'"
+      // shows the input *with* the text, not the empty field just
+      // before the keystrokes. The dashboard converts to a player
+      // offset by subtracting `events[0].timestamp`.
+      const endT = Date.now();
+      const seq = recordBrowser({
+        action,
+        ...fields,
+        ...sessionFields(endT),
+        durationMs: endT - t,
+      }, resv);
+      await drain(action);
+      // 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;
+    } catch (err) {
+      const e = err as Error;
+      const endT = Date.now();
+      recordBrowser({
+        action,
+        ...fields,
+        ...sessionFields(endT),
+        durationMs: endT - t,
+        error: e?.message ?? String(err),
+      }, resv);
+      // Still try to drain — the failure itself may have produced
+      // useful rrweb events (mutations from a half-loaded page, etc.).
+      await drain(action);
+      throw err;
+    }
+  }
+
+  async function endRecording(): Promise<void> {
+    if (recordingEnded) return;
+    // Final drain before we stop writing to this recorder.
+    await drain("close");
+    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 = {
+    url() {
+      return holder.page.url();
+    },
+    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;
+    },
+    keyboard,
+    mouse,
+    touchscreen,
+    goto(url) {
+      recorder?.noteNavigation?.(url);
+      return instrumented("goto", { url }, async () => {
+        try {
+          await holder.page.goto(url, { waitUntil: "load" });
+        } catch (err) {
+          // Restored-renderer DNS bug (see `rebuildView`): only when the
+          // view is persistent (so it may have lived through a snapshot
+          // restore) and the daemon itself CAN resolve the host — a name
+          // that's genuinely unknown must fail without discarding the live
+          // page state a rebuild would cost.
+          if (!buildOpts.persistent || !isNameNotResolved(err)) throw err;
+          if (!(await daemonResolves(url))) throw err;
+          await rebuildView(holder);
+          await holder.page.goto(url, { waitUntil: "load" });
+        }
+      });
+    },
+    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,
+      fn: string | ((arg?: unknown) => T | Promise<T>),
+      arg?: unknown,
+    ): Promise<Wrapped<T>> {
+      const src = typeof fn === "string" ? fn : fn.toString();
+      const t = truncateUtf8(src);
+      return instrumented<T>(
+        "evaluate",
+        { description, script: t.value, scriptTruncated: t.truncated },
+        async () => {
+          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>>;
+    },
+    async waitForURL(
+      pattern: UrlPattern,
+      options: {
+        timeout?: number;
+        waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
+      } = {},
+    ): Promise<Wrapped<string>> {
+      const timeoutMs = options.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
+      const label = describeUrlPattern(pattern);
+      // `url` is stamped with the MATCHED url once we have it (the timeline
+      // wants where we landed, not the pattern); `description` carries the
+      // pattern so a timed-out step still says what it was waiting for.
+      const fields: Partial<RecordableFields> = { description: label };
+      return instrumented<string>(
+        "waitForURL",
+        fields,
+        async () => {
+          try {
+            // Always a predicate, never playwright's own glob: `matchesUrl`
+            // is then the single matching implementation shared with
+            // `expect(browser).toHaveURL`.
+            await holder.page.waitForURL((u: URL) => matchesUrl(u.href, pattern), {
+              timeout: timeoutMs,
+              waitUntil: options.waitUntil ?? "commit",
+            });
+          } catch (err) {
+            // Playwright's timeout message is a wall of call-log; ours names
+            // the pattern and where the page actually sat.
+            if ((err as Error)?.name !== "TimeoutError") throw err;
+            throw new Error(
+              `waitForURL ${label} timed out after ${timeoutMs}ms (current URL: ${holder.page.url()})`,
+            );
+          }
+          const matched = holder.page.url();
+          fields.url = matched;
+          return matched;
+        },
+        { wrap: true },
+        // `wrap: true` hands back a Carrier<string>, which the concrete
+        // (non-generic) return type can't be narrowed to directly.
+      ) as unknown as Promise<Wrapped<string>>;
+    },
+    async waitForFunction<T = unknown>(
+      description: string,
+      fn: string | ((arg?: unknown) => T),
+      arg?: unknown,
+      options: { timeout?: number; polling?: number } = {},
+    ): Promise<Wrapped<T>> {
+      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: t.value,
+        scriptTruncated: t.truncated,
+        attempts: 0,
+      };
+      // 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));
+          }
+        },
+        { wrap: true },
+      ) as Promise<Wrapped<T>>;
+    },
+    async screenshot() {
+      const fields: Partial<RecordableFields> = { format: "png" };
+      return instrumented("screenshot", fields, async () => {
+        // Artifacts are eval-only for now: the daemon wires a
+        // registerArtifact sink onto eval sessions' recorders and nothing
+        // else's, so its absence means "test run / recorder-less browser".
+        const register = recorder?.registerArtifact;
+        if (!register) {
+          throw new Error(
+            "screenshot() uploads the capture as a downloadable artifact and is " +
+              "currently only available inside an eval (`spectest env eval`) — " +
+              "it cannot be used in test runs.",
+          );
+        }
+        // Raw CDP rather than page.screenshot(): captures the viewport
+        // exactly like the pre-Playwright backend.
+        const res = (await holder.cdp.send("Page.captureScreenshot", {
+          format: "png",
+        } as never)) as { data: string };
+        const id = generateId("art");
+        register({
+          id,
+          kind: "screenshot",
+          contentType: "image/png",
+          // CDP already hands us base64 — pass it through un-recoded and
+          // derive the raw byte count from the encoding.
+          sizeBytes: base64ByteLength(res.data),
+          bytesBase64: res.data,
+        });
+        // Stamped onto the browser event before instrumented() records it —
+        // same mutate-fields-inside-fn() precedent as waitFor's `attempts`.
+        fields.artifactId = id;
+        return id;
+      });
+    },
+    async close() {
+      // Ends this wrapper's recording AND destroys the view. For a
+      // persistent view this is the author-facing escape hatch to a fresh
+      // browser: `onDestroy` drops the holder from the shared registry, so
+      // the next `ctx.browser()`/`ctx.mobile()` creates a new one. The
+      // routine test-end path is `detach` (recording stops, view lives on
+      // into the post-test snapshot).
+      await endRecording();
+      if (viewClosed) return;
+      viewClosed = true;
+      buildOpts.onDestroy?.();
+      try {
+        await holder.page.close();
+      } catch {
+        /* already closed by the runtime */
+      }
+      // The context, not the page, holds the cookies and storage — closing
+      // only the page would leave the next session signed in as this one.
+      try {
+        await holder.context.close();
+      } catch {
+        /* context already gone (browser died) */
+      }
+    },
+    // ── Mobile-only primitives ──────────────────────────────────────────
+    async rawTap(x, y, durationMs) {
+      // Dispatches a real touch so RN-Web's responder system fires.
+      await holder.cdp.send("Input.dispatchTouchEvent", {
+        type: "touchStart",
+        touchPoints: [{ x, y, id: 0 }],
+      });
+      // Dwell between start and end, like a real finger. An instant
+      // touchStart→touchEnd starves RN Pressables whose `onPressIn`
+      // mutates state (optimistic label flips, scale animations): React
+      // re-renders mid-gesture and the press never completes. The dwell
+      // lets that commit land before release; well under any long-press
+      // threshold (RN default 500ms).
+      await new Promise((r) => setTimeout(r, durationMs ?? TAP_DWELL_MS));
+      await holder.cdp.send("Input.dispatchTouchEvent", {
+        type: "touchEnd",
+        touchPoints: [],
+      });
+    },
+    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 () => {
+        const steps = 8;
+        await holder.cdp.send("Input.dispatchTouchEvent", {
+          type: "touchStart",
+          touchPoints: [{ x, y, id: 0 }],
+        });
+        for (let i = 1; i <= steps; i++) {
+          await holder.cdp.send("Input.dispatchTouchEvent", {
+            type: "touchMove",
+            touchPoints: [{ x: x + (dx * i) / steps, y: y + (dy * i) / steps, id: 0 }],
+          });
+        }
+        await holder.cdp.send("Input.dispatchTouchEvent", {
+          type: "touchEnd",
+          touchPoints: [],
+        });
+      });
+    },
+    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. The offset is backdated to
+      // where the matcher started polling, since that's what `tOffsetMs` means
+      // everywhere else (the ops that reserve up front stamp their start).
+      const endT = Date.now();
+      const seq = recordBrowser({
+        action,
+        ...fields,
+        ...sessionFields(endT),
+        durationMs: waitedMs,
+        ...(error ? { error } : {}),
+      }, reserveBackdated(waitedMs));
+      // 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), opts);
+    },
+  };
+  // The seam `expect(browser).toHaveURL(...)` polls: a silent URL read plus
+  // the single settled step its assertion nests under — the session twin of
+  // the locator probe, and what brands this object as a browser session for
+  // `expect`'s overload dispatch.
+  attachBrowserProbe(backend, {
+    url: () => holder.page.url(),
+    settle: (action, waitedMs, error) =>
+      backend.recordSettled(action, { url: holder.page.url() }, waitedMs, error),
+  });
+  return { backend, detach: endRecording };
+}
+
+export interface RecordableFields {
+  url: string;
+  selector: string;
+  description: string;
+  script: string;
+  scriptTruncated: boolean;
+  text: string;
+  textTruncated: boolean;
+  key: string;
+  dx: number;
+  dy: number;
+  x: number;
+  y: number;
+  format: string;
+  attempts: number;
+  artifactId: string;
+  attribute: string;
+}