footprint-storydeck 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 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
+  picture full-bleed, its notes as speaker notes (a paragraph per line), its headline or label as an off-page title
+  (the outline and screen readers read it, the audience does not see it), and a fade. With clips, each slide plays
+  its clip and moves on after it (plus `gap`): a narrated deck that runs by itself. It drives the browser through
+  the video's port (`deckStageDriver`). The export is a footprintjs flowchart, so every run leaves a record
+  (`narrative`), and each check is a `decide()` with its evidence. A clip that is missing, empty, not the sound its
+  name says, over `maxClip` or never voiced, a click without a 16:9 PNG, or a package that does not read back is
+  refused before a browser opens or a file is written, naming the fix. Media are shared by their bytes, never by
+  name. The ZIP, the PresentationML parts and the read-back are written by hand and exported (`zip`, `unzip`,
+  `pptxParts`, `checkPptx`). Opened in PowerPoint 16 with no repair prompt; every part validates against the
+  ISO/IEC 29500 schemas. It is pictures, notes and sound, not editable native shapes. footprintjs is an optional
+  peer dependency: `npm i footprintjs` beside StoryDeck to export; nothing else loads it.
+- **`apart`, the exploded view.** A focus mover: named groups fly apart along the vectors you give
+  (`data-focus-apart="lid: 0 -120 | core: 160 0 | base: 0 120 1.1"`), one spring each, `data-focus-stagger` ms apart
+  (35), out in the order written and back in reverse on a later click without it; closing groups settle for one
+  more click. A click reschedules only the groups not yet at its target, in order, never sooner than a start they
+  were already waiting for, so the earlier groups lead. `focusRuntime` plays the springs as Web Animations, each deck
+  its own, so at rest a piece is exactly as drawn and the video renderer steps them; `SlideDeck` now installs it.
+  Two movers on one click are refused, naming the fix; a group's numbers are strict and its scale must be above 0
+  (for `place` too). Every `focusStep` look now carries `apart` (`null` without it), and every piece `apart`.
+- **`footprint-storydeck/tour`: a tour for decks nobody presents.** `idleTour` plays a deck's stops through its own
+  `goTo` after 1.4 s with nobody touching it. A key, tap, click or real move hands the deck over until 45 s of quiet;
+  Escape or the "Stop tour" control (its name is its visible words; hidden while no tour can move in view) stops
+  every tour for the page view (WCAG 2.2.2). It waits while out of sight or while listen mode plays the deck
+  (`data-listening`, now set by `listenRuntime`), and never runs under reduced motion. Declared as
+  `<deck-stage data-tour>`, `SlideDeck`'s `tour`, or post.json's `tour`; `tourPlan` and `tourText` give the plan as
+  data and in one line.
+- **Video:** the driver finishes click n−1's motion before stepping on, so a strip renders the same frames as the
+  full video. `focusRuntime`'s install flag is its version, so an older inlined runtime no longer blocks it.
+
 ## 0.4.0 — a path: the subject piece after piece along a route
 
 - **A fourth kind of focus strategy, the order — how the subject comes on — and its first strategy, `path`.**

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
@@ -73,6 +99,7 @@ decision every click makes again, so it is data on the click, and the library do
 | mover | `zoom` | the view closes in on the subject (`share`, `most`) |
 | 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 |
 | overlay | `blur` | everything outside the subject's frame is blurred; a frame (and a `label`) on it, or on the `rect`s you give |
 | order | `path` | the subject comes on piece after piece along a route, as a request travels it — node, wire, node: each lit piece on it lights at its turn (`step` seconds apart, 0.35) and glows as it is reached; `route` names the order (default — and for an empty `route` — the click's `on`, or its `in`); a greyed piece on it takes no turn, and a route with no order at all (`on: ['*']`) is refused; a `line` ("agent → MCP → gateway") names the route, shown as the last turn starts. A deck's own `filter` on a path piece is not carried through the glow: it steps where the glow starts and ends |
 
@@ -93,6 +120,35 @@ on one `filter` would flash), its ring (`hot`) comes .3 s after its turn, and a
 twin's turn and only then steps aside, so the wire is never missing. Under a new blur the whole path, line included,
 waits .4 s for it, as what a click adds does.
 
+**An exploded view, on a figure of parts.** A figure built of parts — an engine, a stack, a page and the layers
+under it — explains itself best when the parts come apart: the audience sees what it is made of, then sees it whole
+again. Name the parts as groups and the way each one leaves:
+
+```html
+<step data-focus="apart" data-focus-apart="lid: 0 -120 | core: 160 0 | base: 0 120 1.1"></step>
+<step data-on="core"></step>   <!-- no apart: the parts come back together, the core lit -->
+```
+
+Each group has one spring, its value 0 together and 1 apart, a little under critical damping, so a part settles with
+a hint of weight instead of stopping dead. The groups set off `stagger` ms apart (`data-focus-stagger`, 35) — out in
+the order written, back in reverse — so the last one out is the first one back. A click that turns the parts round
+mid-way reschedules only the groups not yet at its target (those turning round, and those still waiting to set off),
+in order, each a stagger after the one before and never sooner than a start it was already waiting for — so the
+order is kept: among them the earlier groups always lead, and a click that keeps a group's target keeps its time.
+The order is what the library keeps; where the parts go is yours — vectors that cross make paths that cross, so give
+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.
+
+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
+transform, an SVG group's `transform` attribute included, is never overwritten), which means the video renderer
+steps them like any animation. Nothing of a spring is written on the piece: at rest the animation is over and the
+piece is exactly as drawn — closed, the figure is its static art. A jump, a step back, print and reduced motion land
+at once, as every focus does.
+
 The plan is plain data (each piece's state, what changed since the last click, how far it moved), so a
 renderer only draws it. `footprint-storydeck/focus-html` writes it into slide HTML at build time and
 `footprint-storydeck/focus.css` animates **only what changed, only on a forward click** — a jump or a step back
@@ -128,6 +184,56 @@ a piece (a dashed wire under a solid one) step aside while its twin is lit. A pi
 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.
 
+## Tour: a deck that shows its point while nobody is using it
+
+A deck left on a screen with nobody presenting it — at a booth, on a post's Watch lens, as a page's hero figure — is
+mostly looked at by people who have not touched it yet. If it sits on its first slide, they never see what it is
+for. So, left alone for a moment (1.4 s), it plays a short loop of **stops**, the clicks that make its point, and the
+moment someone reaches for it, it hands itself over:
+
+- it drives the **same targets a person would** — the deck's own `goTo`, so a stop one click on animates as that click
+  does (focus, `apart`'s springs and all) and a jump lands, as a person's jump does; there is no second animation to
+  keep in step;
+- **accessibility first**: the moment someone uses it — a key, a tap, a click, a focus, a real move of the pointer
+  over it (looked at every 250 ms, so a resting mouse or the deck moving under it is no move, and a finger lifting off
+  is not someone leaving), or a move it did not make (the presenter window) — it hands itself over, and it does not
+  take the deck back soon: only after **45 s of quiet** (`resumeMs`), or once the deck has left sight and come back.
+  It then goes on from the stop they left it on, when that is a stop;
+- **Escape**, or the small **"Stop tour"** control it shows while a tour can move in view (or the page's own element
+  marked `data-tour-stop`, which it uses instead), stops every tour for the rest of the page view (WCAG 2.2.2). Escape
+  is one key with three meanings on a StoryDeck page, each by what is running: while listen mode plays, it stops listen
+  mode, and only that; in `PostView`'s Watch lens it returns to Read; and wherever a tour runs it stops every tour on
+  the page — so in a touring Watch lens one Escape does both;
+- it **waits while out of sight** — scrolled away (IntersectionObserver, reading the newest entry) or the page
+  hidden — and while listen mode plays the deck (the deck carries `data-listening`); under **reduced motion** there
+  is no tour.
+
+The plan is plain data — the stops, each one's hold, the waits — that a person or an LLM can read, and that the
+deck's notes can say in one line (`tourText`):
+
+```js
+import { idleTour, tourPlan, tourText } from 'footprint-storydeck/tour';
+
+idleTour(document.querySelector('deck-stage'), { stops: '3 4 5 9:6s', hold: '3s' });   // clicks as the deck counts them
+tourText({ stops: '3 4 5 9:6s' });
+// "Left alone for 1.4 s, it tours itself: slide 3 for 3 s, then slide 4 for 3 s, then slide 5 for 3 s, then slide 9
+//  for 6 s, and round again. A key, tap, click or move hands it over until 45 s of quiet; Escape or "Stop tour" stops it."
+```
+
+Declared on the deck instead, for a page built as HTML: `<deck-stage data-tour="3 4 5 9:6s" data-tour-hold="3s">` (and
+`data-tour-idle`, `data-tour-resume`), with `(${idleTour})()` once in the page; a deck whose `data-tour` it cannot
+read is left out with a console warning naming the fix, and the others still tour. A stop is held 300 ms or more. In
+React, the Watch lens takes the same spec — `<SlideDeck steps={…} tour="3 4 5 9:6s" />` — and `PostView` passes the
+post's own `tour` (post.json), so a post opts in where its structure is written. A figure that is not a deck tours
+through its own function: stops are its names, `go` is what a person's click calls
+(`idleTour(figure, { stops: ['lid', 'core'], go: (part) => show(part) })`). The tour's state rides on the element as `data-tour-state` (`waiting`,
+`touring`, `paused`, `hidden`, `still`, `done`), so a page can say "touring — touch to explore"; the control is
+`.sd-tour-stop`, styled as weakly as can be, so a page restyles it.
+
+It lives on the Watch deck, not in the Scroll or Read lenses: their figure follows the reader's scroll position, so a
+tour there would move the page under the reader's eyes; a deck is a place a person steps through, and the tour steps
+through it the same way.
+
 ## Narration: the deck tells itself, in your voice
 
 A talk lives on after the room: someone opens the deck alone, or it becomes a video. The words were in the
@@ -199,6 +305,66 @@ await renderVideo({
 });
 ```
 
+## PowerPoint: the deck as a .pptx
+
+Conferences often ask for the talk as a PowerPoint file. `footprint-storydeck/pptx` (Node, no ffmpeg) exports one
+through the same browser port as the video, so a deck that can be filmed can be exported:
+
+- **one slide per click** — the click's settled picture (made forward, its entrance played to the end, as the
+  video's held frame) full-bleed on a 16:9 slide; its written notes as the speaker notes, a paragraph per note;
+  its headline (or label) as the slide's title, in the title placeholder just above the page, so the outline, the
+  slide list and a screen reader read it and the audience does not see it; a fade between slides;
+- **a narrated deck that runs by itself** — with clips (as the video takes them, or found in the voice cache), each
+  slide carries its clip, which plays as the slide starts, and moves on after the clip plus `gap` (a click without
+  a clip after `noclip` plus `gap`, the video's timing). Without clips no slide moves on by itself: the speaker clicks.
+
+**What it is, honestly:** pictures plus notes plus sound. A slide's words and shapes are in its picture, not
+native PowerPoint text or shapes, so they cannot be edited there. Turning a deck's HTML into native shapes is a
+possible later step.
+
+**Why a flowchart.** The export is a [footprintjs](https://github.com/footprintjs/footPrint) flowchart —
+PlanClicks → GatherClips → CheckClips → TimeTheDeck → ShootPictures → CheckPictures → WriteParts → Zip →
+CheckPackage → Verdict → Deliver — so every run leaves a record that explains it, to a person or an LLM
+(`done.narrative`). Each check is a `decide()` that records its evidence: a clip whose file is gone, one PowerPoint
+cannot play (not a .wav, .m4a or .mp3; an empty file; or bytes that do not begin as their kind of file — RIFF…WAVE,
+ID3 or an MP3 frame, ftyp), one over `maxClip` (300 s), a click that says words with no clip;
+a click without a 16:9 PNG; a package that does not read back as planned. A refusal names each click and its fix,
+carries the record (`error.narrative`), and writes nothing to `out`. The clips are checked before a browser opens.
+footprintjs is an optional peer dependency: StoryDeck does not install it (a browser-only install stays small), so
+install it beside StoryDeck to export — `npm i footprintjs` — and an export without it is refused, saying so. It is
+loaded only when an export runs; the deck's browser runtime never loads it.
+
+```js
+import { chromium } from 'playwright-core';
+import { deckStageDriver } from 'footprint-storydeck/video';
+import { exportPptx } from 'footprint-storydeck/pptx';   // and `npm i footprintjs`: an optional peer, needed to export
+
+const done = await exportPptx({
+  url: 'file:///…/deck.html', steps, out: 'out/my-talk.pptx',   // the steps the video takes; or `out` a folder → <name>.pptx
+  driver: deckStageDriver({ chromium }),
+});
+// done: { file, slides, voiced, runtime (s the deck runs by itself, or null), bytes, clicks, narrative }
+// [Condition]: No rules matched, fell back to default "Every clip is there, playable and within maxClip": TimeTheDeck.
+// …or, refused: exportPptx: a clip is not ready: click 12: its clip lasts 412 s, over maxClip (300 s) — split its notes across clicks, or raise maxClip
+
+// From the deck's clicks and the voice cache instead of steps (give `voice` the `spell`/`say` the clips were voiced with):
+await exportPptx({ url, deck: clicks.map(c => ({ label: c.label, notes: c.notes })), voice: { cache: 'voice/cache', profile }, out: 'out', driver });
+```
+
+The file is written by hand, with no dependency: a small ZIP writer (`zlib`'s raw deflate and a CRC-32) and a
+minimal PresentationML part set (ECMA-376) — content types, relationships, the presentation, one master and one
+title-only layout, a theme for each master, the slides, a notes master and a notes page per slide, the media (a
+sound said on two clicks is stored once, matched by its bytes) and the document properties. The pieces are
+exported for pictures made elsewhere: `pptxParts({ slides })` gives the parts, `zip(parts)` the file, and
+`checkPptx(bytes)` reads one back — the ZIP against its CRC-32s, every part well-formed and typed, every
+relationship's target there, every `r:id` known, slide, master and layout ids in PowerPoint's ranges, shape ids
+unique on each slide — and lists each slide's title, notes, pictures, sound and time. Each export runs that check
+before it writes to `out`. The tests also run Info-ZIP's `unzip -t`; LibreOffice, where it is installed, opens
+the file and prints it to PDF; and with `STORYDECK_OOXML_SCHEMAS` pointing at the ISO/IEC 29500 schemas, every part
+is validated against them. Limits: a clip is embedded as it is (a .wav as voiced: about 3 MB a minute at 24 kHz
+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).
+
 ## 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
@@ -277,7 +443,7 @@ const { theme, toggle, setTheme } = useTheme();   // flips an html class + persi
 | Export | What |
 |---|---|
 | `PostView` | the lens controller (Read · Scroll · Watch toggle) |
-| `BlogView` · `ScrollyView` · `SlideDeck` | the three lenses (take `sections` / `sections` / `steps`) |
+| `BlogView` · `ScrollyView` · `SlideDeck` | the three lenses (take `sections` / `sections` / `steps`; `SlideDeck` also a `tour`) |
 | `SlideFigure` | one slide rendered as a scaled static figure |
 | `StoryDeckProvider` · `useBasePath` | inject deploy config (asset base path) |
 | `useTheme` · `ThemeToggle` | headless theming + a default toggle |
@@ -287,13 +453,19 @@ const { theme, toggle, setTheme } = useTheme();   // flips an html class + persi
 | `slugify` · `scopeDeckCss` | utilities |
 | `planFocus` · `focusStep` · `readFocus` · `FOCUS` | focus: per click, what it is about and what happens to the rest (also `footprint-storydeck/focus`) |
 | `readPieces` · `readStep` · `drawFocus` · `wrapStage` · `slideClass` · `focusOverlay` · `focusRuntime` | focus, written into slide HTML (also `footprint-storydeck/focus-html`; styles in `footprint-storydeck/focus.css`) |
+| `idleTour` · `tourPlan` · `tourText` | tour: a deck (or a figure) that shows its point while nobody is using it, and its plan in data and in one line (also `footprint-storydeck/tour`) |
 | `narrationText` · `writtenText` | narration: what a click says (also `footprint-storydeck/narration`); the rules beneath, sentences, captions and chapters are `footprint-narration`'s |
 | `notesData` · `notesRuntime` · `listenRuntime` | narration in the page: notes, presenter window, listen mode (also `footprint-storydeck/narration-html`; styles in `footprint-storydeck/narration.css`) |
 | `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 |
 
-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
 
@@ -302,7 +474,7 @@ npm test        # vitest
 npm run test:cov
 ```
 
-186 tests · ~99% lines · coverage thresholds enforced (90% statements, 85% branches, 90% functions, 95% lines).
+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).
 
 ## License
 

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
+};

package/dist/PostView.js

@@ -0,0 +1,170 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import BlogView from "./BlogView.js";
+import ScrollyView from "./ScrollyView.js";
+import SlideDeck from "./SlideDeck.js";
+const LENSES = [
+  { id: "read", label: "Read it" },
+  { id: "scrolly", label: "Scroll it" },
+  { id: "slides", label: "Watch it" }
+];
+const ESCAPE_LENSES = LENSES.filter((l) => l.id !== "slides");
+const NARROW_WATCH_MQ = "(max-width: 700px)";
+function isNarrowViewport() {
+  return typeof window.matchMedia === "function" && window.matchMedia(NARROW_WATCH_MQ).matches;
+}
+function fullscreenElement() {
+  return document.fullscreenElement || document.webkitFullscreenElement || null;
+}
+function PostView({ post }) {
+  const [view, setView] = useState("read");
+  const [takeover, setTakeover] = useState(false);
+  const [fsApi, setFsApi] = useState(false);
+  const stageRef = useRef(null);
+  const viewRef = useRef("read");
+  const autoFsRef = useRef(false);
+  const content = post.sections.filter((s) => s.key !== "Title" && s.key !== "Close");
+  const isWatch = view === "slides";
+  const idle = useIdleFade(isWatch);
+  useEffect(() => {
+    viewRef.current = view;
+  }, [view]);
+  const enterFullscreen = useCallback((auto) => {
+    const el = stageRef.current;
+    if (!el) return;
+    autoFsRef.current = !!auto;
+    const request = el.requestFullscreen || el.webkitRequestFullscreen;
+    if (!request) {
+      setTakeover(true);
+      return;
+    }
+    let p;
+    try {
+      p = request.call(el);
+    } catch (_) {
+      setTakeover(true);
+      return;
+    }
+    if (p && typeof p.catch === "function") {
+      p.catch(() => setTakeover(true));
+    } else if (auto) {
+      setTimeout(() => {
+        if (!fullscreenElement() && viewRef.current === "slides" && autoFsRef.current) setTakeover(true);
+      }, 500);
+    }
+  }, []);
+  const leaveFullscreen = useCallback(() => {
+    autoFsRef.current = false;
+    setTakeover(false);
+    if (!fullscreenElement()) return;
+    const exit = document.exitFullscreen || document.webkitExitFullscreen;
+    if (!exit) return;
+    try {
+      const p = exit.call(document);
+      if (p && typeof p.catch === "function") p.catch(() => {
+      });
+    } catch (_) {
+    }
+  }, []);
+  const choose = useCallback((next) => {
+    setView(next);
+    const u = new URL(window.location.href);
+    if (next === "read") u.searchParams.delete("view");
+    else u.searchParams.set("view", next);
+    window.history.replaceState(null, "", u);
+    if (next === "slides") {
+      if (isNarrowViewport()) enterFullscreen(true);
+    } else {
+      leaveFullscreen();
+    }
+  }, [enterFullscreen, leaveFullscreen]);
+  useEffect(() => {
+    const v = new URLSearchParams(window.location.search).get("view");
+    if (v === "slides" || v === "scrolly") setView(v);
+    if (v === "slides" && isNarrowViewport()) enterFullscreen(true);
+    const el = stageRef.current;
+    setFsApi(!!(el && (el.requestFullscreen || el.webkitRequestFullscreen)));
+  }, [enterFullscreen]);
+  useEffect(() => {
+    function onFullscreenChange() {
+      if (!fullscreenElement() && viewRef.current === "slides" && autoFsRef.current) choose("read");
+    }
+    document.addEventListener("fullscreenchange", onFullscreenChange);
+    document.addEventListener("webkitfullscreenchange", onFullscreenChange);
+    return () => {
+      document.removeEventListener("fullscreenchange", onFullscreenChange);
+      document.removeEventListener("webkitfullscreenchange", onFullscreenChange);
+    };
+  }, [choose]);
+  useEffect(() => {
+    if (!isWatch) return;
+    function onKeyDown(e) {
+      if (e.key === "Escape") choose("read");
+    }
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [isWatch, choose]);
+  return /* @__PURE__ */ jsxs("main", { id: "main", className: "wrap wide", children: [
+    /* @__PURE__ */ jsxs("header", { className: "post-head", children: [
+      /* @__PURE__ */ jsx("p", { className: "eyebrow", children: "Primer" }),
+      /* @__PURE__ */ jsx("h1", { children: post.title }),
+      /* @__PURE__ */ jsx("p", { className: "lead", children: post.description }),
+      /* @__PURE__ */ jsxs("p", { className: "byline", children: [
+        "By ",
+        post.author,
+        " \xB7 ",
+        (/* @__PURE__ */ new Date(post.date + "T00:00:00Z")).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx("div", { className: "view-toggle", role: "group", "aria-label": "Choose a view", children: LENSES.map((l) => /* @__PURE__ */ jsx("button", { "aria-pressed": view === l.id, onClick: () => choose(l.id), children: l.label }, l.id)) }),
+    view === "read" ? /* @__PURE__ */ jsx(BlogView, { sections: content }) : null,
+    view === "scrolly" ? /* @__PURE__ */ jsx(ScrollyView, { sections: content }) : null,
+    /* @__PURE__ */ jsx("div", { ref: stageRef, className: `watch-stage${isWatch && takeover ? " is-takeover" : ""}`, children: isWatch ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsxs("div", { className: `watch-lens-dock${idle ? " is-idle" : ""}`, role: "group", "aria-label": "Switch view", children: [
+        ESCAPE_LENSES.map((l) => /* @__PURE__ */ jsx("button", { type: "button", onClick: () => choose(l.id), children: l.label.replace(/ it$/, "") }, l.id)),
+        fsApi ? /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            className: "watch-lens-fs",
+            "aria-label": "Toggle fullscreen",
+            title: "Full screen",
+            onClick: () => fullscreenElement() || takeover ? leaveFullscreen() : enterFullscreen(false),
+            children: "\u26F6"
+          }
+        ) : null,
+        /* @__PURE__ */ jsx("span", { className: "watch-lens-hint", title: "Press Esc to return to Read", "aria-hidden": "true", children: "Esc" })
+      ] }),
+      /* @__PURE__ */ jsx(SlideDeck, { steps: post.deckSteps, tour: post.tour })
+    ] }) : null })
+  ] });
+}
+function useIdleFade(active, ms = 2600) {
+  const [idle, setIdle] = useState(false);
+  useEffect(() => {
+    if (!active) {
+      setIdle(false);
+      return;
+    }
+    let timer = setTimeout(() => setIdle(true), ms);
+    function wake() {
+      setIdle(false);
+      clearTimeout(timer);
+      timer = setTimeout(() => setIdle(true), ms);
+    }
+    window.addEventListener("pointermove", wake);
+    window.addEventListener("touchstart", wake, { passive: true });
+    window.addEventListener("keydown", wake);
+    return () => {
+      clearTimeout(timer);
+      window.removeEventListener("pointermove", wake);
+      window.removeEventListener("touchstart", wake);
+      window.removeEventListener("keydown", wake);
+    };
+  }, [active, ms]);
+  return idle;
+}
+export {
+  PostView as default
+};

package/dist/ScrollyView.js

@@ -0,0 +1,93 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import SlideFigure from "./SlideFigure.js";
+import { slugify } from "./slug.js";
+import { isStoryFigure } from "./figure.js";
+function ScrollyView({ sections }) {
+  const beats = [];
+  sections.forEach((s) => {
+    s.steps.forEach((html, stepIdx) => {
+      beats.push({
+        key: `${slugify(s.key)}-${stepIdx}`,
+        index: beats.length,
+        html,
+        label: s.label,
+        heading: s.heading,
+        body: s.body,
+        // the section this beat belongs to, and which of its steps it is — what a live figure needs
+        // to know WHICH beat it is being asked to draw
+        sectionKey: s.key,
+        step: stepIdx,
+        firstOfSection: stepIdx === 0,
+        figure: isStoryFigure(s.figure) || typeof s.figure === "function" ? s.figure : null
+      });
+    });
+  });
+  const [active, setActive] = useState(0);
+  const refs = useRef([]);
+  useEffect(() => {
+    const io = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((e) => {
+          if (e.isIntersecting) {
+            const i = Number(e.target.dataset.beat);
+            if (!Number.isNaN(i)) setActive(i);
+          }
+        });
+      },
+      { rootMargin: "-45% 0px -45% 0px", threshold: 0 }
+      // fire as a beat crosses the viewport centre
+    );
+    refs.current.forEach((el) => el && io.observe(el));
+    return () => io.disconnect();
+  }, [beats.length]);
+  const activeBeat = beats[active] || beats[0];
+  const live = beats.some((b) => b.figure !== null);
+  return /* @__PURE__ */ jsxs("div", { className: `scrolly${live ? " scrolly-live" : ""}`, children: [
+    /* @__PURE__ */ jsxs("div", { className: "scrolly-stage", children: [
+      activeBeat ? activeBeat.figure !== null ? isStoryFigure(activeBeat.figure) ? /* @__PURE__ */ jsx(FigureHost, { figure: activeBeat.figure, beat: activeBeat }) : /* @__PURE__ */ jsx("div", { className: "scrolly-stage-live", children: activeBeat.figure(activeBeat) }) : /* @__PURE__ */ jsx(SlideFigure, { html: activeBeat.html }, active) : null,
+      /* @__PURE__ */ jsx("div", { className: "scrolly-rail", "aria-hidden": "true", children: beats.map((b, i) => /* @__PURE__ */ jsx("span", { className: i === active ? "on" : "" }, b.key)) })
+    ] }),
+    /* @__PURE__ */ jsx("div", { className: "scrolly-flow", children: beats.map((b, i) => /* @__PURE__ */ jsxs("div", { className: "scrolly-beat", "data-beat": i, ref: (el) => refs.current[i] = el, children: [
+      b.firstOfSection ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("p", { className: "eyebrow", children: b.label }),
+        /* @__PURE__ */ jsx("h2", { children: b.heading }),
+        b.body ? /* @__PURE__ */ jsx("div", { className: "prose", dangerouslySetInnerHTML: { __html: b.body } }) : null
+      ] }) : null,
+      /* @__PURE__ */ jsx("div", { className: "scrolly-beat-figure", children: /* @__PURE__ */ jsx(SlideFigure, { html: b.html }) })
+    ] }, b.key)) })
+  ] });
+}
+const UNREACHED = "this figure could not move to this beat";
+const useMountEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+function FigureHost({ figure, beat }) {
+  const host = useRef(null);
+  const [said, setSaid] = useState(null);
+  useMountEffect(() => {
+    figure.mount(host.current);
+    return () => figure.dispose();
+  }, [figure]);
+  const { key, index, sectionKey, step } = beat;
+  useEffect(() => {
+    let current = true;
+    new Promise((resolve) => resolve(figure.seek({ key, index, sectionKey, step }))).then(
+      (answer) => {
+        if (current) setSaid(typeof answer === "string" && answer !== "" ? answer : null);
+      },
+      () => {
+        if (current) setSaid(UNREACHED);
+      }
+    );
+    return () => {
+      current = false;
+    };
+  }, [figure, key, index, sectionKey, step]);
+  return /* @__PURE__ */ jsxs("div", { className: "scrolly-stage-live", children: [
+    /* @__PURE__ */ jsx("div", { className: "scrolly-figure", ref: host }),
+    said === null ? null : /* @__PURE__ */ jsx("p", { className: "scrolly-figure-said", role: "status", children: said })
+  ] });
+}
+export {
+  ScrollyView as default
+};