footprint-storydeck 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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`.**

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,6 +73,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 +94,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 +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
@@ -199,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
@@ -277,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 |
@@ -287,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.
@@ -302,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

@@ -26,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));

package/focus.d.ts

@@ -60,10 +60,16 @@ export interface FocusContext {
  */
 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: '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 };
 
@@ -93,7 +99,11 @@ 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;
@@ -101,6 +111,12 @@ export interface FocusPieceLook {
   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 {
@@ -111,6 +127,13 @@ export interface FocusLook {
   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;
@@ -119,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' | 'path' | '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`. */

package/focus.js

@@ -10,7 +10,10 @@
 //                                      left · right · up · down (the context steps aside that way, smaller,
 //                                      and the subject grows into the room it leaves) ·
 //                                      place (named groups moved by the amounts you give — a layout you
-//                                      art-direct, still animated from wherever the last click left it)
+//                                      art-direct, still animated from wherever the last click left it) ·
+//                                      apart (the exploded view: named groups fly apart along the vectors you
+//                                      give, one spring each, staggered, and come back together on a later
+//                                      click without it — the last one out is the first one back)
 //   overlay  what lies over the slide  blur (everything outside the subject's frame is blurred; a frame,
 //                                      and a label if given, on the subject)
 //   order    how the subject comes on  all at once (the default) · path (piece after piece along a route —
@@ -74,14 +77,31 @@ function aside(side) {
   }});
 }
 
-/** place's groups: 'names: dx dy scale [@ ox oy] | …' (or a list of such strings). */
-function readGroups(v) {
-  if (v === undefined || v === null || v === '') throw new Error('focus "place": give groups, \'names: dx dy scale [@ ox oy] | …\'');
-  return [].concat(v).flatMap(x => String(x).split('|')).map(g => g.trim()).filter(Boolean).map(g => {
-    const m = /^([^:]+):\s*(-?[\d.]+)\s+(-?[\d.]+)(?:\s+(-?[\d.]+))?(?:\s*@\s*(-?[\d.]+)\s+(-?[\d.]+))?$/.exec(g);
-    if (!m) throw new Error(`focus "place": a group is 'names: dx dy scale [@ ox oy]', not "${g}"`);
-    return {names: m[1].trim().split(/\s+/), dx: Number(m[2]), dy: Number(m[3]), s: m[4] === undefined ? 1 : Number(m[4]), origin: m[5] === undefined ? null : [Number(m[5]), Number(m[6])]};
+/**
+ * Groups moved by amounts: 'names: dx dy scale [@ ox oy] | …' (or a list of such strings) — place's, and apart's
+ * without the origin ('names: dx dy [scale]', written in data-focus-apart).
+ */
+const NUMBER = '(-?(?:\\d+(?:\\.\\d*)?|\\.\\d+))';   // 12, -3.5, .5 — never '1.2.3' or '.'
+const GROUP = new RegExp(`^([^:]+):\\s*${NUMBER}\\s+${NUMBER}(?:\\s+${NUMBER})?(?:\\s*@\\s*${NUMBER}\\s+${NUMBER})?$`);
+function readGroups(v, who = 'place', origin = true) {
+  const form = origin ? 'names: dx dy scale [@ ox oy]' : 'names: dx dy [scale]';
+  const give = `focus "${who}": give groups, '${form} | …'${origin ? '' : ` (data-focus-${who}, or the option ${who})`}`;
+  if (v === undefined || v === null || v === '') throw new Error(give);
+  const groups = [].concat(v).flatMap(x => String(x).split('|')).map(g => g.trim()).filter(Boolean).map(g => {
+    const m = GROUP.exec(g);
+    if (!m || (!origin && m[5] !== undefined)) throw new Error(`focus "${who}": a group is '${form}', not "${g}"`);
+    const s = m[4] === undefined ? 1 : Number(m[4]);
+    if (!(s > 0)) throw new Error(`focus "${who}": a group's scale is a number above 0 (1 keeps its size), not ${m[4]} in "${g}"`);
+    return {names: m[1].trim().split(/\s+/), dx: Number(m[2]), dy: Number(m[3]), s, origin: m[5] === undefined ? null : [Number(m[5]), Number(m[6])]};
   });
+  if (!groups.length) throw new Error(`${give} — not ${JSON.stringify(v)}`);
+  return groups;
+}
+
+/** A group move that puts the centre of the group's box (or the point `origin`, map px) where dx dy (slide px) and s say. */
+function groupMove({names, dx, dy, s, origin}, boxOf, view) {
+  const box = boxOf(names); if (!box && !origin) return {names, g: null};
+  return {names, g: {o: origin ?? centre(box), s, t: [dx / view.s, dy / view.s]}};
 }
 
 /** Rectangles x y w h from an option: numbers, a string of them, or a list of either. */
@@ -108,11 +128,16 @@ export const FOCUS = Object.freeze({
    * moves by dx, dy (slide px) and scales around its own centre, or around the point ox oy (map px) when given.
    */
   place: Object.freeze({name: 'place', kind: 'mover', place({boxOf, view, options}) {
-    return {groups: readGroups(options.groups).map(({names, dx, dy, s, origin}) => {
-      const box = boxOf(names); if (!box && !origin) return {names, g: null};
-      const o = origin ?? centre(box);
-      return {names, g: {o, s, t: [dx / view.s, dy / view.s]}};
-    })};
+    return {groups: readGroups(options.groups).map(g => groupMove(g, boxOf, view))};
+  }}),
+  /**
+   * The exploded view: `apart` is 'names: dx dy [scale] | names: …' — each named group (lines and connectors that
+   * carry one of its names come with it) flies out by dx, dy (slide px), scaled around its own centre, and comes back
+   * together on a later click without apart. Its way there is a spring per group (focusHtml.js · focusRuntime), the
+   * groups `stagger` (35) ms apart: out in the order written, back in reverse, so the last one out is the first one back.
+   */
+  apart: Object.freeze({name: 'apart', kind: 'mover', place({boxOf, view, options}) {
+    return {groups: readGroups(options.apart, 'apart', false).map(g => groupMove(g, boxOf, view)), spring: {stagger: num(options.stagger, 35)}};
   }}),
   /**
    * The subject comes on piece after piece along a route, as a request travels it: `route` names the pieces in
@@ -164,7 +189,7 @@ function pick(focus, strategies) {
     const s = all[strategy];
     if (!s) throw new Error(`no focus strategy "${strategy}" (there are ${Object.keys(all).join(', ')})`);
     if (!KINDS.includes(s.kind)) throw new Error(`focus strategy "${strategy}" has kind ${JSON.stringify(s.kind)}: a strategy is a look, a mover, an overlay or an order`);
-    if (byKind[s.kind]) throw new Error(`a click takes one ${s.kind} at most: "${byKind[s.kind].name}" and "${strategy}" are both ${s.kind}s`);
+    if (byKind[s.kind]) throw new Error(`a click takes one ${s.kind} at most: "${byKind[s.kind].name}" and "${strategy}" are both ${s.kind}s — keep one, and give the other a click of its own`);
     byKind[s.kind] = {s: {...s, name: s.name ?? strategy}, options, name: strategy};
   }
   return byKind;
@@ -186,6 +211,17 @@ function readRoute(r, strategy) {
   return {names: [...names], step, line: line ?? '', lineAt: lineAt?.trim() ? lineAt : null};   // (a blank lineAt, an empty data-focus-line-at, is none)
 }
 
+/**
+ * What a mover's `spring` gave — its groups go by a spring each, `stagger` ms apart — checked like an order's route
+ * (a deck's own mover is held to what apart gives) and read into a new object.
+ */
+function readSpring(r, strategy) {
+  const shown = v => (typeof v === 'number' || v === undefined ? String(v) : JSON.stringify(v));
+  if (!r || typeof r !== 'object') throw new Error(`focus "${strategy}": spring is {stagger}, the ms between two groups — not ${shown(r)}`);
+  if (typeof r.stagger !== 'number' || !(r.stagger >= 0 && r.stagger <= 1000)) throw new Error(`focus "${strategy}": stagger is the ms between two groups setting off, a number from 0 to 1000 — not ${shown(r.stagger)}`);
+  return {stagger: r.stagger};
+}
+
 /** Where a group move puts one piece: its reference point (the centre, or the top-left when it has no size) moves by [dx, dy], and it scales by s around it. */
 function placePiece(g, box) {
   if (!g || !box) return null;
@@ -217,8 +253,10 @@ function changeOf(st, was, look, wasLook, entering, before) {
  * fresh). `deck`: {pieces: [{keys, box, twin?}], strategies?, area?, view?, canvas?}. Returns {state, look}:
  * the state to hand the next click, and the look to draw — per piece {state, was, change, look, fromLook, hot,
  * hotIn, move, from, twinOff, twinTurn (stepping aside for a lit twin on a route: the seconds until that twin's
- * turn; else null), path (a lit piece on a route: the seconds until its turn; else null)}, the stage's move, the
- * overlay, the path ({turns, step, done, line, lineAt}, or null) and which strategies were used.
+ * turn; else null), path (a lit piece on a route: the seconds until its turn; else null), apart (a piece that goes by
+ * its group's spring on this click: the group's index in the look's apart; else null)}, the stage's move, the
+ * overlay, the path ({turns, step, done, line, lineAt}, or null), the apart ({stagger, groups: [{names, to, was}]} —
+ * to 1 opens, to 0 closes, was is where the last click left it — or null) and which strategies were used.
  */
 export function focusStep(prev, step, deck) {
   const {pieces, strategies = {}} = deck, canvas = deck.canvas ?? {w: 1920, h: 1080};
@@ -250,8 +288,15 @@ export function focusStep(prev, step, deck) {
   // boxOf(names): the box around the shown pieces of those names, for a mover that moves named groups (place).
   const boxOf = l => union(all.filter(i => states[i] !== 'gone' && has(i, known(names([].concat(l)), 'focus group: '))).map(i => pieces[i].box));
   const placed = chosen.mover ? chosen.mover.s.place({subject, context, area, view, canvas, boxOf, options: chosen.mover.options}) ?? {} : {};
-  // Named groups (later ones win a piece in two of them) take their pieces out of the subject and context groups.
-  for (const {names: l, g} of placed.groups ?? []) for (const i of all) if (states[i] !== 'gone' && has(i, l)) inGroup.set(i, g ? {g} : 'still');
+  // Named groups (later ones win a piece in two of them) take their pieces out of the subject and context groups. A
+  // mover whose groups go by a spring (apart) has each moved piece remember its group, so the next click knows what closes.
+  const spring = placed.spring === undefined || placed.spring === null ? null : readSpring(placed.spring, chosen.mover.name);
+  const springOf = new Map();
+  for (const {names: l, g} of placed.groups ?? []) for (const i of all) if (states[i] !== 'gone' && has(i, l)) {
+    inGroup.set(i, g ? {g} : 'still');
+    if (spring && g) springOf.set(i, l.join(' ')); else springOf.delete(i);
+  }
+  const springGroups = [...new Map((spring ? placed.groups ?? [] : []).filter(x => x.g).map(x => [x.names.join(' '), [...x.names]]))];
   const stage = placed.stage ? {s: round(placed.stage.s, 4), x: round(placed.stage.o[0] * (1 - placed.stage.s) + placed.stage.t[0]), y: round(placed.stage.o[1] * (1 - placed.stage.s) + placed.stage.t[1])} : null;
   const groupOf = i => { const k = inGroup.get(i); return k === 'subject' ? placed.subject : k === 'context' ? placed.context : k?.g ?? null; };
   const moves = pieces.map((p, i) => states[i] === 'gone' ? null : placePiece(groupOf(i), p.box));
@@ -278,15 +323,45 @@ export function focusStep(prev, step, deck) {
   // stood, so it fades out from there instead of jumping home in colour first.
   const before = prev && !step.fresh ? prev : null;
   const hotNow = new Set(all.filter(i => states[i] !== 'gone' && has(i, hot)));
+  // apart: the groups that open on this click (in the order written), then those the last click opened that close now
+  // (in its order, was 1), then those the last click closed (to 0, was 0): carried one click more, so a spring still
+  // closing settles from wherever it is instead of snapping home. A piece shown on both clicks goes by its group's
+  // spring; one whose group keeps its target but moved anyway (a new vector) glides as any mover's piece does.
+  const last = before?.spring ?? null, nowKeys = new Set(springGroups.map(([k]) => k));
+  const lastTo = new Map((last?.groups ?? []).map(g => [g.key, g.to]));
+  const springList = [...springGroups.map(([key, l]) => ({key, names: l, to: 1, was: lastTo.get(key) === 1 ? 1 : 0})),
+    ...(last?.groups ?? []).filter(g => !nowKeys.has(g.key)).map(g => ({key: g.key, names: g.names, to: 0, was: g.to}))];
+  const springAt = new Map(springList.map((g, k) => [g.key, k]));
+  // Each shown piece's group: the one that opens it now, else the one it was in, while that group is still listed.
+  const member = pieces.map((_, i) => {
+    if (states[i] === 'gone') return null;
+    const had = before?.springOf?.[i] ?? null;
+    return springOf.get(i) ?? (had !== null && springAt.has(had) && !nowKeys.has(had) ? had : null);
+  });
+  const springIdx = (i, moved) => {
+    if (!before || member[i] === null || before.states[i] === 'gone') return null;
+    const k = springAt.get(member[i]);
+    return springList[k].to === springList[k].was && moved ? null : k;
+  };
+  // The other end of a piece's spring: where it stands together as its group opens, where it stood apart as it closes —
+  // carried while the group keeps its target, so a spring caught mid-way goes on from there.
+  const home = () => ({dx: 0, dy: 0, s: 1});
+  const end = pieces.map((_, i) => {
+    if (member[i] === null) return null;
+    const g = springList[springAt.get(member[i])];
+    return g.to === g.was ? before?.springEnd?.[i] ?? home() : before?.moves[i] ?? home();
+  });
   const out = pieces.map((p, i) => {
     const st = states[i], was = before ? before.states[i] : 'gone', wasLook = before?.looks?.[i] ?? null;
     const change = changeOf(st, was, looks[i], wasLook, has(i, ins), before);
     const leaving = change === 'leave', stood = before?.moves[i] ?? null;
     const from = stood, moved = st !== 'gone' && was !== 'gone' && !!before && !sameMove(from, moves[i]);
+    // A piece on its group's spring has the spring's other end as `from`: together as it opens, apart as it closes.
+    const k = springIdx(i, moved), spun = k === null ? null : end[i];
     return {state: st, was, change, look: leaving ? wasLook : looks[i], fromLook: change === 'relook' ? wasLook : null,
       hot: hotNow.has(i), hotIn: hotNow.has(i) && (!before || !before.hot.has(i)),
-      move: leaving ? stood : st === 'gone' ? null : moves[i], from: moved ? from ?? {dx: 0, dy: 0, s: 1} : null, twinOff: twinOff.has(i),
-      twinTurn: leaving && twinOff.has(i) ? twinTurn(i) : null, path: delayOf(i)};
+      move: leaving ? stood : st === 'gone' ? null : moves[i], from: spun ?? (moved ? from ?? home() : null), twinOff: twinOff.has(i),
+      twinTurn: leaving && twinOff.has(i) ? twinTurn(i) : null, path: delayOf(i), apart: k};
   });
   const stageMoved = !!before && !sameStage(before.stage, stage);
   // The blur: new only when the last click had none (a blur that moves to another subject stays, and only its
@@ -294,9 +369,12 @@ export function focusStep(prev, step, deck) {
   const overlay = cover ? {rects: cover.rects, label: cover.label, phase: before?.cover ? 'in' : 'in-new', frameNew: !before?.cover || !sameCover(before.cover, cover)}
     : before?.cover ? {rects: before.cover.out ?? before.cover.rects, label: '', phase: 'out', frameNew: false} : null;
   return {
-    state: {vis, states, moves, stage, hot: hotNow, cover, looks},
+    state: {vis, states, moves, stage, hot: hotNow, cover, looks,
+      spring: springList.some(g => g.to === 1 || g.was === 1) ? {stagger: (spring ?? last).stagger, groups: springList.filter(g => g.to === 1 || g.was === 1).map(({key, names: l, to}) => ({key, names: l, to}))} : null,
+      springOf: member, springEnd: end},
     look: {pieces: out, stage: stage || stageMoved ? {move: stage, from: stageMoved ? before.stage ?? {s: 1, x: 0, y: 0} : null} : null, overlay,
       path: turns ? {turns, step: order.step, done: round((turns - 1) * order.step, 3), line: order.line, lineAt: order.lineAt} : null,
+      apart: springList.length ? {stagger: (spring ?? last).stagger, groups: springList.map(({names: l, to, was}) => ({names: [...l], to, was}))} : null,
       strategies: Object.values(chosen).map(c => c.name), subject: subjectOnSlide},
   };
 }

package/focusHtml.d.ts

@@ -10,7 +10,9 @@ export function readStep(attrs: string): FocusClick;
 /**
  * That HTML, each piece dressed for this click's look (classes from focus.css, its move as CSS variables). On a path, a
  * piece's moment rides as `--sd-path-delay`: its turn (`sd-path`), or, stepping aside for its lit twin, that twin's
- * (`sd-twin-turn`); focus.css adds .4 s under a new blur. A click without a path is drawn exactly as before.
+ * (`sd-twin-turn`); focus.css adds .4 s under a new blur. A click without a path is drawn exactly as before. A piece
+ * that goes by its group's spring (apart) is marked `sd-apart` (no CSS move: focusRuntime plays the spring) and
+ * carries `data-sd-apart="index to was stagger names…"`; a click without apart is drawn exactly as before.
  */
 export function drawFocus(html: string, look: FocusLook): string;
 /** The pieces inside the stage the view moves (a zoom); unchanged when nothing moves the view. Put it in the map's own box. */
@@ -19,5 +21,10 @@ export function wrapStage(inner: string, look: FocusLook): string;
 export function slideClass(look: FocusLook): string;
 /** The overlay of a click in slide px — the blur, its frame and label, and a path's line (once its route is done, .4 s later under a new blur) — put outside the map's box; '' when the click has none. */
 export function focusOverlay(look: FocusLook, options?: { canvas?: { w: number; h: number }; area?: readonly [number, number, number, number] }): string;
-/** Runs in the page; call it once, at any time: only a forward click animates; a jump or a step back lands at once. */
+/**
+ * Runs in the page; call it once, at any time: only a forward click animates; a jump or a step back lands at once.
+ * It plays apart's springs (one per group, staggered, from wherever the last click left a group, mid-way too; each deck
+ * on the page its own) as Web Animations, so a group at rest is exactly as drawn; under reduced motion, or without
+ * Element.animate, it lands.
+ */
 export function focusRuntime(): void;