storyink 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.4.0
+
+- **Rich nodes** (architecture, dataflow, workflow): `panel` (window with rows: `tag`, `icon`,
+  `text`, `detail`, `status`, `indent`, `muted`), `code` (syntax-coloured program, `lang`
+  ts|js|json|text) and `chip` (icon + label, `stack` 1..3); `size: { cols, lines }` reserves body
+  space; `icon` set (wrench plug file terminal search globe bolt user spark); `muted` nodes; bare
+  groups (`bare: true`, heading only).
+- **Anchors**: edges and story targets may name a panel row (`node#row`) or a code line
+  (`node#3`); wires attach at that row/line.
+- **Content steps**: `type` (char typing with caret for code, `cps` / `duration`; word typing for
+  rows), `set` / `clear` (crossfade), `line` (active-line bar), `status` (spinner + shimmer, check,
+  cross), `dim` / `undim` (levels, independent of `hide` / `show`), `wire` / `unwire`, `glow` /
+  `unglow`, `focus`. Pulses gain `reverse` and `delay`. Story options `spotlight` and
+  `rewind: "glitch"` (HTML only). Typing speed is not scaled by `pace`. Warnings when the end state
+  still shows a spinner or a glow.
+- **Animated SVG** covers the new content (typing clips, caret, crossfades, line bar, status,
+  shimmer, levels, wire/unwire, glows, spotlight) with the final frame still the static diagram.
+  Checked in headless Chrome (frame parity, `<img>` playback, loop return); Firefox plays it;
+  Safari untested.
+- Four examples: `code-mode.architecture`, `retry-helper.architecture`,
+  `agent-session.architecture`, `failover.dataflow`; animated SVGs in `docs/gallery/`.
+- Fix: with reading holds (pace > 0), a step with an absolute `at` inside a beat stayed at its
+  authored time while its beat was pushed later, so it ran out of order and → / ← could stop with
+  pulses mid-wire. It now keeps its authored offset from the previous step.
+- Docs: `story` is no longer described as reserved; `#t=` documented as a seek.
+
+## 0.3.6
+
+- **Default `story.pace` is 0.6** (was 1): shorter reading holds after each beat. `pace: 1` gives
+  the 0.3.5 holds, `pace: 0` the pre-0.3.5 timing. Applies to the viewer, `render` (and
+  `--pace`), the plugin and animated SVGs (built with their pace). Durations: OpenWick
+  architecture 176 s → 135 s, data flow 95 s → 78 s, checkout 30 s → 26 s, OAuth 57 s → 47 s.
+- **Pauses in the viewer**, changeable after the build: a toolbar button (`Pauses: Normal`)
+  cycles None (0) · Short (0.3) · Normal (0.6) · Long (1.0) · Longer (1.5); `[` / `]` step down /
+  up; the choice is remembered (`localStorage["storyink-pace"]`); `#pace=<n>` wins. The HTML
+  embeds a small `timeline.source` and the viewer recompiles the timeline in the browser with the
+  same compiler (`recompilePace`, byte-identical to `render --pace`). The reader keeps their place
+  (same beat, same progress; `mapStoryTime`) and playback continues; duration, ticks, → / ← stops,
+  stepped holds and the follow camera follow the new timeline. Page contract: `pace()`,
+  `setPace(n)`. Viewer bundle +16.5 KiB (388.5 → 405.0 KiB).
+- `storyink snapshot --pace N` (tool `storyink_snapshot` `pace`) pins the pace for every capture;
+  by default snapshots use the author pace.
+- **→ / ← no longer wait for the text.** Step moves animate the graph only: → plays to the end
+  of the next beat's graph motion (pulses arrived, reveals and draw-ons done; not caption typing,
+  glows, trail cooling, rings or the reading hold; `beatMotionEnds`) and pauses; pressed during a
+  reading hold (or right after a stop) it starts the next beat at once. ← rewinds the graph at 2×
+  to the previous beat's motion end. The beat's caption shows whole and instantly as the move
+  starts (← shows the target beat's) and stays at the stop (`storyState(…, { captionBeat })`).
+  Continuous play, stepped playback, the scrubber and the default `storyState` are unchanged.
+- Stepped (reduced-motion) stops last at least 0.8 s (the bare-beat hold).
+- Fix: clicking a toolbar button while the play gate showed also started the story.
+
 ## 0.3.5
 
 - **Fix: the diagram showed a hover tooltip** (the diagram title) wherever the cursor rested. The

package/README.md

@@ -128,8 +128,10 @@ previous one (Shift: by chapter; repeated presses extend the move).
 
 Playback **pauses to read after each beat**: about 1 s + 0.3 s per word of its caption (1.5–6 s;
 0.8 s without one) once the beat is still, before the next beat starts. The animation speed is
-unchanged. Set `"story": { "pace": 1.5 }` (or `--pace`) to slow it further, `0` for none, or
-`"hold": 3` on a step for its beat.
+unchanged. The default `pace` is 0.6; set `"story": { "pace": 1.5 }` (or `--pace`) to slow it,
+`0` for none, or `"hold": 3` on a step for its beat. Readers change it on the page with
+**Pauses** in the toolbar (None · Short · Normal · Long · Longer, `[` / `]`, remembered;
+`#pace=` in the URL); the viewer recompiles the timeline in the browser and keeps their place.
 
 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
@@ -146,7 +148,26 @@ and a drag pauses following until the next step that is out of view. Toggle it w
 (`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
+### Rich nodes and content steps (0.4.0)
+
+For agent sessions, generated code and tool servers, graph diagrams take `panel` (a window of
+rows), `code` (a syntax-coloured program) and `chip` nodes, with wires anchored to a row
+(`session#exec`) or a code line (`code#1`). Stories can then `type` code and rows, swap content
+(`set` / `clear`), move an active-line bar (`line`), show row `status` (spinner and shimmer,
+check, cross), `dim` / `hide` / `show`, draw or retract wires (`wire` / `unwire`), keep nodes lit
+(`glow`), follow the action with a `spotlight`, send reverse and staggered pulses, and reset with
+a `glitch` rewind (HTML only). Examples:
+[code-mode](examples/code-mode.architecture.json),
+[retry-helper](examples/retry-helper.architecture.json),
+[agent-session](examples/agent-session.architecture.json),
+[failover](examples/failover.dataflow.json). Details: [docs/spec.md](docs/spec.md#rich-nodes-panel-code-chip).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/gallery/code-mode.architecture.animated.dark.svg">
+  <img alt="Code mode: a session runs a program that calls MCP servers (animated)" src="docs/gallery/code-mode.architecture.animated.light.svg">
+</picture>
+
+The final frame is the static diagram (with content steps: the story's end state). 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
@@ -182,12 +203,19 @@ storyink render examples/checkout.architecture.json --animated-svg docs/checkout
 - 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).
+- Rich content (typing, status glyphs, line bars, spotlight) animates too. Frame parity is checked
+  in headless Chrome; Firefox plays it in `<img>`; Safari is untested. The glitch rewind and the
+  follow camera are HTML-only.
 
 ## Gallery
 
 `bun run gallery` renders every example and Mermaid sample and writes one light and one dark PNG per
 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
+examples (`*.animated.light.svg` / `*.animated.dark.svg`; `--only name,…` writes just those);
+animated: [code-mode](docs/gallery/code-mode.architecture.animated.light.svg),
+[failover](docs/gallery/failover.dataflow.animated.light.svg),
+[retry-helper](docs/gallery/retry-helper.architecture.animated.light.svg),
+[agent-session](docs/gallery/agent-session.architecture.animated.light.svg). `bun run verify:smil` checks them in
 headless Chrome (frame parity with the viewer's frames, `<img>` playback, embedded font).
 
 | | |