storyink 0.0.1 → 0.2.0

package/README.md

@@ -1,6 +1,151 @@
 # storyink
 
-Diagrams that tell a story: turn a JSON spec or Mermaid into polished, animated, standalone HTML and SVG.
-Usable as a library, a CLI, and an OpenCode plugin.
+Architecture, workflow, sequence, data-flow and lifecycle diagrams from a small JSON spec (or
+Mermaid) into **one offline HTML file** (a React + Motion viewer over server-rendered SVG) and a
+**static SVG**. Warm ink-on-paper style with Commit Mono labels, light and dark themes.
 
-This version only reserves the package name. The first real release is coming soon.
+One package, four ways to use it: library, CLI, OpenCode plugin, and a skill for other agents.
+
+```sh
+npx storyink render examples/checkout.architecture.json -o checkout.html --svg checkout.svg
+```
+
+The HTML has no external requests. It includes pan/zoom (wheel at the cursor, drag, `+`/`-`/`0`,
+fit on load), a theme toggle that follows `prefers-color-scheme` and is saved in `localStorage`,
+SVG export, and 2× PNG export. It also works without JavaScript.
+
+## 1. Library
+
+```ts
+import { validate, fromMermaid, renderHtml, renderSvg, layout } from "storyink/core" // browser-safe
+import { writeDiagram, snapshot, findBrowser } from "storyink/node" // Node only
+
+const v = validate(spec) // { ok, diagnostics: [{ severity, path, message, hint }], spec }
+const html = renderHtml(v.spec!) // standalone page
+const svg = renderSvg(v.spec!, { theme: "dark" }) // omit theme to follow prefers-color-scheme
+const scene = layout(v.spec!) // absolute geometry with stable ids (nodes, groups, edges, ports, labels)
+const m = fromMermaid("flowchart LR\n a --> b") // { ok, spec, diagnostics }
+```
+
+`storyink/core` has no Node APIs. The viewer bundle and the font are compiled in as string
+modules, so it works with bundlers and in the browser. `storyink` (the root export) re-exports
+both and has the OpenCode plugin as its default export. Runs on Node ≥ 20 and Bun.
+
+## 2. CLI
+
+```
+storyink render <in.json|in.mmd|-> [-o out.html] [--svg out.svg] [--theme light|dark] [--story auto]
+storyink mermaid <in.mmd> [-o out.json]
+storyink validate <in> [--json]
+storyink snapshot <out.html> [--theme light,dark] [--width N] [--sheet [themes|beats]|--no-sheet] [--at 0.5,1.2,end] [--scale 2] [-o dir] [--json]
+storyink skill
+```
+
+`snapshot` finds a browser in this order: `$STORYINK_CHROME`, then the newest Playwright
+`chrome-headless-shell`, then system Chrome (`--headless=new`). It writes one PNG per theme and
+a light|dark contact sheet, reads the in-page lint through `--dump-dom`, and writes a receipt
+JSON containing the browser, flags, sha256 of each image, lint results and gates. Exit codes:
+0 pass, 1 gate failed, 2 no browser.
+
+## 3. OpenCode plugin
+
+From npm (once published), pinned or not:
+
+```jsonc
+// opencode.json (global ~/.config/opencode/ or project .opencode/)
+{ "plugins": ["storyink"] }            // or "storyink@0.1.0"
+```
+
+From a local checkout, for development: build first, then point `plugins` at the **directory**
+(OpenCode v2 accepts directories here, not single files):
+
+```sh
+cd ~/projects/storyink && bun install && bun run build
+```
+
+```jsonc
+// <project>/.opencode/opencode.json
+{ "plugins": ["/absolute/path/to/storyink"] }
+```
+
+OpenCode resolves a local plugin directory as `<dir>/server` and then `<dir>/index`. It does not
+read `package.json` `main`, which is why the repo ships a root `server.js` that re-exports
+`dist/index.js`. npm packages resolve `storyink/server` and then `storyink`, and both are exported.
+Rebuild after changes, then restart the server (or touch the config) to reload.
+
+This adds the tools `storyink_render`, `storyink_from_mermaid`, `storyink_validate` and
+`storyink_snapshot`. `storyink_snapshot` returns the contact sheet as an image, so the model can
+see its own render. The plugin also adds the `storyink` skill (`skill/SKILL.md`), which covers
+choosing a diagram type, writing the spec, and the render → look → fix loop. If you already have
+a skill with the id `storyink`, yours is kept. Relative paths resolve against the project
+directory.
+
+## 4. Other agents
+
+Use the CLI, and install the skill from the package:
+
+```sh
+npx storyink skill        # prints the SKILL.md path and its content
+```
+
+An MCP server is planned.
+
+## Storyboards (opt-in)
+
+Add a `story` to play a diagram as a sequence of beats in the HTML viewer:
+- nodes reveal;
+- wires draw on under a travelling pulse;
+- arrivals glow;
+- captions type in;
+- counters roll (via [@kitlangton/rolling-number](https://github.com/kitlangton/rolling-number)).
+
+`"story": "auto"` (or `--story auto`) derives the beats from the graph or message order. Playback
+has a click-to-play gate, play/pause, a tape-rewind replay and a scrubber with step and chapter
+ticks. Space, ←/→ and R control it. When reduced motion is on, the viewer jumps to the final frame.
+
+The final frame is always the static diagram. Every frame is a pure function of time
+(`storyState(scene, timeline, t)`), so `#t=2.5` seeks exactly and
+`storyink snapshot --at 1,2.5,end --sheet beats` renders stills and a beat contact sheet. The
+receipt gates check that the end frame and the reduced-motion page match the static diagram. See
+[docs/spec.md](docs/spec.md#storyboard-story-opt-in).
+
+![Checkout beats](docs/gallery/checkout.architecture.beats.light.png)
+
+## Gallery
+
+`bun run gallery` renders every example and Mermaid sample and writes one light and one dark PNG per
+example to `docs/gallery/`.
+
+| | |
+| --- | --- |
+| ![Checkout platform](docs/gallery/checkout.architecture.light.png) | ![Agent run lifecycle](docs/gallery/agent-run.lifecycle.dark.png) |
+| ![Release pipeline](docs/gallery/release.workflow.light.png) | ![OAuth sequence](docs/gallery/oauth.sequence.dark.png) |
+| ![Analytics pipeline](docs/gallery/analytics.dataflow.dark.png) | ![Order state machine (Mermaid)](docs/gallery/order.state.light.png) |
+| ![OAuth beats](docs/gallery/oauth.sequence.beats.dark.png) | ![Order state machine, auto story](docs/gallery/order.state.beats.light.png) |
+
+## Spec
+
+See [docs/spec.md](docs/spec.md) and [schema/storyink.schema.json](schema/storyink.schema.json).
+Graph edges have no arrowheads by default, matching Kit's style. Set `"style": { "arrowheads": true }`
+to draw them. If you leave out `direction`, the layout picks TB or LR, whichever gets the aspect
+ratio closer to 16:10.
+Examples of each type are in [examples/](examples), and Mermaid samples are in
+[examples/mermaid/](examples/mermaid).
+
+## Develop
+
+```sh
+bun install
+bun test          # generates src/generated/* first
+bun run typecheck
+bun run build     # dist/ (ESM for node, .d.ts, CLI with a node shebang)
+bun run gallery   # docs/gallery/*.png (needs Chrome / Playwright headless shell)
+```
+
+All design tokens (palette, type, geometry, motion) live in `src/theme/tokens.ts` and are
+exported as CSS variables.
+
+## License
+
+MIT © 2026 grenaad. The bundled font and libraries are listed in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,50 @@
+# Third-party notices
+
+## Commit Mono (embedded in every HTML/SVG output)
+
+Commit Mono v1.143 by Eigil Nikolajsen, <https://github.com/eigilnikolajsen/commit-mono>.
+Licensed under the SIL Open Font License 1.1; full text in [`fonts/OFL.txt`](fonts/OFL.txt).
+`fonts/CommitMono-400.woff2` and `CommitMono-700.woff2` are unmodified format conversions
+(OTF → WOFF2 with fontTools) of `CommitMono-400-Regular.otf` / `CommitMono-700-Regular.otf`
+from the official release zip. The font is embedded as base64 `@font-face`; it is not sold
+by itself.
+
+## React, React DOM, scheduler (bundled into the HTML viewer)
+
+MIT License. Copyright (c) Meta Platforms, Inc. and affiliates. <https://github.com/facebook/react>
+
+## Motion (motion, framer-motion, motion-dom, motion-utils; bundled into the HTML viewer)
+
+MIT License. Copyright (c) 2024 Motion B.V.; Copyright (c) 2018 Framer B.V. <https://github.com/motiondivision/motion>
+
+The viewer bundle inlined into each HTML file starts with a comment banner that carries
+these notices and the MIT permission text.
+
+## @kitlangton/rolling-number (bundled into the HTML viewer)
+
+MIT License. Copyright (c) 2026 Kit Langton. <https://github.com/kitlangton/rolling-number>
+Used unmodified from npm for live counter reels; its stylesheet is inlined when a story has
+counters. The notice is also in the viewer bundle banner.
+
+## Storyboard design
+
+Timings and curves (beats, springs, pulse phases, rewind, gate) follow the numbers documented in
+our own style study of the "OpenCode Reloaded" figures; the runtime is an independent
+implementation. No code, shaders or figure content from anoma.ly are included.
+
+## archify (design reference)
+
+The spec's overall shape (one JSON document per diagram with `type`, `nodes`/`edges`/`groups`,
+sequence `participants`/`messages`) was informed by the MIT-licensed archify skill's schemas.
+No archify code was copied; storyink's schema, validator and renderer are independent.
+
+## Visual design
+
+The look is an independent reimplementation inspired by Kit Langton's "OpenCode Reloaded"
+post (<https://anoma.ly/notes/opencode-reloaded/>). No code, fonts or figure content from that
+site are included. Serif headings use system fonts ("Iowan Old Style", Charter, Georgia).
+
+## Mermaid syntax
+
+storyink parses a subset of Mermaid syntax with its own hand-written parsers; no Mermaid
+or merman code is included.

package/dist/chunks/index-aq1sxjmx.js

@@ -0,0 +1,369 @@
+import {
+  detectMermaid,
+  fromMermaid,
+  renderHtml,
+  renderSvg,
+  validate
+} from "./index-xjaczbn5.js";
+
+// src/node/index.ts
+import fs3 from "node:fs";
+import path3 from "node:path";
+
+// src/node/chrome.ts
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function newestPlaywrightShell() {
+  const caches = [
+    path.join(os.homedir(), "Library/Caches/ms-playwright"),
+    path.join(os.homedir(), ".cache/ms-playwright"),
+    process.env.PLAYWRIGHT_BROWSERS_PATH ?? ""
+  ].filter(Boolean);
+  const found = [];
+  for (const dir of caches) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const m = /^chromium_headless_shell-(\d+)$/.exec(e);
+      if (!m)
+        continue;
+      const base = path.join(dir, e);
+      let subs = [];
+      try {
+        subs = fs.readdirSync(base).filter((s) => s.startsWith("chrome-headless-shell-"));
+      } catch {}
+      for (const s of subs) {
+        const bin = path.join(base, s, process.platform === "win32" ? "chrome-headless-shell.exe" : "chrome-headless-shell");
+        if (fs.existsSync(bin))
+          found.push({ rev: Number(m[1]), file: bin });
+      }
+    }
+  }
+  found.sort((a, b) => b.rev - a.rev);
+  return found[0]?.file;
+}
+var SYSTEM = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser",
+  "/snap/bin/chromium"
+];
+function browserVersion(bin) {
+  try {
+    return execFileSync(bin, ["--version"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return;
+  }
+}
+function findBrowser(env = process.env) {
+  const fromEnv = env.STORYINK_CHROME;
+  if (fromEnv && fs.existsSync(fromEnv))
+    return { path: fromEnv, flavor: /headless[-_]shell/.test(fromEnv) ? "headless-shell" : "chrome", source: "env" };
+  const pw = newestPlaywrightShell();
+  if (pw)
+    return { path: pw, flavor: "headless-shell", source: "playwright" };
+  for (const p of SYSTEM)
+    if (fs.existsSync(p))
+      return { path: p, flavor: "chrome", source: "system" };
+  return;
+}
+// src/node/snapshot.ts
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs2 from "node:fs";
+import os2 from "node:os";
+import path2 from "node:path";
+import { pathToFileURL } from "node:url";
+var HARD_TIMEOUT = 15000;
+function readScene(html) {
+  const m = /<script type="application\/json" id="storyink-data">([\s\S]*?)<\/script>/.exec(html);
+  if (!m)
+    throw new Error("not a storyink HTML file (no #storyink-data)");
+  const data = JSON.parse(m[1]);
+  return data.scene;
+}
+var live = new Set;
+function killTree(child) {
+  try {
+    if (child.pid && process.platform !== "win32")
+      process.kill(-child.pid, "SIGKILL");
+    else
+      child.kill("SIGKILL");
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {}
+  }
+}
+var hooked = false;
+function hookExit() {
+  if (hooked)
+    return;
+  hooked = true;
+  process.on("exit", () => {
+    for (const c of live)
+      killTree(c);
+  });
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+    process.once(sig, () => {
+      for (const c of live)
+        killTree(c);
+      process.exit(128 + (sig === "SIGINT" ? 2 : sig === "SIGTERM" ? 15 : 1));
+    });
+}
+function run(bin, args, opts) {
+  hookExit();
+  return new Promise((resolve) => {
+    const t0 = performance.now();
+    const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" });
+    live.add(child);
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+    let written = false;
+    const finish = (ok) => {
+      if (done)
+        return;
+      done = true;
+      clearTimeout(timer);
+      opts.signal?.removeEventListener("abort", onAbort);
+      killTree(child);
+      live.delete(child);
+      resolve({ ok, stdout, stderr, ms: Math.round(performance.now() - t0) });
+    };
+    const onAbort = () => finish(false);
+    opts.signal?.addEventListener("abort", onAbort);
+    const timer = setTimeout(() => finish(written), opts.timeoutMs);
+    child.stdout.on("data", (d) => {
+      stdout += d;
+      if (opts.untilStdout?.test(stdout))
+        finish(true);
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d;
+      if (/bytes written to file/.test(stderr)) {
+        written = true;
+        finish(true);
+      }
+    });
+    child.on("error", (e) => {
+      stderr += String(e);
+      finish(false);
+    });
+    child.on("exit", (code) => {
+      live.delete(child);
+      finish(code === 0 || written);
+    });
+  });
+}
+function ffmpegSheet(inputs, out) {
+  const n = inputs.length;
+  const filter = `${inputs.map((_, i) => `[${i}:v]`).join("")}concat=n=${n}:v=1:a=0,tile=${n}x1`;
+  const ff = spawnSync("ffmpeg", ["-y", "-loglevel", "error", ...inputs.flatMap((p) => ["-i", p]), "-filter_complex", filter, "-frames:v", "1", out]);
+  return ff.status === 0 && fs2.existsSync(out) && fs2.statSync(out).size > 0;
+}
+var sha256 = (file) => createHash("sha256").update(fs2.readFileSync(file)).digest("hex");
+async function snapshot(htmlPath, opts = {}) {
+  const browser = opts.browser ?? findBrowser();
+  if (!browser)
+    return { code: 2, error: "no Chrome/Chromium found (set STORYINK_CHROME)" };
+  const abs = path2.resolve(htmlPath);
+  const html = fs2.readFileSync(abs, "utf8");
+  const scene = readScene(html);
+  const vb = scene.viewBox;
+  const themes = opts.themes?.length ? opts.themes : ["light", "dark"];
+  const outDir = path2.resolve(opts.outDir ?? path2.dirname(abs));
+  fs2.mkdirSync(outDir, { recursive: true });
+  const base = path2.basename(abs).replace(/\.html?$/i, "");
+  const scale = opts.scale ?? 1;
+  const timeoutMs = opts.timeoutMs ?? HARD_TIMEOUT;
+  const budget = opts.budgetMs ?? 3000;
+  const tl = scene.timeline;
+  const headerH = (scene.subtitle ? 128 : 100) + (tl ? 54 : 0);
+  const ats = opts.at?.length ? opts.at : opts.t ? [opts.t === "end" ? "end" : Number(opts.t)] : ["end"];
+  const tq = (at) => tl ? `&t=${at === "end" ? "end" : +at.toFixed(3)}` : "";
+  const sheetMode = opts.sheet === false ? false : opts.sheet === "beats" ? "beats" : "themes";
+  const W = Math.round(Math.max(500, opts.width ?? Math.min(1600, vb.w + 64)));
+  const s = Math.min(1, (W - 64) / vb.w);
+  const H = Math.round(headerH + vb.h * s + 64 + 8);
+  const url = (hash) => `${pathToFileURL(abs).href}#${hash}`;
+  const baseFlags = [
+    ...browser.flavor === "chrome" ? ["--headless=new"] : [],
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--hide-scrollbars",
+    `--force-device-scale-factor=${scale}`,
+    "--force-prefers-no-reduced-motion",
+    "--disable-extensions",
+    "--mute-audio",
+    `--virtual-time-budget=${budget}`
+  ];
+  const tmpRoot = fs2.mkdtempSync(path2.join(os2.tmpdir(), "storyink-chrome-"));
+  let n = 0;
+  const fresh = () => {
+    const d = path2.join(tmpRoot, `p${n++}`);
+    fs2.mkdirSync(d);
+    return `--user-data-dir=${d}`;
+  };
+  const shoot = async (hash, png, w, h) => {
+    fs2.rmSync(png, { force: true });
+    const args = [...baseFlags, fresh(), `--window-size=${w},${h}`, `--screenshot=${png}`, url(hash)];
+    let r = await run(browser.path, args, { timeoutMs, signal: opts.signal });
+    if ((!fs2.existsSync(png) || fs2.statSync(png).size === 0) && !opts.signal?.aborted) {
+      const retry = [...baseFlags, fresh(), `--window-size=${w},${h}`, `--screenshot=${png}`, url(hash)];
+      r = await run(browser.path, retry, { timeoutMs, signal: opts.signal });
+    }
+    if (!fs2.existsSync(png) || fs2.statSync(png).size === 0)
+      throw new Error(`screenshot failed (${r.ms} ms): ${r.stderr.split(`
+`).filter((l) => l.trim()).slice(-3).join(" | ")}`);
+    return r.ms;
+  };
+  const gates = [];
+  const captures = [];
+  let sheetCap;
+  let beatCaps = [];
+  let lint;
+  try {
+    for (const theme of themes)
+      for (const at of ats) {
+        const tag = at === "end" ? "" : `.t${+at.toFixed(2)}`;
+        const png = path2.join(outDir, `${base}.${theme}${tag}.png`);
+        const ms = await shoot(`theme=${theme}&chrome=0${tq(at)}`, png, W, H);
+        captures.push({ theme, at, png, sha256: sha256(png), bytes: fs2.statSync(png).size, width: W * scale, height: H * scale, ms });
+      }
+    const first = captures[0];
+    const midT = tl ? ats.find((a) => a !== "end") ?? +(tl.duration / 2).toFixed(3) : "end";
+    const a1 = path2.join(tmpRoot, "same-1.png");
+    const a2 = path2.join(tmpRoot, "same-2.png");
+    await shoot(`theme=${first.theme}&chrome=0${tq(midT)}`, a1, W, H);
+    await shoot(`theme=${first.theme}&chrome=0${tq(midT)}`, a2, W, H);
+    const same = sha256(a1) === sha256(a2);
+    gates.push({ name: "deterministic", pass: same, detail: same ? `${first.theme} at t=${midT} captured twice: identical` : `${first.theme} at t=${midT} differs between runs` });
+    if (tl) {
+      const stat = path2.join(tmpRoot, "static.png");
+      const end = path2.join(tmpRoot, "end.png");
+      const red = path2.join(tmpRoot, "reduced.png");
+      await shoot(`theme=${first.theme}&chrome=0&static=1`, stat, W, H);
+      await shoot(`theme=${first.theme}&chrome=0&t=end`, end, W, H);
+      await shoot(`theme=${first.theme}&chrome=0&motion=reduced`, red, W, H);
+      const sStat = sha256(stat);
+      gates.push({ name: "end=static", pass: sha256(end) === sStat, detail: sha256(end) === sStat ? "t=end matches the static diagram" : "t=end differs from the static diagram" });
+      gates.push({ name: "reduced=static", pass: sha256(red) === sStat, detail: sha256(red) === sStat ? "reduced motion shows the static diagram" : "reduced motion differs from the static diagram" });
+    }
+    const beats = [];
+    if (sheetMode === "beats" && tl) {
+      const bw = 1440;
+      for (const theme of themes) {
+        const probe = await run(browser.path, [...baseFlags, fresh(), `--window-size=${bw},900`, "--dump-dom", url(`theme=${theme}&chrome=0&sheet=beats`)], {
+          timeoutMs,
+          untilStdout: /<\/html>\s*$/,
+          signal: opts.signal
+        });
+        const mh = /<html[^>]*data-content-height="(\d+)"/.exec(probe.stdout);
+        const bh = mh ? Number(mh[1]) : 1800;
+        const png = path2.join(outDir, `${base}.beats.${theme}.png`);
+        const ms = await shoot(`theme=${theme}&chrome=0&sheet=beats`, png, bw, bh);
+        beats.push({ theme: "beats", png, sha256: sha256(png), bytes: fs2.statSync(png).size, width: bw * scale, height: bh * scale, ms });
+      }
+    }
+    beatCaps = beats;
+    if (sheetMode === "themes" && themes.length > 1) {
+      const colW = Math.max(500, Math.min(1000, vb.w + 48));
+      const sw = colW * themes.length;
+      const sh = Math.round(headerH + 46 + vb.h * (colW - 48) / vb.w + 36);
+      const png = path2.join(outDir, `${base}.sheet.png`);
+      try {
+        if (process.env.STORYINK_SHEET === "ffmpeg")
+          throw new Error("forced ffmpeg sheet");
+        const ms = await shoot(`sheet=${themes.join(",")}&chrome=0`, png, sw, sh);
+        sheetCap = { theme: "sheet", png, sha256: sha256(png), bytes: fs2.statSync(png).size, width: sw * scale, height: sh * scale, ms };
+      } catch (e) {
+        const ff = ffmpegSheet(captures.map((c) => c.png), png);
+        if (ff)
+          sheetCap = { theme: "sheet", png, sha256: sha256(png), bytes: fs2.statSync(png).size, width: W * captures.length * scale, height: H * scale, ms: 0 };
+        else
+          gates.push({ name: "sheet", pass: false, detail: String(e.message) });
+      }
+    }
+    const dom = await run(browser.path, [...baseFlags, fresh(), `--window-size=${W},${H}`, "--dump-dom", url(`theme=${themes[0]}&chrome=0${tq("end")}`)], {
+      timeoutMs,
+      untilStdout: /<\/html>\s*$/,
+      signal: opts.signal
+    });
+    const lm = /<script type="application\/json" id="storyink-lint">([\s\S]*?)<\/script>/.exec(dom.stdout);
+    const ready = /<html[^>]*data-ready="1"/.test(dom.stdout);
+    gates.push({ name: "ready", pass: ready, detail: ready ? "hydrated, fonts ready" : "page never signalled ready" });
+    if (lm) {
+      lint = JSON.parse(lm[1]);
+      const l = lint;
+      gates.push({ name: "lint", pass: l.ok, detail: l.ok ? "no overflow or overlap" : `${l.issues.length} issue(s)` });
+    } else
+      gates.push({ name: "lint", pass: false, detail: "no lint output in DOM" });
+  } catch (e) {
+    gates.push({ name: "capture", pass: false, detail: e.message });
+  } finally {
+    fs2.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+  const receipt = {
+    html: abs,
+    browser: { path: browser.path, version: browser.version ?? browserVersion(browser.path), flavor: browser.flavor, source: browser.source },
+    flags: [...baseFlags, "--user-data-dir=<fresh tmp>", `--window-size=${W},${H}`],
+    captures,
+    ...sheetCap ? { sheet: sheetCap } : {},
+    ...beatCaps.length ? { beats: beatCaps } : {},
+    ...tl ? { story: { duration: tl.duration, steps: tl.steps.length } } : {},
+    ...lint ? { lint } : {},
+    gates,
+    ok: gates.every((g) => g.pass),
+    createdAt: new Date().toISOString()
+  };
+  const receiptPath = path2.join(outDir, `${base}.receipt.json`);
+  fs2.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}
+`);
+  return { code: receipt.ok ? 0 : 1, receipt, receiptPath };
+}
+
+// src/node/index.ts
+function parseSource(text, hint) {
+  const trimmed = text.trimStart();
+  const isMermaid = hint ? /\.(mmd|mermaid)$/i.test(hint) : !trimmed.startsWith("{") && !!detectMermaid(text);
+  if (isMermaid) {
+    const r = fromMermaid(text);
+    return { ok: r.ok, spec: r.spec, diagnostics: r.diagnostics, source: "mermaid" };
+  }
+  const v = validate(text);
+  return { ok: v.ok, spec: v.spec, diagnostics: v.diagnostics, source: "json" };
+}
+function loadSpec(file) {
+  return parseSource(fs3.readFileSync(file, "utf8"), file);
+}
+function writeDiagram(input, out) {
+  const v = validate(input);
+  if (!v.ok || !v.spec)
+    return { ok: false, diagnostics: v.diagnostics };
+  const res = { ok: true, diagnostics: v.diagnostics };
+  if (out.html) {
+    const html = renderHtml(v.spec, { ...out.htmlOptions, ...out.theme ? { theme: out.theme } : {} });
+    fs3.mkdirSync(path3.dirname(out.html), { recursive: true });
+    fs3.writeFileSync(out.html, html);
+    res.html = { path: path3.resolve(out.html), bytes: Buffer.byteLength(html) };
+  }
+  if (out.svg) {
+    const svg = renderSvg(v.spec, out.theme ? { theme: out.theme } : {});
+    fs3.mkdirSync(path3.dirname(out.svg), { recursive: true });
+    fs3.writeFileSync(out.svg, svg);
+    res.svg = { path: path3.resolve(out.svg), bytes: Buffer.byteLength(svg) };
+  }
+  return res;
+}
+
+export { browserVersion, findBrowser, snapshot, parseSource, loadSpec, writeDiagram };