@specific.dev/spectest 0.17.0 → 0.18.0

package/src/browser.ts

@@ -1,8 +1,13 @@
-// 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.
+// 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
@@ -32,52 +37,17 @@ 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;
-}
+import { chromium } from "playwright-core";
+import type {
+  Browser as PlaywrightBrowser,
+  BrowserContext,
+  CDPSession,
+  Page,
+} from "playwright-core";
 
-declare const Bun: { WebView: BunWebViewCtor };
+// Minimal declaration of the one Bun global we use (executable lookup), so
+// the SDK type-checks in projects that don't install `@types/bun`.
+declare const Bun: { which(bin: string): string | null };
 
 export interface BrowserOptions {
   /** Viewport width in pixels. Default 1280. Ignored when `frame: "mobile"`
@@ -147,9 +117,9 @@ export interface BrowserSessionRecorder {
 }
 
 /**
- * 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.
+ * Headless browser handle. Drive operations sequentially per view — the
+ * recorder assumes op-at-a-time semantics (each op's rrweb drain is
+ * attributed to it). For parallel browsing open multiple views.
  */
 export interface Browser {
   /** Last-navigated URL (updated on navigate completion). */
@@ -264,10 +234,28 @@ export interface MobileBackend extends Browser {
   swipeBy(x: number, y: number, dx: number, dy: number): Promise<void>;
   /**
    * Evaluate a JS expression in the page WITHOUT recording an event or
-   * draining rrweb — the locator layer's internal element resolver. rrweb
-   * keeps buffering page-side; the next recorded op drains it.
+   * draining rrweb. rrweb keeps buffering page-side; the next recorded op
+   * drains it.
    */
   probe<T = unknown>(expression: string): Promise<T>;
+  /**
+   * Run `fn` against the live playwright {@link Page}, recorded as a single
+   * `action` event (with the usual rrweb drain). The locator layer's hook:
+   * one author-facing locator action = one recorded event, however many
+   * playwright calls it composes. `evaluate`/`waitFor` actions get their
+   * return value provenance-wrapped like the first-class verbs.
+   */
+  pageOp<T>(
+    action: BrowserAction,
+    fields: Partial<RecordableFields>,
+    fn: (page: Page) => Promise<T>,
+  ): Promise<T>;
+  /**
+   * Unrecorded CDP touch tap (touchStart → dwell → touchEnd). The locator
+   * layer composes it inside a {@link pageOp} so a locator `tap()` stays a
+   * single recorded event; `tapAt` is the recorded public twin.
+   */
+  rawTap(x: number, y: number, durationMs?: number): Promise<void>;
 }
 
 // Default extra flags for headless Chromium inside a Firecracker microVM.
@@ -295,6 +283,75 @@ const CHROME_ARGV = [
 /** Default touchStart→touchEnd dwell for `tapAt` — see the comment there. */
 const TAP_DWELL_MS = 60;
 
+/** Default deadline for element-targeting ops (click/scrollTo and the mobile
+ *  locator actions). Playwright's own default is 30 s — far too slow-failing
+ *  for tests; 5 s matches the pre-Playwright behavior. Navigations keep a
+ *  longer 30 s deadline (cold app servers). */
+const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+const NAVIGATION_TIMEOUT_MS = 30_000;
+
+// ────────────────────────────────────────────────────────────────────────
+// Shared Chromium (playwright-core)
+// ────────────────────────────────────────────────────────────────────────
+
+// One Chromium per daemon, launched lazily on first view creation and kept
+// for the daemon's lifetime. It rides snapshots: the process, playwright's
+// pipe connection to it, and every open page freeze into the VM snapshot
+// and resume in each fork (like dockerd and the daemon itself). Profile
+// state — cookies, localStorage — is per-Chromium, and the in-VM CA trust
+// comes from the HOME-scoped NSS user DB, so neither cares that playwright
+// runs a temp --user-data-dir.
+let PW_BROWSER: PlaywrightBrowser | null = null;
+// The shared desktop context (default 1280×720 viewport). All desktop views
+// live here so they share one cookie jar, mirroring the old one-Chrome-
+// profile model. Mobile sessions and custom-viewport views get their own
+// contexts (viewport/DPR/UA/touch are context-scoped in playwright).
+let DESKTOP_CTX: BrowserContext | null = null;
+
+function chromiumPath(): string {
+  return (
+    Bun.which("chromium") ??
+    Bun.which("chromium-browser") ??
+    Bun.which("google-chrome") ??
+    "/usr/bin/chromium"
+  );
+}
+
+async function ensurePlaywrightBrowser(): Promise<PlaywrightBrowser> {
+  if (PW_BROWSER?.isConnected()) return PW_BROWSER;
+  PW_BROWSER = await chromium.launch({
+    executablePath: chromiumPath(),
+    headless: true,
+    args: CHROME_ARGV,
+  });
+  DESKTOP_CTX = null; // contexts died with the old browser (if any)
+  return PW_BROWSER;
+}
+
+/** Context options for the mobile device preset — playwright's native
+ *  emulation (viewport/DPR/UA/touch are context-scoped). Safe-area insets
+ *  have no context option; they stay a raw-CDP override per page. */
+function deviceContextOptions(d: DevicePreset) {
+  return {
+    viewport: { width: d.viewport.width, height: d.viewport.height },
+    deviceScaleFactor: d.deviceScaleFactor,
+    isMobile: d.isMobile,
+    hasTouch: d.hasTouch,
+    userAgent: d.userAgent,
+  };
+}
+
+async function ensureDesktopContext(): Promise<BrowserContext> {
+  const browser = await ensurePlaywrightBrowser();
+  if (DESKTOP_CTX) return DESKTOP_CTX;
+  DESKTOP_CTX = await browser.newContext({
+    viewport: { width: 1280, height: 720 },
+  });
+  DESKTOP_CTX.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
+  DESKTOP_CTX.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+  return DESKTOP_CTX;
+}
+
 /**
  * Make a user script evaluable by the page: Bun's `view.evaluate` accepts a
  * single EXPRESSION (it wraps the source in `await (...)`), so a statement
@@ -363,44 +420,27 @@ const LATEST_IPHONE: DevicePreset = {
   safeAreaInsets: { top: 59, right: 0, bottom: 34, left: 0 },
 };
 
-/** Apply CDP device emulation to a freshly-created view. The overrides are
- *  CDP-session-global, so they persist across the app navigation that
- *  follows (we set them on the about:blank bootstrap page). Best-effort:
- *  a CDP failure degrades to a plain desktop view rather than aborting.
+/** 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 safe-area insets that actually took effect (`null` when the
- *  override failed — Chromium < 135 lacks the CDP method). 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 applyDeviceEmulation(
-  view: BunWebViewInstance,
+ *  Returns the insets that actually took effect (`null` when the override
+ *  failed). The caller stamps them onto the session record so the dashboard
+ *  can substitute the same values for `env(safe-area-inset-*)` in the
+ *  replayed CSS; stamping only what was really applied keeps capture layout
+ *  and replay layout in lockstep (recorded touch coordinates would
+ *  misalign otherwise). */
+async function applySafeAreaInsets(
+  cdp: CDPSession,
   d: DevicePreset,
 ): Promise<SafeAreaInsets | null> {
   try {
-    await view.cdp("Emulation.setDeviceMetricsOverride", {
-      width: d.viewport.width,
-      height: d.viewport.height,
-      deviceScaleFactor: d.deviceScaleFactor,
-      mobile: d.isMobile,
-      screenWidth: d.viewport.width,
-      screenHeight: d.viewport.height,
-    });
-    await view.cdp("Emulation.setUserAgentOverride", { userAgent: d.userAgent });
-    await view.cdp("Emulation.setTouchEmulationEnabled", {
-      enabled: d.hasTouch,
-      maxTouchPoints: 5,
-    });
-  } catch (err) {
-    // eslint-disable-next-line no-console
-    console.warn("[spectest] device emulation failed; using desktop view:", err);
-    return null;
-  }
-  try {
-    await view.cdp("Emulation.setSafeAreaInsetsOverride", {
-      insets: { ...d.safeAreaInsets },
-    });
+    await cdp.send(
+      // Not in playwright's Protocol types yet (Chromium ≥ ~135 method).
+      "Emulation.setSafeAreaInsetsOverride" as Parameters<CDPSession["send"]>[0],
+      { insets: { ...d.safeAreaInsets } } as never,
+    );
     return d.safeAreaInsets;
   } catch (err) {
     // eslint-disable-next-line no-console
@@ -413,7 +453,9 @@ async function applyDeviceEmulation(
 // rrweb bootstrap
 // ────────────────────────────────────────────────────────────────────────
 
-// Vendored rrweb-record bundle (UMD, exposes `rrwebRecord` global). Read
+// Vendored `@rrweb/record` UMD bundle (rrweb 2.x). Its global `rrwebRecord`
+// is a module object — the record function is `rrwebRecord.record` (the
+// bootstrap resolves both this and the legacy function-shaped global). Read
 // once at module init — the SDK ships this file in the base snapshot so
 // no network fetch happens inside the VM.
 const RRWEB_BUNDLE: string = (() => {
@@ -459,9 +501,18 @@ const RRWEB_CONSOLE_PLUGIN_BUNDLE: string = (() => {
 // 10 KiB so longer error stacks survive without dwarfing the event stream).
 const RRWEB_BOOTSTRAP = `
 ;(function () {
-  if (typeof rrwebRecord !== "function") return;
+  // 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 {
@@ -475,7 +526,7 @@ const RRWEB_BOOTSTRAP = `
     }
   } catch (e) { /* plugin init failed — keep recording DOM only. */ }
   try {
-    rrwebRecord({
+    rec({
       emit: function (ev) { window.__spectestRrwebEvents.push(ev); },
       plugins: plugins,
       // Capture page assets into the event stream so the replay renders
@@ -617,9 +668,8 @@ const RRWEB_BOOTSTRAP = `
           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();
+          if (rec && typeof rec.takeFullSnapshot === "function") {
+            rec.takeFullSnapshot();
             log("took full snapshot");
           }
         } catch (e) { log("snapshot FAIL " + (e && e.message)); }
@@ -638,8 +688,14 @@ const RRWEB_BOOTSTRAP = `
 })();
 `;
 
+// 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${RRWEB_CONSOLE_PLUGIN_BUNDLE}\n${RRWEB_BOOTSTRAP}`
+  ? `${RRWEB_BUNDLE}\n;\n${RRWEB_CONSOLE_PLUGIN_BUNDLE}\n;\n${RRWEB_BOOTSTRAP}`
   : "";
 
 // Page-side expression that atomically swaps in a fresh buffer and
@@ -661,7 +717,7 @@ const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
 //
 // 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()`
+// 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
@@ -671,16 +727,16 @@ const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
 function drainExpr(forceFullIfMissing: boolean): string {
   return `(function () {
   try {
+    var rec = window.__spectestRec;
     if (${forceFullIfMissing ? "true" : "false"} &&
         window.__spectestRrwebInit &&
-        typeof rrwebRecord === "function" &&
-        typeof rrwebRecord.takeFullSnapshot === "function") {
+        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) rrwebRecord.takeFullSnapshot();
+      if (!hasFull) rec.takeFullSnapshot();
     }
   } catch (e) { /* recording inactive or DOM detached — drain what's there. */ }
   var buf = window.__spectestRrwebEvents;
@@ -694,23 +750,37 @@ function drainExpr(forceFullIfMissing: boolean): string {
 // Factory
 // ────────────────────────────────────────────────────────────────────────
 
-/** A pre-opened, never-used view: renderer already spawned, rrweb init
- *  script installed, parked on about:blank. */
-interface PooledView {
-  view: BunWebViewInstance;
+/** A page freshly spawned into a context: renderer up, CDP session open,
+ *  rrweb init script installed, parked on about:blank. */
+interface SpawnedPage {
+  page: Page;
+  cdp: CDPSession;
   recordingInstalled: boolean;
 }
 
+/** A pre-opened, never-used desktop view (lives in the shared desktop
+ *  context). */
+interface PooledView extends SpawnedPage {}
+
 /**
- * The unit a Browser/Mobile handle drives. `view` is deliberately mutable:
- * the DNS-recovery path (see `navigate` in {@link buildBackend}) replaces a
- * broken restored renderer with a freshly-spawned view in the same Chrome,
- * and every wrapper reads through the holder so the swap is transparent.
- * `device`/`width`/`height` are kept so a rebuilt view comes back with the
- * same viewport and emulation.
+ * The unit a Browser/Mobile handle drives. `page`/`cdp` are deliberately
+ * mutable: the DNS-recovery path (see `navigate` in {@link buildBackend})
+ * replaces a broken restored renderer with a freshly-spawned page in the
+ * SAME context (cookies/localStorage survive), and every wrapper reads
+ * through the holder so the swap is transparent. `device`/`width`/`height`
+ * are kept so a rebuilt page comes back with the same emulation.
  */
 interface ViewHolder {
-  view: BunWebViewInstance;
+  /** Context this view lives in. Shared desktop context for default-size
+   *  desktop views; a private one for mobile/custom-viewport views. */
+  context: BrowserContext;
+  /** Whether close() should also close the context (private contexts). */
+  ownsContext: boolean;
+  page: Page;
+  cdp: CDPSession;
+  /** Cached page title — playwright's `title()` is async but our public
+   *  surface is a sync getter; refreshed after every recorded op. */
+  lastTitle: string;
   recordingInstalled: boolean;
   device: DevicePreset | null;
   width: number;
@@ -720,7 +790,7 @@ interface ViewHolder {
    *  session record so the replay can mirror them. */
   safeAreaInsets: SafeAreaInsets | null;
   /** User scripts installed via `addInitScript`, kept so the DNS-recovery
-   *  rebuild can re-install them on the replacement view. */
+   *  rebuild can re-install them on the replacement page. */
   initScripts: string[];
 }
 
@@ -736,22 +806,19 @@ interface ViewHolder {
 // 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");
+/** Spawn a page (+ CDP session + rrweb init script) into `context` — the
+ *  slow part (renderer process spawn). */
+async function spawnPage(context: BrowserContext): Promise<SpawnedPage> {
+  const page = await context.newPage();
+  const cdp = await context.newCDPSession(page);
+  // Without Page.enable the addScriptToEvaluateOnNewDocument registration
+  // silently never fires on this session (verified in the fork spike).
+  await cdp.send("Page.enable");
 
   let recordingInstalled = false;
   if (PAGE_INIT_SCRIPT) {
     try {
-      await view.cdp("Page.addScriptToEvaluateOnNewDocument", {
+      await cdp.send("Page.addScriptToEvaluateOnNewDocument", {
         source: PAGE_INIT_SCRIPT,
       });
       recordingInstalled = true;
@@ -761,7 +828,36 @@ async function createView(width: number, height: number): Promise<PooledView> {
       console.warn("[spectest] failed to install rrweb recorder:", err);
     }
   }
-  return { view, recordingInstalled };
+  return { page, cdp, recordingInstalled };
+}
+
+/** Acquire the context a view of this shape lives in. */
+async function contextFor(
+  width: number,
+  height: number,
+  device: DevicePreset | null,
+): Promise<{ context: BrowserContext; ownsContext: boolean }> {
+  if (device) {
+    const browser = await ensurePlaywrightBrowser();
+    const context = await browser.newContext(deviceContextOptions(device));
+    context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
+    context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+    return { context, ownsContext: true };
+  }
+  if (width === 1280 && height === 720) {
+    return { context: await ensureDesktopContext(), ownsContext: false };
+  }
+  const browser = await ensurePlaywrightBrowser();
+  const context = await browser.newContext({ viewport: { width, height } });
+  context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
+  context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+  return { context, ownsContext: true };
+}
+
+/** Create a default-desktop view for the pool. */
+async function createView(width: number, height: number): Promise<PooledView> {
+  const { context } = await contextFor(width, height, null);
+  return spawnPage(context);
 }
 
 /**
@@ -777,9 +873,8 @@ export async function prewarmViewPool(n = 1): Promise<void> {
 }
 
 /**
- * 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.
+ * 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}
@@ -805,21 +900,28 @@ export async function openMobileBackend(
   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, and a mobile view needs its emulation applied fresh anyway.
+  // 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;
-  const base = pooled ?? (await createView(wantW, wantH));
-  const holder: ViewHolder = {
-    view: base.view,
-    recordingInstalled: base.recordingInstalled,
-    device,
-    width: wantW,
-    height: wantH,
-    safeAreaInsets: null,
-    initScripts: [],
-  };
-
-  if (device) holder.safeAreaInsets = await applyDeviceEmulation(holder.view, device);
+  let holder: ViewHolder;
+  if (pooled) {
+    holder = {
+      context: await ensureDesktopContext(),
+      ownsContext: false,
+      page: pooled.page,
+      cdp: pooled.cdp,
+      lastTitle: "",
+      recordingInstalled: pooled.recordingInstalled,
+      device,
+      width: wantW,
+      height: wantH,
+      safeAreaInsets: null,
+      initScripts: [],
+    };
+  } else {
+    holder = await newHolder(wantW, wantH, device);
+  }
 
   const { backend } = buildBackend(holder, opts.recorder ?? null, {
     persistent: false,
@@ -849,6 +951,30 @@ export async function openMobileBackend(
 let SHARED_BROWSER: ViewHolder | null = null;
 const SHARED_MOBILE = new Map<string, ViewHolder>();
 
+async function newHolder(
+  width: number,
+  height: number,
+  device: DevicePreset | null,
+): Promise<ViewHolder> {
+  const { context, ownsContext } = await contextFor(width, height, device);
+  const spawned = await spawnPage(context);
+  const holder: ViewHolder = {
+    context,
+    ownsContext,
+    page: spawned.page,
+    cdp: spawned.cdp,
+    lastTitle: "",
+    recordingInstalled: spawned.recordingInstalled,
+    device,
+    width,
+    height,
+    safeAreaInsets: null,
+    initScripts: [],
+  };
+  if (device) holder.safeAreaInsets = await applySafeAreaInsets(holder.cdp, device);
+  return holder;
+}
+
 /**
  * What acquiring a persistent session returns. `detach` is the test-end
  * hook (final rrweb drain, stop writing to this test's recorder, keep the
@@ -873,37 +999,18 @@ export interface PersistentBrowser {
 const ATTACH_RESET_EXPR = `(function () {
   window.__spectestRrwebEvents = [];
   try {
-    if (typeof rrwebRecord === "function" &&
-        typeof rrwebRecord.takeFullSnapshot === "function") {
-      rrwebRecord.takeFullSnapshot();
+    var rec = window.__spectestRec;
+    if (rec && typeof rec.takeFullSnapshot === "function") {
+      rec.takeFullSnapshot();
     }
   } catch (e) { /* recording not active on this document */ }
   return true;
 })()`;
 
-async function newHolder(
-  width: number,
-  height: number,
-  device: DevicePreset | null,
-): Promise<ViewHolder> {
-  const { view, recordingInstalled } = await createView(width, height);
-  const holder: ViewHolder = {
-    view,
-    recordingInstalled,
-    device,
-    width,
-    height,
-    safeAreaInsets: null,
-    initScripts: [],
-  };
-  if (device) holder.safeAreaInsets = await applyDeviceEmulation(view, device);
-  return holder;
-}
-
 async function attachReset(holder: ViewHolder): Promise<void> {
   if (!holder.recordingInstalled) return;
   try {
-    await holder.view.evaluate(ATTACH_RESET_EXPR);
+    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.
@@ -994,33 +1101,34 @@ async function daemonResolves(url: string): Promise<boolean> {
 }
 
 /**
- * Replace a persistent holder's view with a freshly-spawned one in the same
- * Chrome. Profile state — cookies, localStorage, the in-VM CA trust — is
- * per-Chrome, so it survives; only renderer-held page state is lost, and
- * this path only runs when that renderer already can't navigate.
+ * 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 view in the SAME restored Chrome resolves fine (root cause never
+ * 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 view,
+ * a child test navigates, so the recovery lives here: rebuild the page,
  * retry once.
  */
 async function rebuildView(holder: ViewHolder): Promise<void> {
   try {
-    holder.view.close();
+    await holder.page.close();
   } catch {
-    /* view may already be gone */
+    /* page may already be gone */
   }
-  const fresh = await createView(holder.width, holder.height);
-  holder.view = fresh.view;
+  const fresh = await spawnPage(holder.context);
+  holder.page = fresh.page;
+  holder.cdp = fresh.cdp;
   holder.recordingInstalled = fresh.recordingInstalled;
   if (holder.device) {
-    holder.safeAreaInsets = await applyDeviceEmulation(holder.view, holder.device);
+    holder.safeAreaInsets = await applySafeAreaInsets(holder.cdp, holder.device);
   }
   for (const source of holder.initScripts) {
-    await holder.view.cdp("Page.addScriptToEvaluateOnNewDocument", { source });
+    await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source });
   }
 }
 
@@ -1038,7 +1146,7 @@ function buildBackend(
   recorder: BrowserSessionRecorder | null,
   buildOpts: BackendBuildOptions,
 ): { backend: MobileBackend; detach(): Promise<void> } {
-  // All page access goes through `holder.view` — never capture the view in
+  // 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()).
@@ -1055,9 +1163,9 @@ function buildBackend(
   async function drain(action: BrowserAction | "close"): Promise<void> {
     if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
-      const urlChanged = holder.view.url !== lastDrainUrl;
-      const events = await holder.view.evaluate<unknown[]>(drainExpr(urlChanged));
-      lastDrainUrl = holder.view.url;
+      const urlChanged = holder.page.url() !== lastDrainUrl;
+      const events = (await holder.page.evaluate(drainExpr(urlChanged))) as unknown[];
+      lastDrainUrl = holder.page.url();
       if (Array.isArray(events) && events.length > 0) {
         recorder.recordStep({
           stepSeq: stepSeq++,
@@ -1082,6 +1190,12 @@ function buildBackend(
     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
@@ -1132,10 +1246,10 @@ function buildBackend(
 
   const backend: MobileBackend = {
     get url() {
-      return holder.view.url;
+      return holder.page.url();
     },
     get title() {
-      return holder.view.title;
+      return holder.lastTitle;
     },
     get safeAreaInsets() {
       return holder.safeAreaInsets;
@@ -1144,7 +1258,7 @@ function buildBackend(
       recorder?.noteNavigation?.(url);
       return instrumented("navigate", { url }, async () => {
         try {
-          await holder.view.navigate(url);
+          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
@@ -1154,7 +1268,7 @@ function buildBackend(
           if (!buildOpts.persistent || !isNameNotResolved(err)) throw err;
           if (!(await daemonResolves(url))) throw err;
           await rebuildView(holder);
-          await holder.view.navigate(url);
+          await holder.page.goto(url, { waitUntil: "load" });
         }
       });
     },
@@ -1173,7 +1287,7 @@ function buildBackend(
           scriptTruncated: truncatedScript.truncated,
         },
         async () => {
-          const v = await holder.view.evaluate<T>(toEvaluable(script));
+          const v = (await holder.page.evaluate(toEvaluable(script))) as T;
           return v;
         },
       ) as Promise<Wrapped<T>>;
@@ -1188,10 +1302,12 @@ function buildBackend(
           scriptTruncated: truncated.truncated,
         },
         async () => {
-          await holder.view.cdp("Page.addScriptToEvaluateOnNewDocument", {
+          // Raw CDP (not context.addInitScript) so the script stays scoped
+          // to THIS page — the desktop context is shared across views.
+          await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
             source,
           });
-          // Remember it so a DNS-recovery view rebuild re-installs it.
+          // Remember it so a DNS-recovery page rebuild re-installs it.
           holder.initScripts.push(source);
         },
       );
@@ -1226,7 +1342,7 @@ function buildBackend(
           fields.attempts = (fields.attempts ?? 0) + 1;
           let v: unknown;
           try {
-            v = await holder.view.evaluate<unknown>(evaluable);
+            v = await holder.page.evaluate(evaluable);
           } catch (err) {
             if (Date.now() >= deadline) throw err;
             await new Promise((r) => setTimeout(r, intervalMs));
@@ -1243,46 +1359,61 @@ function buildBackend(
       }) as Promise<Wrapped<T>>;
     },
     click(selector) {
-      return instrumented("click", { selector }, () => holder.view.click(selector));
+      return instrumented("click", { selector }, () =>
+        holder.page.click(selector, { timeout: DEFAULT_ACTION_TIMEOUT_MS }),
+      );
     },
     clickAt(x, y) {
-      return instrumented("click", { x, y }, () => holder.view.click(x, y));
+      return instrumented("click", { x, y }, () => holder.page.mouse.click(x, y));
     },
     type(text) {
+      // insertText path (no per-char keydown) — same semantics as before.
       const t = truncateUtf8(text);
       return instrumented(
         "type",
         { text: t.value, textTruncated: t.truncated },
-        () => holder.view.type(text),
+        () => holder.page.keyboard.insertText(text),
       );
     },
     press(key) {
-      return instrumented("press", { key }, () => holder.view.press(key));
+      return instrumented("press", { key }, () => holder.page.keyboard.press(key));
     },
     scroll(dx, dy) {
-      return instrumented("scroll", { dx, dy }, () => holder.view.scroll(dx, dy));
+      return instrumented("scroll", { dx, dy }, () => holder.page.mouse.wheel(dx, dy));
     },
     scrollTo(selector) {
-      return instrumented("scrollTo", { selector }, () => holder.view.scrollTo(selector));
+      return instrumented("scrollTo", { selector }, () =>
+        holder.page
+          .locator(selector)
+          .first()
+          .scrollIntoViewIfNeeded({ timeout: DEFAULT_ACTION_TIMEOUT_MS }),
+      );
     },
     back() {
-      return instrumented("back", {}, () => holder.view.back());
+      return instrumented("back", {}, async () => {
+        await holder.page.goBack();
+      });
     },
     forward() {
-      return instrumented("forward", {}, () => holder.view.forward());
+      return instrumented("forward", {}, async () => {
+        await holder.page.goForward();
+      });
     },
     reload() {
-      return instrumented("reload", {}, () => holder.view.reload());
+      return instrumented("reload", {}, async () => {
+        await holder.page.reload();
+      });
     },
     async screenshot(options) {
       const format = options?.format ?? "png";
       return instrumented("screenshot", { format }, async () => {
-        const buf = await holder.view.screenshot({
-          encoding: "buffer",
+        // Raw CDP rather than page.screenshot(): CDP supports webp too, and
+        // captures the viewport exactly like the pre-Playwright backend.
+        const res = (await holder.cdp.send("Page.captureScreenshot", {
           format,
-          quality: options?.quality,
-        });
-        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+          ...(format === "png" ? {} : { quality: options?.quality ?? 90 }),
+        } as never)) as { data: string };
+        return new Uint8Array(Buffer.from(res.data, "base64"));
       });
     },
     async close() {
@@ -1297,55 +1428,70 @@ function buildBackend(
       viewClosed = true;
       buildOpts.onDestroy?.();
       try {
-        holder.view.close();
+        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: [],
+      });
+    },
     tapAt(x, y, opts) {
       // Recorded as a "click" (the event schema stays desktop-shaped; the
-      // mobile facade owns the author-facing "tap" vocabulary). Dispatches
-      // a real touch so RN-Web's responder system fires.
-      return instrumented("click", { x, y }, async () => {
-        await holder.view.cdp("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, opts?.durationMs ?? TAP_DWELL_MS));
-        await holder.view.cdp("Input.dispatchTouchEvent", {
-          type: "touchEnd",
-          touchPoints: [],
-        });
-      });
+      // mobile facade owns the author-facing "tap" vocabulary).
+      return instrumented("click", { x, y }, () => backend.rawTap(x, y, opts?.durationMs));
     },
     swipeBy(x, y, dx, dy) {
       return instrumented("scroll", { dx, dy }, async () => {
         const steps = 8;
-        await holder.view.cdp("Input.dispatchTouchEvent", {
+        await holder.cdp.send("Input.dispatchTouchEvent", {
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
         for (let i = 1; i <= steps; i++) {
-          await holder.view.cdp("Input.dispatchTouchEvent", {
+          await holder.cdp.send("Input.dispatchTouchEvent", {
             type: "touchMove",
             touchPoints: [{ x: x + (dx * i) / steps, y: y + (dy * i) / steps, id: 0 }],
           });
         }
-        await holder.view.cdp("Input.dispatchTouchEvent", {
+        await holder.cdp.send("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],
         });
       });
     },
     probe<T = unknown>(expression: string): Promise<T> {
-      return holder.view.evaluate<T>(expression);
+      return holder.page.evaluate(expression) as Promise<T>;
+    },
+    pageOp<T>(
+      action: BrowserAction,
+      fields: Partial<RecordableFields>,
+      fn: (page: Page) => Promise<T>,
+    ): Promise<T> {
+      return instrumented(action, fields, () => fn(holder.page));
     },
   };
   return { backend, detach: endRecording };