playwright-browser-harness 0.0.1 → 0.3.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 ask for the `'buffer'` Node polyfill (see
+[Explicit Node polyfills](#explicit-node-polyfills)):
+
+```bash
+pnpm add -D buffer   # only if you use nodePolyfills: ['buffer', ...]
+```
+
 ## 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,166 @@ 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).
+
+## Explicit Node polyfills
+
+Many web3 / crypto libraries (ethereumjs, tevm, and anything pulling in
+`readable-stream` / `safe-buffer`) transitively `import 'buffer'` and touch
+`process` / `global` / `events` / `stream`. esbuild's `platform:'browser'` will
+**not** resolve those, so the bundle fails with `Could not resolve "buffer"`.
+
+There is **no** catch-all preset. A named "web3" preset is a leaky abstraction:
+it would shim `buffer`/`process`/`global` but not `events`/`stream`/`util`, so
+you'd fall back to the `esbuild` escape-hatch anyway. Instead you **declare
+exactly what you need**.
+
+### `nodePolyfills?: ('buffer' | 'process' | 'global')[]` (default `[]`)
+
+The three Node builtins the harness can shim **itself**, with zero opinions.
+Each entry is a **self-contained** fragment — `['buffer']` shims ONLY buffer; it
+does **not** touch `process` or `global`. `[]` or omitted = nothing.
+
+| entry | what it does |
+|---|---|
+| `'buffer'`  | alias `buffer` / `node:buffer` → the [`buffer`](https://www.npmjs.com/package/buffer) npm package, and inject a `Buffer` global (also assigned onto `globalThis`). Requires the optional `buffer` peer dep (`pnpm add -D buffer`). |
+| `'process'` | inject a minimal `process` stub: `{env:{}, browser:true, version:'', nextTick}`. |
+| `'global'`  | set `define: { global: 'globalThis' }`. |
+
+**Anything beyond these three** (`events`, `stream`, `util`, `crypto`, …) is the
+consumer's job via the [`esbuild`](#esbuild-escape-hatch--esbuild--plugins-inject-define-alias-loader-external-tsconfig-)
+pass-through below.
+
+#### Copy-paste recipe: ethereumjs / tevm
+
+A typical web3 EVM tree needs all three builtins **plus** `events`/`stream`
+aliased through the escape hatch:
+
+```ts
+const h = await mountHarness(page, {
+  cut,
+  coi: false,                              // pure-compute EVM → no SharedArrayBuffer needed
+  nodePolyfills: ['buffer', 'process', 'global'], // the harness's three builtins
+  esbuild: {
+    // everything the harness intentionally does NOT preset:
+    alias: {events: 'events', stream: 'stream-browserify'},
+  },
+});
+```
+
+```bash
+pnpm add -D buffer events stream-browserify
+```
+
+> **Migrating from 0.2.0** — `nodePolyfills` shipped in 0.2.0 as `true | 'web3'`.
+> That form was **removed** (clean break; 0.2.0 had ≈no users). Replace
+> `true` / `'web3'` with `['buffer', 'process', 'global']`.
+
+### 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 (the chosen builtins, 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 |
+
+#### Doing it entirely by hand (no `nodePolyfills`)
+
+`nodePolyfills` is just sugar for these three fragments. If you'd rather not use
+it at all (e.g. you want one custom shim module), alias `buffer` to the npm
+package and inject a `Buffer`/`process` shim purely 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,131 @@ import { existsSync } from 'node:fs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Explicit, composable Node-builtin polyfill fragments.
+ *
+ * There is intentionally NO catch-all "web3" preset: a named preset is a leaky
+ * abstraction — it would shim `buffer`/`process`/`global` but not
+ * `events`/`stream`/`util`/`crypto`, so consumers fall back to the `esbuild`
+ * escape-hatch anyway. Instead the harness exposes exactly the three builtins it
+ * can shim with zero opinions, and each maps to a self-contained fragment:
+ *
+ *   - 'buffer'  → alias `buffer`/`node:buffer` to the `buffer` npm package +
+ *                 inject a `Buffer` shim that also assigns `globalThis.Buffer`.
+ *   - 'process' → inject a minimal `process` stub `{env,browser,version,nextTick}`.
+ *   - 'global'  → define `{ global: 'globalThis' }`.
+ *
+ * Anything else (`events`, `stream`, `util`, `crypto`, …) is the consumer's job
+ * via the `esbuild: { alias, inject, define, plugins }` pass-through.
+ *
+ * Each helper returns an esbuild *fragment* (`{alias?, inject?, define?}`) so a
+ * consumer can compose them with their own esbuild opts. `buffer` is an
+ * optional/peer dependency: the consumer installs it when they opt into the
+ * `'buffer'` polyfill.
+ *
+ * @typedef {'buffer'|'process'|'global'} NodePolyfill
+ */
+
+/**
+ * Build a single Node-polyfill fragment by name. Self-contained: passing
+ * `'buffer'` shims ONLY buffer, etc. Unknown names throw with a clear message.
+ *
+ * @param {NodePolyfill} name which builtin to shim
+ * @param {string} outdir directory to write any generated shim modules into
+ * @returns {Promise<{alias?: Record<string,string>, inject?: string[], define?: Record<string,string>}>}
+ */
+export async function nodePolyfill(name, outdir) {
+  if (name === 'buffer') {
+    // Resolve the `buffer` npm package from the consumer's install via its bare
+    // specifier so esbuild aliases `buffer`/`node:buffer` to it. (We don't
+    // hard-require it here — esbuild surfaces a clear error if the consumer
+    // asked for the 'buffer' polyfill without installing `buffer`.)
+    const bufferPkg = 'buffer';
+    // 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],
+    };
+  }
+
+  if (name === 'process') {
+    // 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 & co.
+    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'),
+    );
+    return { inject: [procShim] };
+  }
+
+  if (name === 'global') {
+    return { define: { global: 'globalThis' } };
+  }
+
+  throw new Error(
+    `nodePolyfill: unknown polyfill ${JSON.stringify(name)} — valid values are 'buffer', 'process', 'global'.`,
+  );
+}
+
+/**
+ * The set of builtins the harness can shim itself, as a reusable/testable map of
+ * `name → (outdir) => fragment`. Exposed so a consumer can compose individual
+ * fragments with their own esbuild opts without going through `buildBundle`.
+ *
+ * @type {Record<NodePolyfill, (outdir: string) => Promise<{alias?: Record<string,string>, inject?: string[], define?: Record<string,string>}>>}
+ */
+export const nodePolyfills = {
+  buffer: (outdir) => nodePolyfill('buffer', outdir),
+  process: (outdir) => nodePolyfill('process', outdir),
+  global: (outdir) => nodePolyfill('global', outdir),
+};
+
+/**
+ * Compose the requested Node-polyfill fragments into a single
+ * `{alias, inject, define}` bundle. Order-stable; later entries' alias/define
+ * keys win on clash (none do today since the three fragments are disjoint).
+ *
+ * @param {NodePolyfill[]} names
+ * @param {string} outdir
+ * @returns {Promise<{alias: Record<string,string>, inject: string[], define: Record<string,string>}>}
+ */
+async function composeNodePolyfills(names, outdir) {
+  const out = { alias: {}, inject: [], define: {} };
+  for (const name of names) {
+    const frag = await nodePolyfill(name, outdir);
+    if (frag.alias) Object.assign(out.alias, frag.alias);
+    if (frag.inject) out.inject.push(...frag.inject);
+    if (frag.define) Object.assign(out.define, frag.define);
+  }
+  return out;
+}
+
 /**
  * @param {object} opts
  * @param {string} opts.cut        absolute path to the code-under-test module
@@ -31,14 +156,74 @@ 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 {Array<'buffer'|'process'|'global'>} [opts.nodePolyfills] explicit,
+ *   composable list of Node builtins the harness shims itself. `['buffer']`
+ *   shims ONLY buffer; `[]` or omitted = nothing. Each entry is self-contained:
+ *   'buffer' aliases `buffer`/`node:buffer` + injects a `Buffer` global,
+ *   'process' injects a minimal `process` stub, 'global' defines
+ *   `{global:'globalThis'}`. There is NO catch-all preset; everything beyond
+ *   these three (events, stream, util, crypto, …) goes through `opts.esbuild`.
+ * @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 = [],
+  esbuild: esbuildOpts = {},
+}) {
+  if (!Array.isArray(nodePolyfills)) {
+    throw new TypeError(
+      `buildBundle: \`nodePolyfills\` must be an array of 'buffer' | 'process' | 'global' ` +
+        `(got ${JSON.stringify(nodePolyfills)}). The 0.2.0 \`true\`/'web3' form was removed; ` +
+        `migrate to e.g. ['buffer','process','global'].`,
+    );
+  }
   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 }));
+    },
+  };
+
+  // Compose the explicitly-requested Node-builtin polyfill fragments (default
+  // none). Produces alias/inject/define merged UNDER the consumer's explicit
+  // esbuild opts (so the consumer can still override any specific key).
+  const preset =
+    nodePolyfills.length > 0
+      ? await composeNodePolyfills(nodePolyfills, 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 +232,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 → polyfills → 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,67 @@ 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). */
+    /**
+     * Explicit, composable Node-builtin polyfills. Declare exactly what your
+     * code-under-test needs — there is **no** catch-all preset. Default `[]`
+     * (nothing); omitted is the same as `[]`.
+     *
+     * The three builtins the harness can shim itself (with zero opinions):
+     *   - `'buffer'`  — alias `buffer` / `node:buffer` to the [`buffer`] npm
+     *     package and inject a `Buffer` global (also assigned onto `globalThis`).
+     *     Requires the optional `buffer` peer dependency to be installed.
+     *   - `'process'` — inject a minimal `process` stub
+     *     (`{ env: {}, browser: true, version: '', nextTick }`).
+     *   - `'global'`  — set `define: { global: 'globalThis' }`.
+     *
+     * Each entry is self-contained: `['buffer']` shims ONLY buffer and does NOT
+     * touch `process` or `global`. Anything beyond these three (`events`,
+     * `stream`, `util`, `crypto`, …) is your job via `esbuild.{alias,inject,
+     * define,plugins}` below.
+     *
+     * web3 / crypto trees (ethereumjs, tevm, anything pulling `readable-stream` /
+     * `safe-buffer`) typically want `['buffer','process','global']` plus an
+     * `esbuild.alias` for `events`/`stream`. See README "Explicit Node polyfills".
+     *
+     * **Migration from 0.2.0:** the old `true` / `'web3'` form was removed (clean
+     * break — 0.2.0 had ~no users). Replace `true`/`'web3'` with
+     * `['buffer','process','global']`.
+     *
+     * [`buffer`]: https://www.npmjs.com/package/buffer
+     */
+    nodePolyfills?: Array<'buffer' | 'process' | 'global'>;
+    /**
+     * 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
+     * extra builtins (e.g. `alias: { events: 'events', stream: 'stream-browserify' }`).
+     */
+    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 +142,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 ?? [],
+            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.3.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",