duckfn-docs-kit 0.2.0 → 0.3.0

package/README.md

@@ -24,7 +24,7 @@ npm install duckfn-docs-kit
 | --- | --- | --- |
 | `duckfn-docs-kit` | browser | Home-page custom elements (`<dfk-hero>`, `<dfk-features>`, `<dfk-next-steps>`, `<dfk-sql>`), `registerDfkElements()` and the value types their setters accept |
 | `duckfn-docs-kit/remark` | Node (build) | `remarkVersionPlaceholder`: replaces `{{DUCKFN_VERSION}}` inside `text` / `inlineCode` / `code` nodes |
-| `duckfn-docs-kit/sql/remark` | Node (build) | `remarkRunnableSql`: turns fenced `sql run` blocks into `<dfk-sql>` elements |
+| `duckfn-docs-kit/sql/remark` | Node (build) | `remarkRunnableSql`: turns fenced `sql {"type":"duckfn",…}` blocks into `<dfk-sql>` elements |
 | `duckfn-docs-kit/sql/extensions` | Node (build) | `dfkExtensions()` Docusaurus plugin: preloads a site's DuckDB extensions before the first block runs |
 | `duckfn-docs-kit/toc-toggle/plugin` | Node (build) | `dfkTocToggle()` Docusaurus plugin: adds the TOC collapse control |
 | `duckfn-docs-kit/toc-toggle/TocToggle` | browser | The TOC collapse class, for a site that drives it itself |
@@ -97,10 +97,12 @@ styles inside the JS bundle, so they need nothing here.
 
 ## Documentation
 
-The user guide lives at <https://shijianjs.github.io/duckfn/docs/docs-kit>. The
-conventions this package is written to — retained-mode components, shadow DOM,
-SSR safety, the SQL rendering contract — are documented in
-[`AGENTS.md`](./AGENTS.md), which ships inside the package.
+The user guide lives at <https://shijianjs.github.io/duckfn/docs/docs-kit>. If you —
+or an AI agent — are *using* this package, read [`AGENTS.md`](./AGENTS.md): it ships
+inside the package and states the contracts (the block metastring, the config
+fields, the traps). The conventions this package is *written to* — retained-mode
+components, shadow DOM, SSR safety — live in `CONVENTIONS.md` in the repository and
+are not published.
 
 ## License
 

package/bin/sql-verify.mjs

@@ -1,12 +1,12 @@
-#!/usr/bin/env node
-/**
- * The `duckfn-sql-verify` executable.
- *
- * A hand-written wrapper rather than a built entry: Vite's library build emits
- * ESM and does not preserve a shebang, and npm only needs one file with one and
- * an executable bit. `dist/` is built by `prepack`, so the import below always
- * resolves in a published tarball.
- */
-import {cliMain} from '../dist/sql/verify.js';
-
-await cliMain(process.argv.slice(2));
+#!/usr/bin/env node
+/**
+ * The `duckfn-sql-verify` executable.
+ *
+ * A hand-written wrapper rather than a built entry: Vite's library build emits
+ * ESM and does not preserve a shebang, and npm only needs one file with one and
+ * an executable bit. `dist/` is built by `prepack`, so the import below always
+ * resolves in a published tarball.
+ */
+import {cliMain} from '../dist/sql/verify.js';
+
+await cliMain(process.argv.slice(2));

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, r, t as i } from "./register-DKLiYs-F.js";
+import { a as e, i as t, n, r, t as i } from "./register-CALCwFBv.js";
 export { e as DfkFeatures, t as DfkHero, r as DfkNextSteps, n as DfkSql, i as registerDfkElements };

package/dist/{register-DKLiYs-F.js → register-CALCwFBv.js}

@@ -168,7 +168,8 @@ var p = class extends c {
 	#i = null;
 	#a = !1;
 	#o = null;
-	#s = /* @__PURE__ */ new Map();
+	#s = null;
+	#c = /* @__PURE__ */ new Map();
 	get state() {
 		return this.#e;
 	}
@@ -176,24 +177,32 @@ var p = class extends c {
 		return this.#t;
 	}
 	init(e = {}) {
-		if (e.allowUnsignedExtensions && (this.#a = !0), this.#e === "ready") return Promise.resolve();
+		if (e.allowUnsignedExtensions && (this.#a = !0), e.bundle && (this.#o = e.bundle), this.#e === "ready") return Promise.resolve();
 		if (this.#n) return this.#n;
-		let t = this.#c();
-		return t.allowUnsignedExtensions && (this.#a = !0), this.#e = "loading", this.#n = this.#l(t.preload).catch((e) => {
+		let t = this.#l();
+		return t.allowUnsignedExtensions && (this.#a = !0), this.#e = "loading", this.#n = this.#u(t.preload).catch((e) => {
 			throw this.#e = "error", this.#t = y(e), this.#n = null, e;
 		}), this.#n;
 	}
-	#c() {
-		return this.#o ??= re(), this.#o;
+	#l() {
+		return this.#s ??= re(), this.#s;
 	}
-	async #l(e) {
-		let t = await import("@duckdb/duckdb-wasm"), n = await t.selectBundle(t.getJsDelivrBundles());
+	async #u(e) {
+		let t = await import("@duckdb/duckdb-wasm");
+		if (this.#o) {
+			let n = new Worker(this.#o.mainWorker);
+			this.#r = new t.AsyncDuckDB(new t.ConsoleLogger(), n), await this.#r.instantiate(this.#o.mainModule, this.#o.pthreadWorker ?? null), await this.#r.open({ allowUnsignedExtensions: this.#a }), this.#i = await this.#r.connect();
+			for (let t of e) await this.#d(t);
+			this.#e = "ready", this.#t = "";
+			return;
+		}
+		let n = await t.selectBundle(t.getJsDelivrBundles());
 		if (!n.mainWorker) throw Error("The selected DuckDB-Wasm bundle has no worker script");
 		let r = URL.createObjectURL(new Blob([`importScripts("${n.mainWorker}");`], { type: "text/javascript" })), i = new Worker(r);
 		URL.revokeObjectURL(r);
 		let a = new t.ConsoleLogger();
 		this.#r = new t.AsyncDuckDB(a, i), await this.#r.instantiate(n.mainModule, n.pthreadWorker), await this.#r.open({ allowUnsignedExtensions: this.#a }), this.#i = await this.#r.connect();
-		for (let t of e) await this.#u(t);
+		for (let t of e) await this.#d(t);
 		this.#e = "ready", this.#t = "";
 	}
 	async execute(e) {
@@ -219,38 +228,38 @@ var p = class extends c {
 		}
 	}
 	async loadExtension(e, t = {}) {
-		return await this.init(), this.#u({
+		return await this.init(), this.#d({
 			name: e,
 			repository: t.repository
 		});
 	}
-	#u(e) {
+	#d(e) {
 		let t = o(e);
-		if (typeof t == "string") return this.#d(`\u0000${t}`, () => this.#f(t));
+		if (typeof t == "string") return this.#f(`\u0000${t}`, () => this.#p(t));
 		if ("name" in t) {
 			let { name: e, repository: n } = t;
-			return this.#d(`${n ?? ""}\u0000${e}`, () => this.#f(e, n));
+			return this.#f(`${n ?? ""}\u0000${e}`, () => this.#p(e, n));
 		}
 		let { url: n } = t;
-		return this.#d(`url\u0000${n}`, () => this.#p(n));
+		return this.#f(`url\u0000${n}`, () => this.#m(n));
 	}
-	#d(e, t) {
-		let n = this.#s.get(e);
+	#f(e, t) {
+		let n = this.#c.get(e);
 		if (n) return n;
 		let r = t().catch((t) => {
-			throw this.#s.delete(e), t;
+			throw this.#c.delete(e), t;
 		});
-		return this.#s.set(e, r), r;
+		return this.#c.set(e, r), r;
 	}
-	async #f(e, t) {
+	async #p(e, t) {
 		if (!r.test(e)) throw Error(`Not a valid extension name: ${e}`);
-		let n = this.#m();
+		let n = this.#h();
 		t !== void 0 && await n.query(`INSTALL ${e} FROM ${ne(t)}`), await n.query(`LOAD ${e}`);
 	}
-	async #p(e) {
-		await this.#m().query(`LOAD '${v(e)}'`);
+	async #m(e) {
+		await this.#h().query(`LOAD '${v(e)}'`);
 	}
-	#m() {
+	#h() {
 		let e = this.#i;
 		if (!e) throw Error(this.#t || "DuckDB unavailable");
 		return e;

package/dist/remark.d.ts

@@ -13,7 +13,7 @@ import type { Plugin } from 'unified';
  */
 export declare 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/dist/sql/browserRunner.d.ts

@@ -0,0 +1,41 @@
+/** 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;
+}
+/** 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 declare class BrowserSqlRunner {
+    #private;
+    private constructor();
+    static create(options: RunnerOptions): Promise<BrowserSqlRunner>;
+    /** Drops the current page state and opens a fresh one: new instance, new connection. */
+    newPage(): Promise<void>;
+    /** Runs one block; a SQL failure is thrown so the caller can weigh it. */
+    run(sql: string): Promise<RunResult>;
+    /**
+     * 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.
+     */
+    query(sql: string): Promise<QueryResult>;
+    close(): Promise<void>;
+}

package/dist/sql/browserRunner.js

@@ -0,0 +1,186 @@
+import { createRequire as e } from "node:module";
+import { basename as t, dirname as n, join as r } from "node:path";
+import { existsSync as i, readFileSync as a } from "node:fs";
+import { createServer as o } from "node:http";
+import { chromium as s } from "playwright-core";
+//#region src/sql/browserRunner.ts
+var c = e(import.meta.url), l = {
+	eh: {
+		wasm: "duckdb-eh.wasm",
+		worker: "duckdb-browser-eh.worker.js"
+	},
+	mvp: {
+		wasm: "duckdb-mvp.wasm",
+		worker: "duckdb-browser-mvp.worker.js"
+	}
+}, u = class e {
+	#e = null;
+	#t = null;
+	#n = null;
+	#r = "";
+	#i = null;
+	#a;
+	#o;
+	#s;
+	#c;
+	#l;
+	constructor(e) {
+		this.#a = e.extensionUrl, this.#o = e.enginePath, this.#s = e.workerPath, this.#c = e.browserExecutable, this.#l = e.allowUnsigned;
+	}
+	static async create(t) {
+		let i = l[t.platform ?? "eh"], a = n(c.resolve("@duckdb/duckdb-wasm/dist/duckdb-browser.mjs")), o = t.engine ? d(t.engine) : r(a, i.wasm), s = r(a, i.worker), u = /^https?:\/\//i.test(t.extension) ? t.extension : d(t.extension);
+		return new e({
+			extensionUrl: u,
+			enginePath: o,
+			workerPath: s,
+			browserExecutable: m(t.browser),
+			allowUnsigned: !0
+		});
+	}
+	async #u() {
+		if (this.#n) return;
+		this.#e = await f(this.#d());
+		let e = this.#e.address(), t = typeof e == "object" && e ? e.port : 0;
+		this.#r = `http://127.0.0.1:${t}/harness.html`, this.#t = await s.launch({
+			executablePath: this.#c,
+			headless: !0
+		}), this.#n = await this.#t.newPage();
+	}
+	#d() {
+		let e = /^https?:\/\//i.test(this.#a) ? { remoteUrl: this.#a } : {
+			localFile: this.#a,
+			baseName: t(this.#a)
+		};
+		return {
+			harnessScript: c.resolve("duckfn-docs-kit/sql/harness"),
+			engine: {
+				file: this.#o,
+				name: t(this.#o)
+			},
+			worker: {
+				file: this.#s,
+				name: t(this.#s)
+			},
+			extension: e,
+			allowUnsigned: this.#l
+		};
+	}
+	async newPage() {
+		await this.#u();
+		let e = this.#n;
+		if (!e) throw Error("sql/browserRunner: browser is not running");
+		this.#i = null, await e.goto(this.#r, { waitUntil: "load" });
+		try {
+			await e.evaluate(() => window.__dfkReady);
+		} catch (e) {
+			this.#i = h(e);
+		}
+	}
+	async run(e) {
+		if (this.#i) throw Error(this.#i);
+		let t = this.#n;
+		if (!t) throw Error("sql/browserRunner: no page is open — call newPage() first");
+		let n = await t.evaluate((e) => window.__dfkRun(e), e);
+		if (n?.error) throw Error(n.error);
+		return {
+			rows: n.rows,
+			columns: n.columns
+		};
+	}
+	async query(e) {
+		if (this.#i) return {
+			columns: [],
+			rows: [],
+			error: this.#i
+		};
+		let t = this.#n;
+		if (!t) throw Error("sql/browserRunner: no page is open — call newPage() first");
+		return await t.evaluate((e) => window.__dfkQuery(e), e) ?? {
+			columns: [],
+			rows: [],
+			error: "no result"
+		};
+	}
+	async close() {
+		try {
+			await this.#n?.close();
+		} catch {}
+		this.#n = null;
+		try {
+			await this.#t?.close();
+		} catch {}
+		this.#t = null, this.#e &&= (await new Promise((e) => this.#e?.close(() => e())), null);
+	}
+};
+function d(e) {
+	return /^file:\/\//i.test(e) ? new URL(e).pathname.replace(/^\/(\w:)/i, "$1") : e;
+}
+async function f(e) {
+	let t = a(e.harnessScript), n = a(e.engine.file), r = a(e.worker.file), i = "localFile" in e.extension ? a(e.extension.localFile) : null, s = "baseName" in e.extension ? e.extension.baseName : "", c = "remoteUrl" in e.extension ? e.extension.remoteUrl : `ext/${e.extension.baseName}`, l = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>duckfn sql harness</title>
+    <script>
+      window.DFK_HARNESS_BUNDLE = {
+        mainModule: '/vendor/${e.engine.name}',
+        mainWorker: '/vendor/${e.worker.name}',
+      };
+    <\/script>
+    <script id="dfk-sql-runtime" type="application/json">
+      {"allowUnsignedExtensions":${e.allowUnsigned},"preload":[{"url":"${c}"}]}
+    <\/script>
+  </head>
+  <body>
+    <script type="module" src="/harness.js"><\/script>
+  </body>
+</html>`, u = o((a, o) => {
+		let c = new URL(a.url ?? "/", "http://localhost").pathname;
+		if (c === "/harness.html") {
+			p(o, "text/html; charset=utf-8", Buffer.from(l, "utf8"));
+			return;
+		}
+		if (c === "/harness.js") {
+			p(o, "text/javascript; charset=utf-8", t);
+			return;
+		}
+		if (c === `/vendor/${e.engine.name}`) {
+			p(o, "application/wasm", n);
+			return;
+		}
+		if (c === `/vendor/${e.worker.name}`) {
+			p(o, "text/javascript; charset=utf-8", r);
+			return;
+		}
+		if (i && c === `/ext/${s}`) {
+			p(o, "application/octet-stream", i);
+			return;
+		}
+		o.writeHead(404, { "content-type": "text/plain" }), o.end("not found");
+	});
+	return await new Promise((e, t) => {
+		u.once("error", t), u.listen(0, "127.0.0.1", e);
+	}), u;
+}
+function p(e, t, n) {
+	e.writeHead(200, {
+		"content-type": t,
+		"content-length": n.length
+	}), e.end(n);
+}
+function m(e) {
+	let t = e ?? process.env.DFK_BROWSER;
+	if (t) return t;
+	let n = [];
+	if (process.platform === "win32") {
+		let e = process.env.PROGRAMFILES ?? "C:\\Program Files", t = process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)", i = process.env.LOCALAPPDATA ?? "";
+		n.push(r(e, "Google", "Chrome", "Application", "chrome.exe"), r(t, "Google", "Chrome", "Application", "chrome.exe"), r(t, "Microsoft", "Edge", "Application", "msedge.exe"), r(e, "Microsoft", "Edge", "Application", "msedge.exe"), i ? r(i, "Google", "Chrome", "Application", "chrome.exe") : "");
+	} else process.platform === "darwin" ? n.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge") : n.push("/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/microsoft-edge", "/usr/bin/chromium", "/usr/bin/chromium-browser");
+	for (let e of n) if (e && i(e)) return e;
+	throw Error("sql/browserRunner: no Chrome/Edge found — pass --browser <path> or set DFK_BROWSER");
+}
+function h(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
+export { u as BrowserSqlRunner };

package/dist/sql/client.js

@@ -1,4 +1,4 @@
-import { t as e } from "../register-DKLiYs-F.js";
+import { t as e } from "../register-CALCwFBv.js";
 //#region src/sql/client.ts
 typeof window < "u" && e();
 //#endregion

package/dist/sql/harness.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `duckfn-docs-kit/sql/harness` — the browser page the offline SQL verifier
+ * (`sql/browserRunner`) drives with Playwright.
+ *
+ * It is deliberately thin: it reuses the site's own runtime (`sql/runtime`) so
+ * a verified block runs through exactly the code path a reader's **Run** click
+ * does — same `AsyncDuckDB` wiring, same ordered extension preload, same
+ * "multi-statement returns the last result" `execute()`. The only difference is
+ * where the engine comes from: instead of the jsDelivr CDN, the runner serves
+ * `duckdb-*.wasm` and its worker script same-origin and hands those URLs in
+ * through {@link window.DFK_HARNESS_BUNDLE}, which `runtime.init` accepts as a
+ * {@link LocalBundle}.
+ *
+ * The two contracts the page reads are injected by the served `harness.html`:
+ *
+ * - `window.DFK_HARNESS_BUNDLE` — `{mainModule, mainWorker, pthreadWorker?}`,
+ *   the locally-served engine bundle (an absolute same-origin URL each).
+ * - the `<script id="dfk-sql-runtime">` JSON tag — the preload list and
+ *   `allowUnsignedExtensions`, in the very shape the site plugin injects
+ *   (see `sql/runtimeConfig`), so nothing here re-implements extension loading.
+ *
+ * The runner communicates through `window.__dfkReady`, `window.__dfkRun` and
+ * `window.__dfkQuery`, each reached with a Playwright `page.evaluate` (which
+ * awaits the returned promise and marshals the value back to Node). Page reload
+ * per content file is what gives "one instance per page": a fresh document
+ * resets the module-level singleton, so pages never share a DuckDB instance
+ * while the blocks of one page keep sharing its connection (via
+ * `DuckDBRuntime.execute`).
+ */
+import { type LocalBundle } from './runtime';
+declare global {
+    interface Window {
+        /** The locally-served engine bundle, injected by the runner's harness.html. */
+        DFK_HARNESS_BUNDLE?: LocalBundle;
+        /** Resolves once the instance is up and the site preloads have loaded. */
+        __dfkReady?: Promise<void>;
+        /** Runs one block and reports rows/columns, or a captured error message. */
+        __dfkRun?: (sql: string) => Promise<HarnessRunResult>;
+        /**
+         * Runs one statement and returns its actual result — the rows, not just a
+         * count. Used by the vfs browser probe (`browserRunner.query`) to read the
+         * value each statement produced; the docs verifier never needs it.
+         */
+        __dfkQuery?: (sql: string) => Promise<HarnessQueryResult>;
+    }
+}
+/** What {@link window.__dfkRun} resolves with; mirrors the runner's `RunResult`. */
+export interface HarnessRunResult {
+    rows: number;
+    columns: number;
+    /** Set when the block failed; `rows`/`columns` are then 0. */
+    error?: string;
+}
+/** What {@link window.__dfkQuery} resolves with: the marshalled result rows. */
+export interface HarnessQueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    error?: string;
+}