@specific.dev/spectest 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/browser.ts

@@ -16,7 +16,14 @@
 // 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";
@@ -160,6 +167,24 @@ export interface Browser {
    * test event log so the step list isn't a wall of minified code.
    */
   evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
+  /**
+   * Install a script that runs in every document loaded from now on, BEFORE
+   * any of the document's own scripts execute (CDP
+   * `Page.addScriptToEvaluateOnNewDocument` — the Playwright `addInitScript`
+   * equivalent). The deterministic way to plant shims and instrumentation
+   * (`fetch`/`XMLHttpRequest` wrappers, clock stubs, feature flags): unlike an
+   * `evaluate` racing the app bundle after a navigation, an init script is
+   * guaranteed to win.
+   *
+   * Does NOT run in the *current* document — call it before the `navigate`
+   * (or in-page `location.assign`) whose document needs it. Installed
+   * scripts persist for the browser session's lifetime, which for the
+   * persistent `ctx.browser()`/`ctx.mobile()` sessions means they ride
+   * snapshots into `dependsOn` children like the rest of the session state.
+   *
+   * `description` labels the step in the test event log.
+   */
+  addInitScript(description: string, source: string): Promise<void>;
   /**
    * Poll `expression` in the page until it returns a truthy value
    * (the returned value is what `waitFor` resolves with). Useful for
@@ -205,7 +230,15 @@ export interface Browser {
   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. */
+  /**
+   * Destroy the underlying view. Idempotent; drains any pending rrweb
+   * events first. For the persistent session behind `ctx.browser()` /
+   * `ctx.mobile()` this is the escape hatch to a FRESH browser — the
+   * shared instance is discarded and the next call creates a new one.
+   * Don't call it for routine cleanup: the daemon detaches recording at
+   * test end automatically and deliberately keeps the browser alive so
+   * dependent tests inherit its state.
+   */
   close(): Promise<void>;
 }
 
@@ -218,6 +251,10 @@ export interface Browser {
  * drain as the desktop verbs.
  */
 export interface MobileBackend extends Browser {
+  /** Safe-area insets emulated on this view (`null` on desktop views or
+   *  when the CDP override is unavailable). The daemon stamps these onto
+   *  the session record for the dashboard's replay. */
+  readonly safeAreaInsets: SafeAreaInsets | null;
   /** Touch-tap at viewport CSS coordinates (touchStart→touchEnd). */
   tapAt(x: number, y: number): Promise<void>;
   /** Touch-drag from (x,y) by (dx,dy) over a short move sequence. */
@@ -266,6 +303,15 @@ interface DevicePreset {
   isMobile: boolean;
   hasTouch: boolean;
   userAgent: string;
+  safeAreaInsets: SafeAreaInsets;
+}
+
+/** iOS safe-area insets (CSS `env(safe-area-inset-*)`), in CSS px. */
+export interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
 }
 
 /** The fixed mobile device. Logical resolution + DPR of a current iPhone;
@@ -281,16 +327,28 @@ const LATEST_IPHONE: DevicePreset = {
   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 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. */
+ *  a CDP failure degrades to a plain desktop view rather than aborting.
+ *
+ *  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,
   d: DevicePreset,
-): Promise<void> {
+): Promise<SafeAreaInsets | null> {
   try {
     await view.cdp("Emulation.setDeviceMetricsOverride", {
       width: d.viewport.width,
@@ -308,6 +366,17 @@ async function applyDeviceEmulation(
   } 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 },
+    });
+    return d.safeAreaInsets;
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("[spectest] safe-area inset emulation unavailable:", err);
+    return null;
   }
 }
 
@@ -603,6 +672,29 @@ interface PooledView {
   recordingInstalled: boolean;
 }
 
+/**
+ * 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.
+ */
+interface ViewHolder {
+  view: BunWebViewInstance;
+  recordingInstalled: boolean;
+  device: DevicePreset | null;
+  width: number;
+  height: number;
+  /** Safe-area insets actually applied to the view (`null` for desktop
+   *  views or when the CDP override is unavailable). Stamped onto the
+   *  session record so the replay can mirror them. */
+  safeAreaInsets: SafeAreaInsets | null;
+  /** User scripts installed via `addInitScript`, kept so the DNS-recovery
+   *  rebuild can re-install them on the replacement view. */
+  initScripts: string[];
+}
+
 // Pre-opened view pool. Renderer spawn is the expensive part of
 // `ctx.browser()` — ~1.8s for the first view in a fresh Chrome and
 // (measured 2026-06-05) a constant ~1.2-1.5s per view in a Chrome that
@@ -659,6 +751,11 @@ 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.
+ *
+ * This is the EPHEMERAL path — `close()` destroys the view. The daemon's
+ * `ctx.browser()`/`ctx.mobile()` go through {@link acquirePersistentBrowser}
+ * / {@link acquirePersistentMobileBackend} instead, which keep one view
+ * alive across tests so it rides snapshots/forks.
  */
 export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
   return openMobileBackend(opts);
@@ -668,10 +765,9 @@ export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
  * 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. The mobile facade
- * (`sdk/src/mobile.ts`) calls this; desktop callers go through
- * {@link openBrowser} and get the narrower {@link Browser} view of the same
- * object.
+ * device emulation applied before the first navigation. Desktop callers go
+ * through {@link openBrowser} and get the narrower {@link Browser} view of
+ * the same object.
  */
 export async function openMobileBackend(
   opts: BrowserOptions = {},
@@ -683,27 +779,242 @@ export async function openMobileBackend(
   // views, and a mobile view needs its emulation applied fresh anyway.
   const pooled =
     !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
-  const { view, recordingInstalled } = pooled ?? (await createView(wantW, wantH));
+  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) await applyDeviceEmulation(view, device);
+  if (device) holder.safeAreaInsets = await applyDeviceEmulation(holder.view, device);
 
-  const browser = wrapView(view, opts.recorder ?? null, recordingInstalled);
+  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.url !== undefined) {
-    await browser.navigate(opts.url);
+    await backend.navigate(opts.url);
   }
-  return browser;
+  return backend;
 }
 
-function wrapView(
-  view: BunWebViewInstance,
+// ────────────────────────────────────────────────────────────────────────
+// Persistent sessions (the default behind ctx.browser / ctx.mobile)
+// ────────────────────────────────────────────────────────────────────────
+
+// One long-lived desktop browser plus one mobile session per app URL.
+// Module state lives in daemon memory, so it forks with the snapshot the
+// same way fake `state` and TEST_DATA do: a test's browser — its live
+// page, cookies, localStorage, in-memory SPA state — is captured in the
+// post-test snapshot and inherited by `dependsOn` children, while sibling
+// forks never see each other's sessions. That's what lets a child test
+// continue where its parent left off (e.g. already signed in) instead of
+// re-navigating and re-authenticating.
+let SHARED_BROWSER: ViewHolder | null = null;
+const SHARED_MOBILE = new Map<string, ViewHolder>();
+
+/**
+ * What acquiring a persistent session returns. `detach` is the test-end
+ * hook (final rrweb drain, stop writing to this test's recorder, keep the
+ * view alive); `browser.close()` is the author-facing escape hatch that
+ * actually destroys the view (the next `ctx.browser()` starts fresh).
+ */
+export interface PersistentBrowser {
+  browser: MobileBackend;
+  /** True when this call attached to a view inherited from an earlier
+   *  test (possibly across a snapshot fork) rather than creating one. */
+  attached: boolean;
+  /** Final rrweb drain + detach from the current recorder. The view stays
+   *  alive so the post-test snapshot captures it. Idempotent. */
+  detach(): Promise<void>;
+}
+
+// Runs in the page when a persistent view is attached to a new test's
+// recorder: drop whatever rrweb buffered since the previous detach (idle
+// mutations; the previous test's session already drained everything it
+// owns) and emit a fresh Meta + FullSnapshot so the new session's replay
+// is self-contained from its first event.
+const ATTACH_RESET_EXPR = `(function () {
+  window.__spectestRrwebEvents = [];
+  try {
+    if (typeof rrwebRecord === "function" &&
+        typeof rrwebRecord.takeFullSnapshot === "function") {
+      rrwebRecord.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);
+  } catch {
+    // Page mid-navigation or renderer unhappy — the first drain forces a
+    // full snapshot when one is missing (drainExpr), so replay still works.
+  }
+}
+
+/**
+ * Acquire THE persistent desktop browser (creating it on first use). There
+ * is deliberately a single one — `ctx.browser()` always returns it — so a
+ * test DAG shares one browsing session along each branch. The first call's
+ * options win; later calls attach to the existing view as-is.
+ */
+export async function acquirePersistentBrowser(
+  opts: BrowserOptions = {},
+): Promise<PersistentBrowser> {
+  const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
+  let attached = true;
+  if (!SHARED_BROWSER) {
+    attached = false;
+    SHARED_BROWSER = await newHolder(
+      device ? device.viewport.width : opts.width ?? 1280,
+      device ? device.viewport.height : opts.height ?? 720,
+      device,
+    );
+  } else {
+    await attachReset(SHARED_BROWSER);
+  }
+  const holder = SHARED_BROWSER;
+  const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
+    },
+  });
+  if (!attached && opts.url !== undefined) await backend.navigate(opts.url);
+  return { browser: backend, attached, detach };
+}
+
+/**
+ * Acquire the persistent mobile session for an app URL (one per app). A
+ * fresh session navigates to the app; an attach continues on the live page.
+ */
+export async function acquirePersistentMobileBackend(
+  url: string,
+  recorder: BrowserSessionRecorder | null,
+): Promise<PersistentBrowser> {
+  const existing = SHARED_MOBILE.get(url);
+  const holder =
+    existing ??
+    (await newHolder(
+      LATEST_IPHONE.viewport.width,
+      LATEST_IPHONE.viewport.height,
+      LATEST_IPHONE,
+    ));
+  if (existing) {
+    await attachReset(holder);
+  } else {
+    SHARED_MOBILE.set(url, holder);
+  }
+  const { backend, detach } = buildBackend(holder, recorder, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(url);
+    },
+  });
+  if (!existing) await backend.navigate(url);
+  return { browser: backend, attached: existing !== undefined, detach };
+}
+
+/** True when a navigation failed on Chromium name resolution. */
+function isNameNotResolved(err: unknown): boolean {
+  return String((err as Error)?.message ?? err).includes("ERR_NAME_NOT_RESOLVED");
+}
+
+/**
+ * Whether the daemon's own resolver can look the URL's host up. Chromium
+ * runs with AsyncDns disabled (see CHROME_ARGV) so it uses the same
+ * getaddrinfo path — a host the daemon resolves but Chrome can't means
+ * the RENDERER is broken, not the name.
+ */
+async function daemonResolves(url: string): Promise<boolean> {
+  try {
+    await dns.lookup(new URL(url).hostname);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Replace a persistent holder's 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.
+ *
+ * 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
+ * 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,
+ * retry once.
+ */
+async function rebuildView(holder: ViewHolder): Promise<void> {
+  try {
+    holder.view.close();
+  } catch {
+    /* view may already be gone */
+  }
+  const fresh = await createView(holder.width, holder.height);
+  holder.view = fresh.view;
+  holder.recordingInstalled = fresh.recordingInstalled;
+  if (holder.device) {
+    holder.safeAreaInsets = await applyDeviceEmulation(holder.view, holder.device);
+  }
+  for (const source of holder.initScripts) {
+    await holder.view.cdp("Page.addScriptToEvaluateOnNewDocument", { source });
+  }
+}
+
+interface BackendBuildOptions {
+  /** Persistent views get the DNS-recovery navigate and a close() that
+   *  clears them out of the shared registry; ephemeral views just close. */
+  persistent: boolean;
+  /** Called when close() destroys the underlying view — the acquire
+   *  functions use it to drop the holder from the shared registry. */
+  onDestroy?: () => void;
+}
+
+function buildBackend(
+  holder: ViewHolder,
   recorder: BrowserSessionRecorder | null,
-  recordingInstalled: boolean,
-): MobileBackend {
-  let closed = false;
+  buildOpts: BackendBuildOptions,
+): { backend: MobileBackend; detach(): Promise<void> } {
+  // All page access goes through `holder.view` — never capture the view 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
@@ -713,11 +1024,11 @@ function wrapView(
   let lastDrainUrl: string | null = null;
 
   async function drain(action: BrowserAction | "close"): Promise<void> {
-    if (!recordingInstalled || !recorder || closed) return;
+    if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
-      const urlChanged = view.url !== lastDrainUrl;
-      const events = await view.evaluate<unknown[]>(drainExpr(urlChanged));
-      lastDrainUrl = view.url;
+      const urlChanged = holder.view.url !== lastDrainUrl;
+      const events = await holder.view.evaluate<unknown[]>(drainExpr(urlChanged));
+      lastDrainUrl = holder.view.url;
       if (Array.isArray(events) && events.length > 0) {
         recorder.recordStep({
           stepSeq: stepSeq++,
@@ -783,16 +1094,40 @@ function wrapView(
     }
   }
 
-  return {
+  async function endRecording(): Promise<void> {
+    if (recordingEnded) return;
+    // Final drain before we stop writing to this recorder.
+    await drain("close");
+    recordingEnded = true;
+  }
+
+  const backend: MobileBackend = {
     get url() {
-      return view.url;
+      return holder.view.url;
     },
     get title() {
-      return view.title;
+      return holder.view.title;
+    },
+    get safeAreaInsets() {
+      return holder.safeAreaInsets;
     },
     navigate(url) {
       recorder?.noteNavigation?.(url);
-      return instrumented("navigate", { url }, () => view.navigate(url));
+      return instrumented("navigate", { url }, async () => {
+        try {
+          await holder.view.navigate(url);
+        } 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.view.navigate(url);
+        }
+      });
     },
     async evaluate<T = unknown>(
       description: string,
@@ -809,11 +1144,29 @@ function wrapView(
           scriptTruncated: truncatedScript.truncated,
         },
         async () => {
-          const v = await view.evaluate<T>(script);
+          const v = await holder.view.evaluate<T>(script);
           return v;
         },
       ) as Promise<Wrapped<T>>;
     },
+    addInitScript(description: string, source: string): Promise<void> {
+      const truncated = truncateUtf8(source);
+      return instrumented(
+        "addInitScript",
+        {
+          description,
+          script: truncated.value,
+          scriptTruncated: truncated.truncated,
+        },
+        async () => {
+          await holder.view.cdp("Page.addScriptToEvaluateOnNewDocument", {
+            source,
+          });
+          // Remember it so a DNS-recovery view rebuild re-installs it.
+          holder.initScripts.push(source);
+        },
+      );
+    },
     async waitFor<T = unknown>(
       description: string,
       expression: string,
@@ -842,7 +1195,7 @@ function wrapView(
           fields.attempts = (fields.attempts ?? 0) + 1;
           let v: unknown;
           try {
-            v = await view.evaluate<unknown>(expression);
+            v = await holder.view.evaluate<unknown>(expression);
           } catch (err) {
             if (Date.now() >= deadline) throw err;
             await new Promise((r) => setTimeout(r, intervalMs));
@@ -859,41 +1212,41 @@ function wrapView(
       }) as Promise<Wrapped<T>>;
     },
     click(selector) {
-      return instrumented("click", { selector }, () => view.click(selector));
+      return instrumented("click", { selector }, () => holder.view.click(selector));
     },
     clickAt(x, y) {
-      return instrumented("click", { x, y }, () => view.click(x, y));
+      return instrumented("click", { x, y }, () => holder.view.click(x, y));
     },
     type(text) {
       const t = truncateUtf8(text);
       return instrumented(
         "type",
         { text: t.value, textTruncated: t.truncated },
-        () => view.type(text),
+        () => holder.view.type(text),
       );
     },
     press(key) {
-      return instrumented("press", { key }, () => view.press(key));
+      return instrumented("press", { key }, () => holder.view.press(key));
     },
     scroll(dx, dy) {
-      return instrumented("scroll", { dx, dy }, () => view.scroll(dx, dy));
+      return instrumented("scroll", { dx, dy }, () => holder.view.scroll(dx, dy));
     },
     scrollTo(selector) {
-      return instrumented("scrollTo", { selector }, () => view.scrollTo(selector));
+      return instrumented("scrollTo", { selector }, () => holder.view.scrollTo(selector));
     },
     back() {
-      return instrumented("back", {}, () => view.back());
+      return instrumented("back", {}, () => holder.view.back());
     },
     forward() {
-      return instrumented("forward", {}, () => view.forward());
+      return instrumented("forward", {}, () => holder.view.forward());
     },
     reload() {
-      return instrumented("reload", {}, () => view.reload());
+      return instrumented("reload", {}, () => holder.view.reload());
     },
     async screenshot(options) {
       const format = options?.format ?? "png";
       return instrumented("screenshot", { format }, async () => {
-        const buf = await view.screenshot({
+        const buf = await holder.view.screenshot({
           encoding: "buffer",
           format,
           quality: options?.quality,
@@ -902,12 +1255,18 @@ function wrapView(
       });
     },
     async close() {
-      if (closed) return;
-      // Final drain before the page evaporates.
-      await drain("close");
-      closed = true;
+      // 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 {
-        view.close();
+        holder.view.close();
       } catch {
         /* already closed by the runtime */
       }
@@ -918,11 +1277,11 @@ function wrapView(
       // 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 view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],
         });
@@ -931,26 +1290,27 @@ function wrapView(
     swipeBy(x, y, dx, dy) {
       return instrumented("scroll", { dx, dy }, async () => {
         const steps = 8;
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
         for (let i = 1; i <= steps; i++) {
-          await view.cdp("Input.dispatchTouchEvent", {
+          await holder.view.cdp("Input.dispatchTouchEvent", {
             type: "touchMove",
             touchPoints: [{ x: x + (dx * i) / steps, y: y + (dy * i) / steps, id: 0 }],
           });
         }
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],
         });
       });
     },
     probe<T = unknown>(expression: string): Promise<T> {
-      return view.evaluate<T>(expression);
+      return holder.view.evaluate<T>(expression);
     },
   };
+  return { backend, detach: endRecording };
 }
 
 interface RecordableFields {