storyink 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## 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`,