storyink 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,192 @@
 # Changelog
 
+## 0.6.0
+
+- **Payload label track** — a pulse label now appears at departure parked clear of the source box,
+  holds until the dot catches up, moves with the dot, parks clear of the destination box and stays
+  fully visible until the dot touches it, then fades out over 0.2 s after arrival (was: faded out
+  before arrival and near every box). Multi-hop routes hand off between hops with a short fade
+  instead of drawing over the intermediate node. One rule (`pulseLabelWindows` /
+  `pulseLabelAnchor`) drives playback, the animated SVG and the labelled flight timing, whose
+  legible share is now the share where the label follows the dot.
+- **Readable payload labels in flight** — a pulse with a `label` now flies slower and at a steady
+  cruise (not `inOutCubic`), so its text stays legible while it travels: reading budget 0.6 s +
+  0.05 s per character over the legible share of the flight, clamped to 1.2–3.2 s, never faster
+  than before. An explicit pulse `duration` still wins; unlabelled pulses are unchanged
+  (byte-identical output). Shared by playback, step moves, snapshots and the animated SVG.
+- **Tones: colour carries meaning** — five tones (`note` blue · `warn` gold · `risk` rose · `good`
+  sage · `neutral` ink), one source shared with page tones (`theme/tones.ts`). Pulses take
+  `tone`, a payload `label` (mono, rides beside the dot, fades clear of nodes; layer gaps widen for
+  it), `land: "edge"` (the label stays as the arriving edge's label), `tint` (the target takes the
+  tone on arrival) and `stain` (each wire keeps the tone once the dot has passed). New `tone` step
+  field `{ ids, to, stagger? }` for nodes (all kinds), groups and edges: tinted face, toned
+  stroke / tag / detail, toned wire / ports / label, toned group border; 0.35 s crossfade; `to:
+  null` clears; `stagger` sweeps. `set` works on plain graph nodes (`label`, `detail`, `tag`, and a
+  detail-line `tone`), `status` on plain nodes draws the glyph at the start of the detail line;
+  boxes fit every version (no resize mid-story). `glow: { ids, tone }` glows in a tone. Caption
+  `*emphasis*` in the accent (`\*` literal). Timeline `tones`, frame `tone` / `litTone`, pulse
+  `tone` / `label`, caption `em`; HTML viewer, static SVG, snapshots, beat sheets and the
+  animated SVG (opacity-only tone layers) agree. Diagnostics with did-you-mean (tones, ids, pulse
+  fields), warnings for clipped labels, `tint` / `stain` without a tone, `land` without a label,
+  no-op tones, plain nodes still running at the end. Schema, docs ("Tones"), example
+  `examples/stories/request-colours.dataflow.json`. Specs without these features render
+  byte-identically.
+- **Acts: problem → rewind → fix** — `story.acts` (2–6 `{ id, label, tone? }`) and step fields
+  `act` / `enter` (`rewind` default · `cut` · `continue`) tell several scenarios on one stage
+  (graph diagrams). Elements say `in: [acts]`, or `delta` decides (removed → first act, added →
+  later acts); act stories drop the delta look. Positions are shared; each edge is routed only
+  against the boxes it coexists with, so a first-act wire runs straight through the slot of a
+  node the fix inserts (lint ignores pairs that never coexist). A rewind plays the previous act
+  backwards (eased, `clamp(len / 4, 0.6, 1.5)` s, captions hidden; HTML glitch + blur, plain in
+  the animated SVG), a cut dips; then a morph retracts leaving wires, fades leaving boxes, reveals
+  entering ones and draws entering wires. Later acts start from the previous act's start state.
+  Act chip ("● label", "◀◀ rewind") on the HTML stage and in the animated SVG header. `#act=<id>`,
+  `#sheet=acts`, `snapshot --act / --sheet acts` (tool `act`, `sheet: "acts"`), `render --svg
+  --act`. Timeline `acts`, frame `act`. Diagnostics with did-you-mean. Examples
+  `examples/stories/secret-broker.architecture.json` and
+  `examples/stories/payment-retry.acts.architecture.json`.
+- **Overlays: annotations, toasts, HUD** — `annotations: [{ id, on, side?, text, tone?, in? }]`:
+  one mono line on a node's left edge, above or below it, its room reserved by the layout (edge
+  labels avoid it); story `reveal` / `hide` / `show` / `type` (char or word, caret) / `set` (`text`,
+  `tone`) / `clear` / `tone` take annotation ids; a typed-first annotation is hidden until typed.
+  Step `toast` (`{ id?, near, title?, text, tone?, for? }`) and `dismiss` (ids or `"all"`):
+  floating cards placed deterministically at layout time (above the anchor, then shifted, then a
+  row higher, then below; never over nodes, groups, edge labels, annotations or toasts up at the
+  same time; the viewBox grows to fit), fade + rise + scale in, fade out; `tone` steps reach them;
+  warnings for toasts still up when an act or the story ends. `story.hud: [{ id, label, value?,
+  tone?, prefix?, suffix?, at? }]`: stage metrics driven by `counter` steps, toned and revealed
+  like elements; HTML stage overlay below the act chip, a header row in the animated SVG, a line on
+  beat / act sheet tiles. Rewinds and act resets cover all three. Timeline `toasts` / `hud`, frame
+  `toasts`; schema, docs ("Annotations", "Toasts", "HUD metrics"). The secret-broker and
+  payment-retry examples use them; `bun run gallery:stories` builds a local showcase
+  (`examples/stories/out/index.html`). Specs without these features render byte-identically.
+
+## 0.5.0
+
+- **Scrollytelling and slides: viewer** — figure API `beats()` and `moveTo({ beat } | { t },
+  { animate })` (forward plays, 2.5× across two or more beats; backward rewinds like ←; reduced
+  motion / `animate: false` jump to the settled state with a pure follow camera). Scrolly
+  controller: `sp-scrolly-live`, the step crossing a 55 % trigger line is `.is-active` and moves
+  the figure; figure transport / gate / rail hidden in scrolly (zoom, Fit, Expand stay); cite hover
+  highlights and file cites open the drawer; `#scrolly=<id>&step=<n>` (settled, for snapshots).
+  Deck (present mode): `html.sp-presenting`, `.is-current` slide in a 1280×720 frame scaled to fit
+  (`--sp-slide-scale`), builds from page data (entry forward = start, backward = end), keys →
+  Space PgDn Enter / ← PgUp Backspace / Home End / O outline / ? help / Esc / P, Present button,
+  chrome (progress, `n / N`, prev / next), figure keys off while presenting, `#present=1|0`,
+  `#slide=n`, `#build=k`, `layout: "slides"` opens presenting; `slide-overflow` lint (content
+  needing a scale under 0.7). `__storyink.deck = { present, exit, next, prev, state }`. Snapshot
+  `--slides [--builds]`, `--scrolly <id|all>` (plugin `slides`, `builds`, `scrolly`): frames +
+  labelled sheets per theme, gates ready / lint / deterministic, `--preview`.
+  `scripts/deck-verify.ts` (`bun run verify:deck`).
+- **Scrollytelling and slides (pages)**: `scrolly` block (a figure pinned beside prose step
+  cards; each step's `at` names a story step id, chapter stop, beat number, `start` or `end`;
+  `steps: "auto"` from narrated steps or stops; cites; decreasing targets warn), static / no-JS /
+  print fallback and live CSS (sticky graphic, `.is-active` steps, narrow stacking). Slides from
+  the same DOM: `layout: "slides"`, `present`, section `slide: { layout }`, `break` blocks, figure
+  `builds`; title slide + one slide per section, layouts `title` / `full` / `split` / `center` /
+  `flow` (auto inferred; `data-fig-shape="tall|wide"` gives tall figures the full slide height),
+slide content CSS inside the viewer's 1280×720 frame, Present button. Figure `spec` paths may be
+relative, absolute, `file://` or `~/`. Page data gains
+  `scrolly` and `slides` (targets `{ beat, t }` resolved from the figure timelines). Pages markup
+  gains `.sp-slide` wrappers (`display: contents` in the article) and `data-layout` /
+  `data-present`. Examples: `payment-retry.scrolly`, `storyink-0.4.0.scrolly`, `pr-review.deck`.
+- **Pages** (`"type": "page"`): offline single-file explainer documents (PR / diff reviews, plan
+  reviews, recaps) rendered from JSON: header (eyebrow, title, subtitle, `change` meta, summary,
+  theme toggle), sticky contents sidebar with scroll-spy (auto at ≥ 4 sections; a top list on
+  narrow screens / without JS), sections of blocks: `prose` (safe Markdown subset, no raw HTML),
+  `figure` (an embedded storyink diagram, spec object or path, with a `claim` caption), `kpis`,
+  `table`, `cards`, `callout`, `filemap` (tree with status, +/− and bars; collapses past 16
+  files), `diff` (from `--changes` or hunk text), `code`, `risks`, `decisions`, `evidence`,
+  `timeline`, `checklist`, `details`, `columns`. Serif reading measure, wide figures / tables /
+  diffs, semantic tones on the delta palette (`pagePalettes` / `page` tokens), both themes, print
+  stylesheet. Core: `isPageSpec`, `validatePage` (figure diagnostics prefixed with the figure
+  path), `renderPageHtml`, `resolvePageChanges`, `layoutPage`; Node: `loadPage`, `writePage`.
+  CLI `render` / `validate` and the plugin's `storyink_render` / `storyink_validate` (new `path`
+  param on render) detect pages and resolve figure paths; `--svg` / `--animated-svg` on a page are
+  errors. Schema: root `type: "page"` alternative. The drawer's HTML diff is now a shared
+  `DiffView` (`src/core/render/DiffView.tsx`, same markup). Diagram `validate()` points pages at
+  `validatePage`. Examples in `examples/pages/`. Single-diagram output unchanged.
+- **Pages: viewer** — page figures are the interactive viewer embedded (`renderFigure` →
+  server-rendered App in embedded mode): captions above an aspect-sized stage, compact toolbar (no
+  theme button, Expand), transport, gate, pan / zoom (wheel zoom needs Ctrl / ⌘ unless expanded so
+  the page scrolls), story playback, follow camera, narration rail beside the stage when the figure
+  is wide (container query) else below, drawer as a page overlay, Expand (fills the window; Esc
+  returns). The viewer bundle detects `#storyink-page-data` and hydrates every `[data-si-fig]` root:
+  keys act only on the focused figure (tabindex, click focuses), `#fig=<id>` scopes `t` / `camera`
+  / `motion` / `pace` / `drawer` / `rail` / `autoplay` / `static` to a figure (page-wide: `theme`,
+  `static=1`), unrelated hash changes (TOC anchors) don't refit, exports / counters / lint are
+  per figure, `__storyink = { page: true, figures: { id: api }, ready, whenReady, lint }`.
+  `#fig=<id>&solo=1` shows only that figure with the standalone chrome and contract. `idPrefix`
+  on `Diagram` / `renderSvg` (every def id and `url(#…)`), default empty. Snapshot detects page
+  HTML: full-page PNG per theme (width 1280; figures at their final frame), gates ready / lint
+  (figures + page text overflow) / deterministic, `--preview` split into ≤ 3 parts;
+  `--figure <id>` (tool param `figure`) runs the single-diagram pipeline on one figure.
+  `scripts/page-verify.ts` (`bun run verify:page`). Single-diagram output unchanged.
+- **Change stories**: story step `change` (before look until the step: removed = plain, added =
+  absent, modified = plain; then removed edges retract and ghost, removed nodes strike and fade,
+  added ones reveal / draw on, modified ones flash and turn gold, diff nodes apply; badges, strikes
+  and legend items follow); `story: "changes"` / `{ steps: "changes" }` / `--story changes` /
+  tool `story: "changes"` derive the walkthrough (data-flow order, edges and attached diff nodes
+  per beat, hero pulse trains, overview, `narrate` from `summary`); `focus` takes a list (union
+  box); `spotlight: "veil"` (soft rounded cutout around the step's focus, gliding, gone at the
+  end; HTML and animated SVG). Animated SVG: diff rows settle exactly (tighter keyframe tolerance).
+- **Narration rail and change drawer** (HTML viewer): story step `narrate: { heading?, body,
+  cites? }` (cites link body text to element ids, `node#row` or `path#L12-20`; validated in order,
+  refs must resolve). A narrated step without a caption captions with its heading (or the body's
+  first sentence) at compile time, so the animated SVG and beat tiles agree; narrated beats hold
+  for their body. The viewer shows a rail ("02 / 06", heading, body with cites) that tracks the
+  header caption's beat through playback, the scrubber, → / ← and the gate; side column on wide
+  screens, bottom sheet below 760 px; toolbar toggle and `N`. Clicking (not dragging) an element
+  with `summary` / `files` / a delta opens a drawer with its badge, stat, summary and file refs,
+  and with `--changes` the selected hunks as an HTML diff (gutter, tints, syntax colours,
+  intra-line marks); Esc / × close it. `#drawer=<id|path>`, `#rail=0|1`,
+  `__storyink.openDrawer(id)` / `closeDrawer()` / `drawer()`, `steps[i].narrate`. The scene carries
+  embedded `changes` for the drawer. `storyink snapshot --rail --drawer <id>` (tool params `rail`,
+  `drawer`; captures the 16:9 page viewport, gates compare the same configuration). The drawer
+  takes the rail's column while open. `scripts/narrate-verify.ts` (`bun run verify:narrate`). Example:
+  `examples/changes/storyink-0.4.0.pr.json` (commit b526d50). Specs without these fields render
+  byte-identically.
+- **Diff code nodes**: `code` nodes take `diff` (unified hunk text, `{ file, lines?, context?,
+  max? }` resolved by `--changes`, or resolved `{ file, hunks }`): gutter with old | new numbers,
+  `+` / `−` markers, sage / rose row tints (`diffAddBg` / `diffDelBg` tokens) with stronger
+  intra-line marks (token-level LCS), muted `@@` hunk headers with their section, per-language
+  syntax colours, a `… N more lines` fold (`max`, default 24) and long lines cut at 72 columns.
+  Anchors `node#+14` (head line) / `node#-13` (base line); `line` takes them and `{ id, hunk }`.
+  Story step `apply` (`"id"` or `{ id, hunk?, cps? }`): the node shows the base version until
+  then, removed rows tint and strike, added rows open (rows below slide) and type in, gutter
+  numbers fade in; HTML and animated SVG. Validation for diff shapes (an unresolved `{ file }`
+  without `--changes` is an error with a hint), anchors, `apply` and set / clear / type on diff
+  nodes. `diffRows(hunks, lang, { max?, headers? })` row model in `storyink/core`. Animated SVG:
+  wired dashed edges and the labels of wired edges now fade with their draw (as in the HTML).
+  Change scenes: `unchanged` nodes use the neutral accent. Examples: `payment-retry`,
+  `etl-dedupe` (Python + SQL), `storyink-core` (rendered with `--changes`).
+- **Change diagrams**: `delta` (`added` / `modified` / `removed` / `unchanged`) on nodes, groups,
+  edges, participants and messages; `emphasis` (`hero` / `muted`) on edges and messages; `stat`
+  (`+38 −12`), `summary` and `files` (paths or `{ path, lines, revision }`); root `change`
+  (`base → head` shown above the diagram) and `style.legend`. Added = sage + `NEW` badge,
+  modified = gold + `CHANGED`, removed = rose dashed ghost with a struck label + `REMOVED`,
+  unchanged = receded context; hero edges are thicker with a soft glow. Layout reserves badge room
+  (header strip, top strip, right slot or a centred row by shape) and a legend band listing the
+  deltas present. Static SVG, HTML and animated SVG (change scenes use the union SMIL mode; removed
+  edges draw on by opacity so they keep their dash); composes with story levels and rich nodes.
+  Validation with JSON paths and hints (enums, file refs, negative stats, added edges to removed
+  nodes, more than 2 hero edges). New palette `deltaPalettes` and `delta` geometry tokens, emitted
+  only when a scene uses them: specs without the new fields render byte-identically. Examples in
+  `examples/changes/` (`batch-email` ported from PR Lens, `auth-session-to-jwt` sequence,
+  `rate-limit-plugin` with panel / code / chip deltas).
+- **Diff ingestion**: `storyink diff [<range>|<base> [<head>]] [--staged] [--patch file|-] [-o
+  changes.json] [--json] [-- <pathspec>…]` parses `git diff` (default: working tree vs the merge
+  base with main/master) into a `DiffSet` and prints a per-file summary; `render --changes
+  <changes.json|.diff|.patch>` resolves the spec first. Core (browser-safe): `parseUnifiedDiff`,
+  `parseHunks`, `selectHunks`, `statFor`, `langForPath`, `normalizeLang`, `coverage`,
+  `resolveChanges` (fills `stat` from `files`, resolves `diff: { file, lines }` code nodes,
+  embeds the referenced hunks as `changes`, capped at 400 lines per file, and warns about
+  uncovered files / hunks and refs that miss the diff). Node: `gitDiff`, `diffSetFrom`.
+  Plugin: `storyink_diff` tool and `changes` on `storyink_render`.
+- **Code languages**: `py`, `go`, `rust`, `sql`, `yaml`, `sh` lexers; `lang` aliases (`python`,
+  `golang`, `rs`, `yml`, `bash`/`shell`/`zsh`, `typescript`/`tsx`, `javascript`/`jsx`) are
+  accepted and normalized. TS / JS / JSON colouring is unchanged.
+
 ## 0.4.0
 
 - **Rich nodes** (architecture, dataflow, workflow): `panel` (window with rows: `tag`, `icon`,