footprint-storydeck 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 0.7.0 — a deck from a folder, an editing loop, co-editing and wire motion
+
+- **A packet rides its wire's curve, and a wire shows itself in.** On a `path` click, a `pkt` packet now follows the
+  wire's quadratic curve (it crossed a bent wire in a straight line, up to 78 px off it); in Chromium, Firefox and
+  WebKit it stays within 0.15 px of the drawn line. CSS only: one registered number, `--sd-t`, runs 0 → 1 and the
+  packet stands at B(t) from the control point and end each wire gives it (`--cdx`/`--cdy`, beside `--pdx`/`--pdy`).
+  A wire that comes in shows itself from start to tip behind a sweeping soft edge — a mask, so a theme's dashes and
+  colours stay as they are — at its own moment (its turn on a path, after a new blur); a highlighted wire just fades
+  in, so its ring (drawn outside its box) shows. focus.css gains one more animation slot a stylesheet may give a piece,
+  `--sd-a-more`, and `--sd-twin-lag`, so a wire stepping aside for its twin leaves as the twin's sweep nears the tip.
+  Reduced motion, a jump and print show the plain wire.
+
+- **`storydeck`: a deck is a folder, and the library builds it.** deck.json, clicks.html (a `<section>` per part; on a
+  map, a `<step>` per click), the maps, theme.css and icons/ become one self-contained page (`storydeck build`): every
+  stylesheet and runtime inlined, notes, presenter and listen mode, a light/dark toggle (T), no network request. No
+  build script per deck: a 37-click talk's own script is replaced, and its slides come out byte for byte. Built-in
+  helpers: `data-arrow` wires (with a packet, class `pkt`, that rides the wire at its turn on a `path` click) and
+  `data-icon` icons. New `footprint-storydeck/deck.css`: the page's chrome, wires, packets, icons and toggle, every rule
+  `:where()` so a deck's theme wins.
+- **`storydeck dev`: one page in development and in the room.** It serves the page `build` writes, plus a dev client: a
+  save rebuilds (milliseconds), reloads on the same click and plays it again; a save that breaks the build shows why over
+  the last good page. Loopback only, localhost requests only, read-only, nothing hidden or outside the deck folder.
+- **Co-editing: the person points, the agent edits.** In `storydeck dev`, **note** leaves a note on the click you are on
+  (appended to `feedback.md`, a checklist with the click, its label and the time), and **Alt-drag** moves a piece of the
+  map: its inline left/top, or a wire's `data-arrow`, is written into the map file — every other byte kept — and the
+  page reloads on the same click. `storydeck feedback` (and the MCP `feedback` tool) lists the open notes; `check`
+  counts them. The server takes these two edits only from its own page: its origin, a per-session token only that page
+  carries, JSON, 16 KB at most; written never through a link; no other origin may frame it. A note is signed with a key
+  kept with the person (`~/.storydeck/key`, or STORYDECK_HOME), and only signed notes are listed — a feedback.md that
+  came with someone else's deck is counted, never read as your requests. A move names the piece by the number the build
+  gave it (in the dev page only) and is refused while the build fails, when the map changed since the build, or when a
+  browser would read the piece's tag differently; a bare `0` moved is written in px. Everything the tools print is
+  text, never what a reader cannot see (controls, bidi marks, Unicode tag characters, runs of selectors); a note's
+  signature covers the person's words and the deck's folder, never the click's label (the deck's text), which is never
+  listed. In development only StoryDeck's own scripts run (a nonce policy on every answer): a deck's own scripts run in
+  the built page, and none can reach the dev page's edits. The build refuses a `data-sd-…` attribute a deck writes
+  itself. The note key is never read through a link or a second name, nor kept inside the deck folder. Every rule that
+  compares paths does so as the disk spells them (`realpathSync.native`), so on a disk that ignores case one folder is
+  never taken for two. `loadDeck`/`compileDeck` take `{dev}`; `deckHtml` also returns the source.
+- **Every scan of a deck's text is one pass.** Stripping comments, reading a map's pieces and drawing a slide's focus
+  (`readPieces`, `drawFocus`, also on `footprint-storydeck/focus-html`), reading an icon file, and drawing wires and
+  icons were quadratic on unfinished tags, unclosed comments or one tag repeating an attribute: a hostile 4 MB map took
+  minutes, and `storydeck dev` never came up. Each now reads in one pass (a 4 MB hostile map builds in about 30 ms),
+  proved equal to the regex it replaced on thousands of generated inputs, with one deliberate difference: a tag ends at
+  its first `>`, so a `data-k` name holding `>` is not read. An `<i data-icon>` naming a property every object has
+  (`constructor`) is now refused as an unknown icon.
+- **Read first, look last.** `storydeck outline` (a line per click), `review --click n` (headline and words, focus, route,
+  lit, greyed, what enters, leaves and moves, notes) and `check` (headline words, pieces lit by coming in, clicks that
+  change nothing, pieces never shown, missing notes — each with its click and its fix). `check --layout` measures each
+  click in a browser for text that spills out of its box (through the video driver's new `measure(n)`; needs
+  `playwright-core`). `storydeck mcp` serves the same tools to an AI assistant over stdio. `storydeck init` writes a
+  starter that builds and checks clean.
+- **A deck is files, never a program — on your machine.** No deck code runs in Node; Playwright, for the layout check,
+  is loaded only from beside StoryDeck (never from the deck folder or the folder you run in), and the page is measured
+  offline (`deckStageDriver({offline: true})`: no name resolves, the context is offline and routed to the page's own
+  file, WebSockets and popups closed; Playwright 1.48 or newer). A deck reads only its own files: a link out of the
+  folder, or to a hidden file, is refused. A build renames a new file into place (never writing through a link) and a
+  file deck.json names never lands outside the deck; `--out` writes where you say. The dev server is loopback-only and
+  survives any request; the MCP server reaches only decks inside the folder it was started with. A deck's own HTML still
+  runs in the browser, like any page: open decks you trust.
+- **`zoom` is a camera, so it goes with a mover.** A click can close in while its parts fly apart (`zoom apart`) or move
+  (`zoom place`): the camera frames the subject where the mover leaves it. A new strategy kind, `camera` (one a click);
+  a camera sees the click as the mover leaves it (subject, context and named groups moved). `zoom` alone draws exactly
+  as before, its `subject`/`aside` options included. Refused, naming the fix: a camera with `left`/`right`/`up`/`down`
+  (they keep the context in view beside the subject, which closing in would push off the slide), and a camera with a
+  deck's own mover that moves the view itself.
+- **A blur frames the subject where it ends up.** On an `apart` or `place` click, the subject's box in the plan
+  (`look.subject`) and the blur's frame now follow the subject to where its group moved it (before, they kept where it
+  stood). Other clicks are unchanged.
+- `footprint-storydeck/deck` exports the same parts for a script; `deckStageDriver` gains `measure(n)`, and
+  `measureSlide` is exported from `footprint-storydeck/video`.
+
+## 0.6.0 — a figure in any framework, and compiled JavaScript
+
+- **`StoryFigure`: the Scroll lens drives a figure it does not know how to draw.** A section's `figure` may
+  now be `{ mount(el), seek(beat), dispose() }` beside the React render function it already took. The lens
+  mounts it once into a plain element in the pinned stage, asks it to `seek` with the beat's plain coordinates
+  (`{ key, index, sectionKey, step }`) on every beat change, and prints the sentence a seek resolves to under
+  the figure (a refusal, verbatim) until a later seek answers; only the latest seek's answer is shown.
+  `isStoryFigure` is exported. Additive: render-function figures and HTML steps are unchanged.
+- **The package ships compiled JavaScript.** `dist/` holds each source file compiled on its own (JSX to
+  `react/jsx-runtime`, relative imports with `.js`, `'use client'` kept), so plain Node and any bundler load
+  it with no transform: the `.jsx` workarounds consumers needed (`transpilePackages`, a test runner's
+  inline list) are no longer required. Types stay the hand-kept `*.d.ts`. `npm run check:dist` loads every
+  door in plain Node and refuses a package that ships source JSX; CI runs it.
+
 ## 0.5.0 — PowerPoint, the exploded view, and a tour for decks nobody presents
 
 - **`footprint-storydeck/pptx`: the deck as a PowerPoint file.** `exportPptx` makes a slide per click: its settled

package/README.md

@@ -7,7 +7,7 @@
 - **Watch** — an animated, click-through slide deck.
 
 Same content, your lens. It's the footprintjs idea — *one canonical record, you choose the view* —
-applied to content. A React library; theme-agnostic; ships as source.
+applied to content. A React library; theme-agnostic; ships compiled ESM that Node and any bundler load as-is.
 
 > Demo (dogfooded — storydeck explaining storydeck): **[footprintjs.github.io/storydeck](https://footprintjs.github.io/storydeck/)**
 > First consumer: the **[footprintjs blog](https://footprintjs.github.io/blog/)**.
@@ -58,6 +58,32 @@ A function cannot come from JSON, so `figure` is not part of the authoring model
 builds sections from post.json + Markdown, and the consumer attaches `figure` to them. The beat a
 figure is handed carries `sectionKey`, `step` and `index` — which beat it is being asked to draw.
 
+### A figure in any framework: `StoryFigure`
+
+A section's `figure` may instead be a **`StoryFigure`** — three plain methods, no React:
+
+```ts
+interface StoryFigure {
+  mount(el: HTMLElement): void;                         // draw into this element
+  seek(beat: StoryFigureBeat): Promise<string | void>;  // the reader is on this beat: move there
+  dispose(): void;                                      // take down what mount drew
+}
+// StoryFigureBeat = { key, index, sectionKey, step } — plain data
+```
+
+```js
+const figure = { mount(el) { chart.attach(el); }, seek: (beat) => chart.goTo(beat.sectionKey), dispose() { chart.detach(); } };
+<ScrollyView sections={sections.map((s) => ({ ...s, figure }))} />
+```
+
+It is the seam for a figure the story should not have to know: a chart library, a canvas, another
+framework's component. `ScrollyView` adapts it in a thin host — mounted once while it is on stage (a
+different section's figure is disposed and the new one mounted), and asked to `seek` on every beat change.
+**A seek that cannot move says why:** it resolves to a sentence, and the lens prints that sentence under the
+figure, verbatim, until a later seek answers; it resolves nothing when it moved. Only the latest seek's
+answer is shown, and a seek that rejects is shown as the lens's own sentence. The lens judges nothing — the
+figure knows whether it can stand on a beat. `isStoryFigure(value)` is the check the lens uses.
+
 ## Focus: what a click is about, and what happens to the rest
 
 A talk often tells its story on **one picture** — a diagram, a page, a timeline — click by click. Each
@@ -70,7 +96,7 @@ decision every click makes again, so it is data on the click, and the library do
 | Kind | Strategies | What happens |
 |---|---|---|
 | look | `grey` (default) · `hide` · `keep` | how the context looks: greyed in place, hidden, or left as it is |
-| mover | `zoom` | the view closes in on the subject (`share`, `most`) |
+| camera | `zoom` | the view closes in on the subject — where the click's mover leaves it (`share`, `most`): so a click can close in while its parts fly apart (`zoom apart`) or move (`zoom place`). With `left`/`right`/`up`/`down`, which keep the context in view beside the subject, it is refused |
 | mover | `left` · `right` · `up` · `down` | the context steps aside that way, smaller (`scale`), and the subject grows into the room it leaves (`grow`, `fill`, `gap`, `align`; `move: 'aside'` keeps the subject where it is) |
 | mover | `place` | named groups moved by the amounts you give (`groups: 'page floor: -90 -200 0.5 \| tl: 0 -230 1.1 @ 960 968'`): a layout you art-direct, still animated from wherever the last click left it |
 | mover | `apart` | the exploded view: named groups fly apart along the vectors you give (`apart: 'lid: 0 -120 \| core: 160 0 \| base: 0 120 1.1'`), one spring each, `stagger` ms apart (35), and come back together on a later click without it — the last one out is the first one back |
@@ -113,8 +139,9 @@ The order is what the library keeps; where the parts go is yours — vectors tha
 each part its own way out. The click after a close keeps the closing groups on their springs one click more, so a
 quick click lets them settle from wherever they are. A line or connector that carries a group's name
 (`data-k="wire core"`) moves with that group, keeping its place against it. `apart` is a mover, so it goes with a look (the rest
-greyed), an overlay and an order, and a click that also asks for `place` is refused, naming the fix; across clicks
-the two compose: the parts fly out from the layout `place` left, and back into it.
+greyed), a camera (`zoom apart`: the view closes in on the subject where it flies to), an overlay and an order, and a
+click that also asks for `place` is refused, naming the fix; across clicks the two compose: the parts fly out from the
+layout `place` left, and back into it.
 
 The springs run in `focusRuntime` (the Watch lens, `SlideDeck`, installs it; a built page inlines it), each deck on
 the page its own, played as Web Animations of the same `translate`/`scale` every mover uses (so a piece's own
@@ -152,8 +179,8 @@ const slides = looks.map(look => `<section class="${slideClass(look)}">`
 
 Pieces don't nest, so each one greys and moves on its own; a mover keeps every group's shape (the
 pieces of the subject move together, around the subject's centre) and composes with a piece's own
-transform (it uses CSS `translate`/`scale`, not `transform`). A mover's `aside` and `subject` options
-name its two groups when they are not simply the greyed and the lit pieces, and `data-twin="name"` makes
+transform (it uses CSS `translate`/`scale`, not `transform`). A mover's `aside` and `subject` options (or, on a
+click with no mover, the camera's) name its two groups when they are not simply the greyed and the lit pieces, and `data-twin="name"` makes
 a piece (a dashed wire under a solid one) step aside while its twin is lit. A piece that leaves fades out
 from how it looked and where it stood; a blur that moves to another subject stays, and only its frame is
 new; overlapping holes stay clear, and nothing outside the `area` is blurred.
@@ -339,6 +366,81 @@ is validated against them. Limits: a clip is embedded as it is (a .wav as voiced
 mono — convert to .m4a to shrink a long talk); no ZIP64, so a file stays under 4 GB; the slides advance by
 themselves when the show's "use timings" is on (PowerPoint's default).
 
+## A deck from a folder: `storydeck`
+
+Building a talk by hand meant writing a build script for it: reading the maps, planning each click's focus,
+wrapping the slides, inlining every runtime. That script was the same for every deck, and it was where an editing
+session spent its time. So a deck is now a **folder**, and the library builds it:
+
+```
+my-talk/
+  deck.json      { "title": "A request, end to end" }   — and footer, area, checks when you need them
+  clicks.html    a <section> per part; on a map, a <step> per click (data-in, data-on, data-focus, <h2>, notes)
+  map.html       the picture: every data-k element with an inline left/top/width/height is a piece
+  theme.css      tokens (light, :root.dark) and the look of your pieces
+  icons/*.svg    drawn identities, used as <i class="ic" data-icon="server"></i>
+```
+
+```bash
+npx footprint-storydeck init my-talk      # a starter deck that builds and checks clean
+npx footprint-storydeck dev my-talk       # live preview: a save rebuilds, reloads on the same click, plays it again
+npx footprint-storydeck feedback my-talk  # the notes left in the dev page, for whoever edits next
+npx footprint-storydeck build my-talk     # my-talk/index.html — one page, every runtime inside, no network request
+```
+
+- **One page, in development and in the room.** `dev` serves the very page `build` writes, with a small dev client
+  added: a save reloads on the click you were on and plays that click again (*replay on save*), a save that breaks the
+  build shows why over the last good page, and a bar names the click you are on. Nothing of it ships. The page keeps the
+  keys a talk needs: ← → Space step, **T** light/dark, **N** notes, **P** presenter window, **L** read aloud.
+- **Co-editing: the person points, the agent edits.** In the dev page, **note** leaves a note on the click you are on
+  (appended to `feedback.md`, a checklist), and **Alt-drag** moves a piece: its new left/top — or a wire's
+  coordinates — is written into the map file, every other byte kept, and the page reloads on the same click. An agent
+  reads the open notes (`storydeck feedback`, or the MCP `feedback` tool; `check` counts them), makes the change, and
+  ticks the line (`- [x]`). Pointing costs the person a second and the agent no screenshot. Each note is signed with a
+  key kept with you (`~/.storydeck/key`) for that deck's folder, so a feedback.md that came with someone else's deck is
+  never read as your requests: its lines are counted, never listed.
+- **Read first, look last.** A reviewer — a person, or a model that pays for every screenshot — reads the deck as text:
+  `outline` (a line per click), `review --click 14` (its headline and words, what it lights, greys, brings in and moves,
+  its route, its notes), `check` (what to fix, each with its click and its fix: a headline over 12 words, pieces that
+  light just by coming in, a click that changes nothing, a piece never shown, clicks without notes). `check --layout`
+  opens the page in a browser, offline, and finds text that spills out of its box (it needs Playwright installed beside
+  StoryDeck: `npm i -D footprint-storydeck playwright-core`; without it, it says so and the other checks run). `mcp` serves the same tools to an AI assistant:
+  `claude mcp add storydeck -- npx footprint-storydeck mcp my-talk`.
+- **The helpers a diagram needs.** `<i data-k="w1" class="wire pkt" data-arrow="252 352 318 352"></i>` is a wire (an
+  SVG arrow, with an optional bend; class `pkt` adds a packet that rides it on a `path` click, at its turn — along the
+  curve itself, not a straight line across the bend). A wire that comes in shows itself from its start to its tip,
+  its dashes and colours as your theme draws them.
+  `<i class="ic" data-icon="server"></i>` is `icons/server.svg`. `deck.css` styles the chrome (kicker, headline, footer
+  and count), wires, packets, icons and the theme toggle from the token contract, every rule `:where()`, so your
+  theme wins.
+- **A deck is files, never a program — on your machine.** No deck code runs in Node: no build script, no deck module.
+  Playwright (1.48 or newer), for `check --layout`, is loaded only from beside StoryDeck — never from the deck folder or
+  the folder you run in — and the page is measured offline: no name resolves, the browser context is offline and routed
+  to the page's own file, and WebSockets and popups are closed. A hostile test deck's fetch, WebSocket, popup, beacon,
+  worker, service worker, WebRTC, form and navigation all failed to reach a local server.
+  A deck reads only its own files: a link that leaves the folder, or points at a hidden file (`.env`), is refused, so
+  a deck someone sent you cannot pull a file from elsewhere into its page, its review or its server. A build renames a
+  new file into place, so it never writes through a link, and a file deck.json names never lands outside the deck.
+  `dev` listens on the loopback address only, answers only requests addressed to localhost, and survives any request.
+  It writes only the two edits its own page sends — a note and a piece moved — each checked before it is read (the
+  page's origin, a per-session token only that page carries, JSON, 16 KB at most) and written by the same rules as a
+  build; a move edits only the piece the build drew, and only bytes a browser reads the same way. No other origin may
+  frame it, and only StoryDeck's own scripts run in it (a nonce policy): a deck's own scripts run in the built page,
+  never in development, so nothing a deck carries can send those edits. Every scan of a deck's text is one pass, so a hostile 4 MB file costs no more than its length, and what the
+  tools print is text, never a deck's control characters. A deck's own HTML — its scripts included — runs in the browser like any page you open, in the dev page
+  and in the layout check: open decks you trust. Run the commands from your own project, naming the deck folder.
+
+The same parts are a Node door, for a script or a test of your own:
+
+```js
+import { loadDeck, buildDeck, reviewClick, checkDeck, serveDeck } from 'footprint-storydeck/deck';
+
+const { compiled } = loadDeck('my-talk');
+console.log(reviewClick(compiled, 3));      // click 3 of 6 · "1 · The route · 2" (map "map", step 2 of 3) …
+console.log(checkDeck(compiled));           // [{ level, rule, click, label, message }]
+buildDeck('my-talk');                       // { file, bytes, slides, clicks, ms }
+```
+
 ## Faster edits — what making one talk taught us
 
 - **Cache by content, not by position.** A clip is keyed by its words and settings: inserting or removing a
@@ -349,6 +451,12 @@ themselves when the show's "use timings" is on (PowerPoint's default).
   (0.48–0.70 s spaced out, 0.24–0.28 s as written) — fix, re-voice those clips, measure again.
 - **One source, several builds.** The room's build carries the presenter's voice and a live demo; the public
   one (slides page, video) leaves both out — a build switch over the same parts, never a second copy.
+- **Read a click before you look at it.** On a 37-click talk ported to a deck folder (its 12 KB build script no longer
+  needed; the library rebuilds its 37 slides byte for byte), a rebuild after a save takes about 6.5 ms, and reviewing a click as
+  text costs about 154 tokens against about 1,844 for a screenshot of it — the whole deck about 5,800 tokens as text, about
+  68,000 as screenshots. Measured with `node bench/devloop.mjs <deck>` (an Apple M5 Pro, Node 24); text tokens are
+  estimated as characters ÷ 4 and a screenshot's by Anthropic's image formula (width × height ÷ 750, at 1568 × 882), not a
+  model run. The layout check found a word spilling 17 px out of its box on 24 of those clicks, which the earlier screenshot checks had missed.
 
 ## Quick start
 
@@ -370,7 +478,8 @@ export default function App({ post }) {
 ```
 
 `PostView` renders the Read · Scroll · Watch toggle and each lens. Bring your own `post` (see
-**Authoring**). Requires `react`/`react-dom` (peer) and a slide runtime for Watch (a
+**Authoring**). For a talk on its own page, start from a folder instead: `npx footprint-storydeck init my-talk`, then
+`npx footprint-storydeck dev my-talk` (see **A deck from a folder**). Requires `react`/`react-dom` (peer) and a slide runtime for Watch (a
 `deck-stage.js` web component served at `${basePath}/deck-stage.js` — it ships as `footprint-storydeck/deck-stage.js`).
 
 **For agents:** a skill ships in the package — `plugin/skills/storydeck/SKILL.md` (which door for which job,
@@ -433,9 +542,14 @@ const { theme, toggle, setTheme } = useTheme();   // flips an html class + persi
 | `embedClips` | `footprint-storydeck/voice` (Node only): a deck's clips inside one page; the clip cache, the voice port and its local-kit adapter are `footprint-narration/voice`'s |
 | `renderVideo` · `planVideo` · `deckStageDriver` · `ffmpegMajor` | `footprint-storydeck/video` (Node only, ffmpeg 5.0+): the deck as a narrated video, with captions and chapters |
 | `exportPptx` · `pptxParts` · `zip` · `unzip` · `checkPptx` | `footprint-storydeck/pptx` (Node only): the deck as a PowerPoint file — a slide per click, its picture, notes and clip — through a footprintjs flowchart that records why |
+| `loadDeck` · `buildDeck` · `serveDeck` · `outline` · `reviewClick` · `checkDeck` · `layoutCheck` · `initDeck` · `serveMcp` · `runCli` | `footprint-storydeck/deck` (Node only): a deck folder made into one page, served for editing, read back as text — the `storydeck` command (also `npx footprint-storydeck`); its page's base styles are `footprint-storydeck/deck.css` |
 
-Types ship beside the source in `index.d.ts` — hand-kept (there is no build to generate them from),
-and here rather than in a consumer's shim, because a package's shape belongs in the package.
+The package ships compiled JavaScript (`dist/`, built by `npm run build`: each source file compiled on its
+own, JSX turned into `react/jsx-runtime` calls, every relative import given its `.js`, `'use client'` kept), so
+plain Node and every bundler load it with no transform of their own; `npm run check:dist` loads every door in
+plain Node and refuses a package that ships source JSX. Types ship in `index.d.ts` — hand-kept (nothing
+type-checks the JSX to generate them from), and here rather than in a consumer's shim, because a package's
+shape belongs in the package.
 
 ## Tests
 
@@ -444,7 +558,7 @@ npm test        # vitest
 npm run test:cov
 ```
 
-317 tests (and 2 that run where LibreOffice or the ECMA-376 schemas are found) · ~99% lines · coverage thresholds enforced (90% statements, 85% branches, 90% functions, 95% lines).
+438 tests (and 2 that run where LibreOffice or the ECMA-376 schemas are found) · ~99% lines · coverage thresholds enforced (90% statements, 85% branches, 90% functions, 95% lines).
 
 ## License
 

package/deck.css

@@ -0,0 +1,87 @@
+/* footprint-storydeck/deck.css — the base of a page `storydeck build` makes: the slide, its chrome (kicker,
+   headline, footer), the map, wires and their packets, icons and the theme toggle. Every rule is :where(), so a
+   deck's theme.css (inlined after it) wins over any of them, whatever its selectors. It reads StoryDeck's token
+   contract with a fallback for each: --bg --bg-elev --fg --fg-muted --line --accent-ink --sans --mono. */
+
+:where(html, body) { margin: 0; padding: 0; background: var(--bg, #ffffff); color: var(--fg, #14181f); }
+:where(deck-stage) { background: var(--bg, #ffffff); }
+:where(deck-stage:not(:defined)) { visibility: hidden; }
+
+/* a slide: the design size, its own ground */
+:where(deck-stage > section) {
+  background: var(--bg, #ffffff); color: var(--fg, #14181f);
+  font-family: var(--sans, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+  box-sizing: border-box; overflow: hidden;
+}
+
+/* the chrome: kicker and headline on top, footer and count at the bottom (each carries data-chrome) */
+:where(.head) { position: absolute; left: 50px; top: 56px; right: 50px; z-index: 3; }
+:where(.kicker) {
+  font: 600 26px/1 var(--mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+  letter-spacing: .08em; text-transform: uppercase; color: var(--accent-ink, #8a5a00);
+}
+:where(.head h2) { margin: 18px 0 0; font-size: 64px; line-height: 1.15; font-weight: 700; letter-spacing: -.02em; }
+:where(.foot) {
+  position: absolute; left: 50px; right: 50px; bottom: 26px; height: 34px;
+  display: flex; justify-content: space-between; align-items: center;
+  font: 500 20px/1 var(--mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace); color: var(--fg-muted, #5d6673);
+}
+:where(.foot .count) { color: var(--fg, #14181f); font-weight: 700; }
+
+/* the map: every piece is placed by its own inline left/top/width/height */
+:where(.map) { position: absolute; inset: 0; }
+:where(.map [data-k]) { position: absolute; box-sizing: border-box; }
+
+/* wires (data-arrow): the curve and its head */
+:where(svg.wire) { overflow: visible; color: var(--fg-muted, #5d6673); }
+:where(svg.wire path) { fill: none; stroke: currentColor; stroke-width: 4; stroke-linecap: round; }
+:where(svg.wire path.head) { fill: currentColor; stroke: none; }
+
+/* a wire's packet (class "pkt"): hidden at rest (print, a jump, reduced motion show the plain wire). On a forward path
+   click it rides the curve once, at the wire's turn: --sd-t runs 0 → 1 and it stands at B(t) = 2(1-t)t·C + t²·E from
+   its start (C: --cdx/--cdy, E: --pdx/--pdy, from transforms.js). */
+@property --sd-t { syntax: '<number>'; inherits: false; initial-value: 0; }
+:where(svg.wire .pkt) {
+  opacity: 0; fill: var(--sd-glow, currentColor); stroke: none;
+  transform: translate(calc(var(--cdx) * 2 * (1 - var(--sd-t)) * var(--sd-t) + var(--pdx) * var(--sd-t) * var(--sd-t)),
+    calc(var(--cdy) * 2 * (1 - var(--sd-t)) * var(--sd-t) + var(--pdy) * var(--sd-t) * var(--sd-t)));
+}
+@keyframes sdPkt { from { --sd-t: 0; } to { --sd-t: 1; } }
+@keyframes sdPktShow { 0%, 100% { opacity: 0; } 15%, 80% { opacity: 1; } }
+/* a wire that comes in shows itself start to tip behind a sweeping soft edge (a mask: a theme's dashes stay), square to
+   its run (--sd-angle) — its curve's control point sits halfway along the run, so the curve shows in drawing order. It
+   is the piece's own animation (focus.css · --sd-a-more): at its turn on a path, after a new blur. */
+@property --sd-reveal { syntax: '<percentage>'; inherits: false; initial-value: 100%; }
+@keyframes sdReveal { from { --sd-reveal: -12%; } }
+@media screen and (prefers-reduced-motion: no-preference) {
+  :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) :where(.sd-path) :where(.pkt) {
+    animation: sdPkt .6s ease-in-out var(--sd-path-delay, 0s) both, sdPktShow .6s linear var(--sd-path-delay, 0s) both;
+  }
+  :where([data-deck-active].sd-focus-new:not([data-sd-instant]):not([data-deck-static])) :where(.sd-path) :where(.pkt) {
+    animation-delay: calc(var(--sd-path-delay, 0s) + .4s);
+  }
+  /* a highlighted wire keeps its ring, drawn outside its box where no mask paints: it just fades in */
+  :where(svg.wire.sd-enter:not(.sd-hot, .sd-hot-in)) { --sd-a-more: sdReveal .6s cubic-bezier(.4, 0, .2, 1) var(--sd-delay, 0s) both; }
+  :where(svg.wire.sd-path.sd-enter:not(.sd-hot, .sd-hot-in)) { --sd-a-more: sdReveal .6s cubic-bezier(.4, 0, .2, 1) var(--sd-turn, 0s) both; }
+  :where(svg.wire.sd-twin-turn) { --sd-twin-lag: .3s; }   /* the wire it hands over to sweeps in: it leaves as the sweep nears the tip */
+  :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) :where(svg.wire.sd-enter:not(.sd-hot, .sd-hot-in)) {
+    -webkit-mask-image: linear-gradient(var(--sd-angle, 90deg), #000 var(--sd-reveal), transparent calc(var(--sd-reveal) + 12%));
+    mask-image: linear-gradient(var(--sd-angle, 90deg), #000 var(--sd-reveal), transparent calc(var(--sd-reveal) + 12%));
+  }
+}
+
+/* icons (data-icon): drawn in currentColor */
+:where(svg.ic) { width: 60px; height: 60px; flex: none; fill: none; stroke: currentColor; stroke-width: 3; stroke-linecap: round; stroke-linejoin: round; }
+
+/* the theme toggle (T): light or dark, the choice kept */
+:where(.theme-toggle) {
+  position: fixed; top: 12px; right: 12px; z-index: 10; width: 40px; height: 40px; border-radius: 50%;
+  border: 1.5px solid var(--line, #c9d0d9); background: var(--bg-elev, #f6f8fa); color: var(--fg, #14181f);
+  display: grid; place-items: center; cursor: pointer; opacity: .55; padding: 0;
+}
+:where(.theme-toggle:hover, .theme-toggle:focus-visible) { opacity: 1; }
+:where(.theme-toggle svg) { width: 18px; height: 18px; }
+:where(.theme-toggle .sun) { display: none; }
+:where(:root.dark .theme-toggle .sun) { display: block; }
+:where(:root.dark .theme-toggle .moon) { display: none; }
+@media print { :where(.theme-toggle) { display: none; } }

package/deck.d.ts

@@ -0,0 +1,175 @@
+/**
+ * storydeck · footprint-storydeck/deck (Node) — a deck folder made into one self-contained page, served for editing
+ * with a reload on the same click, and read back as text for a reviewer (a person, or a model). The `storydeck`
+ * command (bin) runs the same parts.
+ *
+ *   my-deck/deck.json · clicks.html · map.html · theme.css · icons/*.svg
+ */
+import type { FocusClick, FocusLook, FocusPiece } from './focus';
+
+/** deck.json, read: every default filled in. */
+export interface DeckConfig {
+  readonly title: string;
+  readonly description: string;
+  readonly lang: string;
+  /** The text in every slide's footer (default: the title). */
+  readonly footer: string;
+  /** The slide's design size, [width, height] (1920 × 1080). */
+  readonly canvas: readonly [number, number];
+  /** Where focus may move and blur, [x0, y0, x1, y1] in slide px (below the headline, above the footer). */
+  readonly area: readonly [number, number, number, number];
+  readonly clicks: string;
+  readonly theme: string;
+  readonly icons: string;
+  /** A map's file, by name (default for a map not listed: <name>.html). */
+  readonly maps: Readonly<Record<string, string>>;
+  /** The built page, inside the deck folder (index.html). */
+  readonly out: string;
+  readonly post: string | null;
+  readonly deckData: string | null;
+  /** What `storydeck check` asks: words in a map click's headline (12), on a plain slide (40). */
+  readonly checks: { readonly maxWords: number; readonly maxSlideWords: number };
+  /** The keys deck.json wrote (a file it names must be there; a default may be absent). */
+  readonly given: readonly string[];
+}
+/** deck.json (text or parsed) with its defaults; throws, naming the fix, on an unknown key or a value it cannot use. */
+export function readConfig(json: string | object): DeckConfig;
+
+/** One click on a map, as written: its attributes (focus-html · readStep reads them), headline (HTML) and notes. */
+export interface DeckStepSource { readonly attrs: string; readonly headline: string; readonly notes: readonly string[] }
+/** A part of the deck: a plain slide (map null) or clicks told on a map. */
+export type DeckPart =
+  | { readonly label: string; readonly kicker: string; readonly map: null; readonly body: string; readonly notes: readonly string[] }
+  | { readonly label: string; readonly kicker: string; readonly map: string; readonly steps: readonly DeckStepSource[] };
+/**
+ * The clicks file read into parts, scanned once. A step holds only its <h2> and notes (anything else is refused, naming
+ * where it goes); a <section> or <step> left open, or opened inside another, is refused.
+ */
+export function parseClicks(html: string): DeckPart[];
+
+export interface DeckIcon { readonly viewBox: string; readonly body: string }
+/**
+ * The built-in drawing helpers, icons then wires: <i data-icon="name"></i> becomes that icon's SVG, and
+ * <i data-arrow="x1 y1 x2 y2 [bend]"></i> an SVG wire (class "pkt": a packet that rides it on a path click).
+ */
+export function applyTransforms(html: string, options?: { icons?: Readonly<Record<string, DeckIcon>> }): string;
+
+/** A deck folder as plain data. Every file is read by its real path, inside the folder, never a hidden one. */
+export interface DeckSource {
+  readonly dir: string;
+  readonly config: DeckConfig;
+  readonly clicksHtml: string;
+  readonly parts: readonly DeckPart[];
+  readonly maps: Readonly<Record<string, string>>;
+  readonly themeCss: string;
+  readonly icons: Readonly<Record<string, DeckIcon>>;
+  readonly post: { sections?: readonly { key?: string; slides?: readonly string[] }[] } | null;
+}
+export function readDeck(dir: string): DeckSource;
+
+/** A click of the compiled deck, as review and check read it. */
+export type DeckClick = {
+  readonly n: number;
+  readonly label: string;
+  readonly part: string;
+  readonly kicker: string;
+  /** The headline as plain text ('' on a plain slide). */
+  readonly headline: string;
+  readonly notes: readonly string[];
+} & (
+  | { readonly kind: 'plain'; readonly map: null; readonly text: string }
+  | { readonly kind: 'map'; readonly map: string; readonly step: FocusClick; readonly look: FocusLook; readonly stepIndex: number; readonly steps: number }
+);
+export interface DeckSlide {
+  readonly label: string;
+  readonly html: string;
+  /** What notesData carries for the slide. */
+  readonly notes: { readonly slide: string; readonly step: number; readonly steps: number; readonly now: readonly string[]; readonly earlier: readonly string[] };
+}
+export interface CompiledDeck {
+  readonly config: DeckConfig;
+  readonly title: string;
+  readonly themeCss: string;
+  readonly slides: readonly DeckSlide[];
+  readonly clicks: readonly DeckClick[];
+  readonly maps: Readonly<Record<string, { readonly pieces: readonly FocusPiece[] }>>;
+}
+/** The deck's clicks planned (each map's state carried click to click) and drawn as <deck-stage> slides. */
+export function compileDeck(source: Pick<DeckSource, 'config' | 'parts' | 'maps'> & Partial<DeckSource>, options?: { dev?: boolean }): CompiledDeck;
+
+/** What the library ships that a page carries: the <deck-stage> runtime, focus.css, narration.css, deck.css, the version. */
+export interface PageAssets { readonly stageJs: string; readonly css: readonly string[]; readonly version: string }
+export function pageAssets(): PageAssets;
+/** One self-contained page: slides, notes, every stylesheet and runtime inlined, the theme toggle. */
+export function deckPage(compiled: CompiledDeck, assets: PageAssets): string;
+
+export function loadDeck(dir: string, options?: { dev?: boolean }): { source: DeckSource; compiled: CompiledDeck };
+/** The page of a deck folder, as a string (no file written). */
+export function deckHtml(dir: string, options?: { dev?: unknown }): { source: DeckSource; compiled: CompiledDeck; html: string };
+/**
+ * Write the page (deck.json "out", or `out` — a path you choose, anywhere) and deck-data.json when deck.json names
+ * one. A new file is renamed into place, never written through a link; a file deck.json names never lands outside
+ * the deck folder.
+ */
+export function buildDeck(dir: string, options?: { out?: string }): { file: string; bytes: number; slides: number; clicks: number; data: string | null; ms: number };
+
+/** The whole deck, one line per click. */
+export function outline(compiled: CompiledDeck): string;
+/** One click (a number from 1, or a label) as text: headline (and its words), focus, route, lit, greyed, what changes, motion, notes. */
+export function reviewClick(compiled: CompiledDeck, which: number | string, options?: { maxWords?: number }): string;
+
+export interface DeckProblem {
+  readonly level: 'error' | 'warn' | 'info';
+  /** words · lit-on-entry · no-change · never-shown · no-notes · compile · spills · outside */
+  readonly rule: string;
+  readonly click: number | null;
+  readonly label: string | null;
+  readonly message: string;
+}
+export function checkDeck(compiled: CompiledDeck): DeckProblem[];
+/** Problems as text, one per line, worst first; 'no problems' when there are none. */
+export function formatProblems(problems: readonly DeckProblem[]): string;
+
+/** The browser port the layout check drives (the video's deckStageDriver, with measure). */
+export interface LayoutDriver {
+  open(url: string): Promise<void>;
+  measure(n: number): Promise<readonly { kind: 'spills' | 'outside'; piece: string | null; text: string; dx: number; dy: number }[]>;
+  close(): Promise<unknown> | unknown;
+}
+/** Text that spills out of its box and lit pieces off the slide, measured click by click in a browser. */
+export function layoutCheck(url: string, options: { clicks: readonly DeckClick[]; driver?: LayoutDriver; chromium?: unknown }): Promise<DeckProblem[]>;
+
+export interface DeckServer {
+  readonly url: string;
+  readonly port: number;
+  rebuild(): void;
+  state(): { version: number; problem: string | null };
+  close(): Promise<void>;
+}
+/**
+ * Serve a deck folder for editing: a save rebuilds, and the page reloads on the same click. Loopback only (host
+ * 127.0.0.1, ::1 or localhost; anything else is refused), requests addressed to localhost only. It reads, and takes
+ * two edits from its own page (its origin and its per-session token, JSON, at most 16 KB): a note on a click, appended
+ * to feedback.md and signed with the person's note key (kept in `home`: STORYDECK_HOME or ~/.storydeck), and a piece
+ * moved by Alt-drag, written into its map file. Only StoryDeck's own scripts run in what it serves (a nonce policy).
+ * `poll` (ms, 0 for none) compares the folder's stamp so a save the watcher missed still rebuilds.
+ */
+export function serveDeck(dir: string, options?: { port?: number; host?: '127.0.0.1' | '::1' | 'localhost'; watch?: boolean; poll?: number; log?: (line: string) => void; tries?: number; home?: string }): Promise<DeckServer>;
+
+/** Write the starter deck into a new or empty folder. */
+export function initDeck(dir: string): { dir: string; files: string[] };
+
+/**
+ * The read-first tools (outline, review, check, build) over MCP: stdio, one JSON-RPC message per line. A call may name
+ * another deck only inside `dir`. Resolves when the input closes.
+ */
+export function serveMcp(options?: { dir?: string; input?: NodeJS.ReadableStream; output?: { write(text: string): unknown } }): Promise<void>;
+
+/** One `storydeck` command (argv without node and the script); resolves to its exit code. */
+export function runCli(argv: readonly string[], io?: {
+  stdout?: { write(text: string): unknown };
+  stderr?: { write(text: string): unknown };
+  stdin?: NodeJS.ReadableStream;
+  /** `dev`: the server once it listens, with stop(). */
+  onStart?: (server: DeckServer & { stop(): Promise<number | void> }) => void;
+}): Promise<number>;

package/dist/BlogView.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import SlideFigure from "./SlideFigure.js";
+import { finalStep } from "./sections.js";
+import { slugify } from "./slug.js";
+function BlogView({ sections }) {
+  const [copied, setCopied] = useState("");
+  function copyLink(e, id) {
+    e.preventDefault();
+    const url = `${window.location.origin}${window.location.pathname}#${id}`;
+    if (window.location.hash !== `#${id}`) window.history.replaceState(null, "", `#${id}`);
+    try {
+      navigator.clipboard.writeText(url);
+    } catch (_) {
+    }
+    setCopied(id);
+    setTimeout(() => setCopied((c) => c === id ? "" : c), 1600);
+  }
+  return /* @__PURE__ */ jsx("article", { children: sections.map((s) => {
+    const id = slugify(s.key);
+    return /* @__PURE__ */ jsxs("section", { id, className: "post-section", children: [
+      /* @__PURE__ */ jsxs("div", { className: "section-head", children: [
+        /* @__PURE__ */ jsx(
+          "a",
+          {
+            className: "section-anchor",
+            href: `#${id}`,
+            onClick: (e) => copyLink(e, id),
+            title: "Copy link to this section",
+            "aria-label": `Copy link to \u201C${s.heading}\u201D`,
+            children: "#"
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { className: "section-head-text", children: [
+          /* @__PURE__ */ jsx("p", { className: "eyebrow", children: s.label }),
+          /* @__PURE__ */ jsx("h2", { children: s.heading })
+        ] }),
+        copied === id ? /* @__PURE__ */ jsx("span", { className: "section-copied", "aria-live": "polite", children: "link copied \u2713" }) : null
+      ] }),
+      /* @__PURE__ */ jsx(SlideFigure, { html: finalStep(s) }),
+      s.body ? /* @__PURE__ */ jsx("div", { className: "prose", dangerouslySetInnerHTML: { __html: s.body } }) : null
+    ] }, id);
+  }) });
+}
+export {
+  BlogView as default
+};