storyink 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.3.3
+
+- **Fix: `snapshot --camera follow` wasn't deterministic on real diagrams** (`follow-deterministic`
+  failed on OpenWick's 24- and 18-node architecture/data-flow diagrams). The DOM, camera and
+  transform were identical across runs; what varied was Chrome's paint history. Some runs painted a
+  frame at the fit transform before the followed camera was placed, which changed the canvas
+  raster (anti-aliasing of some node boxes and text). With `#camera=follow&t=` the canvas now stays
+  hidden until the followed camera has painted. `follow-deterministic` now re-captures every
+  `at` frame, not only the first.
+- **Arrow keys animate step moves.** → plays forward to the next step boundary and pauses (while
+  playing: advance one step); ← rewinds backwards at 2× to the previous boundary with a short
+  bounce-free ease. Shift goes by chapter, repeated presses extend the target, and the opposite key
+  reverses. Space pauses a move, the follow camera follows it (backwards too), and reduced motion
+  still jumps.
+  - `window.__storyink.step(dir, chapter?)` animates the same way and returns a Promise;
+    `stepAnimated()` is the running move. `state()` reads the clock/mode without render lag.
+  - Core: `stepBoundary`, `stepMoveTarget`, `stepMoveSpeed`, `STEP_MOVE`.
+- `verify:viewer` drives → / ← / Shift / Space with real key events (CDP `Input.dispatchKeyEvent`).
+
+## 0.3.2
+
+- **Fix: clicking the transport's play/pause did nothing** (space worked). The stage's native
+  `pointerdown` listener, which starts a pan, ran before React's root listener, so the controls'
+  React `stopPropagation` came too late: the stage captured the pointer and the button's `click`
+  never fired. Pans now start only on the diagram surface (not on buttons, the scrubber, the
+  toolbar, the transport, the gate or `[data-no-pan]`) and capture the pointer only after 3 px of
+  movement, so a still click on the surface stays a click. Quick repeated −/+ clicks now compound.
+- **Follow camera.** While a story plays on a large diagram, the viewer zooms to a readable scale
+  (labels ≈ 12.4 px, when fit would render them below 10 px) and pans to each step, moving only
+  when the step's focus leaves the inner 80 % of the view (bounce-free spring, 0.75 s), then eases
+  back to fit at the end. Manual zoom is kept (follow pans); a drag suspends follow until the next
+  out-of-view step; reduced motion jumps; scrubbing and ←/→ move the camera too.
+  - Toolbar **Follow** toggle (`aria-pressed`, `F`), saved in `localStorage["storyink-follow"]`.
+  - `story.camera: "follow" | "fit"` (default follow), `render --camera`, tool `storyink_render`
+    `camera`; `#camera=follow|fit`; `window.__storyink.camera()`.
+  - Core: `stepFocus`, `cameraAt` (pure: t + stage + scale → camera), `followStep`,
+    `readableScale`, `fitCamera`, `inView`, `stepAt`, `CAMERA`.
+  - `storyink snapshot --camera follow --at …` (tool `camera`) captures the followed view in a
+    16:9 stage, with a `follow-deterministic` gate. Default snapshots and beat sheets stay at fit.
+- `bun run verify:viewer` drives every control with real mouse input (CDP
+  `Input.dispatchMouseEvent`) in full and reduced motion, and checks the follow camera on a
+  25-node diagram (readable zoom, pans, drag suspend/resume, end at fit, toggle persistence,
+  reduced jumps).
+- Not in the animated SVG (SMIL): a follow camera there would need an animated `viewBox`; a
+  possible follow-up.
+
 ## 0.3.1
 
 - **Fix: Play did nothing under reduced motion.** With Reduce Motion on (OS or `#motion=reduced`),

package/README.md

@@ -48,11 +48,12 @@ both and has the OpenCode plugin as its default export. Runs on Node ≥ 20 and
 
 ```
 storyink render <in.json|in.mmd|-> [-o out.html] [--svg out.svg] [--theme light|dark] [--story auto]
+                [--motion full|reduced|system] [--camera follow|fit]
                 [--animated-svg out.svg [--theme light|dark|both] [--once] [--font system|embed]]
 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]
-                  [--preview out.jpg [--preview-size 1024]] [--motion reduced]
+                  [--preview out.jpg [--preview-size 1024]] [--motion reduced] [--camera follow]
 storyink skill
 ```
 
@@ -122,7 +123,8 @@ Add a `story` to play a diagram as a sequence of beats in the HTML viewer:
 
 `"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.
+ticks. Space, ←/→ and R control it: → plays to the next step and pauses, ← rewinds at 2× to the
+previous one (Shift: by chapter; repeated presses extend the move).
 
 Motion is **full by default, even when the reader's system asks for reduced motion**. Authors can
 set `"story": { "motion": "reduced" }` (always step by step) or `"motion": "system"` (follow
@@ -132,6 +134,13 @@ for auto stories. Readers switch with the toolbar's **Motion** toggle (`M`, reme
 each step's settled state shown at once and held for its reading time, with no travelling pulses
 or tweens, and the page opens on the final frame.
 
+The camera **follows the story** while it plays. When the whole diagram would render its labels
+too small, Play zooms to a readable scale and pans from step to step, moving only when the active
+step leaves the middle 80 % of the view, then eases back to fit at the end. Your own zoom is kept
+and a drag pauses following until the next step that is out of view. Toggle it with **Follow**
+(`F`, remembered), `#camera=fit`, or `"story": { "camera": "fit" }` / `--camera fit`.
+`storyink snapshot --camera follow --at …` captures the followed view.
+
 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

package/dist/chunks/{index-b50m4vmv.js → index-wpcz893s.js}

@@ -6,7 +6,7 @@ import {
   renderHtml,
   renderSvg,
   validate
-} from "./index-6h5ajcgs.js";
+} from "./index-xmj21twd.js";
 
 // src/node/index.ts
 import fs3 from "node:fs";
@@ -194,10 +194,13 @@ async function snapshot(htmlPath, opts = {}) {
   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 mq = opts.motion ? `&motion=${opts.motion}` : "";
+  const follow = opts.camera === "follow" && !!tl;
+  const cq = follow ? "&camera=follow" : "";
   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 FW = Math.round(Math.max(500, opts.width ?? 1280));
   const url = (hash) => `${pathToFileURL(abs).href}#${hash}`;
   const baseFlags = [
     ...browser.flavor === "chrome" ? ["--headless=new"] : [],
@@ -321,10 +324,11 @@ async function snapshot(htmlPath, opts = {}) {
   try {
     for (const theme of themes)
       for (const at of ats) {
-        const tag = `${at === "end" ? "" : `.t${+at.toFixed(2)}`}${opts.motion === "reduced" ? ".reduced" : ""}`;
+        const tag = `${at === "end" ? "" : `.t${+at.toFixed(2)}`}${opts.motion === "reduced" ? ".reduced" : ""}${follow ? ".follow" : ""}`;
         const png = path2.join(outDir, `${base}.${theme}${tag}.png`);
-        const ms = await shoot(`theme=${theme}&chrome=0${tq(at)}${mq}`, png, W, H);
-        captures.push({ theme, at, png, sha256: sha256(png), bytes: fs2.statSync(png).size, width: W * scale, height: H * scale, ms });
+        const [cw, ch] = follow ? [FW, Math.round(FW * 0.5625)] : [W, H];
+        const ms = await shoot(`theme=${theme}&chrome=0${tq(at)}${mq}${cq}`, png, cw, ch);
+        captures.push({ theme, at, png, sha256: sha256(png), bytes: fs2.statSync(png).size, width: cw * scale, height: ch * scale, ms });
       }
     const first = captures[0];
     const midT = tl ? ats.find((a) => a !== "end") ?? +(tl.duration / 2).toFixed(3) : "end";
@@ -334,6 +338,17 @@ async function snapshot(htmlPath, opts = {}) {
     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 (follow) {
+      const diff = [];
+      for (const c of captures.filter((x) => x.theme === first.theme)) {
+        const f2 = path2.join(tmpRoot, `follow-${diff.length}-${String(c.at)}.png`);
+        await shoot(`theme=${c.theme}&chrome=0${tq(c.at ?? "end")}${mq}${cq}`, f2, FW, Math.round(FW * 0.5625));
+        if (sha256(f2) !== c.sha256)
+          diff.push(String(c.at));
+      }
+      const at = captures.filter((x) => x.theme === first.theme).map((x) => x.at).join(",");
+      gates.push({ name: "follow-deterministic", pass: !diff.length, detail: !diff.length ? `camera=follow at t=${at} captured twice: identical` : `camera=follow at t=${diff.join(",")} differs between runs` });
+    }
     if (tl) {
       const stat = path2.join(tmpRoot, "static.png");
       const end = path2.join(tmpRoot, "end.png");
@@ -497,6 +512,12 @@ function setStoryMotion(spec, motion) {
   spec.story = spec.story === "auto" ? { steps: "auto", motion } : { ...spec.story, motion };
   return true;
 }
+function setStoryCamera(spec, camera) {
+  if (spec.story === undefined)
+    return false;
+  spec.story = spec.story === "auto" ? { steps: "auto", camera } : { ...spec.story, camera };
+  return true;
+}
 function pictureSnippet(light, dark, alt) {
   const a = alt.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
   return `<picture>
@@ -525,4 +546,4 @@ function writeAnimatedSvg(input, out, opts = {}) {
   return { ok: true, diagnostics: v.diagnostics, files, autoStory, snippet };
 }
 
-export { browserVersion, findBrowser, snapshot, screenshotPage, parseSource, loadSpec, writeDiagram, setStoryMotion, pictureSnippet, writeAnimatedSvg };
+export { browserVersion, findBrowser, snapshot, screenshotPage, parseSource, loadSpec, writeDiagram, setStoryMotion, setStoryCamera, pictureSnippet, writeAnimatedSvg };