@liebstoeckel/engine 0.3.5

package/src/build/licenses.ts

@@ -0,0 +1,336 @@
+// Bundle-time third-party license collection.
+//
+// A built deck inlines its client import graph, React, Motion, Yjs, the variable
+// fonts, into one minified `.html`. Every one of those licenses (MIT, OFL-1.1, and
+// our own MPL-2.0) requires its notice to travel with the redistributed code, but
+// `minify:true` strips all comments. So we recompute the notice from the *actual*
+// module graph of each build and embed it as an inert <script> (same minify-proof
+// carrier as `embedSource`/`embedManifest`). Recomputing per build is the point:
+// swap a font or add a chart lib and the notice updates itself, declared
+// package.json deps would lie. Everything here is Bun-native (no new dependency).
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+
+/** Inert <script> carrier, the browser never parses it (mirrors SOURCE_ATTR). */
+export const LICENSE_ATTR = "data-liebstoeckel-licenses";
+
+const NODE_MODULES = `${sep}node_modules${sep}`;
+const FIRST_PARTY = "@liebstoeckel/";
+
+/** SPDX ids we consider satisfiable by attribution alone (no copyleft/source duties
+ *  beyond shipping the notice, which we do). `licenses --check` fails on anything
+ *  outside this set, a GPL/AGPL/CC-BY/unknown dep should be a loud build-time stop,
+ *  not a silent ship. OFL-1.1 is here because we only ever *embed* fonts (allowed),
+ *  never sell them standalone; MPL-2.0 is our own + build-tool-only deps. */
+export const ALLOWED_SPDX = new Set([
+  "MIT",
+  "MIT-0",
+  "ISC",
+  "0BSD",
+  "BSD-2-Clause",
+  "BSD-3-Clause",
+  "Apache-2.0",
+  "BlueOak-1.0.0",
+  "Unlicense",
+  "CC0-1.0",
+  "Python-2.0",
+  "OFL-1.1",
+  "MPL-2.0",
+]);
+
+export interface LicensePackage {
+  name: string;
+  version: string;
+  /** SPDX id (or expression) as declared in the package's package.json. */
+  license: string;
+  /** Verbatim LICENSE/COPYING text when the package ships one, else a synthesized
+   *  fallback (see `fallbackLicenseText`); null only if neither is available. */
+  text: string | null;
+  /** True when `text` came from a real file on disk (vs. an SPDX template). */
+  fromFile: boolean;
+}
+
+export interface LicenseReport {
+  /** Third-party packages whose code/assets landed in the bundle. */
+  packages: LicensePackage[];
+  /** @liebstoeckel/* packages that contributed (all MPL-2.0; reported once). */
+  firstParty: string[];
+  /** SPDX ids present that are NOT in ALLOWED_SPDX (drives `--check`). */
+  flagged: { name: string; version: string; license: string }[];
+}
+
+/** A recorder plugin + a `report()` that resolves the recorded paths to packages.
+ *  Add `plugin` to a `Bun.build({ plugins })` array; call `report()` after a
+ *  successful build. The plugin only observes (always returns undefined), so it
+ *  never alters resolution or loading. Proven to capture both JS modules and
+ *  CSS `url()` font assets (the resolved absolute path carries the version). */
+export function createLicenseCollector(opts: { selfName?: string } = {}): {
+  plugin: import("bun").BunPlugin;
+  report: () => LicenseReport;
+  /** @liebstoeckel/* packages that resolved to >1 version in the captured graph. */
+  conflicts: () => FirstPartyConflict[];
+} {
+  const paths = new Set<string>();
+  const record = (p: string | undefined) => {
+    // Only absolute, real on-disk paths map to a package; ignore bare specifiers,
+    // virtual modules (`\0`-prefixed), and data: URIs.
+    if (p && p.startsWith(sep) && !p.includes("\0")) paths.add(p);
+  };
+  // ONLY hook onLoad, never onResolve. A catch-all `onResolve` that returns undefined
+  // is NOT a no-op in Bun's bundler: registering it perturbs resolution enough to
+  // miscompile some modules under minification (observed: a deck importing `@visx/shape`
+  // built minified threw `ReferenceError: <mangled> is not defined` from d3-shape's stack
+  // code, because a declaration got dropped while its reference survived). `onLoad` with a
+  // catch-all filter that returns undefined IS inert, and its `args.path` is the resolved
+  // absolute path of every loaded module (including CSS `url()` font assets), so it
+  // captures the full graph (fonts included) without touching the output.
+  const plugin: import("bun").BunPlugin = {
+    name: "liebstoeckel-license-collector",
+    setup(build) {
+      build.onLoad({ filter: /.*/ }, (args) => {
+        record(args.path);
+        return undefined;
+      });
+    },
+  };
+  return {
+    plugin,
+    report: () => buildReport(paths, opts.selfName),
+    conflicts: () => firstPartyVersionConflicts(paths, opts.selfName),
+  };
+}
+
+/** A first-party package that resolved to more than one version in a single build's
+ *  module graph — i.e. two incompatible copies that would both be inlined. */
+export interface FirstPartyConflict {
+  name: string;
+  versions: string[];
+}
+
+/** Detect `@liebstoeckel/*` packages that appear at more than one version across the
+ *  bundled module graph. A deck inlines its whole import graph into one `.html`, so two
+ *  copies of e.g. `plugin-sdk` are two copies of the plugin↔host contract embedded side
+ *  by side — silently broken. This is the consumption-side guard for caret cross-deps:
+ *  a skewed/lagging plugin can pin an older sibling than `engine` resolves. A pure
+ *  reduction over the same paths the license collector already records (no extra build). */
+export function firstPartyVersionConflicts(paths: Iterable<string>, selfName?: string): FirstPartyConflict[] {
+  const versions = new Map<string, Set<string>>();
+  for (const p of paths) {
+    const pkgDir = nearestPackageDir(p);
+    if (!pkgDir) continue;
+    let meta: { name?: string; version?: string };
+    try {
+      meta = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+    } catch {
+      continue;
+    }
+    if (!meta.name || !meta.name.startsWith(FIRST_PARTY)) continue;
+    if (selfName && meta.name === selfName) continue;
+    let set = versions.get(meta.name);
+    if (!set) {
+      set = new Set();
+      versions.set(meta.name, set);
+    }
+    set.add(meta.version ?? "?");
+  }
+  const conflicts: FirstPartyConflict[] = [];
+  for (const [name, set] of versions) {
+    if (set.size > 1) conflicts.push({ name, versions: [...set].sort() });
+  }
+  return conflicts.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Loud, actionable message for a single-copy violation (used by `build`/`build --check`). */
+export function formatFirstPartyConflicts(conflicts: FirstPartyConflict[]): string {
+  const lines = conflicts.map((c) => `  ${c.name} → ${c.versions.join(", ")}`);
+  return (
+    "this deck bundles more than one version of a liebstoeckel package:\n" +
+    lines.join("\n") +
+    "\n\nA deck is inlined into one .html, so mixed versions ship duplicate, incompatible\n" +
+    "copies (e.g. two plugin-sdk runtimes) side by side. Update the framework packages\n" +
+    "together so each resolves to a single version (e.g. `bun update`), then rebuild."
+  );
+}
+
+/** Resolve a set of absolute file paths to their owning packages and build a report.
+ *  `selfName` (the deck's own package name) is excluded, a deck never lists itself.
+ *  Exported for the CLI's collect-from-dir path and for tests. */
+export function buildReport(paths: Iterable<string>, selfName?: string): LicenseReport {
+  const thirdParty = new Map<string, LicensePackage>(); // name@version → pkg
+  const firstParty = new Set<string>();
+  const flagged: LicenseReport["flagged"] = [];
+
+  for (const p of paths) {
+    const pkgDir = nearestPackageDir(p);
+    if (!pkgDir) continue;
+    let meta: { name?: string; version?: string; license?: string; author?: unknown };
+    try {
+      meta = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+    } catch {
+      continue;
+    }
+    if (!meta.name) continue;
+    if (selfName && meta.name === selfName) continue; // the deck never lists itself
+
+    // First-party (@liebstoeckel/*) by name, works whether they resolve to the
+    // monorepo's packages/*/src or to an installed node_modules/.bun/@liebstoeckel+*.
+    if (meta.name.startsWith(FIRST_PARTY)) {
+      firstParty.add(meta.name); // all MPL-2.0, reported once
+      continue;
+    }
+    // Everything else is third-party only if it lives under node_modules; a local
+    // dir that isn't @liebstoeckel is the deck's own source, skip it.
+    if (!p.includes(NODE_MODULES)) continue;
+    const key = `${meta.name}@${meta.version ?? "?"}`;
+    if (thirdParty.has(key)) continue;
+
+    const license = normalizeLicense(meta.license);
+    const { text, fromFile } = readLicense(pkgDir, license, meta);
+    thirdParty.set(key, { name: meta.name, version: meta.version ?? "?", license, text, fromFile });
+    if (!spdxAllowed(license)) flagged.push({ name: meta.name, version: meta.version ?? "?", license });
+  }
+
+  const packages = [...thirdParty.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return { packages, firstParty: [...firstParty].sort(), flagged };
+}
+
+/** Walk up from a file to the nearest directory containing a package.json. Stops at
+ *  a `node_modules`-segment boundary's package so a nested dep maps to itself. */
+function nearestPackageDir(file: string): string | null {
+  let dir = dirname(file);
+  // bound the walk; deep node_modules nesting is still shallow in practice
+  for (let i = 0; i < 50; i++) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Reduce package.json `license`/`licenses` to an SPDX id/expression string. */
+export function normalizeLicense(license: unknown): string {
+  if (typeof license === "string") return license;
+  if (license && typeof license === "object") {
+    const l = license as { type?: string };
+    if (l.type) return l.type;
+  }
+  if (Array.isArray(license)) {
+    return (license as { type?: string }[]).map((l) => l.type ?? "UNKNOWN").join(" OR ");
+  }
+  return "UNKNOWN";
+}
+
+/** True if every required term of an SPDX expression is in ALLOWED_SPDX. For an
+ *  `OR` expression, one allowed term suffices; for `AND` (and bare ids), all must
+ *  be allowed. Parenthesised/compound expressions fall back to "all terms allowed". */
+export function spdxAllowed(expr: string): boolean {
+  const ids = expr.match(/[A-Za-z0-9.+-]+/g)?.filter((t) => !/^(OR|AND|WITH)$/i.test(t)) ?? [];
+  if (ids.length === 0) return false;
+  const allowed = (id: string) => ALLOWED_SPDX.has(id);
+  if (/\bOR\b/i.test(expr)) return ids.some(allowed);
+  return ids.every(allowed);
+}
+
+const LICENSE_FILES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "LICENCE", "LICENCE.md", "COPYING", "COPYING.md"];
+
+function readLicense(
+  pkgDir: string,
+  license: string,
+  meta: { name?: string; version?: string; author?: unknown },
+): { text: string | null; fromFile: boolean } {
+  for (const f of LICENSE_FILES) {
+    const path = join(pkgDir, f);
+    if (existsSync(path)) {
+      try {
+        return { text: readFileSync(path, "utf8").trim(), fromFile: true };
+      } catch {
+        /* fall through */
+      }
+    }
+  }
+  // some packages name it LICENSE-MIT etc.
+  try {
+    const alt = readdirSync(pkgDir).find((n) => /^licen[cs]e/i.test(n));
+    if (alt) return { text: readFileSync(join(pkgDir, alt), "utf8").trim(), fromFile: true };
+  } catch {
+    /* ignore */
+  }
+  return { text: fallbackLicenseText(license, meta), fromFile: false };
+}
+
+/** Authorship line for templated short licenses (MIT/ISC/BSD). */
+function copyrightHolder(meta: { author?: unknown }): string {
+  const a = meta.author as string | { name?: string } | undefined;
+  if (typeof a === "string") return a.replace(/\s*<[^>]*>/, "").replace(/\s*\([^)]*\)/, "").trim();
+  if (a && typeof a === "object" && a.name) return a.name;
+  return "the authors";
+}
+
+/** Short SPDX templates for the permissive licenses that occasionally ship no
+ *  LICENSE file. Longer licenses (Apache-2.0, MPL-2.0, OFL-1.1) effectively always
+ *  ship their own file in practice; if one ever doesn't we record the SPDX id +
+ *  canonical URL rather than inline several KB of boilerplate per package. */
+export function fallbackLicenseText(license: string, meta: { author?: unknown }): string | null {
+  const holder = copyrightHolder(meta);
+  const id = license.trim();
+  if (id === "MIT" || id === "ISC") {
+    const grant =
+      id === "MIT"
+        ? `Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.`
+        : `Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.`;
+    return `${id} License\n\nCopyright (c) ${holder}\n\n${grant}\n\nTHE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.`;
+  }
+  if (id === "0BSD") {
+    return `BSD Zero Clause License\n\nCopyright (c) ${holder}\n\nPermission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.\n\nTHE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE.`;
+  }
+  const url = `https://spdx.org/licenses/${encodeURIComponent(id)}.html`;
+  return `${id}\n\nCopyright (c) ${holder}\nFull license text: ${url}`;
+}
+
+export interface RenderOptions {
+  /** First-party notice prepended verbatim (our MPL-2.0 line + source URL). */
+  selfNotice?: string;
+}
+
+const DIVIDER = "\n\n" + "-".repeat(72) + "\n\n";
+
+/** Render the human-readable THIRD_PARTY_NOTICES text from a report. */
+export function renderNotices(report: LicenseReport, opts: RenderOptions = {}): string {
+  const parts: string[] = [];
+  parts.push(
+    "THIRD-PARTY SOFTWARE NOTICES\n\n" +
+      "This file is generated at build time from the modules actually bundled into\n" +
+      "this presentation. It is regenerated on every build, so it reflects exactly\n" +
+      "the third-party code and fonts embedded in this .html file.",
+  );
+  if (opts.selfNotice) parts.push(opts.selfNotice.trim());
+  if (report.firstParty.length) {
+    parts.push(
+      "liebstoeckel framework packages (MPL-2.0):\n  " +
+        report.firstParty.join("\n  ") +
+        "\nSource: https://github.com/liebstoeckel/liebstoeckel",
+    );
+  }
+  for (const p of report.packages) {
+    const header = `${p.name}@${p.version} ,  ${p.license}`;
+    parts.push(p.text ? `${header}\n\n${p.text}` : header);
+  }
+  return parts.join(DIVIDER) + "\n";
+}
+
+/** Embed the notices as an inert <script> before the last </body> (same insertion
+ *  rule and rationale as embedSource: survives minification, immune to the
+ *  `</body>`-in-a-literal hazard since the payload is plain text we control). */
+export function embedLicenses(html: string, notices: string): string {
+  const tag = `<script type="text/plain" ${LICENSE_ATTR}>\n${notices}\n</script>`;
+  const at = html.lastIndexOf("</body>");
+  return at >= 0 ? html.slice(0, at) + tag + html.slice(at) : html + tag;
+}
+
+/** Read an embedded notices block back, or null if the HTML carries none. */
+export function extractLicenses(html: string): string | null {
+  const re = new RegExp(`<script[^>]*${LICENSE_ATTR}[^>]*>([\\s\\S]*?)</script>`, "i");
+  const m = html.match(re);
+  return m ? m[1]!.trim() : null;
+}

package/src/build/mdx-plugin.ts

@@ -0,0 +1,30 @@
+import type { BunPlugin } from "bun";
+import { compile } from "@mdx-js/mdx";
+import rehypeShiki from "@shikijs/rehype";
+import { createCssVariablesTheme } from "shiki";
+
+// Fenced code blocks are highlighted at build time with Shiki's css-variables
+// theme: each token gets color:var(--shiki-token-*), which @liebstoeckel/theme binds
+// to the active brand. No highlighter/grammars/WASM ship to the browser.
+const codeTheme = createCssVariablesTheme({ name: "brand", variablePrefix: "--shiki-", fontStyle: true });
+
+// Compiles `.mdx` → JS using the automatic React runtime. providerImportSource
+// wires MDX elements to <MDXProvider> components. Works in Bun.build() and, when
+// referenced from bunfig [serve.static].plugins, in the HMR dev server.
+const mdxPlugin: BunPlugin = {
+  name: "mdx",
+  setup(build) {
+    build.onLoad({ filter: /\.mdx$/ }, async (args) => {
+      const source = await Bun.file(args.path).text();
+      const compiled = await compile(source, {
+        jsxImportSource: "react",
+        providerImportSource: "@mdx-js/react",
+        development: false,
+        rehypePlugins: [[rehypeShiki, { theme: codeTheme }]],
+      });
+      return { contents: String(compiled), loader: "js" };
+    });
+  },
+};
+
+export default mdxPlugin;

package/src/build/source-attr.ts

@@ -0,0 +1,4 @@
+/** Inert <script> carrier attribute for the embedded deck source package (eject).
+ *  Lives in its own zero-dependency module so browser runtime (`../source.ts`) can
+ *  read it without pulling in the Bun/node-only packer in `source-package.ts`. */
+export const SOURCE_ATTR = "data-liebstoeckel-source";

package/src/build/source-package.ts

@@ -0,0 +1,210 @@
+import { $ } from "bun";
+import { mkdtempSync, mkdirSync, rmSync, readdirSync, copyFileSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { SOURCE_ATTR } from "./source-attr";
+
+// Inline source package (ADR 0039): the single-file deck carries a compressed copy of
+// its own source so a compiled `.html` can be ejected back to an editable project.
+// Collection reuses `bun pm pack` (npm's real ignore algorithm + `files` allowlist),
+// then repacks gzip→zstd for the in-HTML embed. Everything here is Bun-native (no deps),
+// so the engine never grows a dependency for this.
+
+/** Inert <script> carrier, mirrors plugin-sdk's `embedManifest` (browser never parses it).
+ *  Defined in `source-attr.ts` so browser runtime can read it without this packer. */
+export { SOURCE_ATTR };
+
+// Fail-closed gate: pack's default-ignore table misses bare `.env`/`.env.local` (only
+// `.env.production`), so we add our own net + a best-effort secret-content scan.
+const ENV_FILE = /(^|\/)\.env($|\.)/i;
+const SECRET_SIGNATURE =
+  /-----BEGIN [A-Z ]*PRIVATE KEY|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36}|sk-[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}/;
+
+// Eject is the untrusted-input path (an arbitrary HTML someone sent you). Bound the
+// decompression bomb surface the traversal check can't cover.
+const MAX_COMPRESSED = 8 * 1024 * 1024; // 8 MB of embedded base64-decoded zstd
+const MAX_DECOMPRESSED = 64 * 1024 * 1024; // 64 MB of tar
+const MAX_ENTRIES = 4000;
+
+const PACKAGE_PREFIX = "package/";
+
+export interface CollectOptions {
+  /** Force past the secret gate (loud, explicit). */
+  allowSecret?: boolean;
+}
+
+export interface DeckTarball {
+  /** pack's native gzip `.tgz` bytes, npm/`bun add`-compatible. */
+  gzip: Uint8Array<ArrayBuffer>;
+  /** repacked zstd of pack's (already-normalized) tar, the in-HTML embed payload. */
+  zstd: Uint8Array<ArrayBuffer>;
+  /** deck-relative paths in the package (the `package/` prefix stripped). */
+  files: string[];
+}
+
+/** Parse ustar entry names from a raw tar (Bun.Archive.files() is unusable; this also
+ *  lets the gate run off the exact bytes we embed, with no second pack invocation). */
+function tarEntryNames(tar: Uint8Array): string[] {
+  const names: string[] = [];
+  const dec = new TextDecoder();
+  for (let off = 0; off + 512 <= tar.length; ) {
+    const header = tar.subarray(off, off + 512);
+    if (header.every((b) => b === 0)) break; // end-of-archive zero blocks
+    const name = dec.decode(header.subarray(0, 100)).replace(/\0.*$/s, "");
+    if (!name) break;
+    const sizeOct = dec.decode(header.subarray(124, 136)).replace(/\0.*$/s, "").trim();
+    const size = parseInt(sizeOct, 8) || 0;
+    names.push(name);
+    off += 512 + Math.ceil(size / 512) * 512;
+  }
+  return names;
+}
+
+function looksBinary(bytes: Uint8Array): boolean {
+  const n = Math.min(bytes.length, 8000);
+  for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;
+  return false;
+}
+
+/** Run `bun pm pack` on a deck dir, gate the result, and repack gzip→zstd.
+ *  `--ignore-scripts` is a security control (pack runs prepack/prepare by default →
+ *  arbitrary code); the interpreter is pinned to the running Bun via `process.execPath`,
+ *  and `dir` reaches pack via `.cwd()` (never interpolated into the command). */
+export async function collectDeckTarball(dir: string, opts: CollectOptions = {}): Promise<DeckTarball> {
+  const work = mkdtempSync(join(tmpdir(), "lst-pack-"));
+  const tgzPath = join(work, "deck.tgz");
+  try {
+    const res = await $`${process.execPath} pm pack --ignore-scripts --quiet --filename ${tgzPath}`
+      .cwd(dir)
+      .quiet()
+      .nothrow();
+    if (res.exitCode !== 0 || !existsSync(tgzPath)) {
+      throw new Error(`\`bun pm pack\` failed in ${dir}:\n${res.stderr.toString() || res.stdout.toString()}`);
+    }
+
+    const gzip = new Uint8Array(await Bun.file(tgzPath).bytes());
+    const tar = Bun.gunzipSync(gzip);
+    const files = tarEntryNames(tar)
+      .filter((n) => n.startsWith(PACKAGE_PREFIX))
+      .map((n) => n.slice(PACKAGE_PREFIX.length))
+      .filter(Boolean);
+
+    // pack default-ignores bunfig.toml; if the deck has one but it wasn't packed (not in
+    // `files`), the ejected deck loses its dev-server plugins, warn, don't fail.
+    if (existsSync(join(dir, "bunfig.toml")) && !files.includes("bunfig.toml")) {
+      console.warn('⚠ bunfig.toml is not in the deck\'s "files", the ejected deck won\'t run in dev mode');
+    }
+
+    // ── fail-closed gate ──────────────────────────────────────────────
+    const violations: string[] = [];
+    for (const rel of files) {
+      if (ENV_FILE.test(rel)) {
+        violations.push(`${rel} (env file)`);
+        continue;
+      }
+      const abs = join(dir, rel);
+      if (!existsSync(abs)) continue;
+      const bytes = readFileSync(abs);
+      if (!looksBinary(bytes) && SECRET_SIGNATURE.test(bytes.toString("utf8"))) {
+        violations.push(`${rel} (secret signature)`);
+      }
+    }
+    if (violations.length && !opts.allowSecret) {
+      throw new Error(
+        `Refusing to embed source, likely secrets:\n  ${violations.join("\n  ")}\n` +
+          `Add a "files" allowlist (or .npmignore) to the deck's package.json, or pass --allow-secret.`,
+      );
+    }
+
+    // Preserve pack's reproducible tar (fixed mtimes); only swap the compressor.
+    // Re-taring via Bun.Archive.write would stamp wall-clock mtimes and break determinism.
+    const zstd = new Uint8Array(Bun.zstdCompressSync(tar));
+    return { gzip, zstd, files };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Embed the zstd source payload as an inert <script> before the last </body>
+ *  (same insertion rule as `embedManifest`: a deck's inlined JS can contain a literal
+ *  "</body>", and the real document terminator is the last one). */
+export function embedSource(html: string, zstd: Uint8Array): string {
+  const b64 = Buffer.from(zstd).toString("base64");
+  const tag = `<script type="application/octet-stream" ${SOURCE_ATTR} data-codec="zstd">${b64}</script>`;
+  const at = html.lastIndexOf("</body>");
+  return at >= 0 ? html.slice(0, at) + tag + html.slice(at) : html + tag;
+}
+
+/** Read the embedded zstd payload back, or null if the HTML carries no source package. */
+export function extractSource(html: string): Uint8Array | null {
+  const re = new RegExp(`<script[^>]*${SOURCE_ATTR}[^>]*>([\\s\\S]*?)</script>`, "i");
+  const m = html.match(re);
+  if (!m) return null;
+  try {
+    return Buffer.from(m[1]!.trim(), "base64");
+  } catch {
+    return null;
+  }
+}
+
+export interface EjectOptions {
+  /** allow extracting into a non-empty directory (default: refuse). */
+  force?: boolean;
+}
+
+/** Eject the embedded source to `outDir` (the `package/` prefix stripped), or throw a
+ *  clear error if the HTML has none. Untrusted-input hardened: size/entry caps against
+ *  decompression bombs + per-entry name validation on top of Bun.Archive's own clamping. */
+export async function ejectSource(html: string, outDir: string, opts: EjectOptions = {}): Promise<string[]> {
+  const zstd = extractSource(html);
+  if (!zstd) {
+    throw new Error(
+      "no embedded source package in this HTML, it was built with --no-inline-package " +
+        "(or by an older build). Rebuild without that flag to make the deck ejectable.",
+    );
+  }
+  if (zstd.length > MAX_COMPRESSED) throw new Error("embedded source package is implausibly large, refusing to eject");
+
+  const tar = Bun.zstdDecompressSync(zstd);
+  if (tar.length > MAX_DECOMPRESSED) throw new Error("decompressed source exceeds the size cap, refusing to eject");
+
+  const names = tarEntryNames(tar);
+  if (names.length > MAX_ENTRIES) throw new Error("source package has too many entries, refusing to eject");
+  for (const n of names) {
+    if (n.startsWith("/") || n.split("/").some((seg) => seg === "..")) {
+      throw new Error(`unsafe path in source package: ${n}`);
+    }
+  }
+
+  if (existsSync(outDir) && readdirSync(outDir).length > 0 && !opts.force) {
+    throw new Error(`${outDir} is not empty, pass force to overwrite`);
+  }
+
+  // Extract to a temp dir (Bun.Archive clamps traversal), then lift package/* into outDir.
+  const stage = mkdtempSync(join(tmpdir(), "lst-eject-"));
+  try {
+    const Archive = (Bun as unknown as { Archive: new (b: Uint8Array) => { extract(d: string): Promise<number> } }).Archive;
+    await new Archive(tar).extract(stage);
+    const root = join(stage, "package");
+    const src = existsSync(root) ? root : stage;
+    const written: string[] = [];
+    const lift = (from: string, rel: string) => {
+      for (const ent of readdirSync(from, { withFileTypes: true })) {
+        const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+        const dest = join(outDir, childRel);
+        if (ent.isDirectory()) {
+          lift(join(from, ent.name), childRel);
+        } else {
+          mkdirSync(dirname(dest), { recursive: true });
+          // copy (not rename): the stage temp may be on a different filesystem than outDir (EXDEV).
+          copyFileSync(join(from, ent.name), dest);
+          written.push(childRel);
+        }
+      }
+    };
+    lift(src, "");
+    return written.sort();
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+}

package/src/build/thumbnails.ts

@@ -0,0 +1,49 @@
+// A thumbnails manifest mirrors the plugin manifest: an inert JSON <script> the
+// browser never executes, embedded into the single-file deck. Each entry maps a
+// slide index to a data-URI image (built by @liebstoeckel/thumbnails). The engine
+// reads it to render cheap <img> previews in the overview / presenter instead of
+// mounting N live slides. Pure string/JSON helpers, no DOM, no browser.
+
+export interface ThumbnailManifest {
+  v: 1;
+  /** intrinsic pixel size of each thumbnail */
+  w: number;
+  h: number;
+  /** slide index → data-URI (e.g. "data:image/jpeg;base64,…") */
+  thumbs: Record<number, string>;
+}
+
+export const THUMBS_ATTR = "data-liebstoeckel-thumbnails";
+
+export const encodeThumbnails = (m: ThumbnailManifest): string => JSON.stringify(m);
+export const parseThumbnails = (json: string): ThumbnailManifest => JSON.parse(json) as ThumbnailManifest;
+
+/** Embed (or replace) the thumbnails manifest as an inert JSON <script> before
+ *  the closing </body>. Re-embedding strips any prior block so re-running is idempotent.
+ *  Inserts before the LAST </body>, a deck's inlined JS bundle can contain the string
+ *  "</body>" in a literal (e.g. an iframe srcdoc), and the real document </body> is last. */
+export function embedThumbnails(html: string, m: ThumbnailManifest): string {
+  const stripped = stripThumbnails(html);
+  const tag = `<script type="application/json" ${THUMBS_ATTR}>${encodeThumbnails(m)}</script>`;
+  const at = stripped.lastIndexOf("</body>");
+  return at >= 0 ? stripped.slice(0, at) + tag + stripped.slice(at) : stripped + tag;
+}
+
+const blockRe = new RegExp(`<script[^>]*${THUMBS_ATTR}[^>]*>[\\s\\S]*?</script>`, "i");
+
+/** Remove an embedded thumbnails block (if present). */
+export function stripThumbnails(html: string): string {
+  return html.replace(blockRe, "");
+}
+
+/** Extract the thumbnails manifest from a built HTML, or null if none/invalid. */
+export function extractThumbnails(html: string): ThumbnailManifest | null {
+  const re = new RegExp(`<script[^>]*${THUMBS_ATTR}[^>]*>([\\s\\S]*?)</script>`, "i");
+  const m = html.match(re);
+  if (!m) return null;
+  try {
+    return parseThumbnails(m[1]!);
+  } catch {
+    return null;
+  }
+}

package/src/build/visx-esm-plugin.ts

@@ -0,0 +1,42 @@
+import type { BunPlugin } from "bun";
+import { dirname } from "node:path";
+
+/**
+ * Redirect deep visx CJS imports (`@visx/<pkg>/lib/...`) to the ESM mirror
+ * (`@visx/<pkg>/esm/...`).
+ *
+ * Why: visx's ESM builds default-import their own CJS `lib/` files, e.g.
+ * `@visx/grid` does `import Line from "@visx/shape/lib/shapes/Line"`. Those CJS
+ * files are correctly marked (`exports.__esModule = true; exports.default = …`),
+ * and Bun's *runtime* honors that. But `Bun.build` does NOT honor `__esModule`
+ * for CJS default imports (oven-sh/bun#12463, confirmed unfixed through the
+ * 1.4.0 canary): the default import resolves to the module *namespace object*
+ * instead of the component. It bundles cleanly and then crashes at render with
+ * "Element type is invalid … got: object".
+ *
+ * This bites the chart registry hard: scaffolded charts are owned source that
+ * users/agents extend, pulling in arbitrary visx packages (grid, heatmap,
+ * hierarchy, legend, tooltip, …), any of which may use this pattern. Auditing or
+ * avoiding packages doesn't scale. The ESM mirror exports real defaults, so
+ * redirecting `lib/` → `esm/` sidesteps the broken interop for the whole visx
+ * surface in one place. The fallback keeps original resolution if no ESM mirror
+ * exists, so the plugin can never make a build fail.
+ *
+ * Remove once oven-sh/bun#12463 is fixed.
+ */
+const visxEsmInterop: BunPlugin = {
+  name: "visx-esm-interop",
+  setup(build) {
+    build.onResolve({ filter: /^@visx\/[^/]+\/lib\// }, (args) => {
+      const esm = args.path.replace("/lib/", "/esm/");
+      const from = args.importer ? dirname(args.importer) : process.cwd();
+      try {
+        return { path: Bun.resolveSync(esm, from) };
+      } catch {
+        return undefined; // no ESM mirror → fall back to default resolution
+      }
+    });
+  },
+};
+
+export default visxEsmInterop;