storyink 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 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

@@ -34,10 +34,11 @@ 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]
+                  [--preview out.jpg [--preview-size 1024]]
 storyink skill
 ```
 
@@ -74,8 +75,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.
@@ -90,6 +97,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 +128,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`,