storyink 0.1.0 → 0.2.0

package/README.md

@@ -34,10 +34,10 @@ both and has the OpenCode plugin as its default export. Runs on Node ≥ 20 and
 ## 2. CLI
 
 ```
-storyink render <in.json|in.mmd|-> [-o out.html] [--svg out.svg] [--theme light|dark]
+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] [--no-sheet] [--scale 2] [-o dir] [--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
 ```
 
@@ -90,6 +90,27 @@ 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
@@ -100,6 +121,7 @@ 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
 

package/THIRD_PARTY_NOTICES.md

@@ -20,6 +20,18 @@ MIT License. Copyright (c) 2024 Motion B.V.; Copyright (c) 2018 Framer B.V. <htt
 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`,

package/dist/chunks/{index-3y6t38gc.js → index-aq1sxjmx.js}

@@ -4,7 +4,7 @@ import {
   renderHtml,
   renderSvg,
   validate
-} from "./index-sd10277m.js";
+} from "./index-xjaczbn5.js";
 
 // src/node/index.ts
 import fs3 from "node:fs";
@@ -187,12 +187,15 @@ async function snapshot(htmlPath, opts = {}) {
   const scale = opts.scale ?? 1;
   const timeoutMs = opts.timeoutMs ?? HARD_TIMEOUT;
   const budget = opts.budgetMs ?? 3000;
-  const headerH = scene.subtitle ? 128 : 100;
+  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 tHash = opts.t ? `&t=${encodeURIComponent(opts.t)}` : "";
   const baseFlags = [
     ...browser.flavor === "chrome" ? ["--headless=new"] : [],
     "--no-first-run",
@@ -214,7 +217,11 @@ async function snapshot(htmlPath, opts = {}) {
   const shoot = async (hash, png, w, h) => {
     fs2.rmSync(png, { force: true });
     const args = [...baseFlags, fresh(), `--window-size=${w},${h}`, `--screenshot=${png}`, url(hash)];
-    const r = await run(browser.path, args, { timeoutMs, signal: opts.signal });
+    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(" | ")}`);
@@ -223,19 +230,53 @@ async function snapshot(htmlPath, opts = {}) {
   const gates = [];
   const captures = [];
   let sheetCap;
+  let beatCaps = [];
   let lint;
   try {
-    for (const theme of themes) {
-      const png = path2.join(outDir, `${base}.${theme}.png`);
-      const ms = await shoot(`theme=${theme}&chrome=0${tHash}`, png, W, H);
-      captures.push({ theme, png, sha256: sha256(png), bytes: fs2.statSync(png).size, width: W * scale, height: H * scale, ms });
-    }
+    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 again = path2.join(tmpRoot, "again.png");
-    await shoot(`theme=${first.theme}&chrome=0${tHash}`, again, W, H);
-    const same = sha256(again) === first.sha256;
-    gates.push({ name: "deterministic", pass: same, detail: same ? `${first.theme} captured twice: identical` : `${first.theme} differs between runs` });
-    if (opts.sheet !== false && themes.length > 1) {
+    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);
@@ -243,7 +284,7 @@ async function snapshot(htmlPath, opts = {}) {
       try {
         if (process.env.STORYINK_SHEET === "ffmpeg")
           throw new Error("forced ffmpeg sheet");
-        const ms = await shoot(`sheet=${themes.join(",")}&chrome=0${tHash}`, png, sw, sh);
+        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);
@@ -253,7 +294,7 @@ async function snapshot(htmlPath, opts = {}) {
           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`)], {
+    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
@@ -278,6 +319,8 @@ async function snapshot(htmlPath, opts = {}) {
     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),