duckfn-docs-kit 0.1.0

package/dist/register.d.ts

@@ -0,0 +1,10 @@
+import 'iconify-icon';
+/**
+ * Defines the `dfk-*` custom elements. Idempotent and SSR-safe: it is a no-op
+ * outside the browser, and re-running it never throws
+ * "already been registered with the custom element registry".
+ *
+ * Call it once at module scope in the docs site (and anywhere else that uses
+ * the components); importing the classes alone does not register anything.
+ */
+export declare function registerDfkElements(): void;

package/dist/remark.d.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from 'unified';
+/**
+ * Replaces a build-time version placeholder in the docs tree.
+ *
+ * Written as a plain text substitution so it can live in a shared package: the
+ * version value is passed in by the consuming site (it is the one thing that is
+ * *not* shared), and only "pure text" carriers are touched —
+ * `text` / `inlineCode` / `code` nodes. MDX expression nodes (`{expr}`) and ESM
+ * nodes are deliberately left alone, so this never interferes with MDX's own
+ * evaluation.
+ *
+ * This is Node-side build code: it must not touch `window` / `document`.
+ */
+export declare const DEFAULT_VERSION_PLACEHOLDER = "{{DUCKFN_VERSION}}";
+export interface VersionPlaceholderOptions {
+    /** The real version string to substitute in, e.g. `0.0.13`. */
+    version: string;
+    /** Override the token if a site uses a different one. */
+    placeholder?: string;
+}
+export declare const remarkVersionPlaceholder: Plugin<[VersionPlaceholderOptions]>;

package/dist/remark.js

@@ -0,0 +1,15 @@
+//#region src/remark.ts
+var e = "{{DUCKFN_VERSION}}", t = /* @__PURE__ */ new Set([
+	"text",
+	"inlineCode",
+	"code"
+]), n = ({ version: n, placeholder: r = e }) => (e) => {
+	let i = (e) => {
+		if (typeof e != "object" || !e) return;
+		let a = e, o = a.value;
+		typeof a.type == "string" && typeof o == "string" && t.has(a.type) && o.includes(r) && (a.value = o.split(r).join(n)), Array.isArray(a.children) && a.children.forEach(i);
+	};
+	i(e);
+};
+//#endregion
+export { e as DEFAULT_VERSION_PLACEHOLDER, n as remarkVersionPlaceholder };

package/dist/runtimeConfig-Bokbb8VH.js

@@ -0,0 +1,106 @@
+//#region src/sql/runtimeConfig.ts
+var e = "dfk-sql-runtime", t = /^[a-z][a-z0-9_]*$/i, n = /^https?:\/\/[^\s'";`<>\\]+$/i, r = /* @__PURE__ */ new Set(["community", "core"]), i = /^[\w.-]+\/[\w.-]+$/, a = /^[^\s'";`<>\\?#]+$/, o = /^[a-z][a-z0-9+.-]*:/i;
+function s(e) {
+	return /^https?:\/\//i.test(e);
+}
+function c(e) {
+	let t = e.split(/[?#]/, 1)[0], n = t.slice(t.lastIndexOf("/") + 1), r = n.indexOf(".");
+	return r === -1 ? n : n.slice(0, r);
+}
+function l(e) {
+	if (typeof e == "string") return h(e, "A preload entry");
+	if (typeof e != "object" || !e || Array.isArray(e)) throw Error(`A preload entry must be a string, {name, repository?} or {url, release?}: ${_(e)}`);
+	let t = e, n = t.name !== void 0;
+	if (n === (t.url !== void 0)) throw Error(`A preload entry needs exactly one of \`name\` (load by name) or \`url\` (load a file): ${_(e)}`);
+	return n ? d(t) : f(t);
+}
+function u(e) {
+	if (typeof e != "object" || !e || Array.isArray(e)) throw Error(`Expected an object: ${_(e)}`);
+	let t = e;
+	g(t, ["allowUnsignedExtensions", "preload"], "The config");
+	let { allowUnsignedExtensions: n } = t;
+	if (n !== void 0 && typeof n != "boolean") throw Error(`\`allowUnsignedExtensions\` must be a boolean: ${_(n)}`);
+	let r = t.preload ?? [];
+	if (!Array.isArray(r)) throw Error(`\`preload\` must be an array: ${_(r)}`);
+	let i = r.map((e, t) => {
+		try {
+			return l(e);
+		} catch (e) {
+			throw Error(`preload[${t}]: ${v(e)}`);
+		}
+	});
+	return n === void 0 ? { preload: i } : {
+		allowUnsignedExtensions: n,
+		preload: i
+	};
+}
+function d(e) {
+	g(e, ["name", "repository"], "A name preload entry");
+	let t = h(e.name, "`name`"), { repository: i } = e;
+	if (i === void 0) return { name: t };
+	if (typeof i == "string") {
+		let e = i.toLowerCase();
+		if (r.has(e)) return {
+			name: t,
+			repository: e
+		};
+		if (n.test(i)) return {
+			name: t,
+			repository: i
+		};
+	}
+	throw Error(`\`repository\` must be 'community', 'core' or an http(s) URL without quotes: ${_(i)}`);
+}
+function f(e) {
+	g(e, ["url", "release"], "A url preload entry");
+	let n = e.url;
+	if (typeof n != "string" || !a.test(n)) throw Error(`\`url\` must be a file path or http(s) URL without quotes, whitespace or backslashes: ${_(n)}`);
+	let r = s(n);
+	if (!r && o.test(n)) throw Error(`\`url\` must be a site-relative path or an http(s) URL: ${_(n)}`);
+	let i = r ? n : p(n);
+	if (!t.test(c(i))) throw Error(`The last path segment of \`url\` must start with the extension name before its first dot (that base names the entry symbol, e.g. duckfn.duckdb_extension.wasm): ${i}`);
+	let { release: l } = e;
+	if (l === void 0) return { url: i };
+	if (r) throw Error(`\`release\` copies the asset into the site's static directory, so \`url\` has to be site-relative: ${i}`);
+	return {
+		url: i,
+		release: m(l)
+	};
+}
+function p(e) {
+	if (e.startsWith("//")) throw Error(`Protocol-relative URLs are not supported: ${e}`);
+	let t = e.replace(/^\/+/, ""), n = t.split("/");
+	if (t === "" || n.some((e) => e === "" || e === "." || e === "..")) throw Error(`\`url\` must be a plain site-relative file path: ${e}`);
+	return t;
+}
+function m(e) {
+	if (typeof e != "object" || !e || Array.isArray(e)) throw Error(`\`release\` must be {repository, asset}: ${_(e)}`);
+	let t = e;
+	g(t, ["repository", "asset"], "`release`");
+	let { repository: n, asset: r } = t;
+	if (typeof n != "string" || !i.test(n)) throw Error(`\`release.repository\` must look like 'owner/name': ${_(n)}`);
+	if (typeof r != "string" || !a.test(r) || r.includes("/")) throw Error(`\`release.asset\` is the release asset's file name (no slashes): ${_(r)}`);
+	return {
+		repository: n,
+		asset: r
+	};
+}
+function h(e, n) {
+	if (typeof e != "string" || !t.test(e)) throw Error(`${n} must be a bare SQL identifier ([a-z][a-z0-9_]*): ${_(e)}`);
+	return e;
+}
+function g(e, t, n) {
+	for (let r of Object.keys(e)) if (!t.includes(r)) throw Error(`${n} has an unknown key \`${r}\` (expected: ${t.join(" / ")})`);
+}
+function _(e) {
+	try {
+		return JSON.stringify(e) ?? String(e);
+	} catch {
+		return String(e);
+	}
+}
+function v(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
+export { c as a, u as c, n as i, t as n, s as o, r, l as s, e as t };

package/dist/sql/DfkSql.d.ts

@@ -0,0 +1,7 @@
+import { HTMLElementBase } from '../dom';
+export declare class DfkSql extends HTMLElementBase {
+    #private;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}

package/dist/sql/PreviewTabs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Every renderer's result shell: a tab strip plus the panels behind it.
+ *
+ * The strip is one tab per preview row plus a `Table` tab that always comes
+ * **last**; a renderer with a single view passes no items at all, so a plain
+ * table result is a strip holding nothing but that trailing `Table` tab. Every
+ * result therefore has the same chrome — which is where the fullscreen toggle
+ * lives.
+ *
+ * Retained mode: every button and panel is built in the constructor and held in
+ * a field. Activating a tab mutates the nodes it owns (`hidden`, `classList`,
+ * `aria-selected`, `tabIndex`) — there is no rebuild, and a panel is filled the
+ * first time it is shown rather than up front.
+ *
+ * The table panel is mounted on first activation on purpose: VTable measures
+ * its container when it is constructed, and a `hidden` panel measures to zero.
+ */
+/** One preview row: its tab label and how to fill its panel. */
+export interface PreviewTabItem {
+    label: string;
+    mount(panel: HTMLElement): void;
+}
+/** What `PreviewTabs` needs from the caller to own the trailing table tab. */
+export interface PreviewTableHandle {
+    dispose(): void;
+}
+export declare class PreviewTabs {
+    #private;
+    /**
+     * @param corner Node parked at the right end of the strip, outside the
+     * scrolling tab list. `<dfk-sql>` passes its fullscreen toggle: it owns that
+     * button's state, so it owns the node and only lends it here.
+     */
+    constructor(host: HTMLElement, items: readonly PreviewTabItem[], tableLabel: string, mountTable: (panel: HTMLElement) => Promise<PreviewTableHandle>, corner?: HTMLElement);
+    /** Releases the table (if it was ever shown) and empties every panel. */
+    dispose(): void;
+}

package/dist/sql/client.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sql/client.js

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

package/dist/sql/editor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The CodeMirror 6 editor that *is* the code view of a runnable SQL block.
+ *
+ * Every CodeMirror module arrives through dynamic `import()` inside
+ * {@link mountSqlEditor}: a page full of SQL examples pays nothing for the
+ * editor on its critical path, and Docusaurus' Node prerender never evaluates
+ * any of it.
+ */
+export interface SqlEditor {
+    getValue(): string;
+    setValue(value: string): void;
+    /** Soft-wraps long lines, or stops wrapping them (the block's wrap toggle). */
+    setWrap(wrapped: boolean): void;
+    destroy(): void;
+}
+export declare function mountSqlEditor(container: HTMLElement, value: string, onChange: (value: string) => void): Promise<SqlEditor>;

package/dist/sql/extensions.d.ts

@@ -0,0 +1,108 @@
+import { type PreloadEntry } from './runtimeConfig';
+/**
+ * `duckfn-docs-kit/sql/extensions` — the Docusaurus plugin behind the
+ * runnable-SQL examples' extensions.
+ *
+ * It does two things, both driven by one ordered `preload` list configured in
+ * `docusaurus.config.ts`:
+ *
+ * 1. At startup (dev server and build alike) it fetches every `release`
+ *    source from that GitHub repository's **latest** release into the site's
+ *    `static/` directory, where the file is then served same-origin.
+ *    Downloads are cached locally and only re-fetched when the release
+ *    asset's sha256 differs (GitHub's own `digest` field is the comparison).
+ * 2. It injects the resolved preload list as one JSON `<script>` tag into
+ *    every page; the browser runtime (`sql/runtime`) reads it once and loads
+ *    the extensions in order while the DuckDB instance initialises.
+ *
+ * It also injects the kit's client bootstrap (`sql/client.ts`) on every page
+ * through `getClientModules()`: docs pages never import the kit's React tree,
+ * so the `dfk-*` element registration has to come from a client module — and
+ * it comes from here, not from a file the site keeps by hand.
+ *
+ * The site-relative `url` of an entry doubles as the fetch destination *and*
+ * the runtime path, so the two can never drift: with baseUrl `/duckfn/`,
+ * `duckdb-extensions/duckfn.duckdb_extension.wasm` lands in
+ * `<siteDir>/static/duckdb-extensions/duckfn.duckdb_extension.wasm` and is
+ * preloaded from `/duckfn/duckdb-extensions/duckfn.duckdb_extension.wasm`.
+ * (Docusaurus serves `static/` under each locale's baseUrl, so the localized
+ * value from the plugin context is the right prefix for every build.)
+ *
+ * This is Node-side build code: it must not import any browser module, and
+ * the browser side must not import this file (the shared contract lives in
+ * `./runtimeConfig`).
+ */
+/**
+ * The slice of Docusaurus' plugin API this module touches, typed structurally
+ * instead of importing `@docusaurus/types`: the kit stays free of Docusaurus
+ * dependencies, and the consuming site's own typecheck proves compatibility
+ * when the returned module lands in its `plugins` list.
+ */
+export interface DfkExtensionsContext {
+    siteDir: string;
+    siteConfig: {
+        baseUrl: string;
+    };
+}
+interface DfkHtmlTag {
+    tagName: string;
+    attributes: Record<string, string>;
+    innerHTML: string;
+}
+export interface DfkExtensionsPlugin {
+    name: string;
+    getClientModules(): string[];
+    loadContent(): Promise<void>;
+    injectHtmlTags(): {
+        headTags: DfkHtmlTag[];
+    };
+}
+/** The plugin module Docusaurus calls with its `LoadContext` and options. */
+export type DfkExtensionsPluginModule = (context: DfkExtensionsContext) => DfkExtensionsPlugin;
+/** Options for {@link dfkExtensions}. */
+export interface DfkExtensionsOptions {
+    /**
+     * The ordered list of extensions every page preloads while the shared
+     * DuckDB instance initialises — official names, `{name, repository}`
+     * entries, or `{url}` files (optionally fetched from a GitHub release).
+     * See `PreloadEntry` in `./runtimeConfig` for the exact shapes.
+     */
+    preload?: PreloadEntry[];
+    /**
+     * Let `LOAD` accept extensions whose signature does not verify. Needed
+     * whenever a preloaded file is not signed with DuckDB's keys — the GitHub
+     * release assets of a third-party extension are not — and merged with the
+     * per-block setting of whichever block initialises the runtime first.
+     */
+    allowUnsignedExtensions?: boolean;
+    /**
+     * Where release assets are cached between builds. Relative paths resolve
+     * against the Docusaurus site directory; defaults to
+     * `<siteDir>/.cache/duckfn-docs-kit`.
+     */
+    cacheDir?: string;
+    /** A GitHub token for the release API (rate limits, private repositories). Defaults to `process.env.GITHUB_TOKEN`. */
+    token?: string;
+}
+/**
+ * Builds the Docusaurus plugin. Usage in `docusaurus.config.ts`:
+ *
+ * ```ts
+ * import {dfkExtensions} from 'duckfn-docs-kit/sql/extensions';
+ *
+ * plugins: [
+ *   dfkExtensions({
+ *     allowUnsignedExtensions: true,
+ *     preload: [
+ *       {name: 'inet'},
+ *       {
+ *         url: 'duckdb-extensions/duckfn.duckdb_extension.wasm',
+ *         release: {repository: 'shijianjs/duckfn', asset: 'duckfn-wasm_eh.duckdb_extension.wasm'},
+ *       },
+ *     ],
+ *   }),
+ * ],
+ * ```
+ */
+export declare function dfkExtensions(options?: DfkExtensionsOptions): DfkExtensionsPluginModule;
+export {};

package/dist/sql/extensions.js

@@ -0,0 +1,198 @@
+import { o as e, s as t, t as n } from "../runtimeConfig-Bokbb8VH.js";
+import { createRequire as r } from "node:module";
+import i from "node:path";
+import { createHash as a } from "node:crypto";
+import { mkdir as o, readFile as s, rename as c, stat as l, unlink as u, writeFile as d } from "node:fs/promises";
+//#region src/sql/extensions.ts
+var f = "[dfk-extensions] ";
+function p(a = {}) {
+	let { allowUnsignedExtensions: o = !1, preload: s = [], cacheDir: c, token: l = process.env.GITHUB_TOKEN } = a, u = null, d = () => (u ??= {
+		...o ? { allowUnsignedExtensions: !0 } : {},
+		preload: s.map((e, n) => {
+			try {
+				return t(e);
+			} catch (e) {
+				throw Error(`duckfn-docs-kit preload[${n}]: ${M(e)}`);
+			}
+		})
+	}, u);
+	return (t) => ({
+		name: "dfk-extensions",
+		getClientModules() {
+			return [r(i.join(t.siteDir, "package.json")).resolve("duckfn-docs-kit/sql/client")];
+		},
+		async loadContent() {
+			let n = d(), { siteDir: r } = t, a = i.resolve(r, c ?? ".cache/duckfn-docs-kit");
+			for (let t of n.preload) {
+				if (typeof t == "string" || !("url" in t)) continue;
+				let n = i.join(r, "static", t.url), o = `static/${t.url}`;
+				if (t.release) await m(t.release, {
+					dest: n,
+					label: o,
+					cacheRoot: a,
+					token: l
+				});
+				else if (!e(t.url) && !await A(n)) throw Error(`${f}preload url "${t.url}" has no file: place the file under static/${t.url}, or point the entry at a GitHub release source`);
+			}
+		},
+		injectHtmlTags() {
+			let e = d();
+			if (!e.allowUnsignedExtensions && e.preload.length === 0) return { headTags: [] };
+			let r = {
+				...e,
+				preload: e.preload.map((e) => O(e, t.siteConfig.baseUrl))
+			};
+			return { headTags: [{
+				tagName: "script",
+				attributes: {
+					id: n,
+					type: "application/json"
+				},
+				innerHTML: JSON.stringify(r).replaceAll("<", "\\u003c")
+			}] };
+		}
+	});
+}
+async function m(e, t) {
+	let { dest: n, label: r, cacheRoot: i, token: a } = t, o = (t) => console.log(`${f}${e.repository}#${e.asset}: ${t}`), s = await h(e, {
+		cacheRoot: i,
+		token: a,
+		log: o
+	});
+	await E(n, s.bytes, s.sha256, o, r);
+}
+async function h(e, t) {
+	let { cacheRoot: n, token: r, log: i } = t, a = C(n, e), o = await w(a), s = (t) => {
+		if (!o) throw t;
+		return console.warn(`${f}${e.repository}#${e.asset}: ${M(t)} — using the cached copy (${j(o.sha256)})`), o;
+	}, c;
+	try {
+		c = await _(e.repository, r);
+	} catch (e) {
+		return s(e);
+	}
+	let l = v(c, e), u = x(l.digest);
+	if (o && u !== null && o.sha256 === u) return i(`up to date (${j(u)})`), o;
+	i(`downloading${c.tag_name ? ` ${c.tag_name}` : ""}…`);
+	let d;
+	try {
+		d = await y(l, r);
+	} catch (e) {
+		return s(e);
+	}
+	let p = S(d);
+	if (u !== null && p !== u) throw Error(`${f}${e.repository}#${e.asset}: sha256 mismatch, expected ${u}, downloaded ${p}`);
+	let m = c.tag_name ?? "";
+	return await T(a, d, p, m), i(`cached ${j(p)}`), {
+		bytes: d,
+		sha256: p,
+		tag: m
+	};
+}
+var g = "https://api.github.com";
+async function _(e, t) {
+	let n = b(t, "application/vnd.github+json"), r = await fetch(`${g}/repos/${e}/releases/latest`, { headers: n });
+	if (!r.ok) throw Error(`GitHub API ${r.status} for ${e}: ${(await r.text()).slice(0, 200)}`);
+	return await r.json();
+}
+function v(e, t) {
+	let n = e.assets ?? [], r = n.find((e) => e.name === t.asset);
+	if (!r || typeof r.browser_download_url != "string") {
+		let r = n.map((e) => e.name).filter(Boolean).join(", ") || "none";
+		throw Error(`${f}release ${e.tag_name ?? "?"} of ${t.repository} has no asset "${t.asset}" (available: ${r})`);
+	}
+	return r;
+}
+async function y(e, t) {
+	let n = await fetch(e.browser_download_url, {
+		headers: b(t, "application/octet-stream"),
+		redirect: "follow"
+	});
+	if (!n.ok) throw Error(`asset download failed with ${n.status}: ${e.browser_download_url}`);
+	return Buffer.from(await n.arrayBuffer());
+}
+function b(e, t) {
+	let n = {
+		Accept: t,
+		"User-Agent": "duckfn-docs-kit",
+		"X-GitHub-Api-Version": "2022-11-28"
+	};
+	return e && (n.Authorization = `Bearer ${e}`), n;
+}
+function x(e) {
+	if (typeof e != "string") return null;
+	let [t, n] = e.split(":");
+	return t !== "sha256" || n === void 0 || !/^[0-9a-f]{64}$/i.test(n) ? null : n.toLowerCase();
+}
+function S(e) {
+	return a("sha256").update(e).digest("hex");
+}
+function C(e, t) {
+	let n = i.join(e, t.repository.replace("/", "__"));
+	return {
+		file: i.join(n, t.asset),
+		meta: i.join(n, `${t.asset}.json`)
+	};
+}
+async function w(e) {
+	try {
+		let [t, n] = await Promise.all([s(e.file), s(e.meta, "utf8")]), r = JSON.parse(n);
+		return typeof r.sha256 != "string" || !/^[0-9a-f]{64}$/.test(r.sha256) ? null : {
+			bytes: t,
+			sha256: r.sha256,
+			tag: r.tag ?? ""
+		};
+	} catch {
+		return null;
+	}
+}
+async function T(e, t, n, r) {
+	await o(i.dirname(e.file), { recursive: !0 }), await D(e.file, t);
+	let a = {
+		sha256: n,
+		tag: r,
+		fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await D(e.meta, Buffer.from(`${JSON.stringify(a, null, 2)}\n`));
+}
+async function E(e, t, n, r, a) {
+	let c = await s(e).catch(() => null);
+	if (c && S(c) === n) {
+		r(`${a} up to date`);
+		return;
+	}
+	await o(i.dirname(e), { recursive: !0 }), await D(e, t), r(`wrote ${a} (${t.length} bytes)`);
+}
+async function D(e, t) {
+	let n = `${e}.tmp-${process.pid.toString(36)}-${Date.now().toString(36)}`;
+	await d(n, t);
+	for (let t = 1;; t += 1) try {
+		await c(n, e);
+		return;
+	} catch (e) {
+		if (t >= 3) throw await u(n).catch(() => void 0), e;
+		await new Promise((e) => setTimeout(e, 50 * t));
+	}
+}
+function O(t, n) {
+	return typeof t == "string" || !("url" in t) ? t : e(t.url) ? { url: t.url } : { url: k(n, t.url) };
+}
+function k(e, t) {
+	let n = e.replace(/^\/+|\/+$/g, "");
+	return n === "" ? `/${t}` : `/${n}/${t}`;
+}
+async function A(e) {
+	try {
+		return await l(e), !0;
+	} catch {
+		return !1;
+	}
+}
+function j(e) {
+	return e.slice(0, 12);
+}
+function M(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
+export { p as dfkExtensions };

package/dist/sql/remark.d.ts

@@ -0,0 +1,88 @@
+import type { Plugin } from 'unified';
+/**
+ * Turns a fenced SQL block whose metastring is a JSON config with
+ * `{"type":"duckfn", …}` into a `<dfk-sql>` custom element, so the docs site
+ * can render it as a runnable example.
+ *
+ * The original `code` node is kept as the element's *child*: Docusaurus'
+ * `codeCompatPlugin` still stamps `metastring` onto it and the classic theme
+ * renders it as a regular `@theme/CodeBlock`. That child is the block's
+ * prerendered text and nothing else — `<dfk-sql>` has no default slot and hides
+ * unslotted children through CSS, because the code view is a CodeMirror editor.
+ * The SQL text and the parsed config travel as string attributes (`sql` /
+ * `config`) — React 19 reconciles string props onto custom elements as
+ * attributes, so they survive prerendering and hydration.
+ *
+ * The element also gets a prerendered *placeholder* (see {@link skeleton}): one
+ * bar per line of the SQL, which is what the reader sees before this package's
+ * JS arrives and `<dfk-sql>` upgrades.
+ *
+ * Unlike Docusaurus' own `key=value` metastring format, the config here is
+ * JSON, which allows nested fields (`option: {…}`) for future renderers.
+ *
+ * This is Node-side build code: it must not touch `window` / `document`, and it
+ * must not import any browser module (type-only imports are fine).
+ */
+/** The JSON payload written after the info string of a runnable SQL block. */
+export interface RunnableSqlConfig {
+    /** Marks the block as a duckfn runnable example; the only value today. */
+    type: 'duckfn';
+    /**
+     * Which result renderer to use. Defaults to `table` at runtime, except that a
+     * single-column single-row result degrades to `text` (a bare scalar reads
+     * better as a line than as a 1×1 table).
+     *
+     * `html` and `iframe` are the same renderer: both sandbox the markup in an
+     * iframe, so scripts run with an opaque origin.
+     */
+    show?: 'table' | 'html' | 'iframe' | 'svg' | 'text';
+    /**
+     * The column holding the markup, for the preview renderers. A single-column
+     * result is unambiguous and is used as-is.
+     */
+    field?: string;
+    /** The column to label each preview tab with; falls back to `Row N`. */
+    tab_name?: string;
+    /** Presentation knobs for the preview renderers; see `option.width` etc. */
+    option?: {
+        /** CSS length for the preview box (e.g. `'100%'`, `'640px'`). */
+        width?: string;
+        height?: string;
+        /**
+         * `sandbox` tokens for the `iframe` renderer, replacing the default
+         * `allow-scripts`. Only set this to *widen* what the report may do — the
+         * default deliberately omits `allow-same-origin`.
+         */
+        sandbox?: string;
+    };
+    /**
+     * duckfn community extensions to `LOAD` before running the block. The kit
+     * never hard-codes an extension name; the docs source names what it needs.
+     */
+    extensions?: string[];
+    /** A repository serving the extensions, instead of the DuckDB default. */
+    repository?: string;
+    /**
+     * Allows `LOAD` to accept extensions without a valid signature. Opt-in
+     * per block, and only meaningful for the *first* block that initialises the
+     * shared runtime — `open()` fixes it for the instance.
+     */
+    allowUnsignedExtensions?: boolean;
+    /**
+     * Forward-compatible fields: the remark plugin passes the whole object
+     * through untouched, so a newer kit version can read new keys without the
+     * docs source changing.
+     */
+    [key: string]: unknown;
+}
+export interface RunnableSqlOptions {
+    /**
+     * Reserved for future remark-level options (kept so sites passing an empty
+     * options object keep typechecking). Site-wide extension preloading is
+     * configured on the `dfkExtensions` plugin (`sql/extensions`), not here.
+     */
+    [key: string]: unknown;
+}
+/** The custom element the plugin emits; must match `register.ts`. */
+export declare const DFK_SQL_TAG = "dfk-sql";
+export declare const remarkRunnableSql: Plugin<[RunnableSqlOptions?]>;