storyink 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 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
+  sheets (1440 px wide, thousands of px tall) could stall the next model request and bloat
+  session context. It now returns **one compact JPEG preview**, with its longest side at most
+  1024 px and a 300 KB budget. Beat sheets are reflowed into 3–8 columns so they fit in one
+  image.
+  - New tool options: `image: "overview" | "full" | "none"` (default `overview`; `full` returns
+    at most 3 parts) and `maxImageSize` (default 1024).
+  - Full-resolution PNGs stay on disk and are listed in the text result.
+- CLI: `storyink snapshot … --preview out.jpg [--preview-size 1024]` writes the same preview.
+- Snapshot receipts include `previews` (path, size, bytes, what the image shows).
+- The beat-sheet page accepts `#cols=N`, `#range=a-b` and `#zoom=z`.
+- SKILL.md: guidance on keeping image reads few and on using `at` frames for detail.
+
+## 0.2.0
+
+- Storyboard mode: `story` steps and `"story": "auto"`, the pure `storyState(t)`, the viewer
+  transport and counters. Snapshot gets `--at`, `--sheet beats` and the static gates.
+- Fixes: captions belong to their own step, humanised beat titles, warm light-theme glow,
+  beat sheets sized to their content.
+
+## 0.1.0
+
+- First release: spec, validation, Mermaid import, layout, SSR/viewer, CLI, OpenCode plugin.

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,9 +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]]
 storyink skill
 ```
 
@@ -74,8 +89,14 @@ read `package.json` `main`, which is why the repo ships a root `server.js` that
 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
+`storyink_snapshot`. `storyink_snapshot` returns **one compact preview image** so the model can see its
+own render: a JPEG no larger than `maxImageSize` (1024 px by default) on its longest side, and
+usually well under 300 KB.
+- Beat sheets are reflowed into more columns so they fit in that single image.
+- Set `image: "full"` to get the normal sheet layout instead, split into at most 3 parts, or
+  `image: "none"` to get paths only.
+- Full-resolution PNGs are never inlined; they stay on disk and their paths are listed. The CLI
+  equivalent is `--preview out.jpg`. 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.
@@ -111,10 +132,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.