@specific.dev/spectest 0.26.0 → 0.28.0

package/dist/browser.js

@@ -0,0 +1,1320 @@
+// 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 { DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
+import { chromium } from "playwright-core";
+/** Decoded byte count of a base64 string, without decoding it. */
+function base64ByteLength(b64) {
+    let padding = 0;
+    if (b64.endsWith("=="))
+        padding = 2;
+    else if (b64.endsWith("="))
+        padding = 1;
+    return (b64.length * 3) / 4 - padding;
+}
+// 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 = 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 = null;
+function chromiumPath() {
+    return (Bun.which("chromium") ??
+        Bun.which("chromium-browser") ??
+        Bun.which("google-chrome") ??
+        "/usr/bin/chromium");
+}
+async function ensurePlaywrightBrowser() {
+    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) {
+    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",
+    };
+}
+async function ensureDesktopContext() {
+    const browser = await ensurePlaywrightBrowser();
+    if (DESKTOP_CTX)
+        return DESKTOP_CTX;
+    DESKTOP_CTX = await browser.newContext({
+        viewport: { width: 1280, height: 720 },
+        // Reduced-motion for replay fidelity — see deviceContextOptions.
+        reducedMotion: "reduce",
+    });
+    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) {
+    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})()`;
+    }
+}
+/** 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 = {
+    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, d) {
+    try {
+        await cdp.send(
+        // Not in playwright's Protocol types yet (Chromium ≥ ~135 method).
+        "Emulation.setSafeAreaInsetsOverride", { insets: { ...d.safeAreaInsets } });
+        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 = (() => {
+    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 = (() => {
+    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) {
+    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;
+})()`;
+}
+// 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 = [];
+/** Spawn a page (+ CDP session + rrweb init script) into `context` — the
+ *  slow part (renderer process spawn). */
+async function spawnPage(context) {
+    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, height, device) {
+    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 },
+        // Reduced-motion for replay fidelity — see deviceContextOptions.
+        reducedMotion: "reduce",
+    });
+    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, height) {
+    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) {
+    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 = {}) {
+    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 = {}) {
+    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;
+    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 = null;
+const SHARED_MOBILE = new Map();
+async function newHolder(width, height, device) {
+    const { context, ownsContext } = await contextFor(width, height, device);
+    const spawned = await spawnPage(context);
+    const holder = {
+        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, source) {
+    await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source });
+    holder.initScripts.push(source);
+}
+// 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) {
+    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 = {}) {
+    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, recorder, initScript) {
+    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) {
+    return String(err?.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) {
+    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) {
+    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 });
+    }
+}
+function buildBackend(holder, recorder, buildOpts) {
+    // 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 = null;
+    async function drain(action) {
+        if (!holder.recordingInstalled || !recorder || recordingEnded)
+            return;
+        try {
+            const urlChanged = holder.page.url() !== lastDrainUrl;
+            const events = (await holder.page.evaluate(drainExpr(urlChanged)));
+            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(action, fields, fn, opts) {
+        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);
+            }
+            return result;
+        }
+        catch (err) {
+            const e = err;
+            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() {
+        if (recordingEnded)
+            return;
+        // Final drain before we stop writing to this recorder.
+        await drain("close");
+        recordingEnded = true;
+    }
+    const strategy = holder.device ? mobileStrategy : desktopStrategy;
+    const 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 = {
+        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 = {
+        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 = {
+        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(description, fn, arg) {
+            const src = typeof fn === "string" ? fn : fn.toString();
+            const t = truncateUtf8(src);
+            return instrumented("evaluate", { description, script: t.value, scriptTruncated: t.truncated }, async () => {
+                if (typeof fn === "string") {
+                    return (await holder.page.evaluate(toEvaluable(fn)));
+                }
+                return (await holder.page.evaluate(fn, arg));
+            }, { wrap: true });
+        },
+        async waitForFunction(description, fn, arg, options = {}) {
+            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 = {
+                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 = () => evaluable !== null
+                ? holder.page.evaluate(evaluable)
+                : holder.page.evaluate(fn, arg);
+            return instrumented("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;
+                    try {
+                        v = await evalOnce();
+                    }
+                    catch (err) {
+                        if (Date.now() >= deadline)
+                            throw err;
+                        await new Promise((r) => setTimeout(r, intervalMs));
+                        continue;
+                    }
+                    if (v)
+                        return v;
+                    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 });
+        },
+        async screenshot() {
+            const fields = { 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",
+                }));
+                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: 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(expression) {
+            return holder.page.evaluate(expression);
+        },
+        silentRead(fn) {
+            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(action, fields, fn, opts) {
+            return instrumented(action, fields, () => fn(holder.page), opts);
+        },
+    };
+    return { backend, detach: endRecording };
+}