@specific.dev/spectest 0.24.0 → 0.27.0

package/src/browser.ts

@@ -1,1807 +0,0 @@
-// 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, 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 {
-  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;
-  /** 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>>;
-  /**
-   * 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.
-   */
-  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_eval` /
-   * `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).
-const CHROME_ARGV = [
-  "--no-sandbox",
-  "--disable-dev-shm-usage",
-  "--disable-features=AsyncDns,DnsOverHttps",
-  "--dns-over-https-mode=off",
-];
-
-/** 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;
-// The shared desktop context (default 1280×720 viewport). All desktop views
-// live here so they share one cookie jar, mirroring the old one-Chrome-
-// profile model. Mobile sessions and custom-viewport views get their own
-// contexts (viewport/DPR/UA/touch are context-scoped in playwright).
-let DESKTOP_CTX: BrowserContext | null = null;
-
-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,
-  });
-  DESKTOP_CTX = null; // contexts died with the old browser (if any)
-  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,
-  };
-}
-
-async function ensureDesktopContext(): Promise<BrowserContext> {
-  const browser = await ensurePlaywrightBrowser();
-  if (DESKTOP_CTX) return DESKTOP_CTX;
-  DESKTOP_CTX = await browser.newContext({
-    viewport: { width: 1280, height: 720 },
-  });
-  DESKTOP_CTX.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-  DESKTOP_CTX.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-  return DESKTOP_CTX;
-}
-
-/**
- * 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: once
-  // fonts have loaded, 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.
-  (function () {
-    if (window.__spectestFontsInlined) return;
-    window.__spectestFontsInlined = 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) {}
-        }
-      }
-    }
-    function run() {
-      // 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 || "";
-          var urls = urlsIn(cssText, base);
-          if (urls.length) faces.push({ cssText: cssText, urls: urls });
-        });
-      }
-      log("sheets=" + sheets.length + " readable=" + readable +
-          " fontFaces=" + faceCount + " withUrl=" + faces.length);
-      if (!faces.length) return;
-      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;
-          }
-          return changed ? text : null;
-        });
-      });
-      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)); }
-      });
-    }
-    try {
-      if (document.fonts && document.fonts.ready && document.fonts.ready.then) {
-        document.fonts.ready.then(function () { setTimeout(run, 0); });
-      } else if (document.readyState === "complete") {
-        run();
-      } else {
-        window.addEventListener("load", run);
-      }
-    } 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)); }
-  })();
-})();
-`;
-
-// 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 (lives in the shared desktop
- *  context). */
-interface PooledView extends SpawnedPage {}
-
-/**
- * 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. Shared desktop context for default-size
-   *  desktop views; a private one for mobile/custom-viewport views. */
-  context: BrowserContext;
-  /** Whether close() should also close the context (private contexts). */
-  ownsContext: boolean;
-  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 };
-}
-
-/** Acquire the context a view of this shape lives in. */
-async function contextFor(
-  width: number,
-  height: number,
-  device: DevicePreset | null,
-): Promise<{ context: BrowserContext; ownsContext: boolean }> {
-  if (device) {
-    const browser = await ensurePlaywrightBrowser();
-    const context = await browser.newContext(deviceContextOptions(device));
-    context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-    context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-    return { context, ownsContext: true };
-  }
-  if (width === 1280 && height === 720) {
-    return { context: await ensureDesktopContext(), ownsContext: false };
-  }
-  const browser = await ensurePlaywrightBrowser();
-  const context = await browser.newContext({ viewport: { width, height } });
-  context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-  context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-  return { context, ownsContext: true };
-}
-
-/** Create a default-desktop view for the pool. */
-async function createView(width: number, height: number): Promise<PooledView> {
-  const { context } = await contextFor(width, height, null);
-  return 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: await ensureDesktopContext(),
-      ownsContext: false,
-      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)
-// ────────────────────────────────────────────────────────────────────────
-
-// One long-lived desktop browser plus one mobile session per app URL.
-// Module state lives in daemon memory, so it forks with the snapshot the
-// same way fake `state` and TEST_DATA do: a test's browser — its live
-// page, cookies, localStorage, in-memory SPA state — is 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.
-let SHARED_BROWSER: ViewHolder | null = null;
-const SHARED_MOBILE = new Map<string, ViewHolder>();
-
-async function newHolder(
-  width: number,
-  height: number,
-  device: DevicePreset | null,
-): Promise<ViewHolder> {
-  const { context, ownsContext } = await contextFor(width, height, device);
-  const spawned = await spawnPage(context);
-  const holder: ViewHolder = {
-    context,
-    ownsContext,
-    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 (creating it on first use). There
- * is deliberately a single one — `ctx.browser()` always returns it — so a
- * test DAG shares one browsing session along each branch. The first call's
- * options win; later calls attach to the existing view as-is.
- */
-export async function acquirePersistentBrowser(
-  opts: BrowserOptions = {},
-): Promise<PersistentBrowser> {
-  const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
-  let attached = true;
-  if (!SHARED_BROWSER) {
-    attached = false;
-    SHARED_BROWSER = await newHolder(
-      device ? device.viewport.width : opts.width ?? 1280,
-      device ? device.viewport.height : opts.height ?? 720,
-      device,
-    );
-  } else {
-    await attachReset(SHARED_BROWSER);
-  }
-  const holder = SHARED_BROWSER;
-  const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
-    persistent: true,
-    onDestroy: () => {
-      if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
-    },
-  });
-  // 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 };
-}
-
-/**
- * Acquire the persistent mobile session for an app URL (one per app). A
- * fresh session navigates to the app; an attach continues on the live page.
- */
-export async function acquirePersistentMobileBackend(
-  url: string,
-  recorder: BrowserSessionRecorder | null,
-  initScript?: string,
-): Promise<PersistentBrowser> {
-  const existing = SHARED_MOBILE.get(url);
-  const holder =
-    existing ??
-    (await newHolder(
-      LATEST_IPHONE.viewport.width,
-      LATEST_IPHONE.viewport.height,
-      LATEST_IPHONE,
-    ));
-  if (existing) {
-    await attachReset(holder);
-  } else {
-    SHARED_MOBILE.set(url, holder);
-  }
-  const { backend, detach } = buildBackend(holder, recorder, {
-    persistent: true,
-    onDestroy: () => {
-      if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(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 };
-}
-
-/** 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;
-
-  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,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: 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,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: 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 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_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 */
-      }
-      if (holder.ownsContext) {
-        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.
-      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), opts);
-    },
-  };
-  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;
-}