playwright-browser-harness 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronan Sandford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# playwright-browser-harness
+
+Run **bundled TypeScript inside a real browser** under Playwright — drive it,
+assert results, measure performance — with the things browser storage needs:
+COOP/COEP cross-origin isolation (`SharedArrayBuffer` / OPFS), Web Workers,
+persistence across reloads, a reset between tests.
+
+**Hybrid distribution.** The machinery (`mountHarness`/driver, the COOP/COEP
+server, the esbuild build, the page glue, the contract) ships in this package and
+is **imported, never copied**. A tiny `init` CLI scaffolds only the per-project
+files you edit anyway (a starter `cut.ts`, a spec, a `playwright.config.ts`).
+
+## Install
+
+```bash
+pnpm add -D playwright-browser-harness @playwright/test esbuild typescript @types/node
+pnpm exec playwright install chromium
+```
+
+`@playwright/test` and `esbuild` are **peerDependencies** — the consumer drives
+their versions. `@sqlite.org/sqlite-wasm` is *not* a dependency; it is only a
+fixture/consumer dep when you test wasm-SQLite.
+
+## tsconfig (required)
+
+```jsonc
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",       // resolve 'playwright-browser-harness/contract'
+    "allowImportingTsExtensions": true,  // the contract ships as raw .ts and is bundled
+    "lib": ["ES2022", "DOM", "DOM.Iterable", "WebWorker"]
+  }
+}
+```
+
+## Scaffold a starter (optional)
+
+```bash
+npx playwright-browser-harness init tests        # writes tests/cut.ts, tests/example.spec.ts, playwright.config.ts
+pnpm exec playwright test
+npx playwright-browser-harness update tests      # report drift of scaffolded files vs current templates
+```
+
+## Use
+
+```ts
+// tests/cut.ts — your code-under-test, BUNDLED INTO THE BROWSER
+import type {CodeUnderTest} from 'playwright-browser-harness/contract';
+import {captureEnv, timed} from 'playwright-browser-harness/contract';
+const cut: CodeUnderTest = { name: 'mine', async run(ctx){ /* ... */ return {results:{},timings:[],errors:[],env:captureEnv()}; } };
+export default cut;
+```
+
+```ts
+// tests/x.spec.ts — Node side
+import {test, expect} from '@playwright/test';
+import {mountHarness} from 'playwright-browser-harness';
+
+test('persists', async ({page}) => {
+  const h = await mountHarness(page, {cut: resolve(__dirname,'cut.ts'), coi: false});
+  const w = await h.run({phase:'write', params:{n:100}});
+  await h.reload();
+  const r = await h.run({phase:'read', params:{n:100}});
+  expect(r.results.survived).toBe(true);
+  await h.dispose();
+});
+```
+
+`MountOptions`: `cut` (required), `coi` (default `true`), `worker`, `wasmDirs`,
+`assets`, `prebuilt`. See the
+[`playwright-browser-test-harness` research topic](../README.md) for the full
+architecture, gotchas, and per-browser OPFS matrix.

package/bin/cli.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * playwright-browser-harness CLI — the "init/copy-in" half of the HYBRID distribution.
+ *
+ * The MACHINERY (mountHarness/driver, the COOP/COEP server, the esbuild build,
+ * page-entry, contract) ships INSIDE this package and is imported, never copied:
+ *   import { mountHarness } from 'playwright-browser-harness';
+ *   import type { CodeUnderTest } from 'playwright-browser-harness/contract';
+ *
+ * This CLI only scaffolds the genuinely PER-PROJECT files a consumer always edits
+ * anyway — a starter `cut.ts`, a starter spec, and a `playwright.config.ts` — so a
+ * consuming repo does not start from a blank page. It does NOT copy page-entry/
+ * server/build/driver (those stay in node_modules and update via your package
+ * manager, no drift).
+ *
+ * Commands:
+ *   init [dir]      scaffold cut.ts + <name>.spec.ts + playwright.config.ts into <dir>
+ *                   (default: ./tests). Prints the tsconfig + devDeps you need.
+ *   update [dir]    re-show the current templates vs your files (diff). With
+ *                   --force, overwrite the scaffolded files (your edits are lost —
+ *                   commit first). Without it, only reports drift.
+ *   help            this help.
+ *
+ * Flags: --force (overwrite on init/update), --name <n> (spec base name).
+ */
+import {fileURLToPath} from 'node:url';
+import {dirname, join, resolve, relative} from 'node:path';
+import {mkdir, readFile, writeFile, stat} from 'node:fs/promises';
+import {existsSync} from 'node:fs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const templatesDir = resolve(here, '..', 'templates');
+const PKG = 'playwright-browser-harness';
+
+function parseArgs(argv) {
+  const args = {_: [], force: false, name: 'example'};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--force') args.force = true;
+    else if (a === '--name') args.name = argv[++i];
+    else args._.push(a);
+  }
+  return args;
+}
+
+async function readTemplate(file) {
+  return readFile(join(templatesDir, file), 'utf8');
+}
+
+// The files the CLI manages. `out` is the destination filename inside <dir>.
+function plan(targetDir, name) {
+  return [
+    {tmpl: 'cut.ts.tmpl', out: join(targetDir, 'cut.ts')},
+    {tmpl: 'example.spec.ts.tmpl', out: join(targetDir, `${name}.spec.ts`)},
+    {tmpl: 'playwright.config.ts.tmpl', out: resolve(targetDir, '..', 'playwright.config.ts')},
+  ];
+}
+
+function tsconfigSnippet() {
+  return `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",        // required: lets cut.ts import '${PKG}/contract'
+    "allowImportingTsExtensions": true,   // required: the contract is shipped as raw .ts and bundled
+    "lib": ["ES2022", "DOM", "DOM.Iterable", "WebWorker"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "tests"]
+}`;
+}
+
+function postInstallNote(dir) {
+  const rel = relative(process.cwd(), dir) || '.';
+  return `
+Scaffolded into ${rel}/ (and ../playwright.config.ts).
+
+NEXT STEPS
+  1. Install peers (the harness drives these; they are YOUR devDeps):
+       pnpm add -D ${PKG} @playwright/test esbuild typescript @types/node
+       pnpm exec playwright install chromium
+
+  2. Your tsconfig.json MUST use bundler resolution + .ts imports:
+${tsconfigSnippet().split('\n').map((l) => '       ' + l).join('\n')}
+
+  3. Edit ${rel}/cut.ts (your code-under-test) and run:
+       pnpm exec playwright test
+
+IMPORTS (already wired in the scaffolded files)
+  import { mountHarness } from '${PKG}';
+  import type { CodeUnderTest } from '${PKG}/contract';
+  import { captureEnv, timed } from '${PKG}/contract';
+
+COOP/COEP NOTE
+  mountHarness(page, { cut, coi: true })  serves with cross-origin isolation
+  (crossOriginIsolated === true → SharedArrayBuffer + OPFS sync VFS). Use
+  coi: false for plain IndexedDB / no-isolation paths. The server is owned by the
+  package; you toggle it via the option, you do not edit server source.
+`;
+}
+
+async function cmdInit(args) {
+  const targetDir = resolve(args._[0] ?? 'tests');
+  await mkdir(targetDir, {recursive: true});
+  const items = plan(targetDir, args.name);
+
+  let wrote = 0;
+  let skipped = 0;
+  for (const {tmpl, out} of items) {
+    const content = await readTemplate(tmpl);
+    if (existsSync(out) && !args.force) {
+      console.error(`  skip   ${relative(process.cwd(), out)} (exists; --force to overwrite)`);
+      skipped++;
+      continue;
+    }
+    await mkdir(dirname(out), {recursive: true});
+    await writeFile(out, content);
+    console.error(`  ${args.force && existsSync(out) ? 'write ' : 'create'} ${relative(process.cwd(), out)}`);
+    wrote++;
+  }
+  console.error(`\n${wrote} written, ${skipped} skipped.`);
+  console.error(postInstallNote(targetDir));
+}
+
+async function cmdUpdate(args) {
+  const targetDir = resolve(args._[0] ?? 'tests');
+  const items = plan(targetDir, args.name);
+  let drift = 0;
+
+  for (const {tmpl, out} of items) {
+    const template = await readTemplate(tmpl);
+    const rel = relative(process.cwd(), out);
+    if (!existsSync(out)) {
+      console.error(`  missing ${rel} (run init to create)`);
+      drift++;
+      continue;
+    }
+    const current = await readFile(out, 'utf8');
+    if (current === template) {
+      console.error(`  same    ${rel}`);
+      continue;
+    }
+    drift++;
+    if (args.force) {
+      await writeFile(out, template);
+      console.error(`  reset   ${rel} (overwritten with current template)`);
+    } else {
+      console.error(`  drift   ${rel} (differs from template; --force to overwrite, commit first)`);
+    }
+  }
+  if (drift === 0) console.error('\nNo drift — scaffolded files match the current templates.');
+  else if (!args.force)
+    console.error(
+      `\n${drift} file(s) differ. These files are YOURS — drift is expected once you edit them. ` +
+        `Only the IMPORTED machinery (driver/server/build/page-entry/contract) updates with your package manager.`,
+    );
+}
+
+function cmdHelp() {
+  console.error(`playwright-browser-harness — hybrid distribution CLI
+
+USAGE
+  npx ${PKG} init [dir]      scaffold cut.ts + spec + playwright.config.ts (default dir: ./tests)
+  npx ${PKG} update [dir]    report drift of scaffolded files vs templates (--force overwrites)
+  npx ${PKG} help
+
+FLAGS
+  --force         overwrite existing files (init) / reset to template (update)
+  --name <n>      spec base name (default: example → example.spec.ts)
+
+The harness MACHINERY is imported, not copied:
+  import { mountHarness } from '${PKG}';
+  import type { CodeUnderTest } from '${PKG}/contract';
+This CLI only scaffolds the per-project files you edit anyway.`);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._.shift();
+
+try {
+  if (cmd === 'init') await cmdInit(args);
+  else if (cmd === 'update') await cmdUpdate(args);
+  else if (cmd === 'help' || cmd === '--help' || cmd === '-h' || !cmd) cmdHelp();
+  else {
+    console.error(`unknown command: ${cmd}\n`);
+    cmdHelp();
+    process.exit(1);
+  }
+} catch (e) {
+  console.error(String(e instanceof Error ? e.stack ?? e.message : e));
+  process.exit(1);
+}

package/dist/build.mjs

@@ -0,0 +1,107 @@
+/**
+ * build.mjs — bundle a code-under-test for the browser with esbuild.
+ *
+ * Why esbuild over Vite for a *test harness*: we want a single, fast,
+ * scriptable function (`buildBundle`) we can call from a Playwright global
+ * setup — no dev server, no HMR, no plugin ecosystem needed. esbuild bundles a
+ * TS entry (incl. a Web Worker entry) to a flat dir in tens of ms and is a
+ * single dependency. Vite shines for app dev (HMR, SSR, rich plugins); here
+ * those are pure overhead. See README "esbuild vs Vite".
+ *
+ * Produces, into <outdir>/:
+ *   index.html          — loads bundle.js
+ *   bundle.js           — page-entry + the chosen code-under-test
+ *   worker.js           — (optional) a Worker entry, if the CUT ships one
+ *   *.wasm              — copied wasm assets (sqlite, etc.)
+ */
+import esbuild from 'esbuild';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { mkdir, writeFile, rm, copyFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * @param {object} opts
+ * @param {string} opts.cut        absolute path to the code-under-test module
+ * @param {string} opts.outdir     output directory
+ * @param {string} [opts.worker]   absolute path to an optional Worker entry
+ * @param {string[]} [opts.wasmDirs] dirs whose *.wasm files to copy to outdir
+ * @param {string[]} [opts.assets]  explicit absolute file paths to copy verbatim
+ *   into outdir (e.g. sqlite3-opfs-async-proxy.js, which the OPFS VFS spawns by
+ *   URL relative to the worker bundle and esbuild does NOT trace).
+ */
+export async function buildBundle({ cut, outdir, worker, wasmDirs = [], assets = [] }) {
+  await rm(outdir, { recursive: true, force: true });
+  await mkdir(outdir, { recursive: true });
+
+  const entryPoints = [{ in: join(here, 'page-entry.ts'), out: 'bundle' }];
+  if (worker) entryPoints.push({ in: worker, out: 'worker' });
+
+  await esbuild.build({
+    entryPoints,
+    outdir,
+    bundle: true,
+    format: 'esm',
+    target: 'es2022',
+    platform: 'browser',
+    sourcemap: true,
+    // Inject the chosen code-under-test as the `__CUT_MODULE__` import.
+    plugins: [
+      {
+        name: 'resolve-cut',
+        setup(b) {
+          b.onResolve({ filter: /^__CUT_MODULE__$/ }, () => ({ path: cut }));
+        },
+      },
+    ],
+    // sqlite-wasm ships an mjs that references the wasm by URL; keep it external
+    // to the worker if needed — here we let esbuild bundle JS and copy wasm.
+    loader: { '.wasm': 'copy' },
+  });
+
+  // Copy wasm assets (e.g. @sqlite.org/sqlite-wasm's sqlite3.wasm) next to JS.
+  for (const dir of wasmDirs) {
+    if (!existsSync(dir)) continue;
+    for (const f of await readdir(dir)) {
+      if (f.endsWith('.wasm')) await copyFile(join(dir, f), join(outdir, f));
+    }
+  }
+  // Copy explicit assets verbatim, preserving basename. GOTCHA: the sqlite-wasm
+  // OPFS VFS loads `sqlite3-opfs-async-proxy.js` via `new URL(..., import.meta
+  // .url)` from a *separate* Worker it spawns itself; esbuild never sees that
+  // string, so the file must be placed next to the worker bundle by hand.
+  for (const a of assets) {
+    if (!existsSync(a)) continue;
+    await copyFile(a, join(outdir, a.split('/').pop()));
+  }
+
+  // Minimal HTML shell. type="module" so top-level await / ESM works.
+  const html = `<!doctype html>
+<html>
+  <head><meta charset="utf-8"><title>harness</title></head>
+  <body>
+    <script type="module" src="./bundle.js"></script>
+  </body>
+</html>`;
+  await writeFile(join(outdir, 'index.html'), html);
+
+  return { outdir, hasWorker: Boolean(worker) };
+}
+
+// CLI: `node harness/build.mjs <cut> <outdir> [worker]`
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [, , cut, outdir, worker] = process.argv;
+  if (!cut || !outdir) {
+    console.error('usage: build.mjs <cut-module> <outdir> [worker-entry]');
+    process.exit(1);
+  }
+  await buildBundle({
+    cut: resolve(cut),
+    outdir: resolve(outdir),
+    worker: worker ? resolve(worker) : undefined,
+    assets: [],
+  });
+  console.log('built', outdir);
+}

package/dist/contract.d.ts

@@ -0,0 +1,60 @@
+/**
+ * contract.ts — the stable contract between the harness and a "code-under-test".
+ *
+ * A consuming topic (e.g. browser-embedded-indexer) supplies a TS module that
+ * default-exports a `CodeUnderTest`. The harness bundles it, loads it in a real
+ * browser page (and/or a Worker), invokes `run()`, and ships the structured
+ * `{ results, timings, errors }` back to the Node test process for assertions.
+ *
+ * This file is intentionally dependency-free so it can be imported from both the
+ * browser bundle and the Node side without pulling in anything browser- or
+ * node-specific.
+ */
+/** A single timing sample, in milliseconds (from `performance.now()`). */
+export interface Timing {
+    label: string;
+    ms: number;
+}
+/** Structured result returned from the browser back to Node. */
+export interface RunResult {
+    /** Arbitrary JSON-serialisable payload the consumer wants to assert on. */
+    results: Record<string, unknown>;
+    /** Named perf samples in ms. */
+    timings: Timing[];
+    /** Any errors collected (stringified). Empty array == success. */
+    errors: string[];
+    /** Environment facts the harness/consumer may want to assert on. */
+    env: EnvInfo;
+}
+/** Environment facts captured in-page so Node can assert on them. */
+export interface EnvInfo {
+    crossOriginIsolated: boolean;
+    hasSharedArrayBuffer: boolean;
+    hasOPFS: boolean;
+    userAgent: string;
+}
+/**
+ * The pluggable unit. A consuming topic implements this and points the harness
+ * at the module (see fixtures/ for two worked examples).
+ *
+ * `phase` lets the same module participate in a navigate→reload flow: the
+ * harness calls `run({ phase: 'write' })`, reloads the page, then calls
+ * `run({ phase: 'read' })` to assert persistence survived the reload.
+ */
+export interface CodeUnderTest {
+    /** Optional human label, surfaced in logs. */
+    name?: string;
+    run(ctx: RunContext): Promise<RunResult>;
+    /** Optional cleanup hook to reset OPFS / IndexedDB between tests. */
+    reset?(): Promise<void>;
+}
+export interface RunContext {
+    /** 'write' (first load) | 'read' (after reload) | 'once' (single shot). */
+    phase: 'write' | 'read' | 'once';
+    /** Free-form params the Node side can pass through (e.g. dataset size). */
+    params: Record<string, unknown>;
+}
+/** Capture standard environment facts. Safe to call in window or Worker. */
+export declare function captureEnv(): EnvInfo;
+/** Small helper: time an async fn and push a labelled sample. */
+export declare function timed<T>(label: string, out: Timing[], fn: () => Promise<T> | T): Promise<T>;

package/dist/contract.js

@@ -0,0 +1,29 @@
+/**
+ * contract.ts — the stable contract between the harness and a "code-under-test".
+ *
+ * A consuming topic (e.g. browser-embedded-indexer) supplies a TS module that
+ * default-exports a `CodeUnderTest`. The harness bundles it, loads it in a real
+ * browser page (and/or a Worker), invokes `run()`, and ships the structured
+ * `{ results, timings, errors }` back to the Node test process for assertions.
+ *
+ * This file is intentionally dependency-free so it can be imported from both the
+ * browser bundle and the Node side without pulling in anything browser- or
+ * node-specific.
+ */
+/** Capture standard environment facts. Safe to call in window or Worker. */
+export function captureEnv() {
+    const g = globalThis;
+    return {
+        crossOriginIsolated: g.crossOriginIsolated === true,
+        hasSharedArrayBuffer: typeof g.SharedArrayBuffer !== 'undefined',
+        hasOPFS: typeof g.navigator?.storage?.getDirectory === 'function',
+        userAgent: g.navigator?.userAgent ?? 'unknown',
+    };
+}
+/** Small helper: time an async fn and push a labelled sample. */
+export async function timed(label, out, fn) {
+    const t0 = performance.now();
+    const v = await fn();
+    out.push({ label, ms: performance.now() - t0 });
+    return v;
+}

package/dist/contract.ts

@@ -0,0 +1,89 @@
+/**
+ * contract.ts — the stable contract between the harness and a "code-under-test".
+ *
+ * A consuming topic (e.g. browser-embedded-indexer) supplies a TS module that
+ * default-exports a `CodeUnderTest`. The harness bundles it, loads it in a real
+ * browser page (and/or a Worker), invokes `run()`, and ships the structured
+ * `{ results, timings, errors }` back to the Node test process for assertions.
+ *
+ * This file is intentionally dependency-free so it can be imported from both the
+ * browser bundle and the Node side without pulling in anything browser- or
+ * node-specific.
+ */
+
+/** A single timing sample, in milliseconds (from `performance.now()`). */
+export interface Timing {
+  label: string;
+  ms: number;
+}
+
+/** Structured result returned from the browser back to Node. */
+export interface RunResult {
+  /** Arbitrary JSON-serialisable payload the consumer wants to assert on. */
+  results: Record<string, unknown>;
+  /** Named perf samples in ms. */
+  timings: Timing[];
+  /** Any errors collected (stringified). Empty array == success. */
+  errors: string[];
+  /** Environment facts the harness/consumer may want to assert on. */
+  env: EnvInfo;
+}
+
+/** Environment facts captured in-page so Node can assert on them. */
+export interface EnvInfo {
+  crossOriginIsolated: boolean;
+  hasSharedArrayBuffer: boolean;
+  hasOPFS: boolean;
+  userAgent: string;
+}
+
+/**
+ * The pluggable unit. A consuming topic implements this and points the harness
+ * at the module (see fixtures/ for two worked examples).
+ *
+ * `phase` lets the same module participate in a navigate→reload flow: the
+ * harness calls `run({ phase: 'write' })`, reloads the page, then calls
+ * `run({ phase: 'read' })` to assert persistence survived the reload.
+ */
+export interface CodeUnderTest {
+  /** Optional human label, surfaced in logs. */
+  name?: string;
+  run(ctx: RunContext): Promise<RunResult>;
+  /** Optional cleanup hook to reset OPFS / IndexedDB between tests. */
+  reset?(): Promise<void>;
+}
+
+export interface RunContext {
+  /** 'write' (first load) | 'read' (after reload) | 'once' (single shot). */
+  phase: 'write' | 'read' | 'once';
+  /** Free-form params the Node side can pass through (e.g. dataset size). */
+  params: Record<string, unknown>;
+}
+
+/** Capture standard environment facts. Safe to call in window or Worker. */
+export function captureEnv(): EnvInfo {
+  const g = globalThis as unknown as {
+    crossOriginIsolated?: boolean;
+    SharedArrayBuffer?: unknown;
+    navigator?: { storage?: { getDirectory?: unknown }; userAgent?: string };
+  };
+  return {
+    crossOriginIsolated: g.crossOriginIsolated === true,
+    hasSharedArrayBuffer: typeof g.SharedArrayBuffer !== 'undefined',
+    hasOPFS:
+      typeof g.navigator?.storage?.getDirectory === 'function',
+    userAgent: g.navigator?.userAgent ?? 'unknown',
+  };
+}
+
+/** Small helper: time an async fn and push a labelled sample. */
+export async function timed<T>(
+  label: string,
+  out: Timing[],
+  fn: () => Promise<T> | T,
+): Promise<T> {
+  const t0 = performance.now();
+  const v = await fn();
+  out.push({ label, ms: performance.now() - t0 });
+  return v;
+}

package/dist/driver.d.ts

@@ -0,0 +1,60 @@
+/// <reference path="./harness.d.ts" />
+/**
+ * driver.ts — the reusable Node-side test driver. THIS is the stable surface a
+ * consuming topic (browser-embedded-indexer) imports.
+ *
+ * Typical use from a consuming topic's Playwright test:
+ *
+ *   import { test, expect } from '@playwright/test';
+ *   import { mountHarness } from '<this>/harness/driver';
+ *
+ *   test('my store persists', async ({ page }) => {
+ *     const h = await mountHarness(page, {
+ *       cut: require.resolve('./my-store.cut.ts'), // your code-under-test
+ *       coi: true,                                  // serve with COOP/COEP
+ *       worker: require.resolve('./my-store.worker.ts'), // optional
+ *     });
+ *     const w = await h.run({ phase: 'write', params: { n: 1000 } });
+ *     expect(w.errors).toEqual([]);
+ *     await h.reload();
+ *     const r = await h.run({ phase: 'read', params: {} });
+ *     expect(r.results.survived).toBe(true);
+ *     console.log(r.timings);
+ *     await h.dispose();
+ *   });
+ *
+ * The driver owns: bundling (esbuild), serving (COOP/COEP toggle), page load,
+ * env assertions, and ferrying `{results,timings,errors,env}` across the bridge.
+ */
+import type { Page } from '@playwright/test';
+import type { EnvInfo, RunContext, RunResult } from './contract.ts';
+declare const here: string;
+export interface MountOptions {
+    /** Absolute path to the code-under-test module (default-exports CodeUnderTest). */
+    cut: string;
+    /** Serve with COOP/COEP (cross-origin isolation). Default true. */
+    coi?: boolean;
+    /** Optional absolute path to a Web Worker entry to bundle alongside. */
+    worker?: string;
+    /** Extra dirs whose *.wasm files should be copied next to the bundle. */
+    wasmDirs?: string[];
+    /** Explicit asset files to copy verbatim next to the bundle (e.g. the OPFS
+     *  async proxy js). */
+    assets?: string[];
+    /** Reuse a prebuilt outdir + server (skip building). */
+    prebuilt?: {
+        outdir: string;
+        serverUrl: string;
+    };
+}
+export interface MountedHarness {
+    serverUrl: string;
+    outdir: string;
+    env(): Promise<EnvInfo>;
+    run(ctx: RunContext): Promise<RunResult>;
+    reset(): Promise<void>;
+    reload(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare function mountHarness(page: Page, opts: MountOptions): Promise<MountedHarness>;
+export { here as harnessDir };

package/dist/driver.js

@@ -0,0 +1,53 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+// build.mjs / server.mjs are JS ESM siblings; imported at runtime by Playwright.
+// @ts-ignore - .mjs has no types
+import { buildBundle } from './build.mjs';
+// @ts-ignore - .mjs has no types
+import { startServer } from './server.mjs';
+const here = dirname(fileURLToPath(import.meta.url));
+export async function mountHarness(page, opts) {
+    let outdir;
+    let serverUrl;
+    let close;
+    if (opts.prebuilt) {
+        outdir = opts.prebuilt.outdir;
+        serverUrl = opts.prebuilt.serverUrl;
+    }
+    else {
+        outdir = await mkdtemp(join(tmpdir(), 'harness-'));
+        await buildBundle({
+            cut: opts.cut,
+            outdir,
+            worker: opts.worker,
+            wasmDirs: opts.wasmDirs ?? [],
+            assets: opts.assets ?? [],
+        });
+        const srv = await startServer({ root: outdir, coi: opts.coi ?? true });
+        serverUrl = srv.url;
+        close = srv.close;
+    }
+    await loadAndWait(page, serverUrl);
+    return {
+        serverUrl,
+        outdir,
+        env: () => page.evaluate(() => window.__harness.env()),
+        run: (ctx) => page.evaluate((c) => window.__harness.run(c), ctx),
+        reset: () => page.evaluate(() => window.__harness.reset()),
+        async reload() {
+            await page.reload({ waitUntil: 'load' });
+            await page.waitForFunction(() => window.__harness?.ready === true);
+        },
+        async dispose() {
+            if (close)
+                await close();
+        },
+    };
+}
+async function loadAndWait(page, url) {
+    await page.goto(url, { waitUntil: 'load' });
+    await page.waitForFunction(() => window.__harness?.ready === true);
+}
+export { here as harnessDir };

package/dist/harness.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Ambient global for the in-page harness API, used by driver.ts `page.evaluate`
+ * callbacks (which are type-checked against the browser global scope).
+ */
+import type { EnvInfo, RunContext, RunResult } from './contract.ts';
+
+declare global {
+  interface Window {
+    __harness: {
+      env: () => EnvInfo;
+      run: (ctx: RunContext) => Promise<RunResult>;
+      reset: () => Promise<void>;
+      ready: true;
+    };
+  }
+}
+
+export {};

package/dist/page-entry.ts

@@ -0,0 +1,49 @@
+/**
+ * page-entry.ts — the in-page glue. esbuild bundles this with a chosen
+ * code-under-test module (injected via the `CUT` define at build time) and the
+ * harness exposes `window.__harness.run(ctx)` for Playwright to call via
+ * `page.evaluate`.
+ *
+ * The code-under-test module path is supplied at build time so a consuming topic
+ * can point the harness at its own module without editing this file.
+ */
+import type { CodeUnderTest, RunContext, RunResult } from './contract.ts';
+import { captureEnv } from './contract.ts';
+
+// `__CUT_MODULE__` is replaced by esbuild's `define` with the real specifier.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - resolved at bundle time
+import cut from '__CUT_MODULE__';
+
+declare global {
+  interface Window {
+    __harness: {
+      env: () => ReturnType<typeof captureEnv>;
+      run: (ctx: RunContext) => Promise<RunResult>;
+      reset: () => Promise<void>;
+      ready: true;
+    };
+  }
+}
+
+const mod = cut as CodeUnderTest;
+
+window.__harness = {
+  env: () => captureEnv(),
+  async run(ctx: RunContext): Promise<RunResult> {
+    try {
+      return await mod.run(ctx);
+    } catch (e) {
+      return {
+        results: {},
+        timings: [],
+        errors: [String(e instanceof Error ? e.stack ?? e.message : e)],
+        env: captureEnv(),
+      };
+    }
+  },
+  async reset(): Promise<void> {
+    await mod.reset?.();
+  },
+  ready: true,
+};

package/dist/server.mjs

@@ -0,0 +1,75 @@
+/**
+ * server.mjs — a tiny static file server with a COOP/COEP toggle.
+ *
+ * Why a real server (not just Playwright `route`): cross-origin-isolation
+ * (`crossOriginIsolated === true`, required for SharedArrayBuffer and the OPFS
+ * `opfs` sync VFS) keys off *response headers* on the top-level document and its
+ * subresources. A real server setting the headers is the most faithful and
+ * reusable way; it also serves `.wasm` with the correct MIME, which some VFS
+ * loaders require.
+ *
+ * Toggle COOP/COEP with the `coi` option (default ON). With it OFF you can test
+ * the no-isolation paths (`opfs-sahpool`, plain IndexedDB) and measure what
+ * breaks when isolation is required.
+ */
+import http from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { extname, join, normalize } from 'node:path';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  // .wasm MUST be served as application/wasm or streaming instantiate / some
+  // VFS loaders reject it. This is a classic gotcha.
+  '.wasm': 'application/wasm',
+  '.map': 'application/json; charset=utf-8',
+};
+
+/**
+ * @param {object} opts
+ * @param {string} opts.root  directory to serve
+ * @param {boolean} [opts.coi] set COOP/COEP headers (cross-origin isolation)
+ * @returns {Promise<{url: string, port: number, close: () => Promise<void>}>}
+ */
+export async function startServer({ root, coi = true }) {
+  const server = http.createServer(async (req, res) => {
+    if (coi) {
+      // These two headers are what make `crossOriginIsolated === true`.
+      res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+      res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+      // CORP so same-origin subresources load under COEP: require-corp.
+      res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+    }
+    try {
+      const urlPath = decodeURIComponent((req.url ?? '/').split('?')[0]);
+      let rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, '');
+      if (rel === '/' || rel === '\\' || rel === '') rel = '/index.html';
+      const file = join(root, rel);
+      const s = await stat(file).catch(() => null);
+      if (!s || !s.isFile()) {
+        res.statusCode = 404;
+        res.end('not found: ' + rel);
+        return;
+      }
+      const body = await readFile(file);
+      res.setHeader('Content-Type', MIME[extname(file)] ?? 'application/octet-stream');
+      res.statusCode = 200;
+      res.end(body);
+    } catch (e) {
+      res.statusCode = 500;
+      res.end(String(e));
+    }
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    port,
+    close: () => new Promise((r) => server.close(() => r(undefined))),
+  };
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "playwright-browser-harness",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Playwright harness that bundles your code, serves it under a COOP/COEP-toggleable server, drives it in a real browser, and returns structured results/timings — for testing real browser-storage persistence (IndexedDB/OPFS), cross-origin isolation, Workers, and perf that Node can't fake. Importable machinery + a tiny `init` CLI for the per-project files.",
+  "license": "MIT",
+  "author": "Ronan Sandford (https://github.com/wighawag)",
+  "homepage": "https://github.com/wighawag/playwright-browser-harness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wighawag/playwright-browser-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wighawag/playwright-browser-harness/issues"
+  },
+  "bin": {
+    "playwright-browser-harness": "./bin/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/driver.d.ts",
+      "default": "./dist/driver.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.ts",
+      "default": "./dist/contract.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "node build.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0",
+    "esbuild": ">=0.20.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@types/node": "^25.9.1",
+    "@playwright/test": "^1.60.0",
+    "esbuild": "^0.28.0"
+  },
+  "keywords": [
+    "playwright",
+    "browser",
+    "test-harness",
+    "esbuild",
+    "opfs",
+    "coop-coep",
+    "indexeddb",
+    "sqlite-wasm"
+  ],
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}

package/templates/cut.ts.tmpl

@@ -0,0 +1,73 @@
+/**
+ * cut.ts — YOUR code-under-test. This file is YOURS to edit (scaffolded by
+ * `playwright-browser-harness init`). It is BUNDLED INTO THE BROWSER by the harness's
+ * esbuild step and loaded behind `window.__harness`.
+ *
+ * Implement the `CodeUnderTest` contract: drive your store/logic, return a
+ * structured { results, timings, errors, env } the Node test asserts on.
+ *
+ * The contract is imported from the package (raw .ts, bundled by esbuild under
+ * `moduleResolution: bundler` + `allowImportingTsExtensions`).
+ */
+import type {CodeUnderTest, RunContext, RunResult} from 'playwright-browser-harness/contract';
+import {captureEnv, timed} from 'playwright-browser-harness/contract';
+
+const DB = 'my-store';
+const STORE = 'kv';
+
+function open(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB, 1);
+    req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function tx<T>(db: IDBDatabase, mode: IDBTransactionMode, fn: (s: IDBObjectStore) => IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const t = db.transaction(STORE, mode);
+    const r = fn(t.objectStore(STORE));
+    r.onsuccess = () => resolve(r.result);
+    r.onerror = () => reject(r.error);
+  });
+}
+
+const cut: CodeUnderTest = {
+  name: 'my-store',
+  async run(ctx: RunContext): Promise<RunResult> {
+    const timings: RunResult['timings'] = [];
+    const errors: string[] = [];
+    const results: Record<string, unknown> = {};
+    const N = Number(ctx.params.n ?? 100);
+
+    const db = await timed('open', timings, open);
+
+    if (ctx.phase === 'write' || ctx.phase === 'once') {
+      await timed('write', timings, async () => {
+        for (let i = 0; i < N; i++) await tx(db, 'readwrite', (s) => s.put({i, v: `val-${i}`}, i));
+        await tx(db, 'readwrite', (s) => s.put({count: N}, '__meta__'));
+      });
+      results.wrote = N;
+    }
+
+    if (ctx.phase === 'read' || ctx.phase === 'once') {
+      const meta = await tx<{count: number} | undefined>(db, 'readonly', (s) => s.get('__meta__'));
+      results.survived = Boolean(meta && meta.count === N);
+      results.metaCount = meta?.count ?? 0;
+    }
+
+    db.close();
+    return {results, timings, errors, env: captureEnv()};
+  },
+  async reset(): Promise<void> {
+    await new Promise<void>((resolve) => {
+      const req = indexedDB.deleteDatabase(DB);
+      req.onsuccess = () => resolve();
+      req.onerror = () => resolve();
+      req.onblocked = () => resolve();
+    });
+  },
+};
+
+export default cut;

package/templates/example.spec.ts.tmpl

@@ -0,0 +1,39 @@
+/**
+ * example.spec.ts — a starter Playwright test that mounts YOUR cut.ts in a real
+ * browser (scaffolded by `playwright-browser-harness init`). Edit freely.
+ *
+ * `mountHarness` is imported from the package; it owns bundling (esbuild),
+ * serving (COOP/COEP toggle), page load, and ferrying results across the bridge.
+ * You only point it at your `cut.ts` (and optional `worker.ts`).
+ */
+import {test, expect} from '@playwright/test';
+import {fileURLToPath} from 'node:url';
+import {dirname, resolve} from 'node:path';
+import {mountHarness} from 'playwright-browser-harness';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cut = resolve(here, './cut.ts');
+
+test('my store persists across reload (no COOP/COEP)', async ({page}) => {
+  const h = await mountHarness(page, {cut, coi: false});
+
+  const env = await h.env();
+  expect(env.crossOriginIsolated).toBe(false);
+
+  await h.reset();
+
+  const w = await h.run({phase: 'write', params: {n: 100}});
+  expect(w.errors).toEqual([]);
+  expect(w.results.wrote).toBe(100);
+
+  await h.reload();
+
+  const r = await h.run({phase: 'read', params: {n: 100}});
+  expect(r.errors).toEqual([]);
+  expect(r.results.survived).toBe(true);
+  expect(r.results.metaCount).toBe(100);
+
+  console.log(`[my-store] coi=${env.crossOriginIsolated} timings=${JSON.stringify(r.timings)}`);
+
+  await h.dispose();
+});

package/templates/playwright.config.ts.tmpl

@@ -0,0 +1,25 @@
+import {defineConfig, devices} from '@playwright/test';
+
+/**
+ * Scaffolded by `playwright-browser-harness init`.
+ *
+ * The harness brings up its OWN static server per test (COOP/COEP toggle), so
+ * there is NO Playwright `webServer` entry. Tests are TS — Playwright bundles its
+ * own TS loader.
+ *
+ * Chromium is the primary target (full OPFS + SharedArrayBuffer). Uncomment
+ * firefox/webkit to surface per-browser differences (some OPFS cases skip there;
+ * see the harness topic README gotcha table).
+ */
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: false, // OPFS + shared servers: keep determinism
+  workers: 1,
+  reporter: [['list']],
+  timeout: 60_000,
+  projects: [
+    {name: 'chromium', use: {...devices['Desktop Chrome']}},
+    // {name: 'firefox', use: {...devices['Desktop Firefox']}},
+    // {name: 'webkit', use: {...devices['Desktop Safari']}},
+  ],
+});