storyink 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.3.1
+
+- **Fix: Play did nothing under reduced motion.** With Reduce Motion on (OS or `#motion=reduced`),
+  Play now walks the story step by step ("Play steps"): each step's settled state at once (reveals,
+  landed pulses, counters, the whole caption), held for its reading time (caption read time or
+  1.5 s), then the next, ending on the final frame. No pulses, trails, glows or tweens. Pause, ←/→,
+  Shift+←/→, R (restart from step 1, no rewind) and the scrubber work on settled steps. The page
+  loads on the final frame with a static play button; `autoplay` is ignored.
+- **`story.motion`: `"full"` (default) | `"reduced"` | `"system"`.** Full motion is the default and
+  **ignores the reader's OS reduced-motion setting**; `"system"` restores the 0.3.0 behaviour
+  (follow `prefers-reduced-motion`), `"reduced"` always steps. Auto stories:
+  `{ "steps": "auto", "motion": … }`, `render --motion …`, tool `storyink_render` `motion`.
+  Precedence: `#motion=` > the reader's toolbar choice > `story.motion` > OS (only for `"system"`).
+- Viewer toolbar: **Motion: full / reduced** toggle (`aria-pressed`, shortcut `M`), saved in
+  `localStorage`; `#motion=` still wins. Switching mid-playback continues from the current step.
+- Core: `steppedSchedule`, `steppedTime`, `steppedIndex`, `steppedStop`, `STEP_BEAT` and
+  `storyState(…, { stepped: true })`.
+- Snapshot: `--motion reduced` (tool `motion`) captures stepped `at` frames; new gate `reduced=stepped`.
+- Fix: live counter reels were placed at the node-local position (top-left of the diagram) and
+  shown before their node was revealed; they now sit on their node and follow its reveal.
+  `bun run verify:viewer` checks this in headless Chrome (full play, reduced → full, reload,
+  resize, theme toggle) along with stepped playback.
+
+## 0.3.0
+
+- **Animated SVG (SMIL):** the story plays inside a plain `<img>`, so in GitHub READMEs and PR
+  comments (camo), docs and chat previews, where no script runs.
+  - `renderAnimatedSvg(spec, { theme, once, font, hold, reset, fps })` / `animatedSvg()` in
+    `storyink/core`; `writeAnimatedSvg()` and `pictureSnippet()` in `storyink/node`.
+  - CLI: `storyink render x.json --animated-svg x.svg [--theme light|dark|both] [--once] [--font system|embed]`;
+    `both` writes `.light.svg` + `.dark.svg` and prints the `<picture>` snippet. Specs without a
+    story use the auto story (with a warning).
+  - Plugin: `storyink_render` takes `animatedSvg: true | "both"`, `animatedSvgPath`, `once`, `font`.
+  - Built by sampling `storyState(t)` (the viewer's frame function) and compressing each track
+    to SMIL keyframes; one shared cycle (story, 3 s hold, 0.4 s reset) or `once` (freeze).
+    Base values are the final frame. Theme-pinned, no custom properties, deterministic.
+  - `bun run gallery:animated`, `bun run verify:smil` (frame parity PSNR, `<img>` playback, font).
+- `Frame` pulse trail segments carry `k`, `s0`, `s1`; captions carry their index `i`.
+- `screenshotPage()` in `storyink/node`: screenshot any local page.
+
 ## 0.2.1
 
 - **Fix:** `storyink_snapshot` no longer inlines the full-resolution contact sheet. Tall beat

package/README.md

@@ -6,6 +6,19 @@ Mermaid) into **one offline HTML file** (a React + Motion viewer over server-ren
 
 One package, four ways to use it: library, CLI, OpenCode plugin, and a skill for other agents.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/grenaad/storyink/main/docs/gallery/checkout.architecture.animated.dark.svg">
+  <img alt="Checkout platform, animated story" src="https://raw.githubusercontent.com/grenaad/storyink/main/docs/gallery/checkout.architecture.animated.light.svg">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/grenaad/storyink@main/docs/gallery/oauth.sequence.animated.dark.svg">
+  <img alt="OAuth sequence, animated story" src="https://cdn.jsdelivr.net/gh/grenaad/storyink@main/docs/gallery/oauth.sequence.animated.light.svg">
+</picture>
+
+*Animated SVGs (SMIL, no script): they play inside a plain `<img>`, so in a README or a PR
+comment too. See [Animated SVG](#animated-svg-readmes-and-prs).*
+
 ```sh
 npx storyink render examples/checkout.architecture.json -o checkout.html --svg checkout.svg
 ```
@@ -35,10 +48,11 @@ 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]
+                [--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]]
+                  [--preview out.jpg [--preview-size 1024]] [--motion reduced]
 storyink skill
 ```
 
@@ -108,7 +122,15 @@ 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. When reduced motion is on, the viewer jumps to the final frame.
+ticks. Space, ←/→ and R control it.
+
+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
+`prefers-reduced-motion`); `--motion full|reduced|system` on `render` does the same, including
+for auto stories. Readers switch with the toolbar's **Motion** toggle (`M`, remembered), and
+`#motion=full|reduced` overrides everything. In reduced mode Play walks the story step by step:
+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 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
@@ -118,10 +140,41 @@ receipt gates check that the end frame and the reduced-motion page match the sta
 
 ![Checkout beats](docs/gallery/checkout.architecture.beats.light.png)
 
+## Animated SVG (READMEs and PRs)
+
+GitHub shows images in READMEs and PR comments as a plain `<img>` through its camo proxy, so no
+script runs and nothing outside the file loads. `--animated-svg` compiles the story into **SMIL**
+inside one self-contained SVG that plays there:
+
+```sh
+storyink render examples/checkout.architecture.json --animated-svg docs/checkout.svg --theme both
+# wrote docs/checkout.light.svg, docs/checkout.dark.svg and prints:
+```
+
+```html
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/checkout.dark.svg">
+  <img alt="Checkout platform" src="docs/checkout.light.svg">
+</picture>
+```
+
+- An SVG image doesn't follow the page theme, so each file is **pinned** to one theme; the
+  `<picture>` picks one. `--theme light|dark` writes a single file.
+- It loops: story, a 3 s hold on the final frame, a 0.4 s reset. `--once` plays once and freezes.
+- The attributes' base values are the final frame, so viewers without SMIL show the static diagram.
+- Fonts: `--font system` (default) uses the system mono stack; `--font embed` embeds Commit Mono
+  (+~127 KB) for the exact look. See the size table in [docs/spec.md](docs/spec.md#animated-svg).
+- No story in the spec? The auto story is used (with a warning).
+- Library: `renderAnimatedSvg(spec, { theme, once, font })` from `storyink/core`; plugin:
+  `storyink_render` with `animatedSvg: true | "both"`, `once`, `font`.
+- GitHub's image proxy caches by URL: when a diagram changes, give it a new file name (or URL).
+
 ## Gallery
 
 `bun run gallery` renders every example and Mermaid sample and writes one light and one dark PNG per
-example to `docs/gallery/`.
+example to `docs/gallery/`. `bun run gallery:animated` writes the animated SVGs of the story
+examples (`*.animated.light.svg` / `*.animated.dark.svg`); `bun run verify:smil` checks them in
+headless Chrome (frame parity with the viewer's frames, `<img>` playback, embedded font).
 
 | | |
 | --- | --- |

package/THIRD_PARTY_NOTICES.md

@@ -48,3 +48,10 @@ site are included. Serif headings use system fonts ("Iowan Old Style", Charter,
 
 storyink parses a subset of Mermaid syntax with its own hand-written parsers; no Mermaid
 or merman code is included.
+
+## PR Lens (patterns only)
+
+The animated SVG export follows the constraints and SMIL patterns of PR Lens's GitHub-safe SVG
+renderer (<https://github.com/coldteadotai/pr-lens>, MIT License, Copyright (c) 2026 Coldtea AI):
+self-contained files, no script or custom properties, animation as SMIL so it plays inside an
+`<img>` behind GitHub's image proxy. No PR Lens code is included.