footprint-storydeck 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 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`.**
+  A click lights its subject 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 — on every forward click,
+  so the request travels again; `route` names the order (default, and for an empty `route`: the click's `on`, or its
+  `in`), a name shared by several pieces is one turn, a name with nothing lit takes none (a greyed piece never waits
+  or glows grey), and a lit piece off the route lights at once. A click that asks for a path with no order at all
+  (`on: ['*']`) is refused, naming the fix: write the pieces in the order they light. A `line` names the route, shown
+  as the last turn starts (`lineAt` places it; default the area's bottom left; a blank one is none). Borrowed from the isometric figures where a
+  request lights its path.
+- Everything on a path keeps its turn. A piece lit from grey plays one animation, `sdLightPulse`, whose filter lists
+  the same functions at every keyframe, so it glides into colour and the glow (a light and a pulse on one filter
+  would flash); a ring (`hot`) comes .3 s after its piece's turn; a dashed twin stays until its solid twin's turn,
+  then steps aside, so the wire is never missing; and under a new blur the whole path, line included, waits .4 s for
+  it, as what a click adds does. One variable carries a piece's moment, `--sd-turn`.
+- `focusStep` gives each piece its `path` (its turn's delay, or null) and `twinTurn` (stepping aside for a lit twin
+  on the route: that twin's turn, or null), and the look its `path` ({turns, step, done, line, lineAt}; `line` '' and
+  `lineAt` null when none is given). What an order's `route()` gives — a deck's own too — is checked (names, a
+  `step` of 0–5 s, a text `line`, a `lineAt` of 'x y' or null) and refused with the strategy's name and the fix,
+  and is only read, never written to (a frozen result is fine). `focusOverlay` writes the line; `focus.css` animates
+  the path only on a forward click, never under reduced motion (`--sd-glow` colours the pulse). A click without a
+  path is drawn byte for byte as 0.3.0 drew it.
+
 ## 0.3.0 — `footprint-storydeck`; the narration rules move into footprint-narration
 
 - **The package is renamed `footprint-storydeck`** — the footprintjs family's name, as footprint-storyreel and

package/PostView.jsx

@@ -188,7 +188,7 @@ export default function PostView({ post }) {
               ) : null}
               <span className="watch-lens-hint" title="Press Esc to return to Read" aria-hidden="true">Esc</span>
             </div>
-            <SlideDeck steps={post.deckSteps} />
+            <SlideDeck steps={post.deckSteps} tour={post.tour} />
           </>
         ) : null}
       </div>

package/README.md

@@ -73,10 +73,55 @@ 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 |
 
 `'left blur'` reads: the context steps aside to the left, greyed, under a blur, and the subject grows on
-the right, framed. Bring your own strategy of any kind (`strategies: { name: { kind, … } }`).
+the right, framed. `'path grey'` lights a route in turn and greys the rest. Bring your own strategy of any kind
+(`strategies: { name: { kind, … } }`); what your own order's `route()` gives is checked like the built-in's — piece
+names, a `step` of 0–5 s, a text `line`, a `lineAt` of `'x y'` — and refused with the fix when it is not.
+
+**A path, on a diagram of an app.** An architecture slide is a route more often than a picture: who calls whom.
+Write the click's `on` in the order a request travels it, wires included, and the path lights it that way:
+
+```html
+<step data-on="agent link-mcp mcp link-gw gw" data-focus="path" data-focus-line="agent → MCP → gateway"></step>
+```
+
+Everything on a path keeps its turn: a piece lit from grey glides into colour and the glow in one animation (two
+on one `filter` would flash), its ring (`hot`) comes .3 s after its turn, and a dashed twin stays until its solid
+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
@@ -113,6 +158,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
@@ -184,6 +279,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
@@ -262,7 +417,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 |
@@ -272,10 +427,12 @@ 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.
@@ -287,7 +444,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/SlideDeck.jsx

@@ -1,14 +1,24 @@
 'use client';
 import { useEffect, useRef, useState } from 'react';
 import { useBasePath } from './context';
+import { idleTour } from './tour';
+import { focusRuntime } from './focusHtml';
 
 // Slide (watch) lens: the deck slides (as raw HTML strings, in order) mounted into <deck-stage>
 // (the deck's own web component, loaded from /deck-stage.js). We set innerHTML imperatively so
 // React doesn't fight the runtime once it restructures the stage; remounts auto-upgrade.
-export default function SlideDeck({ steps }) {
+//
+// It installs focusHtml.js · focusRuntime (once a page), as a built deck inlines it: only a forward click
+// animates, and apart's springs play.
+//
+// `tour` (tour.js · idleTour) makes it a deck nobody has to present: left alone for a moment it shows
+// its stops through the deck's own goTo, and a key, tap, click or move hands it over. It is the
+// readable spec only ('3 4 5 9:6s', or {stops, hold, idleMs, resumeMs, loop}), so it can come from JSON.
+export default function SlideDeck({ steps, tour }) {
   const host = useRef(null);
   const [copied, setCopied] = useState(false);
   const basePath = useBasePath();
+  const tourKey = tour ? JSON.stringify(tour) : '';
 
   // deck-stage keeps the current slide in location.hash (#1, #2, …), so the URL already points at
   // the visible slide — copying window.location shares that exact slide (same scheme as the blog).
@@ -21,6 +31,7 @@ export default function SlideDeck({ steps }) {
   useEffect(() => {
     const el = host.current;
     if (!el) return;
+    focusRuntime();
     const inner = (steps || []).join('\n');
     el.innerHTML = `<deck-stage no-rail width="1920" height="1080">${inner}</deck-stage>`;
     if (!document.querySelector('script[data-deck-stage]')) {
@@ -31,6 +42,14 @@ export default function SlideDeck({ steps }) {
     }
   }, [steps]);
 
+  // After the deck effect, so a new deck (new steps) gets a new tour; keyed by the spec's text, not its identity.
+  useEffect(() => {
+    const stage = host.current?.querySelector('deck-stage');
+    if (!tourKey || !stage) return undefined;
+    const t = idleTour(stage, typeof tour === 'string' ? { stops: tour } : tour);
+    return () => t.stop();
+  }, [steps, tourKey]);
+
   return (
     <>
       <div className="deck-shell deck-scope" ref={host} />

package/focus.css

@@ -9,7 +9,8 @@
  * its own entrance, say — wins without !important.
  *
  * Tokens (set them in your theme; each has a fallback): --sd-dim-opacity · --sd-hot · --sd-blur ·
- * --sd-veil · --sd-accent (falls back to storydeck's --yellow) · --sd-ease · --sd-move-time.
+ * --sd-veil · --sd-accent (falls back to storydeck's --yellow) · --sd-ease · --sd-move-time · --sd-glow (a path's
+ * pulse, falls back to the accent).
  */
 
 /* a piece's state: on (in colour), dim (the context: greyed in place, or hidden, or kept), gone */
@@ -25,6 +26,8 @@
 .sd-moved { translate: var(--sd-dx, 0px) var(--sd-dy, 0px); scale: var(--sd-s, 1); }
 .sd-origin-tl { transform-origin: 0 0; }
 .sd-stage { position: absolute; inset: 0; transform-origin: 0 0; translate: var(--sd-tx, 0px) var(--sd-ty, 0px); scale: var(--sd-ts, 1); }
+/* apart: a piece its group's spring moves is marked .sd-apart and has no CSS motion — focusRuntime plays the spring as
+   Web Animations of the same translate/scale; at rest it is the plain style above (together: the piece as drawn) */
 
 /* the blur overlay: everything outside the holes, in the area, blurred and darkened; a frame on the subject */
 .sd-veil { position: absolute; left: 0; top: 0; pointer-events: none; -webkit-backdrop-filter: blur(var(--sd-blur, 7px)); backdrop-filter: blur(var(--sd-blur, 7px));
@@ -37,10 +40,16 @@
   color: var(--sd-accent, var(--yellow, #facc15)); }
 @media print { .sd-veil { display: none; } }
 
+/* a path: its line, naming the route, in slide px (it shows once the route is done) */
+.sd-path-line { position: absolute; pointer-events: none; white-space: nowrap; font: 600 22px/1 var(--mono, ui-monospace, monospace);
+  letter-spacing: .04em; color: var(--sd-accent, var(--yellow, #facc15)); }
+
 /* motion: each change fills its own slot, so a piece that moves AND lights does both */
 @property --sd-a-state { syntax: '*'; inherits: false; }
 @property --sd-a-move { syntax: '*'; inherits: false; }
 @property --sd-a-hot { syntax: '*'; inherits: false; }
+@property --sd-a-path { syntax: '*'; inherits: false; }
+@property --sd-turn { syntax: '*'; inherits: false; }   /* a piece's moment on a path; never inherited, so 0 off the route */
 @keyframes sdNone {}
 @keyframes sdEnter { from { opacity: 0; scale: calc(var(--sd-s, 1) * .92); } }
 @keyframes sdArrive { from { opacity: 0; } }
@@ -52,6 +61,12 @@
 @keyframes sdStage { from { translate: var(--sd-tx0, 0px) var(--sd-ty0, 0px); scale: var(--sd-ts0, 1); } }
 @keyframes sdVeilIn { from { opacity: 0; } }
 @keyframes sdVeilOut { from { opacity: 1; } to { opacity: 0; } }
+@keyframes sdPulse { 40% { filter: drop-shadow(0 0 14px var(--sd-glow, var(--sd-accent, var(--yellow, #facc15)))) brightness(1.2); } }
+/* a piece that lights from grey at its turn: sdLight and sdPulse as ONE animation. Two on one filter swap their lists
+   (grayscale ↔ drop-shadow brightness) at a jump — a flash; here every keyframe lists the same functions in the same
+   order, so the filter glides from grey into colour and the glow, and back to the plain style (the implicit end) */
+@keyframes sdLightPulse { from { opacity: var(--sd-dim-opacity, .32); filter: grayscale(1) drop-shadow(0 0 0 transparent) brightness(1); }
+  40% { filter: grayscale(0) drop-shadow(0 0 14px var(--sd-glow, var(--sd-accent, var(--yellow, #facc15)))) brightness(1.2); } }
 @media screen and (prefers-reduced-motion: no-preference) {
   .sd-enter { --sd-a-state: sdEnter .6s var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) var(--sd-delay, 0s) both; }
   .sd-arrive { --sd-a-state: sdArrive .6s ease both; }
@@ -62,10 +77,21 @@
   .sd-relook.sd-from-hide { --sd-a-state: sdArrive .6s ease both; }
   .sd-relook.sd-from-keep { --sd-a-state: sdFade .7s ease both; }
   .sd-move { --sd-a-move: sdMove var(--sd-move-time, 1s) var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) both; }
-  .sd-hot-in { --sd-a-hot: sdRing .6s var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) .3s both; }
+  .sd-hot-in { --sd-a-hot: sdRing .6s var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) calc(.3s + var(--sd-turn, 0s)) both; }   /* on a path, .3s after its turn */
   .sd-focus-new .sd-enter { --sd-delay: .4s; }   /* what a click adds waits for its blur */
-  :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) :is(.sd-enter, .sd-arrive, .sd-light, .sd-fade, .sd-leave, .sd-relook, .sd-move, .sd-hot-in) {
-    animation: var(--sd-a-state, sdNone 0s), var(--sd-a-move, sdNone 0s), var(--sd-a-hot, sdNone 0s); }
+  /* a path: everything on it has one moment, --sd-turn — its delay, and .4s more under a new blur, so the whole path
+     waits for the blur and then runs. A piece on the route enters, arrives or lights then, and glows as the route
+     reaches it (on every forward click); a piece stepping aside for its lit twin goes then; the line shows then. */
+  :is(.sd-path, .sd-twin-turn, .sd-path-line) { --sd-turn: var(--sd-path-delay, 0s); }
+  .sd-focus-new :is(.sd-path, .sd-twin-turn, .sd-path-line) { --sd-turn: calc(var(--sd-path-delay, 0s) + .4s); }
+  .sd-path { --sd-a-path: sdPulse .9s ease var(--sd-turn); }
+  .sd-path.sd-enter { --sd-a-state: sdEnter .6s var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) var(--sd-turn) both; }
+  .sd-path.sd-arrive { --sd-a-state: sdArrive .6s ease var(--sd-turn) both; }
+  .sd-path.sd-light { --sd-a-state: sdLightPulse .9s ease var(--sd-turn) backwards; --sd-a-path: sdNone 0s; }   /* grey until its turn */
+  .sd-twin-turn.sd-leave { --sd-a-state: sdLeave .45s ease var(--sd-turn) both; }
+  :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) :is(.sd-enter, .sd-arrive, .sd-light, .sd-fade, .sd-leave, .sd-relook, .sd-move, .sd-hot-in, .sd-path) {
+    animation: var(--sd-a-state, sdNone 0s), var(--sd-a-move, sdNone 0s), var(--sd-a-hot, sdNone 0s), var(--sd-a-path, sdNone 0s); }
+  :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-path-line { animation: sdArrive .5s ease var(--sd-turn) both; }
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-stage.sd-move { animation: sdStage var(--sd-move-time, 1s) var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) both; }
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-veil-in-new { animation: sdVeilIn .7s cubic-bezier(.4, 0, .2, 1) both; }
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-frame.sd-new { animation: sdArrive .5s ease .35s both; }

package/focus.d.ts

@@ -53,11 +53,25 @@ export interface FocusContext {
   readonly options: Readonly<Record<string, unknown>>;
 }
 
-/** A focus strategy: a look (how the context looks), a mover (where things go) or an overlay (what lies over the slide). */
+/**
+ * A route, as an order strategy gives it — checked, and refused (naming the strategy and the fix) when it is not this:
+ * the names in turn (each one's LIT pieces take the next turn; a name with nothing lit takes none), the seconds between
+ * two turns (0–5), and the line that names it, with where it goes ('x y', slide px). The strategy's object is only read.
+ */
+export interface FocusRoute { readonly names: readonly string[]; readonly step: number; readonly line?: string; readonly lineAt?: string | null }
+
+/**
+ * A mover's groups going by a spring each (apart), `stagger` ms apart (0–1000): out in the order the groups are given,
+ * back in reverse. Checked, and refused (naming the strategy and the fix) when it is not this; only read.
+ */
+export interface FocusSpring { readonly stagger: number }
+
+/** A focus strategy: a look (how the context looks), a mover (where things go), an overlay (what lies over the slide) or an order (how the subject comes on). */
 export type FocusStrategy =
   | { readonly name?: string; readonly kind: 'look'; readonly look: 'grey' | 'hide' | 'keep' }
-  | { readonly name?: string; readonly kind: 'mover'; place(ctx: FocusContext): { stage?: FocusGroup; subject?: FocusGroup; context?: FocusGroup; groups?: { names: readonly string[]; g: FocusGroup | null }[] } }
-  | { readonly name?: string; readonly kind: 'overlay'; cover(ctx: { subjectOnSlide: FocusBox | null; canvas: { w: number; h: number }; options: Readonly<Record<string, unknown>> }): { rects: number[][]; label?: string; out?: number[][] } | null };
+  | { readonly name?: string; readonly kind: 'mover'; place(ctx: FocusContext): { stage?: FocusGroup; subject?: FocusGroup; context?: FocusGroup; groups?: { names: readonly string[]; g: FocusGroup | null }[]; spring?: FocusSpring } }
+  | { readonly name?: string; readonly kind: 'overlay'; cover(ctx: { subjectOnSlide: FocusBox | null; canvas: { w: number; h: number }; options: Readonly<Record<string, unknown>> }): { rects: number[][]; label?: string; out?: number[][] } | null }
+  | { readonly name?: string; readonly kind: 'order'; route(ctx: { names: readonly string[]; options: Readonly<Record<string, unknown>> }): FocusRoute };
 
 export interface FocusDeck {
   readonly pieces: readonly FocusPiece[];
@@ -85,10 +99,24 @@ export interface FocusPieceLook {
   readonly hot: boolean;
   readonly hotIn: boolean;
   readonly move: FocusMove | null;
-  /** Where it moved from, when it moved since the last click. (A leaving piece's `move` is where it stood.) */
+  /**
+   * Where it moved from, when it moved since the last click. (A leaving piece's `move` is where it stood.) A piece on
+   * its group's spring (`apart`) has the spring's other end: where it stands together as its group opens — kept while
+   * the group stays open — and where it stood apart as its group closes.
+   */
   readonly from: FocusMove | null;
   /** It stepped aside for its lit twin. */
   readonly twinOff: boolean;
+  /** Stepping aside for a lit twin on a path: the seconds until that twin's turn, when it goes (the first, for several); null when it goes at once (a lit twin off the route) or does not step aside on this click. */
+  readonly twinTurn: number | null;
+  /** On a path: the seconds its turn waits (0 for the first); null when it takes no turn — not on the route, or not lit. */
+  readonly path: number | null;
+  /**
+   * It goes by its group's spring on this click (apart): the group's index in the look's `apart.groups` — the page's
+   * focusRuntime moves it from `from` to `move`. Null for every other piece (one that enters, leaves, or is in no
+   * group that opens or closes; one whose group stays open but moved anyway glides as any mover's piece does).
+   */
+  readonly apart: number | null;
 }
 
 export interface FocusLook {
@@ -97,6 +125,15 @@ export interface FocusLook {
   readonly stage: { readonly move: { s: number; x: number; y: number } | null; readonly from: { s: number; x: number; y: number } | null } | null;
   /** The blur: 'in-new' when the last click had none, 'in' while it stays, 'out' as it melts away; frameNew when its frame moved or appeared. */
   readonly overlay: { readonly rects: readonly (readonly number[])[]; readonly label: string; readonly phase: 'in-new' | 'in' | 'out'; readonly frameNew: boolean } | null;
+  /** A path: how many turns, the seconds between two, when the last starts (done), and its line ('' for none) and where it goes (null: the area's bottom left); null when no lit piece took a turn. */
+  readonly path: { readonly turns: number; readonly step: number; readonly done: number; readonly line: string; readonly lineAt: string | null } | null;
+  /**
+   * apart: the groups that open on this click (to 1, in the order written), then those the last click opened that
+   * close now (to 0, was 1, in its order), then those the last click closed (to 0, was 0) — carried one click more, so
+   * a spring still closing settles from wherever it is; `was` is where the last click left a group (0 together, 1
+   * apart). Null when no group opens, stays open, closes or settles — as on every click of a deck without apart.
+   */
+  readonly apart: { readonly stagger: number; readonly groups: readonly { readonly names: readonly string[]; readonly to: 0 | 1; readonly was: 0 | 1 }[] } | null;
   readonly strategies: readonly string[];
   /** The subject where it ends up, on the slide. */
   readonly subject: FocusBox | null;
@@ -105,7 +142,12 @@ export interface FocusLook {
 /** The state a click leaves, to start the next from. Opaque. */
 export type FocusState = { readonly __focusState: true } & Record<string, unknown>;
 
-export const FOCUS: Readonly<Record<'grey' | 'hide' | 'keep' | 'zoom' | 'left' | 'right' | 'up' | 'down' | 'place' | 'blur', FocusStrategy>>;
+/**
+ * The built-in strategies. `apart` (a mover) is the exploded view: its option `apart` — data-focus-apart — is
+ * 'names: dx dy [scale] | …' (slide px; each group scaled around its own centre), `stagger` the ms between two
+ * groups (35); a later click without it brings the groups back together, the last one out first.
+ */
+export const FOCUS: Readonly<Record<'grey' | 'hide' | 'keep' | 'zoom' | 'left' | 'right' | 'up' | 'down' | 'place' | 'apart' | 'path' | 'blur', FocusStrategy>>;
 export function readFocus(spec: FocusSpec | undefined | null, shared?: Readonly<Record<string, unknown>>): { strategy: string; options: Record<string, unknown> }[];
 export function focusStep(prev: FocusState | null, click: FocusClick, deck: FocusDeck): { state: FocusState; look: FocusLook };
 /** `end` is null only when there are no clicks and no `start`. */