duckfn-docs-kit 0.2.0 → 0.3.0

package/dist/sql/runtime.d.ts

@@ -49,6 +49,26 @@ export type RuntimeState = 'idle' | 'loading' | 'ready' | 'error';
 export interface RuntimeOptions {
     /** Let `LOAD` accept an extension whose signature does not verify. */
     allowUnsignedExtensions?: boolean;
+    /**
+     * Serve the DuckDB-Wasm engine from explicit same-origin URLs instead of the
+     * jsDelivr CDN. Used by the offline SQL verifier (`sql/browserRunner`): the
+     * harness passes the locally-served `duckdb-*.wasm` / worker script so a CI
+     * run never reaches the network. When set, `#create()` skips
+     * `getJsDelivrBundles()`/`selectBundle()` and the cross-origin blob-worker
+     * wrapper (the worker is same-origin here, so it is constructed directly).
+     */
+    bundle?: LocalBundle;
+}
+/**
+ * A locally-served DuckDB-Wasm bundle: absolute same-origin URLs for the
+ * engine wasm and its worker script. `pthreadWorker` is only needed for the
+ * cross-origin-isolated (COI) bundle; the default non-COI `eh`/`mvp` bundles run
+ * single-threaded and leave it unset.
+ */
+export interface LocalBundle {
+    mainModule: string;
+    mainWorker: string;
+    pthreadWorker?: string;
 }
 /** Options for {@link DuckDBRuntime.loadExtension}. */
 export interface LoadExtensionOptions {

package/dist/sql/verify.d.ts

@@ -1,4 +1,4 @@
-import { type WasmPlatform } from './nodeRunner';
+import { type WasmPlatform } from './browserRunner';
 export interface VerifyOptions {
     /** Docs site root; defaults to the working directory. */
     siteDir?: string;
@@ -16,11 +16,10 @@ export interface VerifyOptions {
     /** Per-block timeout in milliseconds; a hang is reported instead of blocking CI. */
     timeoutMs?: number;
     /**
-     * Directory the blocks run in. Defaults to a fresh temporary directory that
-     * is removed afterwards: a block may `COPY … TO 'a.csv'`, and on Node
-     * DuckDB's file system is the real one, relative to the working directory.
+     * The browser executable that runs the blocks. Defaults to a detected
+     * Chrome/Edge; the `DFK_BROWSER` environment variable is the same override.
      */
-    workingDir?: string;
+    browser?: string;
     /** Write the full result list here as JSON. */
     reportFile?: string;
 }

package/dist/sql/verify.js

@@ -1,52 +1,39 @@
 import { collectRunnableSql as e, expectsError as t } from "./collect.js";
-import { WasmSqlRunner as n } from "./nodeRunner.js";
+import { BrowserSqlRunner as n } from "./browserRunner.js";
 import { join as r, resolve as i } from "node:path";
-import { mkdirSync as a, mkdtempSync as o, readdirSync as s, rmSync as c, statSync as l, writeFileSync as u } from "node:fs";
-import { tmpdir as d } from "node:os";
+import { readdirSync as a, statSync as o, writeFileSync as s } from "node:fs";
 //#region src/sql/verify.ts
-var f = ["docs", "i18n"], p = 3e4;
-async function m(t = {}) {
-	let n = i(t.siteDir ?? process.cwd()), s = e({
+var c = ["docs", "i18n"], l = 3e4;
+async function u(t = {}) {
+	let n = i(t.siteDir ?? process.cwd()), r = e({
 		siteDir: n,
-		contentDirs: t.contentDirs ?? v(n)
-	}), l = t.extension, f = l ? /^https?:\/\//i.test(l) ? l : i(l) : y(n), m = t.timeoutMs ?? p, g = t.workingDir ? i(t.workingDir) : o(r(d(), "duckfn-sql-verify-"));
-	a(g, { recursive: !0 });
-	let _ = process.cwd();
-	process.chdir(g);
-	let b;
-	try {
-		b = await h(s, f, t, m);
-	} finally {
-		process.chdir(_), t.workingDir || c(g, {
-			recursive: !0,
-			force: !0
-		});
-	}
-	let x = {
-		blocks: b,
-		asDeclared: b.filter((e) => e.outcome === "ok" || e.outcome === "error-as-expected"),
-		unexpected: b.filter((e) => e.outcome === "unexpected-error" || e.outcome === "unexpected-success")
+		contentDirs: t.contentDirs ?? m(n)
+	}), a = t.extension, o = await d(r, a ? /^https?:\/\//i.test(a) ? a : i(a) : h(n), t, t.timeoutMs ?? l), c = {
+		blocks: o,
+		asDeclared: o.filter((e) => e.outcome === "ok" || e.outcome === "error-as-expected"),
+		unexpected: o.filter((e) => e.outcome === "unexpected-error" || e.outcome === "unexpected-success")
 	};
-	return t.reportFile && u(t.reportFile, `${JSON.stringify(x, null, 2)}\n`), x;
+	return t.reportFile && s(t.reportFile, `${JSON.stringify(c, null, 2)}\n`), c;
 }
-async function h(e, t, r, i) {
+async function d(e, t, r, i) {
 	let a = await n.create({
 		extension: t,
 		platform: r.platform,
-		engine: r.engine
+		engine: r.engine,
+		browser: r.browser
 	}), o = [];
 	try {
 		let t = null;
-		for (let n of e) n.file !== t && (t = n.file, await a.newPage()), o.push(await g(a, n, i));
+		for (let n of e) n.file !== t && (t = n.file, await a.newPage()), o.push(await f(a, n, i));
 	} finally {
 		await a.close();
 	}
 	return o;
 }
-async function g(e, n, r) {
+async function f(e, n, r) {
 	let i = t(n.config);
 	try {
-		let t = await _(e.run(n.sql), r);
+		let t = await p(e.run(n.sql), r);
 		return {
 			file: n.file,
 			line: n.line,
@@ -63,43 +50,43 @@ async function g(e, n, r) {
 		};
 	}
 }
-function _(e, t) {
+function p(e, t) {
 	let n, r = new Promise((e, r) => {
 		n = setTimeout(() => r(/* @__PURE__ */ Error(`timed out after ${t}ms`)), t);
 	});
 	return Promise.race([e, r]).finally(() => clearTimeout(n));
 }
-function v(e) {
+function m(e) {
 	let t = [];
-	b(r(e, f[0])) && t.push(f[0]);
-	let n = r(e, f[1]);
-	if (b(n)) for (let e of s(n)) b(r(n, e, "docusaurus-plugin-content-docs", "current")) && t.push(r("i18n", e, "docusaurus-plugin-content-docs", "current"));
+	g(r(e, c[0])) && t.push(c[0]);
+	let n = r(e, c[1]);
+	if (g(n)) for (let e of a(n)) g(r(n, e, "docusaurus-plugin-content-docs", "current")) && t.push(r("i18n", e, "docusaurus-plugin-content-docs", "current"));
 	return t.length > 0 ? t : ["."];
 }
-function y(e) {
-	let t = r(e, "static", "duckdb-extensions"), n = b(t) ? s(t).filter((e) => e.endsWith(".duckdb_extension.wasm")) : [];
+function h(e) {
+	let t = r(e, "static", "duckdb-extensions"), n = g(t) ? a(t).filter((e) => e.endsWith(".duckdb_extension.wasm")) : [];
 	if (n.length === 0) throw Error(`sql/verify: no extension found in ${t} — pass --extension <file|url>, or let the site's extension preload plugin fetch it first`);
 	if (n.length > 1) throw Error(`sql/verify: several extensions found in ${t} (${n.join(", ")}) — pass --extension to pick one`);
 	return r(t, n[0]);
 }
-function b(e) {
-	return l(e, { throwIfNoEntry: !1 })?.isDirectory() ?? !1;
+function g(e) {
+	return o(e, { throwIfNoEntry: !1 })?.isDirectory() ?? !1;
 }
-async function x(e) {
-	let t = C(e);
+async function _(e) {
+	let t = y(e);
 	if (t.help) {
-		process.stdout.write(S);
+		process.stdout.write(v);
 		return;
 	}
-	let n = Date.now(), r = await m(t), i = ((Date.now() - n) / 1e3).toFixed(1), a = r.blocks.filter((e) => e.outcome === "error-as-expected").length;
+	let n = Date.now(), r = await u(t), i = ((Date.now() - n) / 1e3).toFixed(1), a = r.blocks.filter((e) => e.outcome === "error-as-expected").length;
 	if (t.quiet || (process.stdout.write(`\n${r.blocks.length} block(s) in ${i}s\n`), process.stdout.write(`  ${r.asDeclared.length} as declared (${a} erroring on purpose), ${r.unexpected.length} unexpected\n`)), r.unexpected.length > 0) {
 		process.stdout.write("unexpected behaviour:\n");
 		for (let e of r.unexpected) process.stdout.write(`- ${e.file}:${e.line} [${e.outcome}] :: ${e.detail}\n`);
 		process.exitCode = 1;
 	}
 }
-var S = "Usage: duckfn-sql-verify [options]\n\nRuns every runnable SQL block of a duckfn docs site in DuckDB-Wasm, and checks\nthat each one behaves as its own metadata declares (\"expect\": \"error\" for a\nblock that demonstrates a failure).\n\n  --site <dir>          Docs site root (default: the working directory)\n  --content <dir>       Content directory, relative to the site root (repeatable;\n                        default: docs/ plus every i18n/<locale>/… translation)\n  --extension <path>    The extension to preload: a .duckdb_extension.wasm path,\n                        or an absolute http(s) URL (default: the single file under\n                        static/duckdb-extensions/)\n  --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build\n                        (default: eh)\n  --engine <path>       Engine wasm override\n  --timeout <ms>        Per-block timeout (default: 30000)\n  --working-dir <dir>   Directory the blocks run in (default: a temporary one)\n  --report <file>       Write the full result list as JSON\n  --quiet               Only report unexpected behaviour\n  --help                Show this help\n";
-function C(e) {
+var v = "Usage: duckfn-sql-verify [options]\n\nRuns every runnable SQL block of a duckfn docs site in a headless browser\n(DuckDB-Wasm), and checks that each one behaves as its own metadata declares\n(\"expect\": \"error\" for a block that demonstrates a failure).\n\n  --site <dir>          Docs site root (default: the working directory)\n  --content <dir>       Content directory, relative to the site root (repeatable;\n                        default: docs/ plus every i18n/<locale>/… translation)\n  --extension <path>    The extension to preload: a .duckdb_extension.wasm path,\n                        or an absolute http(s) URL (default: the single file under\n                        static/duckdb-extensions/)\n  --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build\n                        (default: eh)\n  --engine <path>       Engine wasm override\n  --browser <path>      Browser executable (default: a detected Chrome/Edge,\n                        or the DFK_BROWSER environment variable)\n  --timeout <ms>        Per-block timeout (default: 30000)\n  --report <file>       Write the full result list as JSON\n  --quiet               Only report unexpected behaviour\n  --help                Show this help\n";
+function y(e) {
 	let t = {}, n = [];
 	for (let r = 0; r < e.length; r++) {
 		let i = e[r], a = () => {
@@ -123,12 +110,12 @@ function C(e) {
 			case "--engine":
 				t.engine = a();
 				break;
+			case "--browser":
+				t.browser = a();
+				break;
 			case "--timeout":
 				t.timeoutMs = Number(a());
 				break;
-			case "--working-dir":
-				t.workingDir = a();
-				break;
 			case "--report":
 				t.reportFile = a();
 				break;
@@ -145,4 +132,4 @@ function C(e) {
 	return n.length > 0 && (t.contentDirs = n), t;
 }
 //#endregion
-export { x as cliMain, m as verifySqlDocs };
+export { _ as cliMain, u as verifySqlDocs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duckfn-docs-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared Docusaurus building blocks (TOC toggle, home-page web components, brand tokens, remark version placeholder) for duckfn-family extension docs sites.",
   "license": "MIT",
   "keywords": [
@@ -45,7 +45,7 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "build": "vite build && tsc -p tsconfig.build.json",
+    "build": "vite build && vite build --config vite.harness.config.ts && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "prepack": "npm run build"
@@ -62,6 +62,7 @@
     "@visactor/vtable": "^1.26.8",
     "codemirror": "^6.0.2",
     "iconify-icon": "^3.0.3",
+    "playwright-core": "^1.63.0",
     "sql-formatter": "^15.9.0"
   },
   "devDependencies": {

package/src/remark.ts

@@ -15,7 +15,7 @@ import type {Plugin} from 'unified';
 export const DEFAULT_VERSION_PLACEHOLDER = '{{DUCKFN_VERSION}}';
 
 export interface VersionPlaceholderOptions {
-  /** The real version string to substitute in, e.g. `0.0.13`. */
+  /** The real version string to substitute in, e.g. `0.0.15`. */
   version: string;
   /** Override the token if a site uses a different one. */
   placeholder?: string;

package/src/sql/DfkSql.ts

@@ -18,7 +18,7 @@ import {el, HTMLElementBase} from '../dom';
  * Everything but the result is in the shadow root. The result is a slotted
  * light-DOM sibling because VTable injects a *document-level* stylesheet that a
  * shadow boundary could not host — and it is only created when a query runs,
- * long after hydration, so the light DOM still starts empty (AGENTS.md rule 11).
+ * long after hydration, so the light DOM still starts empty (CONVENTIONS.md rule 11).
  * The editor has no such problem: it sits in this shadow root, so CodeMirror's
  * style-mod resolves the root to the same tree its styles are used in.
  *
@@ -30,7 +30,7 @@ import {el, HTMLElementBase} from '../dom';
  * which a renderer builds, so the component keeps the node (and its state) and
  * hands it over through `RenderContext.fullscreenButton`.
  *
- * Content entry is an **attribute seed** (see AGENTS.md rule 5 exception): the
+ * Content entry is an **attribute seed** (see CONVENTIONS.md rule 5 exception): the
  * `config` / `sql` attributes are read once in `connectedCallback` because the
  * remark-generated JSX cannot hand content through a ref setter. Reading once
  * to initialise is not an attribute→render loop, so the retained-mode contract

package/src/sql/browserRunner.ts

@@ -0,0 +1,402 @@
+/**
+ * Runs runnable SQL blocks in a **real browser**, driven from Node with
+ * Playwright — the offline successor to the old Node-worker runner
+ * (`nodeRunner.ts`, now removed).
+ *
+ * Why a browser instead of the Node worker
+ * ----------------------------------------
+ * The Node worker target is not the environment a reader gets: it cannot read
+ * remote `http(s)` data (every remote-data example failed with `IO Error: No
+ * files found`), and loading the extension forced a loopback server on a
+ * Windows-hostile port (the staging path embeds the port, colons are illegal).
+ * A browser is the actual product surface: DuckDB-Wasm reads remote files
+ * there, and the extension loads same-origin over plain http with none of the
+ * staging/port constraints. That is exactly what the docs site ships.
+ *
+ * Why Playwright, and why `playwright-core`
+ * -----------------------------------------
+ * Playwright is the mature, maintained way to drive a browser: it owns the
+ * protocol, the connect/navigate/evaluate plumbing, auto-waiting, timeouts and
+ * crash handling that a hand-rolled driver would have to reinvent. The kit uses
+ * the `playwright-core` package (not the full `playwright`) precisely because
+ * `playwright-core` never downloads a browser — it launches one you point it
+ * at. The runner starts your **system Chrome/Edge** via `executablePath`, so
+ * verification stays fully offline. `--browser <path>` / `DFK_BROWSER` override
+ * which executable is used; otherwise a small set of well-known paths is probed.
+ *
+ * How a page maps to a DuckDB instance
+ * -------------------------------------
+ * `newPage()` navigates to the harness page (`harness.ts`), which builds a
+ * fresh `AsyncDuckDB` from the same-origin engine and preloads the extension.
+ * Reloading per content file is the isolation boundary (pages never share an
+ * instance), while the blocks of one page share its connection — the same "one
+ * instance per page, blocks share a connection" model as the site. Files
+ * (`COPY … TO`, `dfn_file_write_*`) land in the instance's in-memory file
+ * system, readable within the page and gone on reload — the faithful browser
+ * behaviour, not a host-directory emulation.
+ */
+import {createServer, type Server} from 'node:http';
+import {createRequire} from 'node:module';
+import {existsSync, readFileSync} from 'node:fs';
+import {basename, dirname, join} from 'node:path';
+import {chromium, type Browser, type Page} from 'playwright-core';
+
+const require = createRequire(import.meta.url);
+
+/** The extension to `LOAD`: a local `.duckdb_extension.wasm` path or an http(s) URL. */
+export interface RunnerOptions {
+  extension: string;
+  /** DuckDB-Wasm platform bundle; must match how the extension was built. */
+  platform?: WasmPlatform;
+  /** Engine wasm override; defaults to the platform bundle inside duckdb-wasm. */
+  engine?: string;
+  /** Browser executable; defaults to a detected Chrome/Edge (`DFK_BROWSER` wins). */
+  browser?: string;
+}
+
+export type WasmPlatform = 'eh' | 'mvp';
+
+export interface RunResult {
+  rows: number;
+  columns: number;
+}
+
+/** Per-platform file names inside `@duckdb/duckdb-wasm/dist`. */
+const PLATFORM_BUNDLES: Record<WasmPlatform, {wasm: string; worker: string}> = {
+  eh: {wasm: 'duckdb-eh.wasm', worker: 'duckdb-browser-eh.worker.js'},
+  mvp: {wasm: 'duckdb-mvp.wasm', worker: 'duckdb-browser-mvp.worker.js'},
+};
+
+/** The harness's `__dfkRun` return shape (see `harness.ts`). */
+interface HarnessResult {
+  rows: number;
+  columns: number;
+  error?: string;
+}
+
+/** The harness's `__dfkQuery` return shape (see `harness.ts`). */
+export interface QueryResult {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  error?: string;
+}
+
+/**
+ * One DuckDB-Wasm instance at a time, driven through a headless browser.
+ * Mirrors the surface `verify.ts` used from `WasmSqlRunner`.
+ */
+export class BrowserSqlRunner {
+  #server: Server | null = null;
+  #browser: Browser | null = null;
+  #page: Page | null = null;
+  #harnessUrl = '';
+  /** Set when the current page failed to initialise; every run then reports it. */
+  #pageError: string | null = null;
+
+  readonly #extensionUrl: string;
+  readonly #enginePath: string;
+  readonly #workerPath: string;
+  readonly #browserExecutable: string;
+  readonly #allowUnsigned: boolean;
+
+  private constructor(options: {
+    extensionUrl: string;
+    enginePath: string;
+    workerPath: string;
+    browserExecutable: string;
+    allowUnsigned: boolean;
+  }) {
+    this.#extensionUrl = options.extensionUrl;
+    this.#enginePath = options.enginePath;
+    this.#workerPath = options.workerPath;
+    this.#browserExecutable = options.browserExecutable;
+    this.#allowUnsigned = options.allowUnsigned;
+  }
+
+  static async create(options: RunnerOptions): Promise<BrowserSqlRunner> {
+    const platform = options.platform ?? 'eh';
+    const bundle = PLATFORM_BUNDLES[platform];
+    const distDir = dirname(require.resolve('@duckdb/duckdb-wasm/dist/duckdb-browser.mjs'));
+    const enginePath = options.engine ? resolveLocal(options.engine) : join(distDir, bundle.wasm);
+    const workerPath = join(distDir, bundle.worker);
+
+    const remote = /^https?:\/\//i.test(options.extension);
+    const extensionUrl = remote ? options.extension : resolveLocal(options.extension);
+
+    return new BrowserSqlRunner({
+      extensionUrl,
+      enginePath,
+      workerPath,
+      browserExecutable: findBrowser(options.browser),
+      // The runner is a trusted local loopback: an unsigned dev extension must
+      // load, exactly as the site's own config opts in.
+      allowUnsigned: true,
+    });
+  }
+
+  /** Starts the static server and the browser; idempotent. */
+  async #ensureStarted(): Promise<void> {
+    if (this.#page) {
+      return;
+    }
+    this.#server = await startStaticServer(this.#routes());
+    const address = this.#server.address();
+    const port = typeof address === 'object' && address ? address.port : 0;
+    this.#harnessUrl = `http://127.0.0.1:${port}/harness.html`;
+
+    // `playwright-core` launches the executable we hand it and manages the
+    // browser process and a throwaway profile for us.
+    this.#browser = await chromium.launch({
+      executablePath: this.#browserExecutable,
+      headless: true,
+    });
+    this.#page = await this.#browser.newPage();
+  }
+
+  /** Maps the URL space the harness page needs to everything on disk. */
+  #routes(): Routes {
+    // A served extension keeps a `/ext/<name>.duckdb_extension.wasm` shape so
+    // its base name still names the entry symbol (`<name>_init_c_api`).
+    const ext = /^https?:\/\//i.test(this.#extensionUrl)
+      ? {remoteUrl: this.#extensionUrl}
+      : {localFile: this.#extensionUrl, baseName: basename(this.#extensionUrl)};
+    return {
+      // Resolved through the package's own `exports` wildcard
+      // (`./sql/harness` -> `dist/sql/harness.js`), so it finds the built harness
+      // whether the runner runs from the workspace symlink or an installed copy.
+      harnessScript: require.resolve('duckfn-docs-kit/sql/harness'),
+      engine: {file: this.#enginePath, name: basename(this.#enginePath)},
+      worker: {file: this.#workerPath, name: basename(this.#workerPath)},
+      extension: ext,
+      allowUnsigned: this.#allowUnsigned,
+    };
+  }
+
+  /** Drops the current page state and opens a fresh one: new instance, new connection. */
+  async newPage(): Promise<void> {
+    await this.#ensureStarted();
+    const page = this.#page;
+    if (!page) {
+      throw new Error('sql/browserRunner: browser is not running');
+    }
+    this.#pageError = null;
+    await page.goto(this.#harnessUrl, {waitUntil: 'load'});
+    // `__dfkReady` resolves once the engine is up and the preloads have loaded;
+    // Playwright awaits the promise and throws if it rejects.
+    try {
+      await page.evaluate(() => (window as unknown as {__dfkReady: Promise<void>}).__dfkReady);
+    } catch (error) {
+      this.#pageError = messageOf(error);
+    }
+  }
+
+  /** Runs one block; a SQL failure is thrown so the caller can weigh it. */
+  async run(sql: string): Promise<RunResult> {
+    if (this.#pageError) {
+      throw new Error(this.#pageError);
+    }
+    const page = this.#page;
+    if (!page) {
+      throw new Error('sql/browserRunner: no page is open — call newPage() first');
+    }
+    // `sql` crosses as an evaluate argument, never spliced into page code.
+    const result = await page.evaluate(
+      (statement) => (window as unknown as {__dfkRun: (s: string) => Promise<HarnessResult>}).__dfkRun(statement),
+      sql,
+    );
+    if (result?.error) {
+      throw new Error(result.error);
+    }
+    return {rows: result.rows, columns: result.columns};
+  }
+
+  /**
+   * Runs one statement and returns its actual rows (not just a count). Used by
+   * the vfs browser probe to read each value; `run()` is the verifier's path.
+   * Unlike `run()`, a failure is returned as `{error}` rather than thrown.
+   */
+  async query(sql: string): Promise<QueryResult> {
+    if (this.#pageError) {
+      return {columns: [], rows: [], error: this.#pageError};
+    }
+    const page = this.#page;
+    if (!page) {
+      throw new Error('sql/browserRunner: no page is open — call newPage() first');
+    }
+    const result = await page.evaluate(
+      (statement) =>
+        (window as unknown as {__dfkQuery: (s: string) => Promise<QueryResult>}).__dfkQuery(statement),
+      sql,
+    );
+    return result ?? {columns: [], rows: [], error: 'no result'};
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.#page?.close();
+    } catch {
+      // The page may already be gone when the browser is shutting down.
+    }
+    this.#page = null;
+    try {
+      await this.#browser?.close();
+    } catch {
+      // Likewise the browser: closing twice or after a crash is not an error.
+    }
+    this.#browser = null;
+    if (this.#server) {
+      await new Promise<void>((resolve) => this.#server?.close(() => resolve()));
+      this.#server = null;
+    }
+  }
+}
+
+/** A path or `file:` URL to an absolute local path; leaves a remote URL alone. */
+function resolveLocal(value: string): string {
+  return /^file:\/\//i.test(value) ? new URL(value).pathname.replace(/^\/(\w:)/i, '$1') : value;
+}
+
+// ---------------------------------------------------------------------------
+// Static server
+// ---------------------------------------------------------------------------
+
+interface Routes {
+  harnessScript: string;
+  engine: {file: string; name: string};
+  worker: {file: string; name: string};
+  extension: {remoteUrl: string} | {localFile: string; baseName: string};
+  allowUnsigned: boolean;
+}
+
+/**
+ * A loopback static server for the harness: `harness.html` (generated, wiring
+ * the engine/extension URLs into the two contracts `harness.ts` reads),
+ * `harness.js` (the bundled harness), `/vendor/*` (engine + worker), and
+ * `/ext/*` (the served extension file). Nothing else is reachable; this is a
+ * short-lived test fixture, not a web server.
+ */
+async function startStaticServer(routes: Routes): Promise<Server> {
+  const harness = readFileSync(routes.harnessScript);
+  const engine = readFileSync(routes.engine.file);
+  const worker = readFileSync(routes.worker.file);
+  const extension =
+    'localFile' in routes.extension ? readFileSync(routes.extension.localFile) : null;
+  const extBaseName = 'baseName' in routes.extension ? routes.extension.baseName : '';
+
+  const extensionUrl =
+    'remoteUrl' in routes.extension
+      ? routes.extension.remoteUrl
+      : `ext/${routes.extension.baseName}`;
+
+  const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>duckfn sql harness</title>
+    <script>
+      window.DFK_HARNESS_BUNDLE = {
+        mainModule: '/vendor/${routes.engine.name}',
+        mainWorker: '/vendor/${routes.worker.name}',
+      };
+    </script>
+    <script id="dfk-sql-runtime" type="application/json">
+      {"allowUnsignedExtensions":${routes.allowUnsigned},"preload":[{"url":"${extensionUrl}"}]}
+    </script>
+  </head>
+  <body>
+    <script type="module" src="/harness.js"></script>
+  </body>
+</html>`;
+
+  const server = createServer((request, response) => {
+    const path = new URL(request.url ?? '/', 'http://localhost').pathname;
+    if (path === '/harness.html') {
+      send(response, 'text/html; charset=utf-8', Buffer.from(html, 'utf8'));
+      return;
+    }
+    if (path === '/harness.js') {
+      send(response, 'text/javascript; charset=utf-8', harness);
+      return;
+    }
+    if (path === `/vendor/${routes.engine.name}`) {
+      send(response, 'application/wasm', engine);
+      return;
+    }
+    if (path === `/vendor/${routes.worker.name}`) {
+      send(response, 'text/javascript; charset=utf-8', worker);
+      return;
+    }
+    if (extension && path === `/ext/${extBaseName}`) {
+      send(response, 'application/octet-stream', extension);
+      return;
+    }
+    response.writeHead(404, {'content-type': 'text/plain'});
+    response.end('not found');
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    // Port 0 lets the OS pick a free one; a browser has no reason for a fixed
+    // port (unlike the Node worker's staging path, which embedded it).
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  return server;
+}
+
+function send(response: import('node:http').ServerResponse, type: string, body: Buffer): void {
+  response.writeHead(200, {'content-type': type, 'content-length': body.length});
+  response.end(body);
+}
+
+// ---------------------------------------------------------------------------
+// Browser detection
+// ---------------------------------------------------------------------------
+
+/** A short list of well-known Chrome/Edge locations, overridable by DFK_BROWSER. */
+function findBrowser(explicit?: string): string {
+  const candidate = explicit ?? process.env.DFK_BROWSER;
+  if (candidate) {
+    return candidate;
+  }
+  const paths: string[] = [];
+  if (process.platform === 'win32') {
+    const pf = process.env['PROGRAMFILES'] ?? 'C:\\Program Files';
+    const pf86 = process.env['PROGRAMFILES(X86)'] ?? 'C:\\Program Files (x86)';
+    const local = process.env['LOCALAPPDATA'] ?? '';
+    paths.push(
+      join(pf, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      join(pf86, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      join(pf86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      join(pf, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      local ? join(local, 'Google', 'Chrome', 'Application', 'chrome.exe') : '',
+    );
+  } else if (process.platform === 'darwin') {
+    paths.push(
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    );
+  } else {
+    paths.push(
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/microsoft-edge',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+    );
+  }
+  for (const path of paths) {
+    if (path && existsSync(path)) {
+      return path;
+    }
+  }
+  throw new Error(
+    'sql/browserRunner: no Chrome/Edge found — pass --browser <path> or set DFK_BROWSER',
+  );
+}
+
+function messageOf(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}