@specific.dev/spectest 0.131.21 → 0.132.2

package/src/browser-executable.test.ts

@@ -3,10 +3,12 @@ import { mkdtemp, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-test("SDK refuses a Chromium-only runtime instead of silently falling back", async () => {
-  const dir = await mkdtemp(join(tmpdir(), "spectest-no-shell-"));
+test("SDK refuses a Shell-only runtime instead of silently changing browser behavior", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "spectest-no-chromium-"));
   try {
-    await writeFile(join(dir, "chromium"), "#!/bin/sh\necho UNEXPECTED_CHROMIUM_LAUNCH >&2\nexit 1\n", { mode: 0o755 });
+    for (const name of ["chromium-headless-shell", "chrome-headless-shell"]) {
+      await writeFile(join(dir, name), "#!/bin/sh\necho UNEXPECTED_SHELL_LAUNCH >&2\nexit 1\n", { mode: 0o755 });
+    }
     const browserModule = new URL("./browser.ts", import.meta.url).href;
     const child = Bun.spawn([process.execPath, "-e", `
       import { openBrowser } from ${JSON.stringify(browserModule)};
@@ -15,7 +17,7 @@ test("SDK refuses a Chromium-only runtime instead of silently falling back", asy
     `], { env: { ...process.env, PATH: dir }, stdout: "pipe", stderr: "pipe" });
     const stderr = await new Response(child.stderr).text();
     expect(await child.exited).toBe(1);
-    expect(stderr).toContain("Headless Shell is required");
-    expect(stderr).not.toContain("UNEXPECTED_CHROMIUM_LAUNCH");
+    expect(stderr).toContain("Chromium is required");
+    expect(stderr).not.toContain("UNEXPECTED_SHELL_LAUNCH");
   } finally { await rm(dir, { recursive: true, force: true }); }
 });

package/src/browser-finalization.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
 import { acquirePersistentBrowser } from "./browser.js";
 import { finalizeBrowserRecordings } from "./harness/deadline.js";
 
-const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
+const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome"));
 
 test.skipIf(!available)("stuck replay drains are bounded warnings and late replies cannot change the recording or clear a later buffer", async () => {
   const chunks: unknown[] = [];

package/src/browser-image-loading.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
 import { readRaw } from "./inspect.js";
 import { openBrowser } from "./browser.js";
 
-const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
+const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome"));
 const png = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=", "base64");
 
 for (const late of [false, true]) {

package/src/browser-navigation.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
 import { openBrowser } from "./browser.js";
 import { startRecording, stopRecording } from "./recorder.js";
 
-const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
+const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome"));
 
 test.skipIf(!available)("public navigation options control goto/reload and remain visible in recordings", async () => {
   // The document commits immediately but load waits for an image. This

package/src/browser-permissions.test.ts

@@ -0,0 +1,143 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { chromium, type Browser as PlaywrightBrowser, type Page } from "playwright-core";
+import { acquirePersistentBrowser, openBrowser, prewarmViewPool, type Browser } from "./browser.js";
+
+const executable = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome");
+const referenceExecutable = executable ?? chromium.executablePath();
+
+// All 18 Chromium permission names in pinned Playwright 1.61.1, expressed as
+// native web descriptors (midi-sysex uses midi + sysex). No overrides: these
+// tests protect the defaults that apps received before the Shell migration.
+const cases = [
+  { label: "geolocation", expected: "prompt" },
+  { label: "midi", expected: "prompt" },
+  { label: "notifications", expected: "prompt" },
+  { label: "camera", expected: "granted" },
+  { label: "microphone", expected: "granted" },
+  { label: "background-sync", expected: "granted" },
+  { label: "ambient-light-sensor", expected: "TypeError: Failed to execute 'query' on 'Permissions': GenericSensorExtraClasses flag is not enabled." },
+  { label: "accelerometer", expected: "granted" },
+  { label: "gyroscope", expected: "granted" },
+  { label: "magnetometer", expected: "granted" },
+  { label: "clipboard-read", expected: "prompt" },
+  { label: "clipboard-write", expected: "granted" },
+  { label: "payment-handler", expected: "granted" },
+  { label: "midi-sysex", expected: "prompt", descriptor: { name: "midi", sysex: true } },
+  { label: "storage-access", expected: "granted" },
+  { label: "local-fonts", expected: "prompt" },
+  { label: "local-network-access", expected: "prompt" },
+  { label: "screen-wake-lock", expected: "granted" },
+];
+const descriptors = cases.map(row => row.descriptor ?? { name: row.label });
+
+async function permissionStates(arg?: unknown): Promise<string[]> {
+  const states: string[] = [];
+  for (const descriptor of arg as PermissionDescriptor[]) {
+    try { states.push((await navigator.permissions.query(descriptor)).state); }
+    catch (error) { states.push(`${(error as Error).name}: ${(error as Error).message}`); }
+  }
+  return states;
+}
+
+async function sdkStates(browser: Browser): Promise<string[]> {
+  return (await browser.evaluate("read default native permissions", permissionStates, descriptors)).unwrap();
+}
+
+// Runs unchanged in the real SDK and an independently launched full Chrome.
+// Do not request prompt-gated capabilities: the contract is to preserve their
+// native prompt state, not grant them globally or install JavaScript shims.
+async function nativeDefaultCapabilities() {
+  const media = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
+  const tracks = media.getTracks().map(track => `${track.kind}:${track.readyState}`).sort();
+  media.getTracks().forEach(track => track.stop());
+  const lock = await navigator.wakeLock.request("screen");
+  const wakeLock = { type: lock.type, before: lock.released, after: false };
+  await lock.release();
+  wakeLock.after = lock.released;
+  await document.requestStorageAccess();
+  const hasStorageAccess = await document.hasStorageAccess();
+  const registration = await navigator.serviceWorker.register("/permissions-sw.js");
+  await navigator.serviceWorker.ready;
+  // This operation succeeds in full Chromium but Shell throws 'Background
+  // Sync is disabled' even when its permission has explicitly been granted.
+  await (registration as any).sync.register("permission-regression");
+  const paymentManager = typeof (registration as any).paymentManager;
+  await registration.unregister();
+  return {
+    tracks, wakeLock, hasStorageAccess, backgroundSync: "registered", paymentManager,
+    notificationPermission: Notification.permission,
+    ambientConstructor: typeof (window as any).AmbientLightSensor,
+  };
+}
+
+describe.skipIf(!executable || !existsSync(referenceExecutable))("native browser permission compatibility", () => {
+  let server: ReturnType<typeof Bun.serve>;
+  let sdk: Browser;
+  let reference: PlaywrightBrowser;
+  let page: Page;
+  let expected: string[];
+  beforeAll(async () => {
+    server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch(request) {
+      if (new URL(request.url).pathname === "/permissions-sw.js") return new Response(
+        "self.addEventListener('install', () => self.skipWaiting()); self.addEventListener('activate', e => e.waitUntil(clients.claim())); self.addEventListener('sync', () => {});",
+        { headers: { "content-type": "application/javascript" } });
+      return new Response("<title>Default permissions</title>", { headers: { "content-type": "text/html" } });
+    } });
+    sdk = await openBrowser({ url: server.url.href });
+    reference = await chromium.launch({ executablePath: referenceExecutable, headless: true, args: [
+      "--no-sandbox", "--disable-dev-shm-usage", "--disable-features=AsyncDns,DnsOverHttps",
+      "--dns-over-https-mode=off", "--use-fake-device-for-media-stream", "--use-fake-ui-for-media-stream",
+    ] });
+    page = await reference.newPage();
+    await page.goto(server.url.href);
+    expected = await page.evaluate(permissionStates, descriptors);
+  });
+  afterAll(async () => {
+    await sdk?.close();
+    await reference?.close();
+    server?.stop(true);
+  });
+
+  test.each(cases)("$label keeps the previous full-Chromium default", async row => {
+    const index = cases.indexOf(row);
+    const actual = await sdkStates(sdk);
+    expect(expected[index]).toBe(row.expected);
+    expect(actual[index]).toBe(expected[index]);
+  });
+
+  test("default native media, wake lock, storage access and Background Sync match full Chrome", async () => {
+    const actual = (await sdk.evaluate("exercise native default capabilities", nativeDefaultCapabilities)).unwrap();
+    expect(actual).toEqual(await page.evaluate(nativeDefaultCapabilities));
+    expect(actual).toEqual({
+      tracks: ["audio:live", "video:live"], wakeLock: { type: "screen", before: false, after: true },
+      hasStorageAccess: true, backgroundSync: "registered", paymentManager: "object",
+      notificationPermission: "default", ambientConstructor: "undefined",
+    });
+  }, 15000);
+
+  test("navigation away and back retains native permission defaults", async () => {
+    await sdk.goto("about:blank");
+    await sdk.goto(server.url.href.replace("127.0.0.1", "localhost"));
+    expect(await sdkStates(sdk)).toEqual(expected);
+    await sdk.goto(server.url.href);
+    expect(await sdkStates(sdk)).toEqual(expected);
+  });
+
+  test("pooled, mobile and reattached sessions retain the same native defaults", async () => {
+    await prewarmViewPool();
+    const pooled = await openBrowser({ url: server.url.href });
+    const mobile = await openBrowser({ frame: "mobile", url: server.url.href });
+    const persistent = await acquirePersistentBrowser("permission-defaults", { url: server.url.href });
+    try {
+      expect(await sdkStates(pooled)).toEqual(expected);
+      expect(await sdkStates(mobile)).toEqual(expected);
+      expect(await sdkStates(persistent.browser)).toEqual(expected);
+      await persistent.detach();
+      const inherited = await acquirePersistentBrowser("permission-defaults");
+      expect(inherited.attached).toBe(true);
+      expect(await sdkStates(inherited.browser)).toEqual(expected);
+      await inherited.detach();
+    } finally { await pooled.close(); await mobile.close(); await persistent.browser.close(); }
+  }, 15000);
+});

package/src/browser-replay-transport.test.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "bun:test";
+import { acquirePersistentBrowser, type BrowserSessionStep } from "./browser.js";
+
+const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome"));
+
+test.skipIf(!available)("replay JSON transport preserves batches, drains once and leaves finalization read-only", async () => {
+  const chunks: BrowserSessionStep[] = [];
+  const session = await acquirePersistentBrowser("replay-json", {
+    url: "data:text/html,<title>one</title><p>Initial page</p>",
+    recorder: { sessionId: "replay-json", recordStep: step => chunks.push(step) },
+  });
+  const events = () => chunks.flatMap(c => c.events) as any[];
+  try {
+    expect(events().some(e => e.type === 2)).toBe(true);
+    const batch = Array.from({ length: 1000 }, (_, i) => ({
+      type: 5, timestamp: i, data: { tag: "bulk", payload: { id: i, text: '日本語 🙂 "quotes" \\ newline\n\ud800', nested: [null, true, { css: "a{}".repeat(100) }] } },
+    }));
+    await session.browser.probe(`window.__spectestRrwebEvents = ${JSON.stringify(batch)}`);
+    await session.browser.evaluate("flush replay", "1");
+    expect(events().filter(e => e.data?.tag === "bulk")).toEqual(batch);
+    expect(await session.browser.probe("window.__spectestRrwebEvents.length")).toBe(0);
+    await session.browser.evaluate("empty drain", "1");
+    expect(events().filter(e => e.data?.tag === "bulk")).toHaveLength(1000);
+
+    // General evaluations retain Playwright's richer JS value semantics.
+    const rich = await session.browser.probe<any>("({ value: undefined, nan: NaN, minusZero: -0, date: new Date(0) })");
+    expect(Object.hasOwn(rich, "value")).toBe(true);
+    expect(Number.isNaN(rich.nan)).toBe(true);
+    expect(Object.is(rich.minusZero, -0)).toBe(true);
+    expect(rich.date).toEqual(new Date(0));
+
+    await session.browser.goto("data:text/html,<title>two</title><p>New document</p>");
+    const last = chunks.at(-1)!;
+    expect(last.events.some((e: any) => e.type === 2)).toBe(true);
+    const final = [{ type: 5, data: { tag: "final", payload: ["retained"] } }];
+    await session.browser.probe(`window.__spectestRrwebEvents = ${JSON.stringify(final)}`);
+    await session.detach();
+    expect(events().filter(e => e.data?.tag === "final")).toEqual(final);
+    expect(await session.browser.probe("window.__spectestRrwebEvents")).toEqual(final);
+    const count = chunks.length;
+    await session.detach();
+    expect(chunks).toHaveLength(count);
+  } finally { await session.browser.close(); }
+}, 30000);
+
+test.skipIf(!available)("a replay serialization failure retains the buffer for a later drain", async () => {
+  const chunks: BrowserSessionStep[] = [];
+  const session = await acquirePersistentBrowser("replay-json-failure", {
+    url: "data:text/html,<p>Serialization failure</p>",
+    recorder: { sessionId: "replay-json-failure", recordStep: step => chunks.push(step) },
+  });
+  try {
+    await session.browser.probe('window.__spectestRrwebEvents = [{type:5,data:{tag:"retry",value:1n}}]');
+    await session.browser.evaluate("failed recording drain", "1");
+    expect(await session.browser.probe('window.__spectestRrwebEvents[0].data.tag')).toBe("retry");
+    await session.browser.probe('window.__spectestRrwebEvents[0].data.value = 1');
+    await session.browser.evaluate("retry recording drain", "1");
+    expect(chunks.flatMap(c => c.events).filter((e: any) => e.data?.tag === "retry")).toEqual([{type:5,data:{tag:"retry",value:1}}]);
+  } finally { await session.browser.close(); }
+}, 15000);

package/src/browser-screenshot.test.ts

@@ -3,8 +3,7 @@ import { openBrowser, type BrowserSessionRecorder } from "./browser.js";
 import { readRaw } from "./inspect.js";
 
 const available =
-  Bun.which("chromium-headless-shell") ??
-  Bun.which("chrome-headless-shell");
+  Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome");
 for (const frame of ["browser", "mobile"] as const) {
   test.skipIf(!available)(
     `${frame} public screenshot exports full PNG pixels after DOM changes`,

package/src/browser-timezone.test.ts

@@ -21,7 +21,7 @@ async function settings(browser: Browser): Promise<Settings> {
   return readRaw(await browser.evaluate<Settings>("read initial regional settings", "window.settings")) as unknown as Settings;
 }
 
-describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("browser timezone and locale", () => {
+describe.skipIf(!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome")))("browser timezone and locale", () => {
   let server: ReturnType<typeof Bun.serve>;
   beforeAll(() => {
     server = Bun.serve({

package/src/browser.ts

@@ -1,5 +1,5 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
-// driving the guest's Headless Shell (pipe transport — `chromium.launch`
+// driving the guest's full Chromium (pipe transport — `chromium.launch`
 // with an explicit `executablePath`). Electron attaches to the app-owned
 // Chromium over CDP instead; its client also lives inside the VM. The wrapper
 // keeps the public surface stable (we swapped from Bun.WebView to Playwright without
@@ -49,6 +49,7 @@ import {
   attachBrowserCoverage,
   browserCoverageActive,
   harvestBrowserCoverage,
+  releaseBrowserCoverage,
 } from "./browser-coverage.js";
 import type { UrlPattern } from "./url-match.js";
 export type { UrlPattern } from "./url-match.js";
@@ -236,6 +237,10 @@ export interface Browser {
   goForward(options?: NavigationOptions): Promise<void>;
   /** Reload the current page. */
   reload(options?: NavigationOptions): Promise<void>;
+  /** Read native clipboard text from an isolated observer in the same browser.
+   * Requires a secure page and honors its clipboard Permissions-Policy.
+   * Leaves application permissions unchanged and links assertions to the read. */
+  readClipboard(): Promise<Wrapped<string>>;
 
   readonly keyboard: Keyboard;
   readonly mouse: Mouse;
@@ -463,7 +468,7 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
 
-// Browser and mobile sessions share one Headless Shell per daemon, launched lazily and kept
+// Browser and mobile sessions share one full Chromium per daemon, launched lazily and kept
 // for the daemon's lifetime. Fixture sessions own a process because the audio
 // source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
@@ -482,13 +487,15 @@ const VIEW_CLEANUPS = new WeakMap<BrowserContext, () => Promise<void>>();
 // authenticated.
 
 function browserExecutable(): string {
-  const executable = Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell");
+  const executable = Bun.which("chromium") ?? Bun.which("chromium-browser") ??
+    Bun.which("google-chrome") ?? Bun.which("chrome");
   if (!executable) {
-    throw new Error("Chromium Headless Shell is required by this SDK but is missing from the runtime image. Rebuild the environment with a current Spectest golden image; for local development, install chromium-headless-shell on PATH.");
+    throw new Error("Full Chromium is required by this SDK but is missing from the runtime image. Install chromium on PATH; Chromium Headless Shell does not provide compatible browser permissions and background services.");
   }
   return executable;
 }
 
+
 async function ensurePlaywrightBrowser(): Promise<PlaywrightBrowser> {
   if (PW_BROWSER?.isConnected()) return PW_BROWSER;
   PW_BROWSER = await chromium.launch({
@@ -528,11 +535,12 @@ async function newViewContext(
 ): Promise<BrowserContext> {
   const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
   let browser: PlaywrightBrowser | undefined;
+  let context: BrowserContext | undefined;
   try {
     browser = fixture ? await chromium.launch({
       executablePath: browserExecutable(), headless: true, args: [...CHROME_ARGV, fixture.arg],
     }) : await ensurePlaywrightBrowser();
-    const context = await browser.newContext({
+    context = await browser.newContext({
       ...(device
         ? deviceContextOptions(device)
         : {
@@ -554,6 +562,7 @@ async function newViewContext(
     }
     return context;
   } catch (err) {
+    await context?.close().catch(() => {});
     if (fixture) {
       try { await browser?.close(); } finally { await fixture.cleanup(); }
     }
@@ -1176,7 +1185,7 @@ const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
   : "";
 
 // Page-side expression that atomically swaps in a fresh buffer and
-// returns the old one. Wrapped as a single expression so view.evaluate's
+// returns the old batch as JSON. Wrapped as a single expression so view.evaluate's
 // `await (...)` wrapper accepts it.
 //
 // `forceFullIfMissing` (inlined by `drainExpr`) guards a recovery path
@@ -1220,9 +1229,11 @@ function drainExpr(forceFullIfMissing: boolean, timestamp = Date.now()): string
     window.__spectestSyncInputs(${timestamp});
   }
   var buf = window.__spectestRrwebEvents;
-  if (!buf || !buf.length) return [];
+  if (!buf || !buf.length) return "[]";
+  // Serialize before clearing: an encoding failure must leave the batch intact.
+  var json = JSON.stringify(buf);
   window.__spectestRrwebEvents = [];
-  return buf;
+  return json;
 })()`;
 }
 
@@ -1743,11 +1754,6 @@ async function daemonResolves(url: string): Promise<boolean> {
  * retry once.
  */
 async function rebuildView(holder: ViewHolder): Promise<void> {
-  try {
-    await holder.page.close();
-  } catch {
-    /* page may already be gone */
-  }
   // The old renderer's coverage counters die with its page; harvest what
   // it had before the swap (rebuild is triggered on a fresh navigation).
   try {
@@ -1755,6 +1761,12 @@ async function rebuildView(holder: ViewHolder): Promise<void> {
   } catch {
     /* best-effort */
   }
+  releaseBrowserCoverage(holder.cdp);
+  try {
+    await holder.page.close();
+  } catch {
+    /* page may already be gone */
+  }
   const fresh = await spawnPage(holder.context);
   holder.page = fresh.page;
   holder.cdp = fresh.cdp;
@@ -1850,11 +1862,15 @@ function buildBackend(
       // Finalization only reads the buffer. A timed-out evaluation may run
       // after a child/eval attaches; it must not clear that session's events.
       const expression = action === "close"
-        ? "window.__spectestRrwebEvents || []"
+        ? "JSON.stringify(window.__spectestRrwebEvents || [])"
         : drainExpr(urlChanged, timestamp);
-      const events = (await holder.page.evaluate(expression)) as unknown[];
+      // Replay batches are JSON data. Returning one string avoids Playwright's
+      // recursive SerializedValue validation/copying for every event field.
+      // Keep general user evaluations on Playwright's normal value transport.
+      const encoded = await holder.page.evaluate<string>(expression);
       signal?.throwIfAborted();
       if (recordingEnded) return;
+      const events: unknown = JSON.parse(encoded);
       lastDrainUrl = holder.page.url();
       if (Array.isArray(events) && events.length > 0) {
         recorder.recordStep({
@@ -1881,6 +1897,12 @@ function buildBackend(
     const t = Date.now();
     const resv = reserveEvent();
     try {
+      // Any action (including a click or evaluation) can navigate and replace
+      // the renderer. Drain its counters while it is still alive. Collection
+      // failures remain on the collector and fail coverage capture later.
+      if (browserCoverageActive()) {
+        try { await harvestBrowserCoverage(holder.cdp); } catch { /* retained by collector */ }
+      }
       const result = await fn();
       // Refresh the sync title cache (playwright's title() is async).
       try {
@@ -1888,7 +1910,7 @@ function buildBackend(
       } catch {
         /* page mid-navigation or closed — keep the stale cache */
       }
-      if (recordingEnded) return result;
+      if (recordingEnded) return opts?.wrap ? wrap(result, undefined) as T : result;
       // `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
@@ -1902,9 +1924,7 @@ function buildBackend(
         durationMs: endT - t,
       }, resv);
       await drain(action, endT);
-      // Fold this page's V8 counters into the per-service totals now — a
-      // navigation to another origin replaces the renderer and its
-      // counters, so harvesting per op is what keeps them.
+      // Collect the action's effects too, including scripts in a new renderer.
       if (browserCoverageActive()) {
         try {
           await harvestBrowserCoverage(holder.cdp);
@@ -1915,7 +1935,7 @@ function buildBackend(
       // Reads (`opts.wrap`) return user-visible JS values someone is likely to
       // assert on — provenance-wrap so `expect(...)` nests under this step.
       // Actions return void/internals; leave them raw to avoid Proxy surprises.
-      if (seq !== undefined && opts?.wrap) {
+      if (opts?.wrap) {
         return wrap(result, seq) as T;
       }
       return result;
@@ -2054,6 +2074,44 @@ function buildBackend(
         await holder.page.reload(options);
       });
     },
+    readClipboard() {
+      return instrumented<string>(
+        "readClipboard", {},
+        async () => {
+          const page = holder.page;
+          const { origin, policyAllowsRead } = await page.evaluate(() => {
+            if (!isSecureContext || !/^https?:$/.test(location.protocol)) {
+              throw new Error("Clipboard reads require a secure HTTP(S) page");
+            }
+            const policy = (document as Document & { featurePolicy?: { allowsFeature(name: string): boolean } }).featurePolicy;
+            return { origin: location.origin, policyAllowsRead: policy?.allowsFeature("clipboard-read") ?? true };
+          });
+          if (!policyAllowsRead) return page.evaluate(() => navigator.clipboard.readText());
+          const browser = holder.context.browser();
+          if (!browser) throw new Error("Clipboard reads require an attached Chromium browser");
+          // Native clipboard contents belong to the browser, not the context.
+          // Observe from a disposable context: overriding an app permission and
+          // restoring its queried state cannot restore native prompt behavior
+          // or preserve overrides owned by another DevTools session.
+          const observer = await browser.newContext();
+          try {
+            const observerOrigin = "https://spectest-clipboard.invalid";
+            await observer.route("**/*", route => route.fulfill({
+              status: 200, contentType: "text/html", body: "<!doctype html><title>Clipboard observation</title>",
+            }));
+            await observer.grantPermissions(["clipboard-read"], { origin: observerOrigin });
+            const observerPage = await observer.newPage();
+            await observerPage.goto(observerOrigin);
+            const text = await observerPage.evaluate(() => navigator.clipboard.readText());
+            await page.evaluate(expectedOrigin => {
+              if (location.origin !== expectedOrigin) throw new Error("Page navigated during clipboard read");
+            }, origin);
+            return text;
+          } finally { await observer.close(); }
+        },
+        { wrap: true },
+      ) as unknown as Promise<Wrapped<string>>;
+    },
 
     locator: (css) => makeLocator(backend, strategy, { steps: [{ m: "locator", args: [css] }] }),
     getByRole: (role, opts) =>
@@ -2236,6 +2294,7 @@ function buildBackend(
       if (browserCoverageActive()) {
         try { await harvestBrowserCoverage(holder.cdp); } catch { /* capture reports the error */ }
       }
+      releaseBrowserCoverage(holder.cdp);
       viewClosed = true;
       buildOpts.onDestroy?.();
       try {

package/src/change-rules.fixtures.json

@@ -0,0 +1,35 @@
+[
+ {"pattern":"**/*.ts","path":"helper.ts","matches":true},
+ {"pattern":"**/*.ts","path":"a/b/helper.ts","matches":true},
+ {"pattern":"*.ts","path":"a/helper.ts","matches":false},
+ {"pattern":"src/**","path":"src/a/b.ts","matches":true},
+ {"pattern":"src","path":"src/a.ts","matches":false},
+ {"pattern":"app/\\[id\\]/page.tsx","path":"app/[id]/page.tsx","matches":true},
+ {"pattern":"app/[[]id]/page.tsx","path":"app/[id]/page.tsx","matches":true},
+ {"pattern":"app/[id]/page.tsx","path":"app/[id]/page.tsx","matches":false},
+ {"pattern":"app/[id]/page.tsx","path":"app/i/page.tsx","matches":true},
+ {"pattern":"app/(shop)/\\[...slug\\]/page.tsx","path":"app/(shop)/[...slug]/page.tsx","matches":true},
+ {"pattern":"a?b.ts","path":"a😀b.ts","matches":true},
+ {"pattern":"a?b.ts","path":"a/b.ts","matches":false},
+ {"pattern":"[!a].ts","path":"b.ts","matches":true},
+ {"pattern":"[!a].ts","path":"a.ts","matches":false},
+ {"pattern":"[!a].ts","path":"/.ts","matches":false},
+ {"pattern":"[a-c].ts","path":"b.ts","matches":true},
+ {"pattern":"[a-c].ts","path":"d.ts","matches":false},
+ {"pattern":"[😀-🙏].ts","path":"😂.ts","matches":true},
+ {"pattern":"**/*.md","path":"a/line\nbreak.md","matches":true},
+ {"pattern":"file.ts","path":"file.ts\n","matches":false},
+ {"pattern":"!odd#name:foo+.ts","path":"!odd#name:foo+.ts","matches":true},
+ {"pattern":" leading space.ts","path":" leading space.ts","matches":true},
+ {"pattern":"file\\*.ts","path":"file*.ts","matches":true},
+ {"pattern":"*.{ts,js}","path":"a.ts","matches":false},
+ {"pattern":"a/[z-a]","invalid":true},
+ {"pattern":"a/[.-0]","invalid":true},
+ {"pattern":"a/[abc","invalid":true},
+ {"pattern":"a/[]","invalid":true},
+ {"pattern":"a/\\","invalid":true},
+ {"pattern":"foo**bar.ts","invalid":true},
+ {"pattern":"../secret","invalid":true},
+ {"pattern":"/absolute","invalid":true},
+ {"pattern":"a//b","invalid":true}
+]