playwright-browser-harness 0.0.1 → 0.2.0

package/README.md

@@ -21,6 +21,14 @@ pnpm exec playwright install chromium
 their versions. `@sqlite.org/sqlite-wasm` is *not* a dependency; it is only a
 fixture/consumer dep when you test wasm-SQLite.
 
+`buffer` is an **optional peerDependency** — only needed (and only installed) when
+you bundle web3 / Node-dependency-heavy code with `nodePolyfills` (see
+[Bundling web3 / Node-dependency-heavy code](#bundling-web3--node-dependency-heavy-code)):
+
+```bash
+pnpm add -D buffer   # only if you use nodePolyfills
+```
+
 ## tsconfig (required)
 
 ```jsonc
@@ -41,6 +49,28 @@ pnpm exec playwright test
 npx playwright-browser-harness update tests      # report drift of scaffolded files vs current templates
 ```
 
+## Named exports
+
+The package's `.` entry exports the high-level driver plus the lower-level
+building blocks, all as documented named exports:
+
+```ts
+import {mountHarness, buildBundle, startServer} from 'playwright-browser-harness';
+```
+
+- `mountHarness(page, opts)` — the usual entry point (bundle + serve + drive).
+- `buildBundle(opts)` — esbuild-bundle a `cut` (+ optional worker) to an `outdir`.
+- `startServer({root, coi})` — the tiny COOP/COEP-toggleable static server.
+
+Use `buildBundle` / `startServer` directly when you want to drive bundling and
+serving yourself (e.g. a custom Playwright global-setup) instead of `prebuilt`.
+
+The in-page glue is importable too, so your **own** bundler can include it:
+
+- `playwright-browser-harness/contract` — raw `.ts` contract (`captureEnv`, `timed`, types).
+- `playwright-browser-harness/page-entry` — raw `.ts` page glue (for esbuild/bundler consumers).
+- `playwright-browser-harness/page-bootstrap` — plain `.js` page glue (loadable directly in the browser).
+
 ## Use
 
 ```ts
@@ -66,7 +96,147 @@ test('persists', async ({page}) => {
 });
 ```
 
-`MountOptions`: `cut` (required), `coi` (default `true`), `worker`, `wasmDirs`,
-`assets`, `prebuilt`. See the
+`MountOptions`: `cut` (esbuild path) **or** `entry`/`noBundle` (prebuilt JS, no
+esbuild) **or** `prebuilt` (prebuilt dir); `coi` (default `true`), `worker`,
+`wasmDirs`, `assets`, plus the bundling escape-hatches `nodePolyfills` and
+`esbuild` (see below).
+
+## Bundling web3 / Node-dependency-heavy code
+
+Many web3 / crypto libraries (ethereumjs, tevm, and anything pulling in
+`readable-stream` / `safe-buffer`) transitively `import 'buffer'` and touch
+`process` / `global`. esbuild's `platform:'browser'` will **not** resolve those,
+so the bundle fails with `Could not resolve "buffer"`. The harness gives you two
+opt-in escape-hatches, both **off/empty by default** (existing consumers are
+unchanged):
+
+```ts
+const h = await mountHarness(page, {
+  cut,
+  coi: false,                 // pure-compute EVM → no SharedArrayBuffer needed
+  nodePolyfills: 'web3',       // alias buffer, inject Buffer, shim process, define global
+  esbuild: {                   // pass-through merged into the internal esbuild build
+    alias: {events: 'events', stream: 'stream-browserify'}, // any extra builtins
+  },
+});
+```
+
+### `nodePolyfills?: boolean | 'web3'` (default `false`)
+
+When enabled it:
+
+- aliases `buffer` / `node:buffer` → the [`buffer`](https://www.npmjs.com/package/buffer) npm package,
+- injects a `Buffer` global (also assigned onto `globalThis`),
+- provides a minimal `process` stub: `{env:{}, browser:true, version:'', nextTick}`,
+- sets `define: { global: 'globalThis' }`.
+
+`true` and `'web3'` are equivalent today (the string leaves room for future
+presets). **Install the optional `buffer` peer dep** when you opt in
+(`pnpm add -D buffer`). web3 / crypto libraries usually need this; plain DOM /
+storage code does not.
+
+### esbuild escape hatch — `esbuild?: { plugins?, inject?, define?, alias?, loader?, external?, tsconfig? }`
+
+A pass-through merged into the harness's internal esbuild build, so a consumer
+whose code-under-test needs a plugin/alias/define/loader no longer has to **fork
+the bundler** (replicating the page-entry glue and mounting via `prebuilt`).
+**Consumer values take precedence** (objects shallow-merged with the consumer
+winning; arrays concatenated **after** the built-ins). The harness's own
+`__CUT_MODULE__` resolve plugin, the page-entry entry point, and the
+`.wasm`→`copy` loader **always remain**:
+
+| key | merge behaviour |
+|---|---|
+| `plugins` | concatenated **after** the built-in `__CUT_MODULE__` resolver |
+| `inject` | concatenated after the `nodePolyfills` injects (if any) |
+| `define` / `alias` | shallow-merged, **consumer key wins** |
+| `loader` | merged **over** `{'.wasm':'copy'}` (e.g. add `{'.svg':'dataurl'}`) |
+| `external` | as given |
+| `tsconfig` | path to a tsconfig esbuild should honour |
+
+#### Node polyfills recipe (the common case)
+
+The quickest path is the `nodePolyfills` preset above. To do it by hand (or to
+extend it), alias `buffer` to the npm package and inject a `Buffer`/`process`
+shim via the escape hatch:
+
+```ts
+const h = await mountHarness(page, {
+  cut,
+  coi: false,
+  esbuild: {
+    alias: {buffer: 'buffer'},          // the npm `buffer` package
+    inject: [resolve(__dirname, 'node-shim.js')], // exports Buffer; sets globalThis.Buffer/process
+    define: {global: 'globalThis'},
+  },
+});
+```
+
+```js
+// node-shim.js
+import {Buffer} from 'buffer';
+if (!globalThis.Buffer) globalThis.Buffer = Buffer;
+if (!globalThis.process) globalThis.process = {env: {}, browser: true, version: '', nextTick: (cb, ...a) => Promise.resolve().then(() => cb(...a))};
+export {Buffer};
+```
+
+## Testing a prebuilt artifact (no esbuild)
+
+The default path re-bundles your **source** with the harness's esbuild. To
+exercise the **exact bytes your own build emitted** (tsc / tsup / rollup →
+`dist/`), skip esbuild entirely:
+
+### `entry` / `noBundle` — wrap one prebuilt JS module
+
+Point the harness at an already-built `.js` module that default-exports a
+`CodeUnderTest`. The harness serves it **verbatim** (with its sibling `.map`,
+if present) behind a tiny plain-JS loader — no esbuild, no re-bundle, so source
+maps point at your `dist/`, not a harness re-bundle:
+
+```ts
+import {mountHarness} from 'playwright-browser-harness';
+
+// your own build already produced dist/cut.js (+ dist/cut.js.map)
+const h = await mountHarness(page, {entry: resolve('dist/cut.js'), coi: false});
+// equivalently: { cut: resolve('dist/cut.js'), noBundle: true }
+const w = await h.run({phase: 'write', params: {n: 100}});
+await h.reload();
+const r = await h.run({phase: 'read', params: {n: 100}});
+```
+
+The served directory contains `__cut.js` (your module, verbatim), `contract.js`
+(the harness's compiled glue), `bootstrap.js` (the no-esbuild page glue), and
+`index.html`.
+
+### `prebuilt` — serve a fully-built directory
+
+If your own bundler already produced a complete directory (its own `index.html`
+that boots the harness and sets `window.__harness`), serve it as-is. The glue is
+importable so your bundler can include it:
+`playwright-browser-harness/page-entry` (raw `.ts`, for bundler consumers) or
+`playwright-browser-harness/page-bootstrap` (plain `.js`, loadable directly).
+
+```ts
+// harness starts its own COOP/COEP server for the dir:
+const h = await mountHarness(page, {prebuilt: {outdir: resolve('dist/site')}, coi: false});
+// or reuse an already-running server (harness won't start/stop one):
+const h2 = await mountHarness(page, {prebuilt: {outdir, serverUrl: 'http://127.0.0.1:5173'}});
+```
+
+## COOP/COEP (`coi`) vs your wasm executor
+
+`coi` toggles cross-origin isolation (COOP/COEP response headers →
+`crossOriginIsolated === true`, the precondition for `SharedArrayBuffer`).
+Match it to what your wasm needs:
+
+| Workload | `coi` | Why |
+|---|---|---|
+| EVM / pure-compute wasm (ethereumjs, tevm, single-threaded wasm) | `false` | No `SharedArrayBuffer`; isolation is pure overhead and can complicate loading. |
+| Threaded wasm needing `SharedArrayBuffer` (wasm threads, OPFS sync VFS, sqlite-wasm `opfs`) | `true` | `SharedArrayBuffer` / the sync OPFS VFS require `crossOriginIsolated`. |
+| Plain IndexedDB / `opfs-sahpool` | `false` | Works without isolation; flip `true` only to test the isolated path. |
+
+Default is `coi:true`; **EVM / pure-compute executors want `coi:false`**.
+
+See the
 [`playwright-browser-test-harness` research topic](../README.md) for the full
 architecture, gotchas, and per-browser OPFS matrix.

package/dist/build.mjs

@@ -22,6 +22,74 @@ import { existsSync } from 'node:fs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Build the `nodePolyfills` preset (esbuild fragments) for browser bundles of
+ * web3/crypto code whose dependency trees reach for Node builtins.
+ *
+ * Many EVM / crypto libraries (ethereumjs, tevm, anything pulling
+ * `readable-stream`/`safe-buffer`) transitively `import 'buffer'` and touch
+ * `process` / `global`, which esbuild's `platform:'browser'` will NOT resolve —
+ * the bundle fails with `Could not resolve "buffer"`. This opt-in preset:
+ *   - aliases `buffer` / `node:buffer` to the `buffer` npm package,
+ *   - injects a `Buffer` global (so `Buffer.from(...)` works without an import),
+ *   - shims a minimal `process` (`{env,browser,version,nextTick}`),
+ *   - defines `global` → `globalThis`.
+ *
+ * `buffer` is an optional/peer dependency: the consumer installs it when they
+ * opt in (and the harness's own ethereumjs fixture pulls it in for the test).
+ *
+ * @param {string} outdir directory to write the generated `process` shim into
+ * @returns {Promise<{alias: Record<string,string>, inject: string[], define: Record<string,string>}>}
+ */
+async function nodePolyfillsPreset(outdir) {
+  // Resolve the `buffer` npm package from the consumer's install. We resolve
+  // the *bare specifier* so esbuild aliases `buffer`/`node:buffer` to it.
+  // (We don't hard-require it here — esbuild will surface a clear error if the
+  // consumer enabled nodePolyfills without installing `buffer`.)
+  const bufferPkg = 'buffer';
+
+  // A tiny `process` shim written next to the bundle and injected as a global.
+  // Kept minimal on purpose: env bag, browser flag, empty version, and a
+  // microtask-based nextTick — enough for readable-stream/safe-buffer & friends.
+  const procShim = join(outdir, '__process-shim.js');
+  await writeFile(
+    procShim,
+    [
+      'const process = {',
+      '  env: {},',
+      '  browser: true,',
+      "  version: '',",
+      '  nextTick: (cb, ...args) => Promise.resolve().then(() => cb(...args)),',
+      '};',
+      'export { process };',
+      'export default process;',
+    ].join('\n'),
+  );
+
+  // A tiny module that re-exports `Buffer` from the `buffer` package so esbuild
+  // can `inject` it as the `Buffer` global. We ALSO assign it onto `globalThis`
+  // so libraries that reach for `globalThis.Buffer` / `window.Buffer` at runtime
+  // (not just an unqualified `Buffer` identifier) find it too. GOTCHA: esbuild's
+  // `inject` only provides a top-level *binding* in modules that reference the
+  // name — it does not set a real global — so this explicit assignment is what
+  // makes `globalThis.Buffer` truthy in-page.
+  const bufShim = join(outdir, '__buffer-shim.js');
+  await writeFile(
+    bufShim,
+    [
+      "import { Buffer } from 'buffer';",
+      'if (typeof globalThis !== "undefined" && !globalThis.Buffer) globalThis.Buffer = Buffer;',
+      'export { Buffer };',
+    ].join('\n'),
+  );
+
+  return {
+    alias: { buffer: bufferPkg, 'node:buffer': bufferPkg },
+    inject: [bufShim, procShim],
+    define: { global: 'globalThis' },
+  };
+}
+
 /**
  * @param {object} opts
  * @param {string} opts.cut        absolute path to the code-under-test module
@@ -31,14 +99,61 @@ const here = dirname(fileURLToPath(import.meta.url));
  * @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).
+ * @param {boolean|'web3'} [opts.nodePolyfills] opt-in Node-builtin polyfills for
+ *   web3/crypto code (aliases `buffer`/`node:buffer`, injects `Buffer`, shims
+ *   `process`, defines `global`). Default off. `true` and `'web3'` are
+ *   equivalent today (the string leaves room for future presets).
+ * @param {object} [opts.esbuild] esbuild pass-through merged into the internal
+ *   build. Consumer values take precedence; arrays are concatenated AFTER the
+ *   built-ins so the `__CUT_MODULE__` resolver, the page-entry entry point, and
+ *   the `.wasm` copy loader always remain.
+ * @param {import('esbuild').Plugin[]} [opts.esbuild.plugins]
+ * @param {string[]} [opts.esbuild.inject]
+ * @param {Record<string,string>} [opts.esbuild.define]
+ * @param {Record<string,string>} [opts.esbuild.alias]
+ * @param {Record<string,string>} [opts.esbuild.loader] merged OVER `{'.wasm':'copy'}`
+ * @param {string[]} [opts.esbuild.external]
+ * @param {string} [opts.esbuild.tsconfig] path to a tsconfig esbuild should honour
  */
-export async function buildBundle({ cut, outdir, worker, wasmDirs = [], assets = [] }) {
+export async function buildBundle({
+  cut,
+  outdir,
+  worker,
+  wasmDirs = [],
+  assets = [],
+  nodePolyfills = false,
+  esbuild: esbuildOpts = {},
+}) {
   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' });
 
+  // The built-in __CUT_MODULE__ resolver plugin must ALWAYS run, even when the
+  // consumer supplies their own plugins (concat, never clobber).
+  const cutResolver = {
+    name: 'resolve-cut',
+    setup(b) {
+      b.onResolve({ filter: /^__CUT_MODULE__$/ }, () => ({ path: cut }));
+    },
+  };
+
+  // Opt-in Node-builtin polyfill preset (default off). Produces alias/inject/
+  // define fragments that are merged UNDER the consumer's explicit esbuild opts
+  // (so the consumer can still override any specific key).
+  const preset = nodePolyfills ? await nodePolyfillsPreset(outdir) : null;
+
+  const {
+    plugins: userPlugins = [],
+    inject: userInject = [],
+    define: userDefine = {},
+    alias: userAlias = {},
+    loader: userLoader = {},
+    external: userExternal = [],
+    tsconfig: userTsconfig,
+  } = esbuildOpts;
+
   await esbuild.build({
     entryPoints,
     outdir,
@@ -47,18 +162,19 @@ export async function buildBundle({ cut, outdir, worker, wasmDirs = [], assets =
     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 }));
-        },
-      },
-    ],
+    // Merge order: built-ins → preset → consumer. Consumer wins on key clashes
+    // (define/alias/loader) and runs last (plugins). Arrays are concatenated.
+    plugins: [cutResolver, ...userPlugins],
+    inject: [...(preset?.inject ?? []), ...userInject],
+    define: { ...(preset?.define ?? {}), ...userDefine },
+    alias: { ...(preset?.alias ?? {}), ...userAlias },
+    external: [...userExternal],
+    ...(userTsconfig ? { tsconfig: userTsconfig } : {}),
     // 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' },
+    // Consumer loaders merge OVER this (e.g. add `.svg`), but `.wasm` stays copy
+    // unless the consumer deliberately overrides that exact key.
+    loader: { '.wasm': 'copy', ...userLoader },
   });
 
   // Copy wasm assets (e.g. @sqlite.org/sqlite-wasm's sqlite3.wasm) next to JS.

package/dist/driver.d.ts

@@ -27,11 +27,38 @@
  * env assertions, and ferrying `{results,timings,errors,env}` across the bridge.
  */
 import type { Page } from '@playwright/test';
+import { buildBundle } from './build.mjs';
+import { startServer } from './server.mjs';
 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;
+    /**
+     * Absolute path to the code-under-test module (default-exports CodeUnderTest).
+     *
+     * - **Default (esbuild) path:** point at your SOURCE module; the harness
+     *   esbuild-bundles it with the page-entry glue.
+     * - **Prebuilt-entry path** (`noBundle: true` or use `entry`): point at an
+     *   ALREADY-BUILT `.js` module (your own tsc/tsup/rollup output). The harness
+     *   serves it verbatim behind a tiny no-esbuild loader — you exercise the
+     *   exact bytes your build emitted.
+     *
+     * Optional when `entry` or `prebuilt` is supplied.
+     */
+    cut?: string;
+    /**
+     * Absolute path to an ALREADY-BUILT `.js` CodeUnderTest module to load with
+     * **no esbuild**. Equivalent to `{ cut, noBundle: true }`; provided as a
+     * clearer name for the prebuilt-artifact path. The file is copied verbatim
+     * (with its sibling `.map` if present) and wrapped by the harness's plain-JS
+     * page-bootstrap glue. Mutually exclusive with the esbuild path.
+     */
+    entry?: string;
+    /**
+     * Skip esbuild entirely and treat `cut`/`entry` as a prebuilt `.js` module
+     * (see `entry`). Default `false` (the esbuild path). `worker`/`nodePolyfills`/
+     * `esbuild` options are ignored in this mode.
+     */
+    noBundle?: boolean;
     /** Serve with COOP/COEP (cross-origin isolation). Default true. */
     coi?: boolean;
     /** Optional absolute path to a Web Worker entry to bundle alongside. */
@@ -41,10 +68,50 @@ export interface MountOptions {
     /** 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). */
+    /**
+     * Opt-in Node-builtin polyfills for browser bundles of web3 / crypto code
+     * (ethereumjs, tevm, anything pulling `readable-stream` / `safe-buffer`).
+     * Default **off** — existing consumers are unaffected.
+     *
+     * When enabled it aliases `buffer` / `node:buffer` to the `buffer` npm
+     * package, injects a `Buffer` global, shims a minimal `process`
+     * (`{ env: {}, browser: true, version: '', nextTick }`), and sets
+     * `define: { global: 'globalThis' }`. Requires the optional `buffer`
+     * dependency to be installed. `true` and `'web3'` are equivalent today.
+     */
+    nodePolyfills?: boolean | 'web3';
+    /**
+     * esbuild pass-through merged into the harness's internal browser build.
+     * Consumer values take precedence; arrays are concatenated AFTER the
+     * built-ins, so the `__CUT_MODULE__` resolver and the `.wasm` copy loader
+     * always remain. Combine with `nodePolyfills` for web3 code that still needs
+     * an extra alias/define.
+     */
+    esbuild?: {
+        plugins?: import('esbuild').Plugin[];
+        inject?: string[];
+        define?: Record<string, string>;
+        alias?: Record<string, string>;
+        /** Merged OVER the built-in `{'.wasm':'copy'}` loader. */
+        loader?: Record<string, import('esbuild').Loader>;
+        external?: string[];
+        /** Path to a tsconfig esbuild should honour while bundling. */
+        tsconfig?: string;
+    };
+    /**
+     * Serve a FULLY-prebuilt directory as-is (no esbuild, no glue injection). The
+     * directory must already contain an `index.html` that boots the harness and
+     * sets `window.__harness` (e.g. produced by a consumer's own bundler that
+     * imported `playwright-browser-harness/page-entry`).
+     *
+     * - `serverUrl` omitted → the harness starts its own COOP/COEP server for
+     *   `outdir` (honouring `coi`/`headers`/`mime`).
+     * - `serverUrl` provided → the harness reuses that already-running server and
+     *   does not start or stop one.
+     */
     prebuilt?: {
         outdir: string;
-        serverUrl: string;
+        serverUrl?: string;
     };
 }
 export interface MountedHarness {
@@ -58,3 +125,4 @@ export interface MountedHarness {
 }
 export declare function mountHarness(page: Page, opts: MountOptions): Promise<MountedHarness>;
 export { here as harnessDir };
+export { buildBundle, startServer };

package/dist/driver.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { mkdtemp } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { mkdtemp, mkdir, copyFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 // build.mjs / server.mjs are JS ESM siblings; imported at runtime by Playwright.
 // @ts-ignore - .mjs has no types
@@ -12,11 +13,33 @@ export async function mountHarness(page, opts) {
     let outdir;
     let serverUrl;
     let close;
+    const entry = opts.entry ?? (opts.noBundle ? opts.cut : undefined);
     if (opts.prebuilt) {
+        // (b) Serve a fully-prebuilt directory as-is. No esbuild, no glue.
         outdir = opts.prebuilt.outdir;
-        serverUrl = opts.prebuilt.serverUrl;
+        if (opts.prebuilt.serverUrl) {
+            serverUrl = opts.prebuilt.serverUrl;
+        }
+        else {
+            const srv = await startServer({ root: outdir, coi: opts.coi ?? true });
+            serverUrl = srv.url;
+            close = srv.close;
+        }
+    }
+    else if (entry) {
+        // (a) Prebuilt-entry path: wrap an ALREADY-BUILT .js module with the plain-JS
+        //     page-bootstrap glue — NO esbuild. Exercises the exact built bytes.
+        outdir = await mkdtemp(join(tmpdir(), 'harness-'));
+        await wrapPrebuiltEntry({ entry, outdir, assets: opts.assets ?? [] });
+        const srv = await startServer({ root: outdir, coi: opts.coi ?? true });
+        serverUrl = srv.url;
+        close = srv.close;
     }
     else {
+        // Default esbuild path.
+        if (!opts.cut) {
+            throw new Error('mountHarness: provide `cut` (esbuild path), `entry`/`noBundle` (prebuilt JS), or `prebuilt` (prebuilt dir).');
+        }
         outdir = await mkdtemp(join(tmpdir(), 'harness-'));
         await buildBundle({
             cut: opts.cut,
@@ -24,6 +47,8 @@ export async function mountHarness(page, opts) {
             worker: opts.worker,
             wasmDirs: opts.wasmDirs ?? [],
             assets: opts.assets ?? [],
+            nodePolyfills: opts.nodePolyfills ?? false,
+            esbuild: opts.esbuild ?? {},
         });
         const srv = await startServer({ root: outdir, coi: opts.coi ?? true });
         serverUrl = srv.url;
@@ -50,4 +75,51 @@ async function loadAndWait(page, url) {
     await page.goto(url, { waitUntil: 'load' });
     await page.waitForFunction(() => window.__harness?.ready === true);
 }
+/**
+ * Prebuilt-entry path: serve an ALREADY-BUILT `.js` CodeUnderTest module behind
+ * the harness's plain-JS page-bootstrap glue, with **no esbuild**.
+ *
+ * It writes a fresh `outdir` containing:
+ *   - `__cut.js`        the consumer's built module, copied verbatim (+ `.map`),
+ *   - `contract.js`     the harness's compiled contract glue (`captureEnv`),
+ *   - `bootstrap.js`    the page-bootstrap glue (imports the two above, sets
+ *                       `window.__harness`),
+ *   - `index.html`      a `type=module` shell loading `./bootstrap.js`.
+ *
+ * Because nothing is re-bundled, the served `__cut.js` is byte-for-byte the file
+ * your build produced — sourcemaps/line numbers point at YOUR dist, not a
+ * harness re-bundle.
+ */
+async function wrapPrebuiltEntry({ entry, outdir, assets, }) {
+    await mkdir(outdir, { recursive: true });
+    // Copy the consumer's built module verbatim as `__cut.js` (+ sibling sourcemap
+    // if present, so source maps keep resolving).
+    await copyFile(entry, join(outdir, '__cut.js'));
+    const map = entry + '.map';
+    if (existsSync(map))
+        await copyFile(map, join(outdir, '__cut.js.map'));
+    // Copy the harness's compiled glue siblings (live next to this driver.js in
+    // dist/). These are plain JS the browser loads directly — no bundling.
+    await copyFile(join(here, 'contract.js'), join(outdir, 'contract.js'));
+    await copyFile(join(here, 'page-bootstrap.js'), join(outdir, 'bootstrap.js'));
+    // Copy any explicit assets verbatim (same semantics as the esbuild path).
+    for (const a of assets) {
+        if (!existsSync(a))
+            continue;
+        await copyFile(a, join(outdir, basename(a)));
+    }
+    const html = `<!doctype html>
+<html>
+  <head><meta charset="utf-8"><title>harness (prebuilt)</title></head>
+  <body>
+    <script type="module" src="./bootstrap.js"></script>
+  </body>
+</html>`;
+    await writeFile(join(outdir, 'index.html'), html);
+}
 export { here as harnessDir };
+// Re-export the lower-level building blocks as documented named exports so a
+// consumer can drive bundling/serving directly (e.g. a custom global-setup, or
+// re-implementing the mount flow with extra steps) without reaching into the
+// package's internal `.mjs` siblings.
+export { buildBundle, startServer };

package/dist/page-bootstrap.js

@@ -0,0 +1,45 @@
+/**
+ * page-bootstrap.js — the NO-ESBUILD in-page glue.
+ *
+ * This is the plain-JS sibling of `page-entry.ts`. Where `page-entry.ts` is
+ * BUNDLED by esbuild together with the code-under-test (the default path), this
+ * file is served VERBATIM to the browser and loaded as a native ES module. It
+ * imports two things by relative URL at runtime:
+ *
+ *   - `./__cut.js`        the consumer's ALREADY-BUILT CodeUnderTest module
+ *                         (their own tsc/tsup/rollup output, copied in as-is),
+ *   - `./contract.js`     the harness's compiled contract glue (`captureEnv`).
+ *
+ * It then exposes `window.__harness` exactly like `page-entry.ts` does, so the
+ * Node-side driver (`run`/`reset`/`env`/`reload`) is identical across both
+ * paths. The point: you exercise the EXACT bytes your build emitted — no
+ * re-bundling, no second esbuild pass, source maps point at your dist file.
+ *
+ * The two relative specifiers are rewritten by the harness when it writes the
+ * served directory (see driver.ts `wrapPrebuiltEntry`).
+ */
+import { captureEnv } from './contract.js';
+// The consumer's prebuilt CodeUnderTest module, copied into the served dir.
+import cut from './__cut.js';
+
+const mod = cut;
+
+window.__harness = {
+  env: () => captureEnv(),
+  async run(ctx) {
+    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() {
+    await mod.reset?.();
+  },
+  ready: true,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-browser-harness",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "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",
@@ -25,11 +25,19 @@
       "types": "./dist/contract.ts",
       "default": "./dist/contract.ts"
     },
+    "./page-entry": {
+      "types": "./dist/page-entry.ts",
+      "default": "./dist/page-entry.ts"
+    },
+    "./page-bootstrap": {
+      "default": "./dist/page-bootstrap.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
     "build": "node build.mjs",
-    "prepack": "node build.mjs"
+    "prepack": "node build.mjs",
+    "test": "playwright test"
   },
   "files": [
     "dist",
@@ -39,13 +47,26 @@
   ],
   "peerDependencies": {
     "@playwright/test": ">=1.40.0",
+    "buffer": ">=6.0.0",
     "esbuild": ">=0.20.0"
   },
+  "peerDependenciesMeta": {
+    "buffer": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "typescript": "^6.0.3",
-    "@types/node": "^25.9.1",
+    "@ethereumjs/common": "^4.4.0",
+    "@ethereumjs/evm": "^3.1.1",
+    "@ethereumjs/statemanager": "^2.4.0",
+    "@ethereumjs/util": "^9.1.0",
     "@playwright/test": "^1.60.0",
-    "esbuild": "^0.28.0"
+    "@types/node": "^25.9.1",
+    "buffer": "^6.0.3",
+    "esbuild": "^0.28.0",
+    "events": "^3.3.0",
+    "stream-browserify": "^3.0.0",
+    "typescript": "^6.0.3"
   },
   "keywords": [
     "playwright",