@specific.dev/spectest 0.4.0

package/src/browser.ts

@@ -0,0 +1,824 @@
+// Headless browser handle for tests. Thin wrapper around Bun.WebView
+// driving Chromium-over-CDP. The wrapper keeps the public surface stable
+// (we'd swap to a different backend 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.
+//
+// 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).
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { recordBrowser, reserveEvent, truncateUtf8 } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+// Minimal local declaration of the bits of Bun.WebView we use, so the SDK
+// type-checks in projects that don't install `@types/bun` themselves. At
+// runtime Bun supplies the real implementation.
+interface BunWebViewBackendChrome {
+  type: "chrome";
+  path?: string;
+  argv?: string[];
+}
+
+interface BunWebViewOptions {
+  width?: number;
+  height?: number;
+  url?: string;
+  backend?: "chrome" | "webkit" | BunWebViewBackendChrome;
+}
+
+interface BunWebViewScreenshotOptions {
+  encoding?: "buffer";
+  format?: ScreenshotFormat;
+  quality?: number;
+}
+
+interface BunWebViewInstance {
+  readonly url: string;
+  readonly title: string;
+  navigate(url: string): Promise<void>;
+  evaluate<T = unknown>(script: string): Promise<T>;
+  click(selector: string): Promise<void>;
+  click(x: number, y: number): Promise<void>;
+  type(text: string): Promise<void>;
+  press(key: string): Promise<void>;
+  scroll(dx: number, dy: number): Promise<void>;
+  scrollTo(selector: string): Promise<void>;
+  back(): Promise<void>;
+  forward(): Promise<void>;
+  reload(): Promise<void>;
+  screenshot(opts?: BunWebViewScreenshotOptions): Promise<Buffer>;
+  cdp<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  close(): void;
+}
+
+interface BunWebViewCtor {
+  new (options?: BunWebViewOptions): BunWebViewInstance;
+}
+
+declare const Bun: { WebView: BunWebViewCtor };
+
+export interface BrowserOptions {
+  /** Viewport width in pixels. Default 1280. */
+  width?: number;
+  /** Viewport height in pixels. Default 720. */
+  height?: number;
+  /** Initial URL to navigate to before the constructor returns. */
+  url?: 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;
+}
+
+export type ScreenshotFormat = "png" | "jpeg" | "webp";
+
+export interface ScreenshotOptions {
+  /** Image format. WebP requires Chrome. Default PNG. */
+  format?: ScreenshotFormat;
+  /** JPEG/WebP quality 0–100. Ignored for PNG. */
+  quality?: number;
+}
+
+/** 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.navigate(url)` is invoked. */
+  noteNavigation?(url: string): void;
+}
+
+/**
+ * Headless browser handle. Operations are sequential per view — Bun rejects
+ * a second concurrent `evaluate()` with `ERR_INVALID_STATE`, and our wrapper
+ * inherits that. For parallel browsing open multiple views.
+ */
+export interface Browser {
+  /** Last-navigated URL (updated on navigate completion). */
+  readonly url: string;
+  /** Current page `<title>`. */
+  readonly title: string;
+  /** Navigate to a URL; resolves when the main frame's load completes. */
+  navigate(url: string): Promise<void>;
+  /**
+   * Evaluate a JS expression in the page and return the
+   * JSON-deserialised result.
+   *
+   * `description` is a short human-readable label for what the
+   * snippet is doing ("read rendered todo list"); it surfaces in the
+   * test event log so the step list isn't a wall of minified code.
+   */
+  evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
+  /**
+   * Poll `expression` in the page until it returns a truthy value
+   * (the returned value is what `waitFor` resolves with). Useful for
+   * UI assertions that need to wait for an async render — instead of
+   * a manual `while (Date.now() < deadline) await evaluate(...)` loop
+   * which clutters the test log with one event per poll, this records
+   * a single `waitFor` event with the total wait time and how many
+   * attempts it took.
+   *
+   * Express the predicate as "return the data if ready, else falsy":
+   *
+   * ```ts
+   * const items = await browser.waitFor<string[]>(
+   *   "todo appears",
+   *   "(() => { const xs = [...document.querySelectorAll('li')].map(l => l.textContent); return xs.includes('hi') ? xs : null; })()",
+   * );
+   * ```
+   *
+   * Defaults: 5 s total timeout, 100 ms between polls.
+   */
+  waitFor<T = unknown>(
+    description: string,
+    expression: string,
+    options?: { timeoutMs?: number; intervalMs?: number },
+  ): Promise<Wrapped<T>>;
+  /** Wait for `selector` to be actionable and click its center. */
+  click(selector: string): Promise<void>;
+  /** Click at the given viewport coordinates. */
+  clickAt(x: number, y: number): Promise<void>;
+  /** Insert text into the focused element (no `keydown` — same path as paste). */
+  type(text: string): Promise<void>;
+  /** Press a named key (`"Enter"`, `"Tab"`, …) or single character. */
+  press(key: string): Promise<void>;
+  /** Scroll the viewport by the given pixel delta. */
+  scroll(dx: number, dy: number): Promise<void>;
+  /** Wait for `selector` to exist and scroll it into view. */
+  scrollTo(selector: string): Promise<void>;
+  /** Navigate back in session history. */
+  back(): Promise<void>;
+  /** Navigate forward in session history. */
+  forward(): Promise<void>;
+  /** Reload the current page. */
+  reload(): Promise<void>;
+  /** Capture a PNG/JPEG/WebP screenshot of the viewport. Returns raw bytes. */
+  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+  /** Close the underlying view. Idempotent. Drains any pending rrweb events. */
+  close(): Promise<void>;
+}
+
+// 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",
+];
+
+// ────────────────────────────────────────────────────────────────────────
+// rrweb bootstrap
+// ────────────────────────────────────────────────────────────────────────
+
+// Vendored rrweb-record bundle (UMD, exposes `rrwebRecord` 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 () {
+  if (typeof rrwebRecord !== "function") return;
+  if (window.__spectestRrwebInit) return;
+  window.__spectestRrwebInit = true;
+  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 {
+    rrwebRecord({
+      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> and CSS background images into data
+      // URIs. \`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 (typeof rrwebRecord === "function" &&
+              typeof rrwebRecord.takeFullSnapshot === "function") {
+            rrwebRecord.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)); }
+  })();
+})();
+`;
+
+const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
+  ? `${RRWEB_BUNDLE}\n${RRWEB_CONSOLE_PLUGIN_BUNDLE}\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 `rrwebRecord.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 {
+    if (${forceFullIfMissing ? "true" : "false"} &&
+        window.__spectestRrwebInit &&
+        typeof rrwebRecord === "function" &&
+        typeof rrwebRecord.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) rrwebRecord.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 pre-opened, never-used view: renderer already spawned, rrweb init
+ *  script installed, parked on about:blank. */
+interface PooledView {
+  view: BunWebViewInstance;
+  recordingInstalled: boolean;
+}
+
+// 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[] = [];
+
+/** Create a view + CDP session + rrweb init script — the slow part. */
+async function createView(width: number, height: number): Promise<PooledView> {
+  const view = new Bun.WebView({
+    width,
+    height,
+    backend: { type: "chrome", argv: CHROME_ARGV },
+  });
+
+  // Bun's docs: `cdp()` requires at least one navigate first to set up
+  // the CDP session. about:blank is the cheapest bootstrap target.
+  await view.navigate("about:blank");
+
+  let recordingInstalled = false;
+  if (PAGE_INIT_SCRIPT) {
+    try {
+      await view.cdp("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 { view, recordingInstalled };
+}
+
+/**
+ * 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. Always uses the Chrome backend in the daemon
+ * (Firecracker guest is Linux; WKWebView isn't available). Serves from
+ * the pre-opened pool when the caller uses the default viewport.
+ */
+export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
+  const wantW = opts.width ?? 1280;
+  const wantH = opts.height ?? 720;
+  const pooled =
+    wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+  const { view, recordingInstalled } = pooled ?? (await createView(wantW, wantH));
+
+  const browser = wrapView(view, opts.recorder ?? null, recordingInstalled);
+
+  // 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.url !== undefined) {
+    await browser.navigate(opts.url);
+  }
+  return browser;
+}
+
+function wrapView(
+  view: BunWebViewInstance,
+  recorder: BrowserSessionRecorder | null,
+  recordingInstalled: boolean,
+): Browser {
+  let closed = 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 (!recordingInstalled || !recorder || closed) return;
+    try {
+      const urlChanged = view.url !== lastDrainUrl;
+      const events = await view.evaluate<unknown[]>(drainExpr(urlChanged));
+      lastDrainUrl = view.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>,
+  ): Promise<T> {
+    const t = Date.now();
+    const resv = reserveEvent();
+    try {
+      const result = await fn();
+      // `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);
+      // Only `evaluate` and `waitFor` return user-visible JS values
+      // that someone is likely to assert on. Other actions return void
+      // or browser internals; leave them raw to avoid Proxy surprises.
+      if (seq !== undefined && (action === "evaluate" || action === "waitFor")) {
+        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;
+    }
+  }
+
+  return {
+    get url() {
+      return view.url;
+    },
+    get title() {
+      return view.title;
+    },
+    navigate(url) {
+      recorder?.noteNavigation?.(url);
+      return instrumented("navigate", { url }, () => view.navigate(url));
+    },
+    async evaluate<T = unknown>(
+      description: string,
+      script: string,
+    ): Promise<Wrapped<T>> {
+      const truncatedScript = truncateUtf8(script);
+      // `instrumented` wraps the result for evaluate/waitFor (see line ~622),
+      // so the value is a `Wrapped<T>` at runtime; the cast matches the type.
+      return instrumented<T>(
+        "evaluate",
+        {
+          description,
+          script: truncatedScript.value,
+          scriptTruncated: truncatedScript.truncated,
+        },
+        async () => {
+          const v = await view.evaluate<T>(script);
+          return v;
+        },
+      ) as Promise<Wrapped<T>>;
+    },
+    async waitFor<T = unknown>(
+      description: string,
+      expression: string,
+      options: { timeoutMs?: number; intervalMs?: number } = {},
+    ): Promise<Wrapped<T>> {
+      const timeoutMs = options.timeoutMs ?? 5_000;
+      const intervalMs = options.intervalMs ?? 100;
+      const truncatedScript = truncateUtf8(expression);
+      // Pass `fields` by reference so the loop can stamp the final
+      // attempt count onto the event before instrumented records it.
+      const fields: Partial<RecordableFields> = {
+        description,
+        script: truncatedScript.value,
+        scriptTruncated: truncatedScript.truncated,
+        attempts: 0,
+      };
+      return instrumented<T>("waitFor", fields, async () => {
+        const deadline = Date.now() + timeoutMs;
+        // (return value wrapped by `instrumented`; cast below matches.)
+        // The polling loop calls `view.evaluate` directly (not the
+        // wrapped `evaluate`) so it doesn't fan out into N events in
+        // the log or N rrweb drains. rrweb keeps buffering page-side
+        // throughout the wait; the wrapper's single drain at the end
+        // collects everything.
+        for (;;) {
+          fields.attempts = (fields.attempts ?? 0) + 1;
+          let v: unknown;
+          try {
+            v = await view.evaluate<unknown>(expression);
+          } 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(
+              `waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${fields.attempts} attempts)`,
+            );
+          }
+          await new Promise((r) => setTimeout(r, intervalMs));
+        }
+      }) as Promise<Wrapped<T>>;
+    },
+    click(selector) {
+      return instrumented("click", { selector }, () => view.click(selector));
+    },
+    clickAt(x, y) {
+      return instrumented("click", { x, y }, () => view.click(x, y));
+    },
+    type(text) {
+      const t = truncateUtf8(text);
+      return instrumented(
+        "type",
+        { text: t.value, textTruncated: t.truncated },
+        () => view.type(text),
+      );
+    },
+    press(key) {
+      return instrumented("press", { key }, () => view.press(key));
+    },
+    scroll(dx, dy) {
+      return instrumented("scroll", { dx, dy }, () => view.scroll(dx, dy));
+    },
+    scrollTo(selector) {
+      return instrumented("scrollTo", { selector }, () => view.scrollTo(selector));
+    },
+    back() {
+      return instrumented("back", {}, () => view.back());
+    },
+    forward() {
+      return instrumented("forward", {}, () => view.forward());
+    },
+    reload() {
+      return instrumented("reload", {}, () => view.reload());
+    },
+    async screenshot(options) {
+      const format = options?.format ?? "png";
+      return instrumented("screenshot", { format }, async () => {
+        const buf = await view.screenshot({
+          encoding: "buffer",
+          format,
+          quality: options?.quality,
+        });
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+      });
+    },
+    async close() {
+      if (closed) return;
+      // Final drain before the page evaporates.
+      await drain("close");
+      closed = true;
+      try {
+        view.close();
+      } catch {
+        /* already closed by the runtime */
+      }
+    },
+  };
+}
+
+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: ScreenshotFormat;
+  attempts: number;
+}