footprint-storydeck 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.11.0 — FootPrint 11 and a part that says how it differs
+
+- **Migration:** PowerPoint export requires FootPrint 11. Install `footprintjs@^11.0.0` beside Storydeck;
+  the peer stays optional and is loaded when an export runs. Older FootPrint majors are no longer supported.
+
+- **A part that differs from the real thing says so.** A picture is believed, so a process run 30 times faster or a part
+  drawn far larger than it is reads as how the thing is. A part now declares it (`data-differs-time="30"`,
+  `data-differs-scale="…"`), and the deck says it: a label at the top right of its slides by default, in the notes with
+  `data-differs-said` (`"A | B"` gives one phrase per statement), or both. Each statement declared needs a line or a
+  phrase of its own, a number in the time's line must be the one declared, and a deck in another language gives its own
+  words. A time factor is 1.01 or more or 0.99 or less, up to a billion times either way. `check` refuses a phrase the
+  notes do not hold (`differs-unsaid`), matching words as StoryReel matches a phrase, never inside a word, and `check
+  --layout` warns when a label meets the kicker, the headline or a lit piece (`differs-overlap`). `review` says how each
+  click differs. A `>` in a value, or `data-differs-*` on a `<step>`, is refused instead of lost. A deck that declares no
+  label builds byte for byte as before: the page carries the label's CSS only when a part shows one. It cannot see a
+  speed-up nobody declared.
+- **Loops keep running in a video.** `renderVideo` stepped a click until its last entrance ended and held that frame,
+  so a loop (a pulse, packets on a wire) stood still for the rest of the click and started again at the next. A click
+  whose loops run is now stepped on to its end, each loop at the video's own time, so they run on from click to click
+  as in the room; a click without loops renders as before, and the timeline is unchanged. It costs frames — a looping
+  click is one frame per 1/fps of its length — so `loops: false` holds the frame as before, for a fast draft. The
+  browser port gains an optional `loops()` and `seek(ms, {loop})`; a driver without them renders as before.
+
+## 0.10.0 — a part arrives with a change of picture, and a deck a viewer can explore
+
+- **A part arrives with a change of picture: `data-enter`.** `<section … data-enter="push" data-enter-from="right">`
+  plays one of the editor's changes StoryReel's films use (footprint-story/motion's table: the same names, settings,
+  lengths and eases) as the deck steps into the part: cut, fade, dip, wipe, split, iris, push, slide, whip or zoom,
+  each with its settings as `data-enter-*` (`from`, `line`, `at` as "x y" in slide px or "centre", `color`) and
+  `data-enter-seconds` / `data-enter-ease`. The build samples each distinct change once into keyframes for both slides
+  (30 a second, the same curves a film draws); the page plays them with Web Animations only on a forward step into the
+  part — a jump, a step back, reduced motion and motion off land at once — keeping the slide it leaves in view until
+  it ends, and a video steps them like any animation. A dip shows its colour behind both slides (black unless
+  `data-enter-color` says otherwise): `<deck-stage>` now paints what shows behind its slides with `--deck-canvas` (white,
+  as before, when unset). A change a page cannot play (clock, page, through, match: they need a canvas), a setting the
+  change does not take and a value out of range are refused at build, naming the part and the fix. `review` says how
+  each part arrives. While a change plays the frame clips both slides (a push never crosses the letterbox: `<deck-stage>`
+  clips its canvas while it carries `data-deck-changing`), the slide being left keeps its loops running, and printing
+  puts everything back first. Settings are read as a browser reads the tag. A deck without `data-enter` carries none
+  of it (no keyframes, rule or runtime); the `<deck-stage>` every page carries gained the two hooks, and draws as
+  before without them.
+
+- **Explore: a viewer clicks a piece to go to the click about it.** With `"explore": true` in deck.json, a click on a
+  piece goes to the click that is about it — the first click whose `data-on` names it (`gw+`'s gw too), or, when none
+  does, the first that takes it in through a `name+` — and a "Back to click N" control (or Backspace) returns, a step
+  at a time, as a browser's Back does (to where the viewer was before each jump, whatever they stepped through since).
+  Pieces that lead somewhere get a pointer and a ring on hover; a piece whose click is the one shown, or one that
+  cannot be seen, leads nowhere; a link or control inside a piece keeps its click; a drag (the dev page's Alt-drag) is
+  never a click. On a touch screen a tap on a piece that leads somewhere explores — tap beside the pieces to step. The
+  pieces are reached by pointer, not by keyboard: arrow keys still step through the clicks in order. The presenter
+  window does not explore (it follows the room's deck). The authored order never changes: explore is a way through the
+  same clicks. A deck without `"explore"` carries none of it (its look comes with it, not in deck.css).
+
 ## 0.9.0 — living system diagrams: loops, wires between pieces, a wire's label, halo and running packets
 
 - **A wire between pieces: `data-arrow="client to server"`.** The wire runs from the edge of one piece's box to the
@@ -45,8 +98,9 @@
   step back keeps it running (a static arrival no longer zeroes a loop, only entrances). A loop never runs under
   reduced motion (switched live), in print, or with motion off: there the piece rests in its own style. A piece that
   loops and changes on the same click (comes in, lights up) does both: focus.css keeps the loop as the last animation
-  of the piece's list. Loop CSS is drawn only for decks that use loops, so a deck without one builds byte for byte as
-  before.
+  of the piece's list. Loop CSS is drawn only for decks that use loops, so a deck without one gains none; the
+  `<deck-stage>` every page carries changed, and a deck without loops draws as before. (Corrected after release: this
+  line first said such a deck builds byte for byte as before — its page carries the changed stage.)
 - **Motion off: a still deck.** `?motion=off` after the page's address, or `<deck-stage data-motion="off">` (switched
   live too): no loops, and every click lands at once, as a jump does — so a screenshot of a click is the same every
   time.

package/README.md

@@ -1,5 +1,9 @@
 # Footprint StoryDeck
 
+For developers publishing technical explanations, product walkthroughs and teaching material.
+
+[Quick start](#quick-start) · [Folder-based deck CLI](#a-deck-from-a-folder-storydeck) · [Live demo](https://footprintjs.github.io/storydeck/) · [API](#api)
+
 **One source, many lenses.** Write a piece of content once, render it three ways:
 
 - **Read** — a detailed, SEO-first article (figure + prose per section).
@@ -399,6 +403,19 @@ npx footprint-storydeck build my-talk     # my-talk/index.html — one page, eve
   ticks the line (`- [x]`). Pointing costs the person a second and the agent no screenshot. Each note is signed with a
   key kept with you (`~/.storydeck/key`) for that deck's folder, so a feedback.md that came with someone else's deck is
   never read as your requests: its lines are counted, never listed.
+- **A part that differs from the real thing says so.** A picture is believed, so a process run 30 times faster or a
+  part drawn far larger than it is reads as how the thing is. `<section data-label="Inside" data-differs-time="30"
+  data-differs-scale="The dots are drawn far larger than real" data-differs-said="thirty times faster">` declares it, and the
+  deck says it: on the slide by default, a label at the top right of each of the part's slides ("Time shown 30 times
+  faster"; `data-differs-shown` gives other words, `A | B` for two labels, or `false` for the notes alone), in the notes with
+  `data-differs-said`, the phrase that says it (`A | B` for one per statement), or both. A factor a label can say is 1.01 or
+  more, or 0.99 or less, up to a billion times either way. Each statement declared needs a line or a phrase of its own, and
+  a number in the time's line must be the one declared. A deck in another language gives its own words: the default ones
+  are English. A value is read as a browser reads it: write `&gt;` for a `>` and `&#124;` for a `|` in your words. `check`
+  refuses a phrase the part's notes do not hold, matching whole words in order, as a film does. `check --layout` warns when a
+  label meets the kicker, the headline or a lit piece. `review` says how each click differs, and a video shows the labels as
+  the page does. A deck that shows no label builds byte for byte as if this did not exist. It reads what is declared, and
+  cannot see a speed-up nobody declared.
 - **A part can have its own look.** `<section data-label="3 · Storage" … data-theme="ledger">` puts
   `data-theme="ledger"` on each of that part's slides, so `theme.css` can dress it: redefine the tokens for it
   (`[data-theme="ledger"] { --bg: …; --text: …; }`, and `:root.dark [data-theme="ledger"]` for dark) and give its pieces
@@ -408,13 +425,24 @@ npx footprint-storydeck build my-talk     # my-talk/index.html — one page, eve
   follow the part on screen as well, select the active slide in the same rule:
   `[data-theme="ledger"], :root:has([data-deck-active][data-theme="ledger"]) { … }`. `check` warns about a theme
   that theme.css never selects (a misspelt name changes nothing), and `review` names each click's theme.
+- **A part arrives with a change of picture.** `<section … data-enter="push" data-enter-from="right">` plays one of
+  the editor's changes StoryReel's films use — cut, fade, dip, wipe, split, iris, push, slide, whip, zoom — with its
+  settings as `data-enter-*` (`from`, `line`, `at` "x y" or "centre", `color` — a dip goes through black unless it
+  says otherwise — `seconds`, `ease`), as the deck steps into the part; the frame clips both slides while it plays. Only on a forward step: a jump or a step back lands at once, and so does every step under reduced
+  motion or with motion off. `review` says how each part arrives.
+- **Explore: click a piece, go to the click about it.** `"explore": true` in deck.json lets a viewer wander the
+  deck: a click on a piece goes to the click that is about it (the first whose `data-on` names it, else the first that
+  takes it in through a `name+`), and "Back to click N" (or Backspace) returns, as a browser's Back does. Pieces that
+  lead somewhere show a pointer and a ring on hover; on a touch screen a tap on one explores (tap beside the pieces to
+  step), and the keyboard keeps stepping in order. The order you wrote is
+  untouched — explore is a way through the same clicks, for a deck left open on a screen or sent to someone.
 - **Read first, look last.** A reviewer — a person, or a model that pays for every screenshot — reads the deck as text:
   `outline` (a line per click), `review --click 14` (its headline and words, what it lights, greys, brings in and moves,
   its route, its notes), `check` (what to fix, each with its click and its fix: a headline over 12 words, pieces that
   light just by coming in, a click that changes nothing, a piece never shown, clicks without notes, a theme theme.css
   never styles). `check --layout`
-  opens the page in a browser, offline, and finds text that spills out of its box and endless animations that are not
-  loops (it needs Playwright installed beside
+  opens the page in a browser, offline, and finds text that spills out of its box, a label on how a part differs that meets
+  what is on its slide, and endless animations that are not loops (it needs Playwright installed beside
   StoryDeck: `npm i -D footprint-storydeck playwright-core`; without it, it says so and the other checks run). `mcp` serves the same tools to an AI assistant:
   `claude mcp add storydeck -- npx footprint-storydeck mcp my-talk`.
 - **The helpers a diagram needs.** `<i data-k="w1" class="wire pkt" data-arrow="client to server"></i>` is a wire (an

package/deck.d.ts

@@ -29,6 +29,8 @@ export interface DeckConfig {
   readonly deckData: string | null;
   /** What `storydeck check` asks: words in a map click's headline (12), on a plain slide (40). */
   readonly checks: { readonly maxWords: number; readonly maxSlideWords: number };
+  /** A viewer may click a piece to go to the click about it, and come back (false). */
+  readonly explore: boolean;
   /** The keys deck.json wrote (a file it names must be there; a default may be absent). */
   readonly given: readonly string[];
 }
@@ -37,10 +39,14 @@ export function readConfig(json: string | object): DeckConfig;
 
 /** One click on a map, as written: its attributes (focus-html · readStep reads them), headline (HTML) and notes. */
 export interface DeckStepSource { readonly attrs: string; readonly headline: string; readonly notes: readonly string[] }
+/** How a part arrives, as written: data-enter and its data-enter-* settings, as text (compile reads them against the shared table). */
+export interface DeckEnterSource { readonly type: string; readonly given: Readonly<Record<string, string>> }
+/** How a part differs from the real thing, checked (data-differs-*): the time factor, what is out of scale, the labels' words (none: the notes alone), the phrases of its notes that say it. */
+export interface DeckDiffers { readonly time?: number; readonly scale?: string; readonly shown: readonly string[]; readonly said?: readonly string[] }
 /** A part of the deck: a plain slide (map null) or clicks told on a map. */
-export type DeckPart =
+export type DeckPart = { readonly theme: string | null; readonly enter: DeckEnterSource | null; readonly differs: DeckDiffers | null } & (
   | { readonly label: string; readonly kicker: string; readonly map: null; readonly body: string; readonly notes: readonly string[] }
-  | { readonly label: string; readonly kicker: string; readonly map: string; readonly steps: readonly DeckStepSource[] };
+  | { readonly label: string; readonly kicker: string; readonly map: string; readonly steps: readonly DeckStepSource[] });
 /**
  * The clicks file read into parts, scanned once. A step holds only its <h2> and notes (anything else is refused, naming
  * where it goes); a <section> or <step> left open, or opened inside another, is refused.
@@ -80,6 +86,10 @@ export type DeckClick = {
   readonly notes: readonly string[];
   /** What loops on the click (on a map: on the pieces it shows). */
   readonly loops: readonly DeckLoop[];
+  /** How the click's part differs from the real thing, when it declares it. */
+  readonly differs?: DeckDiffers;
+  /** How the click's part arrives, on its first click (null elsewhere, or when it just appears): footprint-story/motion's change, read. */
+  readonly enter: { readonly type: string; readonly seconds: number; readonly ease: string; readonly p: Readonly<Record<string, unknown>> } | null;
 } & (
   | { readonly kind: 'plain'; readonly map: null; readonly text: string }
   | { readonly kind: 'map'; readonly map: string; readonly step: FocusClick; readonly look: FocusLook; readonly stepIndex: number; readonly steps: number }
@@ -98,6 +108,10 @@ export interface CompiledDeck {
   readonly clicks: readonly DeckClick[];
   /** The named loops the clicks show (data-loop values), drawn into the page's CSS once each. */
   readonly loops: readonly string[];
+  /** With deck.json "explore": the map each click is on (null on a plain slide), and where each piece leads on its map — the first click whose data-on names it, else the first that takes it in through a name+ (0-based). */
+  readonly explore: { readonly slides: readonly (string | null)[]; readonly targets: Readonly<Record<string, Readonly<Record<string, number>>>> } | null;
+  /** The parts' entrances as the page plays them: each distinct change sampled once (kinds), and its key per slide — or null when no part has one. */
+  readonly transitions: { readonly kinds: Readonly<Record<string, unknown>>; readonly enter: readonly (string | null)[] } | null;
   readonly maps: Readonly<Record<string, { readonly pieces: readonly FocusPiece[] }>>;
 }
 /** The deck's clicks planned (each map's state carried click to click) and drawn as <deck-stage> slides. */

package/dist/deck/check.js

@@ -1,6 +1,7 @@
 import { wordCount } from "./parse.js";
 import { expandNames } from "../focus.js";
 import { LOOP_NAMES } from "./loops.js";
+import { saidInNotes } from "./differs.js";
 const names = (pieces, idx) => [...new Set(idx.map((i) => pieces[i].keys[0]))];
 const problem = (level, rule, click, message) => ({ level, rule, click: click?.n ?? null, label: click?.label ?? null, message });
 function words(c, { maxWords, maxSlideWords }) {
@@ -62,6 +63,17 @@ function unsetLoops(compiled) {
   const list = [...new Set(bare.map((b) => b.piece))], one = list.length === 1;
   return [problem("warn", "loop-unset", bare[0].c, `${list.join(", ")} ha${one ? "s" : "ve"} data-loop but nothing sets ${one ? "its" : "their"} --loop, so nothing loops \u2014 give ${one ? "it" : "them"} one in theme.css (.gear { --loop: spin 4s linear infinite }), or name a loop: data-loop="${LOOP_NAMES[0]}" (${LOOP_NAMES.join(", ")})`)];
 }
+function unsaidDiffers(compiled) {
+  const out = [], seen = /* @__PURE__ */ new Set();
+  for (const c of compiled.clicks) {
+    if (!c.differs?.said || seen.has(c.part)) continue;
+    seen.add(c.part);
+    const notes = compiled.clicks.filter((x) => x.part === c.part).flatMap((x) => x.notes).join(" ");
+    const missing = c.differs.said.filter((phrase) => !saidInNotes(phrase, notes));
+    if (missing.length) out.push(problem("error", "differs-unsaid", c, `part "${c.part}" says its notes tell how it differs from the real thing (${missing.map((p) => `"${p}"`).join(", ")}), and they do not hold those words \u2014 say it in the notes, or fix data-differs-said`));
+  }
+  return out;
+}
 function checkDeck(compiled) {
   const out = [];
   compiled.clicks.forEach((c, i) => {
@@ -69,7 +81,7 @@ function checkDeck(compiled) {
     if (c.kind === "map") out.push(...litOnEntry(c, compiled.maps[c.map].pieces));
     out.push(...noChange(c, compiled.clicks[i - 1]));
   });
-  out.push(...neverShown(compiled), ...missingNotes(compiled), ...unstyledThemes(compiled), ...unsetLoops(compiled));
+  out.push(...neverShown(compiled), ...missingNotes(compiled), ...unstyledThemes(compiled), ...unsetLoops(compiled), ...unsaidDiffers(compiled));
   return out;
 }
 const failure = (error) => [problem("error", "compile", null, error.message)];

package/dist/deck/compile.js

@@ -2,9 +2,12 @@ import { focusStep } from "../focus.js";
 import { readPieces, readStep, drawFocus, wrapStage, slideClass, focusOverlay } from "../focusHtml.js";
 import { applyTransforms, icons as drawIcons } from "./transforms.js";
 import { loopsIn } from "./loops.js";
+import { exploreTargets } from "./explore.js";
+import { readEnter, transitionTable } from "./transitions.js";
 import { plainText } from "./parse.js";
 import { esc, stripComments } from "./html.js";
 import { readAttributes, tagsWith } from "../pieceRules.js";
+import { differsHtml, refuseEnglishWords } from "./differs.js";
 function numberForDev(html) {
   let out = "", from = 0;
   for (const { start, tag, before, m } of tagsWith(html, /\sdata-sd-i="(\d+)"/)) {
@@ -41,6 +44,7 @@ function planClicks(parts, maps, { area, canvas, icons }) {
   let lastMap = null;
   const clicks = [];
   for (const part of parts) {
+    const enter = readEnter(part.enter, `"${part.label}"`, { frame: canvas });
     if (!part.map) {
       refuseOwnNumbers(`"${part.label}"`, part.body);
       let inner;
@@ -49,7 +53,7 @@ function planClicks(parts, maps, { area, canvas, icons }) {
       } catch (e) {
         throw new Error(`"${part.label}": ${e.message}`, { cause: e });
       }
-      clicks.push({ label: part.label, part, kind: "plain", inner, loops: loopsIn(drawIcons(part.body, icons), `"${part.label}"`), notes: part.notes, headline: "", step: 0, steps: 1 });
+      clicks.push({ label: part.label, part, kind: "plain", inner, enter, loops: loopsIn(drawIcons(part.body, icons), `"${part.label}"`), notes: part.notes, headline: "", step: 0, steps: 1 });
       lastMap = null;
       continue;
     }
@@ -64,7 +68,7 @@ function planClicks(parts, maps, { area, canvas, icons }) {
       }
       map.state = r.state;
       lastMap = map;
-      clicks.push({ label: `${part.label} \xB7 ${k + 1}`, part, kind: "map", map, step, look: r.look, loops: shownLoops(map, r.look), headline: s.headline, notes: s.notes, stepIndex: k, steps: part.steps.length });
+      clicks.push({ label: `${part.label} \xB7 ${k + 1}`, part, kind: "map", map, step, look: r.look, enter: k === 0 ? enter : null, loops: shownLoops(map, r.look), headline: s.headline, notes: s.notes, stepIndex: k, steps: part.steps.length });
     });
   }
   const seen = /* @__PURE__ */ new Set();
@@ -78,8 +82,8 @@ const head = (kicker, headline) => `<div class="head" data-chrome><div class="ki
 const foot = (footer, n, total) => `<div class="foot" data-chrome><span>${esc(footer)}</span><span class="count">${n} / ${total}</span></div>`;
 function drawClick(c, i, total, { footer, area, canvas }) {
   const open = `<section data-label="${esc(c.label)}"${c.part.theme ? ` data-theme="${esc(c.part.theme)}"` : ""}`;
-  if (c.kind === "plain") return `${open} class="slide plain">${head(c.part.kicker, "")}${c.inner}${foot(footer, i + 1, total)}</section>`;
-  return `${open} class="slide on-map ${slideClass(c.look)}">${head(c.part.kicker, c.headline)}<div class="map map-${c.map.name}">${wrapStage(drawFocus(c.map.html, c.look), c.look)}</div>${focusOverlay(c.look, { area, canvas: { w: canvas[0], h: canvas[1] } })}${foot(footer, i + 1, total)}</section>`;
+  if (c.kind === "plain") return `${open} class="slide plain">${head(c.part.kicker, "")}${differsHtml(c.part.differs)}${c.inner}${foot(footer, i + 1, total)}</section>`;
+  return `${open} class="slide on-map ${slideClass(c.look)}">${head(c.part.kicker, c.headline)}${differsHtml(c.part.differs)}<div class="map map-${c.map.name}">${wrapStage(drawFocus(c.map.html, c.look), c.look)}</div>${focusOverlay(c.look, { area, canvas: { w: canvas[0], h: canvas[1] } })}${foot(footer, i + 1, total)}</section>`;
 }
 function checkPost(post, labels) {
   if (!post) return;
@@ -94,6 +98,7 @@ function compileDeck(source, { dev = false } = {}) {
   const { config, parts, icons = {} } = source;
   const maps = Object.fromEntries(Object.entries(source.maps ?? {}).map(([name, html]) => [name, prepareMap(name, html, icons, dev)]));
   for (const part of parts) if (part.map && !maps[part.map]) throw new Error(`"${part.label}" is told on map "${part.map}", which the deck does not have`);
+  for (const part of parts) refuseEnglishWords(part.differs, config.lang, `"${part.label}"`);
   const opts = { area: [...config.area], canvas: config.canvas, icons, footer: config.footer };
   const planned = planClicks(parts, maps, opts);
   const total = planned.length;
@@ -113,15 +118,27 @@ function compileDeck(source, { dev = false } = {}) {
     part: c.part.label,
     kicker: c.part.kicker,
     theme: c.part.theme ?? null,
+    ...c.part.differs ? { differs: c.part.differs } : {},
     kind: c.kind,
     map: c.kind === "map" ? c.map.name : null,
     headline: plainText(c.headline),
     notes: c.notes,
     loops: c.loops,
+    enter: c.enter,
     ...c.kind === "map" ? { step: c.step, look: c.look, stepIndex: c.stepIndex, steps: c.steps } : { text: plainText(c.inner) }
   }));
   const loops = [...new Set(planned.flatMap((c) => c.loops.map((l) => l.value)))].filter(Boolean).sort();
-  return { config, title: config.title, themeCss: source.themeCss ?? "", slides, clicks, loops, maps: Object.fromEntries(Object.values(maps).map((m) => [m.name, { pieces: m.pieces }])) };
+  return {
+    config,
+    title: config.title,
+    themeCss: source.themeCss ?? "",
+    slides,
+    clicks,
+    loops,
+    explore: config.explore ? exploreTargets(planned) : null,
+    transitions: transitionTable(planned.map((c) => c.enter), config.canvas),
+    maps: Object.fromEntries(Object.values(maps).map((m) => [m.name, { pieces: m.pieces }]))
+  };
 }
 export {
   compileDeck

package/dist/deck/config.js

@@ -9,7 +9,7 @@ const DEFAULTS = Object.freeze({
   out: "index.html",
   checks: Object.freeze({ maxWords: 12, maxSlideWords: 40 })
 });
-const KEYS = ["title", "description", "lang", "footer", "area", "canvas", "clicks", "theme", "icons", "maps", "out", "post", "deckData", "checks"];
+const KEYS = ["title", "description", "lang", "footer", "area", "canvas", "clicks", "theme", "icons", "maps", "out", "post", "deckData", "checks", "explore"];
 const CHECK_KEYS = ["maxWords", "maxSlideWords"];
 const isText = (v) => typeof v === "string" && v.trim().length > 0;
 const numbers = (v, n) => Array.isArray(v) && v.length === n && v.every((x) => typeof x === "number" && Number.isFinite(x));
@@ -43,6 +43,7 @@ function readConfig(json) {
     return v;
   };
   const maxWords = count("maxWords"), maxSlideWords = count("maxSlideWords");
+  if (raw.explore !== void 0 && typeof raw.explore !== "boolean") throw new Error(`deck.json "explore" is true or false, not ${JSON.stringify(raw.explore)}`);
   return Object.freeze({
     title: raw.title.trim(),
     description: raw.description ?? "",
@@ -58,6 +59,7 @@ function readConfig(json) {
     post: raw.post === void 0 ? null : deckPath(raw.post, "post"),
     deckData: raw.deckData === void 0 ? null : deckPath(raw.deckData, "deckData"),
     checks: Object.freeze({ maxWords, maxSlideWords }),
+    explore: raw.explore === true,
     given: Object.freeze(Object.keys(raw))
     // the keys deck.json wrote: a file it names must be there; a default may be absent
   });

package/dist/deck/differs.js

@@ -0,0 +1,104 @@
+import { normSpeech } from "footprint-story";
+import { readAttributes } from "../pieceRules.js";
+import { decodeEntities, esc } from "./html.js";
+const DIFFERS_MOST = 70;
+const DIFFERS_SAID_MOST = 120;
+const DIFFERS_TIME_MOST = 1e9;
+const NAMES = ["data-differs-time", "data-differs-scale", "data-differs-shown", "data-differs-said"];
+const plain = (x) => String(+x.toFixed(x >= 10 ? 0 : 2));
+const timeWords = (time) => time > 1 ? `Time shown ${plain(time)} times faster` : `Time shown ${plain(1 / time)} times slower`;
+const factorsOf = (time) => time > 1 ? [time, +plain(time)] : [time, 1 / time, +plain(1 / time)];
+const folded = (value) => decodeEntities(value).replace(/[\s\p{Cc}]+/gu, " ").trim();
+function words(value, name, where) {
+  const text = folded(value);
+  if (!text) throw new Error(`${where}: ${name} is empty \u2014 say it in words, or leave it out`);
+  if (text.length > DIFFERS_MOST) throw new Error(`${where}: ${name} is ${text.length} characters, more than a label can hold in a glance (${DIFFERS_MOST}) \u2014 shorten it, and say the rest in the notes`);
+  return text;
+}
+function readTime(value, where) {
+  const factor = Number(folded(value)), what = `${where}: data-differs-time=${JSON.stringify(value)} \u2014 it is how many times faster the picture runs than the real thing (30; 0.04 is 25 times slower)`;
+  if (!(folded(value) && Number.isFinite(factor) && factor > 0)) throw new Error(what);
+  if (plain(factor > 1 ? factor : 1 / factor) === "1") throw new Error(`${what}: it reads as 1 time, and 1 is real time, so leave it out (a factor that shows is 1.01 or more, or 0.99 or less)`);
+  if (factor > DIFFERS_TIME_MOST || factor < 1 / DIFFERS_TIME_MOST) throw new Error(`${what}: past ${DIFFERS_TIME_MOST} times either way no viewer reads the number, so say it in words in data-differs-scale`);
+  return factor;
+}
+function readSaid(value, where) {
+  if (value === null) return null;
+  const phrases = value.split("|").map((one) => {
+    const text = folded(one);
+    if (!normSpeech(text)) throw new Error(`${where}: data-differs-said is empty \u2014 name the phrase of the part's notes that says how it differs, one per statement ("A | B")`);
+    if (text.length > DIFFERS_SAID_MOST) throw new Error(`${where}: data-differs-said is ${text.length} characters, more than a phrase (${DIFFERS_SAID_MOST}) \u2014 name the few words that say it`);
+    return text;
+  });
+  if (new Set(phrases.map(normSpeech)).size < phrases.length) throw new Error(`${where}: data-differs-said names the same phrase twice \u2014 one per statement`);
+  return phrases;
+}
+const figures = (line) => line.match(/(?<![\p{L}\p{N}])\d+(?:[.,]\d+)*/gu) ?? [];
+const readings = (run) => [run.replace(/,/g, ""), run.replace(/\./g, ""), run.replace(/\./g, "").replace(",", ".")].map(Number);
+function contradicting({ time, scale }, lines) {
+  if (time === void 0) return null;
+  const says = scale === void 0 ? lines : lines.length >= 2 ? [lines[0]] : [];
+  return says.flatMap(figures).find((run) => !readings(run).some((v) => factorsOf(time).includes(v))) ?? null;
+}
+const DIFFERS_NAME = /^data-differs(-|$)/;
+const cutShort = (attrs, rest) => readAttributes(attrs) === null && /(^|\s)data-differs/i.test(attrs + rest.slice(0, Math.max(0, rest.indexOf(">"))));
+function readDiffers(attrs, where, rest = "") {
+  if (cutShort(attrs, rest)) throw new Error(`${where}: a ">" inside an attribute's value ends the tag, so its data-differs-* cannot be read \u2014 write &gt; for it`);
+  const given = (readAttributes(attrs) ?? []).filter((a) => DIFFERS_NAME.test(a.name));
+  if (!given.length) return null;
+  const other = given.find((a) => !NAMES.includes(a.name));
+  if (other) throw new Error(`${where}: ${other.name} is not a way to say how a part differs \u2014 the attributes are ${NAMES.join(", ")}`);
+  const of = (name) => given.find((a) => a.name === name)?.value ?? null;
+  const time = of("data-differs-time"), scale = of("data-differs-scale"), shown = of("data-differs-shown");
+  const factor = time === null ? void 0 : readTime(time, where);
+  if (time === null && scale === null) throw new Error(`${where}: say how the part differs: data-differs-time (how many times faster it runs), data-differs-scale (what is out of scale, in words), or both`);
+  const out = { ...factor === void 0 ? {} : { time: factor }, ...scale === null ? {} : { scale: words(scale, "data-differs-scale", where) } };
+  const lines = shown?.trim().toLowerCase() === "false" ? [] : shown === null ? [...factor === void 0 ? [] : [timeWords(factor)], ...out.scale ? [out.scale] : []] : shown.split("|").map((line) => words(line, "data-differs-shown", where));
+  const phrases = readSaid(of("data-differs-said"), where);
+  if (!lines.length && !phrases) throw new Error(`${where}: data-differs-shown="false", so the notes must say it \u2014 name their phrase in data-differs-said`);
+  const statements = (factor === void 0 ? 0 : 1) + (out.scale === void 0 ? 0 : 1), says = new Set(lines).size + (phrases?.length ?? 0);
+  if (says < statements) throw new Error(`${where}: it declares both time and scale and says only ${says} thing \u2014 give each its own line in data-differs-shown ("A | B") or its own phrase in data-differs-said ("A | B"), so neither goes unstated`);
+  const wrong = contradicting(out, lines);
+  if (wrong !== null) throw new Error(`${where}: data-differs-shown says ${wrong} where data-differs-time says ${factor} \u2014 leave shown out for the default words, or write the number declared (and with scale too, the time's line first)`);
+  return { ...out, shown: lines, ...phrases ? { said: phrases } : {} };
+}
+function refuseStepDiffers(attrs, where) {
+  const named = (readAttributes(attrs) ?? []).some((a) => DIFFERS_NAME.test(a.name)) || readAttributes(attrs) === null && /(^|\s)data-differs/i.test(attrs);
+  if (named) throw new Error(`${where}: a <step> cannot say how it differs \u2014 put data-differs-* on its <section>: a part says it on each of its slides`);
+}
+function refuseEnglishWords(differs, lang, where) {
+  if (differs?.time !== void 0 && lang && !/^en\b/i.test(lang) && differs.shown.includes(timeWords(differs.time))) {
+    throw new Error(`${where}: "${timeWords(differs.time)}" is English and the deck is in "${lang}" \u2014 give the words in its language (data-differs-shown), or "false" for the notes alone`);
+  }
+}
+const differsHtml = (d) => d?.shown.length ? `<div class="differs" data-chrome>${d.shown.map((line) => `<span>${esc(line)}</span>`).join("")}</div>` : "";
+const DIFFERS_CSS = `/* a part that differs from the real thing says so (deck/differs.js): labels on the kicker's row, right-aligned */
+:where(.differs) { position: absolute; right: 50px; top: 44px; z-index: 4; display: flex; gap: 10px; justify-content: flex-end; max-width: 75%; flex-wrap: wrap; }
+:where(.differs span) { padding: 8px 16px; border-radius: 20px; background: var(--fg, #14181f); color: var(--bg, #ffffff); font: 700 20px/1.2 var(--sans, system-ui, sans-serif); }`;
+function saidInNotes(phrase, notes) {
+  const needle = normSpeech(phrase);
+  if (!needle) return false;
+  const starts = /* @__PURE__ */ new Set(), ends = /* @__PURE__ */ new Set();
+  let content = "";
+  for (const word of notes.split(/\s+/)) {
+    const w = normSpeech(word);
+    if (!w) continue;
+    starts.add(content.length);
+    content += w;
+    ends.add(content.length);
+  }
+  for (let at = content.indexOf(needle); at >= 0; at = content.indexOf(needle, at + 1)) if (starts.has(at) && ends.has(at + needle.length)) return true;
+  return false;
+}
+export {
+  DIFFERS_CSS,
+  DIFFERS_MOST,
+  DIFFERS_SAID_MOST,
+  DIFFERS_TIME_MOST,
+  differsHtml,
+  readDiffers,
+  refuseEnglishWords,
+  refuseStepDiffers,
+  saidInNotes,
+  timeWords
+};

package/dist/deck/explore.js

@@ -0,0 +1,88 @@
+import { expandNames } from "../focus.js";
+function exploreTargets(planned) {
+  const targets = {}, through = {}, table = () => /* @__PURE__ */ Object.create(null);
+  planned.forEach((c, i) => {
+    if (c.kind !== "map" || !c.step.on) return;
+    const own = targets[c.map.name] ??= table(), near = through[c.map.name] ??= table();
+    for (const name of c.step.on.map((x) => expandNames(c.map.pieces, [x])[0])) if (name !== "*" && !Object.hasOwn(own, name)) own[name] = i;
+    for (const name of expandNames(c.map.pieces, c.step.on)) if (name !== "*" && !Object.hasOwn(near, name)) near[name] = i;
+  });
+  for (const [map, near] of Object.entries(through)) for (const [name, i] of Object.entries(near)) if (!Object.hasOwn(targets[map], name)) targets[map][name] = i;
+  return { slides: planned.map((c) => c.kind === "map" ? c.map.name : null), targets };
+}
+const exploreData = (explore) => `<script type="application/json" id="deck-explore">${JSON.stringify(explore).replace(/</g, "\\u003c")}<\/script>`;
+const EXPLORE_CSS = `:where(deck-stage[data-explore] .sd-leads) { cursor: pointer; }
+:where(deck-stage[data-explore] .sd-leads:hover) { outline: 3px solid var(--sd-accent, var(--accent-ink, #0b6e99)); outline-offset: 6px; }
+:where(.explore-back) {
+  position: fixed; left: 12px; top: 12px; z-index: 10; padding: 8px 14px; border-radius: 20px; cursor: pointer;
+  border: 1.5px solid var(--line, #c9d0d9); background: var(--bg-elev, #f6f8fa); color: var(--fg, #14181f);
+  font: 600 14px/1 var(--sans, system-ui, sans-serif);
+}
+@media print { :where(.explore-back) { display: none; } }`;
+function exploreRuntime() {
+  const stage = document.querySelector("deck-stage[data-explore]"), data = document.getElementById("deck-explore");
+  if (!stage || !data || window.name === "deck-presenter" || /[?&]_snthumb=/.test(location.search)) return;
+  const { slides, targets } = JSON.parse(data.textContent), back = [];
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "explore-back";
+  button.hidden = true;
+  document.body.appendChild(button);
+  const shown = () => [...stage.children].filter((s) => s.tagName === "SECTION")[stage.index];
+  const unseen = ".sd-gone, .sd-hide, .sd-twin-off";
+  const controls = 'a[href], button, input, select, textarea, summary, label, video[controls], audio[controls], [role="button"], [onclick], [contenteditable]:not([contenteditable="false" i])';
+  const leads = (piece) => {
+    if (piece.closest(unseen)) return null;
+    const own = targets[slides[stage.index]] ?? {};
+    const to = piece.getAttribute("data-k").trim().split(/\s+/).map((k) => Object.hasOwn(own, k) ? own[k] : void 0).find((i) => i !== void 0);
+    return to === void 0 || to === stage.index ? null : to;
+  };
+  const mark = () => {
+    document.querySelectorAll(".sd-leads").forEach((p) => p.classList.remove("sd-leads"));
+    for (const p of shown().querySelectorAll("[data-k]")) if (leads(p) !== null) p.classList.add("sd-leads");
+    button.hidden = !back.length;
+    if (back.length) button.textContent = `\u2190 Back to click ${back.at(-1) + 1}`;
+  };
+  const go = (i) => {
+    stage.goTo(i);
+    mark();
+  };
+  const goBack = () => {
+    if (back.length) go(back.pop());
+  };
+  let down = null;
+  document.addEventListener("pointerdown", (e) => {
+    down = [e.clientX, e.clientY];
+  }, true);
+  document.addEventListener("click", (e) => {
+    const dragged = down && Math.hypot(e.clientX - down[0], e.clientY - down[1]) > 4;
+    down = null;
+    if (e.altKey || e.button !== 0 || dragged || !stage.isConnected) return;
+    const piece = e.target.closest?.("[data-k]");
+    if (!piece || !shown().contains(piece) || e.target.closest(controls)) return;
+    const to = leads(piece);
+    if (to === null) return;
+    e.preventDefault();
+    back.push(stage.index);
+    go(to);
+  }, true);
+  button.addEventListener("click", (e) => {
+    e.stopPropagation();
+    button.blur();
+    goBack();
+  });
+  window.addEventListener("keydown", (e) => {
+    if (e.key !== "Backspace" || !back.length || !stage.isConnected || e.defaultPrevented || e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
+    if (/^(INPUT|TEXTAREA|SELECT)$/.test(e.target?.tagName) || e.target?.isContentEditable) return;
+    e.preventDefault();
+    goBack();
+  });
+  stage.addEventListener("slidechange", mark);
+  mark();
+}
+export {
+  EXPLORE_CSS,
+  exploreData,
+  exploreRuntime,
+  exploreTargets
+};

package/dist/deck/html.js

@@ -30,6 +30,11 @@ const UNSEEN = new RegExp([
   String.raw`(?![\u{200C}\u{200D}\u{FE0E}\u{FE0F}])\p{Default_Ignorable_Code_Point}`,
   String.raw`[^\p{L}\p{M}\p{N}\p{P}\p{S}\p{Zs}\n\t\u{200C}\u{200D}\u{FE0E}\u{FE0F}]`
 ].join("|"), "gu");
+const ENTITY = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+const decodeEntities = (text) => String(text).replace(/&(#\d{1,7}|#x[\da-f]{1,6}|\w{1,32});/gi, (m, e) => e[0] === "#" ? (() => {
+  const cp = e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : Number(e.slice(1));
+  return cp <= 1114111 ? String.fromCodePoint(cp) : m;
+})() : ENTITY[e.toLowerCase()] ?? m);
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
 const scriptSafe = (code) => String(code).replace(/<\/(script)/gi, "<\\/$1");
 const styleSafe = (css) => String(css).replace(/<\/(style)/gi, "<\\/$1");
@@ -57,6 +62,7 @@ export {
   UNSEEN,
   closing,
   commentRanges,
+  decodeEntities,
   elements,
   esc,
   scriptSafe,

package/dist/deck/init.js

@@ -29,6 +29,7 @@ const CLICKS = `<!--
   The deck, click by click.
   <section data-label="\u2026" data-kicker="\u2026">          one part of the story; without data-map it is one plain slide
   <section \u2026 data-theme="ledger">                   optional: its slides carry data-theme, so theme.css can dress that part
+  <section \u2026 data-enter="push" data-enter-from="right">   optional: how the part arrives (cut fade dip wipe split iris push slide whip zoom)
   <section \u2026 data-map="map">                        a part told on map.html: every <step> inside is ONE click
     <step data-in="\u2026" data-out="\u2026" data-on="\u2026" data-focus="\u2026">
       data-in    pieces that come in (they stay)     data-out   pieces that leave

package/dist/deck/layout.js

@@ -28,6 +28,7 @@ function clickRuns(ns) {
 const KINDS = {
   spills: (f, where, also) => ["warn", `text spills out of ${where} by ${size(f)} ("${f.text}")${also} \u2014 shorten it, or give the box more room`],
   outside: (f, where, also) => ["warn", `${where} reaches ${size(f)} past the slide's edge ("${f.text}")${also} \u2014 move it in, or zoom less`],
+  "differs-overlap": (f, where, also) => ["warn", `the label on how this part differs meets ${where} ("${f.text}")${also}, and one hides the other \u2014 shorten the label, or move ${where} clear of the top right`],
   "loose-loop": (f, where, also) => ["warn", `${where} has an endless animation that is not a loop${also}: it starts again at each click and stops on a jump \u2014 give the element data-loop and its animation as --loop (or name a loop: data-loop="pulse")`],
   "hidden-loop": (f, where, also) => ["error", `${f.count} endless animation${f.count === 1 ? "" : "s"} on ${f.piece} keep${f.count === 1 ? "s" : ""} running while the slide is hidden${also} \u2014 make ${f.count === 1 ? "it a loop" : "each a loop"} (data-loop and its animation as --loop): a loop runs only on the slide shown`]
 };

package/dist/deck/page.js

@@ -2,6 +2,9 @@ import { focusRuntime } from "../focusHtml.js";
 import { notesData, notesRuntime, listenRuntime } from "../narrationHtml.js";
 import { esc, scriptSafe, styleSafe } from "./html.js";
 import { loopCss } from "./loops.js";
+import { DIFFERS_CSS } from "./differs.js";
+import { EXPLORE_CSS, exploreData, exploreRuntime } from "./explore.js";
+import { TRANSITION_CSS, transitionData, transitionRuntime } from "./transitions.js";
 function themeRuntime() {
   const root = document.documentElement, btn = document.querySelector(".theme-toggle");
   const set = (dark) => {
@@ -34,9 +37,10 @@ const TOGGLE = '<button class="theme-toggle" type="button" aria-label="Switch th
 function deckPage(compiled, assets, { dev = null } = {}) {
   const { config, slides } = compiled;
   const loops = loopCss(compiled.loops ?? []);
-  const css = [...assets.css, ...loops ? [loops] : [], compiled.themeCss ?? ""].join("\n");
+  const labelled = (compiled.clicks ?? []).some((c) => c.differs?.shown.length);
+  const css = [...assets.css, ...loops ? [loops] : [], ...compiled.explore ? [EXPLORE_CSS] : [], ...compiled.transitions ? [TRANSITION_CSS] : [], ...labelled ? [DIFFERS_CSS] : [], compiled.themeCss ?? ""].join("\n");
   const script = dev?.nonce ? `<script nonce="${esc(dev.nonce)}">` : "<script>";
-  const runtimes = [focusRuntime, notesRuntime, listenRuntime, themeRuntime].map((fn) => `${script}(${scriptSafe(fn)})();<\/script>`);
+  const runtimes = [focusRuntime, notesRuntime, listenRuntime, themeRuntime, ...compiled.explore ? [exploreRuntime] : [], ...compiled.transitions ? [transitionRuntime] : []].map((fn) => `${script}(${scriptSafe(fn)})();<\/script>`);
   return `<!doctype html>
 <html lang="${esc(config.lang)}">
 <head>
@@ -51,12 +55,14 @@ ${config.description ? `<meta name="description" content="${esc(config.descripti
 <style>${styleSafe(css)}</style>
 </head>
 <body>
-<deck-stage width="${config.canvas[0]}" height="${config.canvas[1]}" no-rail>
+<deck-stage width="${config.canvas[0]}" height="${config.canvas[1]}" no-rail${compiled.explore ? " data-explore" : ""}>
 ${slides.map((s) => s.html).join("\n")}
 </deck-stage>
 ${TOGGLE}
 <!-- deck-stage.js, focus and narration runtimes: footprint-storydeck ${esc(assets.version)} (MIT) -->
-${notesData(slides.map((s) => s.notes))}
+${notesData(slides.map((s) => s.notes))}${compiled.explore ? `
+${exploreData(compiled.explore)}` : ""}${compiled.transitions ? `
+${transitionData(compiled.transitions)}` : ""}
 ${script}${scriptSafe(assets.stageJs)}<\/script>
 ${runtimes.join("\n")}
 ${dev ? `${script}(${scriptSafe(dev.client)})();<\/script>

package/dist/deck/parse.js

@@ -1,4 +1,6 @@
-import { closing, elements, stripComments } from "./html.js";
+import { closing, decodeEntities, elements, stripComments } from "./html.js";
+import { readAttributes } from "../pieceRules.js";
+import { readDiffers, refuseStepDiffers } from "./differs.js";
 const NOTES_CLASS = /\sclass=(["'])(?:[^"']*\s)?notes(?:\s[^"']*)?\1/;
 const BLOCK = /* @__PURE__ */ new Set([
   "br",
@@ -24,7 +26,6 @@ const BLOCK = /* @__PURE__ */ new Set([
   "figure",
   "figcaption"
 ]);
-const ENTITY = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
 function attrOf(attrs, name) {
   return new RegExp(`\\s${name}=(["'])(.*?)\\1`).exec(attrs)?.[2] ?? null;
 }
@@ -61,10 +62,7 @@ function plainText(html) {
     }
     if (BLOCK.has(name)) out += " ";
   }
-  return out.replace(/&(#\d{1,7}|#x[\da-f]{1,6}|\w{1,32});/gi, (m, e) => e[0] === "#" ? (() => {
-    const cp = e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : Number(e.slice(1));
-    return cp <= 1114111 ? String.fromCodePoint(cp) : m;
-  })() : ENTITY[e.toLowerCase()] ?? m).replace(/\s+/g, " ").trim();
+  return decodeEntities(out).replace(/\s+/g, " ").trim();
 }
 const wordCount = (html) => (plainText(html).match(/[\p{L}\p{N}][\p{L}\p{N}'’.,%-]*/gu) ?? []).length;
 function takeNotes(html) {
@@ -92,6 +90,7 @@ function themeOf(label, attrs) {
   return theme;
 }
 function readMapStep(label, k, attrs, inner) {
+  refuseStepDiffers(attrs, `${where(label)} click ${k + 1}`);
   const { html, notes } = takeNotes(inner);
   let heads;
   try {
@@ -106,6 +105,13 @@ function readMapStep(label, k, attrs, inner) {
   }
   return { attrs, headline, notes };
 }
+function enterOf(attrs) {
+  const read = readAttributes(attrs) ?? [], type = read.find((a) => a.name === "data-enter");
+  if (!type) return null;
+  const given = {};
+  for (const a of read) if (a.name.startsWith("data-enter-") && a.name.length > 11) given[a.name.slice(11)] ??= a.value;
+  return { type: type.value.trim(), given };
+}
 function parseClicks(html) {
   const source = stripComments(html);
   const parts = [];
@@ -121,10 +127,11 @@ function parseClicks(html) {
     const kicker = attrOf(attrs, "data-kicker") ?? "";
     const map = attrOf(attrs, "data-map");
     const theme = themeOf(label, attrs);
+    const enter = enterOf(attrs), differs = readDiffers(attrs, where(label), body);
     if (map === null) {
       if (/<step\b/i.test(body)) throw new Error(`${where(label)} has <step> clicks but no data-map \u2014 name the map they are told on (data-map="map")`);
       const { html: inner, notes } = takeNotes(body);
-      parts.push({ label, kicker, theme, map: null, body: inner, notes });
+      parts.push({ label, kicker, theme, enter, differs, map: null, body: inner, notes });
       continue;
     }
     if (!map.trim()) throw new Error(`${where(label)}: data-map is empty \u2014 name a map (a file in the deck, e.g. data-map="map")`);
@@ -137,7 +144,7 @@ function parseClicks(html) {
     if (!steps.length) throw new Error(`${where(label)} is told on map "${map}" but has no <step> \u2014 a map part is one click per <step>`);
     const outside = plainText(takeNotes(without(body, steps)).html);
     if (outside) throw new Error(`${where(label)}: "${outside.slice(0, 60)}" is outside every <step> \u2014 put a headline or notes inside the step they belong to`);
-    parts.push({ label, kicker, theme, map: map.trim(), steps: steps.map(({ attrs: a, inner }, k) => readMapStep(label, k, a, inner)) });
+    parts.push({ label, kicker, theme, enter, differs, map: map.trim(), steps: steps.map(({ attrs: a, inner }, k) => readMapStep(label, k, a, inner)) });
   }
   if (!parts.length) throw new Error('the clicks file has no <section> \u2014 a deck is one <section data-label="\u2026"> per part');
   return parts;

package/dist/deck/review.js

@@ -1,9 +1,12 @@
 import { wordCount } from "./parse.js";
+import { enterText } from "./transitions.js";
 const nameOf = (pieces, i) => pieces[i].keys[0];
 const unique = (names) => [...new Set(names)];
 const list = (names, max = 14) => names.length ? `${names.slice(0, max).join(", ")}${names.length > max ? `, \u2026 (${names.length - max} more)` : ""}` : "\u2014";
 const themed = (c) => c.theme ? ` \xB7 theme ${c.theme}` : "";
 const quote = (s, max = 160) => s.length > max ? `"${s.slice(0, max - 1)}\u2026"` : `"${s}"`;
+const enterLine = (c) => c.enter ? `enters by ${enterText(c.enter)} (on a forward step)` : null;
+const differsLine = (c) => c.differs ? `differs: ${c.differs.shown.length ? `on the slide: ${c.differs.shown.join(" \xB7 ")}` : "not on the slide"}${c.differs.said ? `; in the notes: ${c.differs.said.map((p) => `"${p}"`).join(" \xB7 ")}` : ""}` : null;
 const loopsLine = (c) => c.loops?.length ? `loops (${c.loops.length}): ${list(c.loops.map((l) => `${l.piece ?? "an element"} ${l.value || "(its own --loop)"}`), 10)}` : null;
 function pieceGroups(click, pieces) {
   const by = (pred) => unique(click.look.pieces.map((p, i) => pred(p) ? nameOf(pieces, i) : null).filter(Boolean));
@@ -60,6 +63,8 @@ function reviewClick(compiled, which, { maxWords = compiled.config?.checks?.maxW
   if (c.kind === "plain") {
     lines.push(`click ${c.n} of ${compiled.clicks.length} \xB7 "${c.label}" (plain slide)${themed(c)}`);
     lines.push(`text (${words(wordCount(c.text))}): ${quote(c.text, 300)}`);
+    if (enterLine(c)) lines.push(enterLine(c));
+    if (differsLine(c)) lines.push(differsLine(c));
     if (loopsLine(c)) lines.push(loopsLine(c));
   } else {
     lines.push(`click ${c.n} of ${compiled.clicks.length} \xB7 "${c.label}" (map "${c.map}", step ${c.stepIndex + 1} of ${c.steps})${themed(c)}`);
@@ -84,6 +89,8 @@ function reviewClick(compiled, which, { maxWords = compiled.config?.checks?.maxW
     lines.push(`this click: ${changes.length ? changes.join(" \xB7 ") : "nothing changes on the map"}`);
     const motion = motionOf(c.look);
     if (motion.length) lines.push(`motion: ${motion.join(" \xB7 ")}`);
+    if (enterLine(c)) lines.push(enterLine(c));
+    if (differsLine(c)) lines.push(differsLine(c));
     if (loopsLine(c)) lines.push(loopsLine(c));
   }
   const noteWords = c.notes.reduce((sum, p) => sum + wordCount(p), 0);

package/dist/deck/transitions.js

@@ -0,0 +1,161 @@
+import { easeNamed, readTransition } from "footprint-story/motion";
+const CSS_TRANSITIONS = Object.freeze(["cut", "fade", "dip", "wipe", "split", "iris", "push", "slide", "whip", "zoom"]);
+const FPS = 30;
+const r4 = (v) => +(+v).toFixed(4) + 0;
+const pct = (v) => `${r4(v * 100)}%`;
+const UNIT = { left: [-1, 0], right: [1, 0], top: [0, -1], bottom: [0, 1] };
+const REST = { opacity: 1, transform: "translate(0%, 0%) scale(1)", filter: "blur(0px)" };
+const IRIS_UNIT = Math.SQRT1_2;
+function framesAt(type, p, e, [w, h]) {
+  const keep = { ...REST };
+  if (type === "fade") return [keep, { ...REST, opacity: r4(e) }];
+  if (type === "dip") return [{ ...REST, opacity: r4(Math.max(0, 1 - 2 * e)) }, { ...REST, opacity: r4(Math.max(0, 2 * e - 1)) }];
+  if (type === "wipe") {
+    const hidden = pct(1 - e), from = p.from;
+    const inset = from === "left" ? `inset(0% ${hidden} 0% 0%)` : from === "right" ? `inset(0% 0% 0% ${hidden})` : from === "top" ? `inset(0% 0% ${hidden} 0%)` : `inset(${hidden} 0% 0% 0%)`;
+    return [keep, { ...REST, clipPath: inset }];
+  }
+  if (type === "split") {
+    const half = pct((1 - e) / 2);
+    return [keep, { ...REST, clipPath: p.line === "horizontal" ? `inset(${half} 0% ${half} 0%)` : `inset(0% ${half} 0% ${half})` }];
+  }
+  if (type === "iris") {
+    const [x, y] = p.at, far = Math.max(...[[0, 0], [w, 0], [0, h], [w, h]].map(([cx, cy]) => Math.hypot(cx - x, cy - y)));
+    return [keep, { ...REST, clipPath: `circle(${pct(e * far / (Math.hypot(w, h) * IRIS_UNIT))} at ${pct(x / w)} ${pct(y / h)})` }];
+  }
+  if (type === "push" || type === "whip") {
+    const [dx, dy] = UNIT[p.from], blur = type === "whip" ? `blur(${r4(4 * e * (1 - e) * 0.02 * w)}px)` : "blur(0px)";
+    return [{ ...REST, transform: `translate(${pct(-dx * e)}, ${pct(-dy * e)}) scale(1)`, filter: blur }, { ...REST, transform: `translate(${pct(dx * (1 - e))}, ${pct(dy * (1 - e))}) scale(1)`, filter: blur }];
+  }
+  if (type === "slide") {
+    const [dx, dy] = UNIT[p.from];
+    return [keep, { ...REST, transform: `translate(${pct(dx * (1 - e))}, ${pct(dy * (1 - e))}) scale(1)` }];
+  }
+  const origin = `${pct(p.at[0] / w)} ${pct(p.at[1] / h)}`;
+  return [
+    { ...REST, opacity: r4(1 - e), transform: `translate(0%, 0%) scale(${r4(1 + 0.6 * e)})`, transformOrigin: origin },
+    { ...REST, transform: `translate(0%, 0%) scale(${r4(1 + 0.25 * (1 - e))})`, transformOrigin: origin }
+  ];
+}
+const ON_TOP = { fade: "arriving", dip: "arriving", wipe: "arriving", split: "arriving", iris: "arriving", push: "arriving", whip: "arriving", slide: "arriving", zoom: "leaving", cut: "arriving" };
+function transitionKeyframes(t, frame) {
+  if (t.type === "cut") return { type: "cut", seconds: 0, on: "arriving", backdrop: null, leaving: [], arriving: [], options: { duration: 0, easing: "linear", fill: "both" } };
+  const ease = easeNamed(t.ease, `${t.type}: ease`), steps = Math.max(2, Math.ceil(t.seconds * FPS)), leaving = [], arriving = [];
+  for (let i = 0; i <= steps; i++) {
+    const [a, b] = framesAt(t.type, t.p, ease(i / steps), frame), offset = r4(i / steps);
+    leaving.push({ offset, ...a });
+    arriving.push({ offset, ...b });
+  }
+  return {
+    type: t.type,
+    seconds: t.seconds,
+    on: ON_TOP[t.type],
+    backdrop: t.type === "dip" ? t.p.color : null,
+    leaving,
+    arriving,
+    options: { duration: r4(t.seconds * 1e3), easing: "linear", fill: "both" }
+  };
+}
+function readEnter(enter, where, { frame = [1920, 1080] } = {}) {
+  if (!enter) return null;
+  const who = `${where}: data-enter="${enter.type}"`;
+  if (!CSS_TRANSITIONS.includes(enter.type)) {
+    let known = true;
+    try {
+      readTransition(enter.type, who);
+    } catch {
+      known = false;
+    }
+    throw new Error(`${who} \u2014 ${known ? "a page cannot play it (it needs a canvas, as StoryReel draws it); " : ""}a part arrives by ${CSS_TRANSITIONS.join(", ")}`);
+  }
+  const params = readTransition(enter.type, who, { frame }).p, out = { type: enter.type };
+  for (const [name, text] of Object.entries(enter.given)) {
+    if (name !== "seconds" && name !== "ease" && !Object.hasOwn(params, name)) {
+      const takes = ["seconds", "ease", ...Object.keys(params)].map((k) => `data-enter-${k}`).join(", ");
+      throw new Error(`${who} takes ${takes} \u2014 not data-enter-${name}`);
+    }
+    const point = Array.isArray(params[name]), centre = point && text.trim() === "centre";
+    const value = name === "seconds" ? Number(text) : centre ? [frame[0] / 2, frame[1] / 2] : point ? text.trim().split(/[\s,]+/).map(Number) : text.trim();
+    if (name === "seconds" && !Number.isFinite(value)) throw new Error(`${who}: data-enter-seconds is a number of seconds, not "${text}"`);
+    if (point && !centre && (value.length !== 2 || value.some((n) => !Number.isFinite(n)))) throw new Error(`${who}: data-enter-${name} is a point, "x y" in slide px (or "centre"), not "${text}"`);
+    out[name] = value;
+  }
+  const t = readTransition(out, who, { frame });
+  return { type: t.type, seconds: t.seconds, ease: t.ease, p: t.p };
+}
+const enterText = (t) => `${t.type}${Object.entries(t.p).map(([k, v]) => ` ${k} ${Array.isArray(v) ? v.join(" ") : v}`).join("")}, ${t.type === "cut" ? "at once" : `${t.seconds} s`}`;
+function transitionTable(enters, frame) {
+  if (!enters.some(Boolean)) return null;
+  const kinds = {}, enter = enters.map((t) => {
+    if (!t) return null;
+    const key = JSON.stringify([t.type, t.seconds, t.ease, t.p]);
+    kinds[key] ??= transitionKeyframes(t, frame);
+    return key;
+  });
+  return { kinds, enter };
+}
+const transitionData = (table) => `<script type="application/json" id="deck-transitions">${JSON.stringify(table).replace(/</g, "\\u003c")}<\/script>`;
+const TRANSITION_CSS = "deck-stage > [data-sd-leaving] { visibility: visible; opacity: 1; }";
+function transitionRuntime() {
+  const stage = document.querySelector("deck-stage"), data = document.getElementById("deck-transitions");
+  if (!stage || !data) return;
+  const { kinds, enter } = JSON.parse(data.textContent);
+  let playing = null;
+  const settle = () => {
+    if (!playing) return;
+    const p = playing;
+    playing = null;
+    p.anims.forEach((a) => a.cancel());
+    p.leaving.removeAttribute("data-sd-leaving");
+    if (p.looped && !p.leaving.hasAttribute("data-deck-active") && !p.leaving.hasAttribute("data-deck-under")) p.leaving.removeAttribute("data-deck-loop");
+    p.leaving.style.zIndex = p.z[0];
+    p.arriving.style.zIndex = p.z[1];
+    if (p.bg !== null) stage.style.setProperty("--deck-canvas", p.bg);
+    stage.removeAttribute("data-deck-changing");
+  };
+  const calm = () => !!window.matchMedia?.("(prefers-reduced-motion: reduce)").matches || stage.getAttribute("data-motion") === "off";
+  window.addEventListener("beforeprint", settle);
+  stage.addEventListener("slidechange", (e) => {
+    const { index, previousIndex, slide, previousSlide } = e.detail;
+    if (index === previousIndex) return;
+    settle();
+    const t = kinds[enter[index]];
+    if (!t || t.type === "cut" || !slide || !previousSlide || index < previousIndex || calm() || slide.hasAttribute("data-deck-static")) return;
+    const all = [...stage.children].filter((s) => s.tagName === "SECTION");
+    if (!all.slice(previousIndex + 1, index).every((s) => s.hasAttribute("data-deck-skip")) || typeof slide.animate !== "function") return;
+    const over = t.on === "leaving";
+    const p = {
+      anims: [],
+      leaving: previousSlide,
+      arriving: slide,
+      z: [previousSlide.style.zIndex, slide.style.zIndex],
+      bg: t.backdrop ? stage.style.getPropertyValue("--deck-canvas") : null,
+      looped: false
+    };
+    previousSlide.setAttribute("data-sd-leaving", "");
+    if (slide.hasAttribute("data-deck-loop") && !previousSlide.hasAttribute("data-deck-loop")) {
+      previousSlide.setAttribute("data-deck-loop", "");
+      p.looped = true;
+    }
+    previousSlide.style.zIndex = over ? "2" : "1";
+    slide.style.zIndex = over ? "1" : "2";
+    if (t.backdrop) stage.style.setProperty("--deck-canvas", t.backdrop);
+    stage.setAttribute("data-deck-changing", "");
+    p.anims = [previousSlide.animate(t.leaving, t.options), slide.animate(t.arriving, t.options)];
+    playing = p;
+    const done = () => {
+      if (playing === p) settle();
+    };
+    p.anims[1].finished.then(done, done);
+  });
+}
+export {
+  CSS_TRANSITIONS,
+  TRANSITION_CSS,
+  enterText,
+  readEnter,
+  transitionData,
+  transitionKeyframes,
+  transitionRuntime,
+  transitionTable
+};

package/dist/video.js

@@ -88,7 +88,8 @@ function ffmpeg(run, args, what) {
   const why = failure(run("ffmpeg", args, { stdio: "inherit" }));
   if (why) throw new Error(`ffmpeg failed: ${what} (${why})`);
 }
-async function frames(driver, url, plan, dir, { fps, maxEntrance, log }) {
+const LOOP_HOLD = 0.3;
+async function frames(driver, url, plan, dir, { fps, maxEntrance, loops, log }) {
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
   const shots = [];
@@ -96,10 +97,14 @@ async function frames(driver, url, plan, dir, { fps, maxEntrance, log }) {
     await driver.open(url);
     for (const c of plan) {
       await driver.step(c.n);
-      const end = Math.min(maxEntrance, await driver.freeze()), count = Math.max(1, Math.ceil(end / (1e3 / fps)) + 1);
+      const end = Math.min(maxEntrance, await driver.freeze());
+      const looping = loops && typeof driver.loops === "function" && await driver.loops() === true;
+      const count = Math.max(1, Math.ceil(end / (1e3 / fps)) + 1, looping ? Math.floor((c.length - LOOP_HOLD) * fps) : 0);
       const files = [];
       for (let k = 0; k < count; k++) {
-        await driver.seek(Math.min(end, k * 1e3 / fps));
+        const t = k * 1e3 / fps;
+        if (looping) await driver.seek(Math.min(end, t), { loop: c.start * 1e3 + t });
+        else await driver.seek(Math.min(end, t));
         const file = path.join(dir, `c${NUM(c.n)}-${NUM(k)}.png`);
         await driver.shot(file);
         files.push(file);
@@ -139,6 +144,7 @@ async function renderVideo({
   noclip,
   only,
   maxEntrance = 4e3,
+  loops = true,
   chapters = () => null,
   intro = "Intro",
   thumbnail = () => false,
@@ -155,13 +161,13 @@ async function renderVideo({
   const own = !work, dir = own ? mkdtempSync(path.join(tmpdir(), "storydeck-video-")) : path.resolve(work);
   try {
     mkdirSync(dir, { recursive: true });
-    return await render({ url, plan, out, name, driver, run, fps, maxEntrance, chapters, intro, thumbnail, work: dir, log });
+    return await render({ url, plan, out, name, driver, run, fps, maxEntrance, loops, chapters, intro, thumbnail, work: dir, log });
   } finally {
     if (own) rmSync(dir, { recursive: true, force: true });
   }
 }
-async function render({ url, plan, out, name, driver, run, fps, maxEntrance, chapters, intro, thumbnail, work, log }) {
-  const shots = await frames(driver, url, plan, path.join(work, "frames"), { fps, maxEntrance, log });
+async function render({ url, plan, out, name, driver, run, fps, maxEntrance, loops, chapters, intro, thumbnail, work, log }) {
+  const shots = await frames(driver, url, plan, path.join(work, "frames"), { fps, maxEntrance, loops, log });
   const concat = path.join(work, "frames.ffconcat");
   writeFileSync(concat, framesConcat(plan, shots, { fps }));
   const wav = narration(run, plan, work), length = plan.reduce((s, c) => s + c.length, 0), video = path.join(out, `${name}.mp4`);
@@ -245,19 +251,23 @@ function deckStageDriver({ chromium, executablePath, viewport = { width: 1920, h
       const all = [.../* @__PURE__ */ new Set([...document.getAnimations(), ...stage?.shadowRoot?.getAnimations() ?? []])];
       all.forEach((a) => a.pause());
       window.__sdFrozen = all;
+      window.__sdLoops = all.filter((a) => a.effect?.getTiming?.().iterations === Infinity && a.effect.target?.closest?.("[data-deck-loop]"));
       const ends = all.map((a) => a.effect?.getComputedTiming().endTime).filter((t) => Number.isFinite(t));
       return Math.max(0, ...ends);
     }),
-    async seek(ms) {
-      await page.evaluate((t) => {
-        for (const a of window.__sdFrozen ?? []) a.currentTime = t;
-      }, ms);
+    loops: () => page.evaluate(() => (window.__sdLoops ?? []).length > 0),
+    /** Every frozen animation to `ms` — its loops, given `loop`, to that (the video's own time, so they run on across clicks). */
+    async seek(ms, { loop } = {}) {
+      await page.evaluate(([t, l]) => {
+        const loops = new Set(window.__sdLoops ?? []);
+        for (const a of window.__sdFrozen ?? []) a.currentTime = l !== null && loops.has(a) ? l : t;
+      }, [ms, loop ?? null]);
       await settle();
     },
     shot: (file) => page.screenshot({ path: file }),
     /**
      * Click n (1-based) as it settles, measured: jump there (a jump lands at once), finish what still moves, and
-     * report text that spills out of its box and lit pieces outside the slide — [{kind, piece, text, dx, dy}] (the
+     * report text that spills out of its box, lit pieces outside the slide and a label that meets what is on it — [{kind, piece, text, dx, dy}] (the
      * layout check, deck/layout.js, reads it).
      */
     async measure(n) {
@@ -316,6 +326,21 @@ function measureSlide() {
     const dx = Math.max(0, -x0, x1 - W), dy = Math.max(0, -y0, y1 - H);
     if (dx > 2 || dy > 2) out.push({ kind: "outside", piece: pieceOf(el), text: textOf(el), dx: Math.round(dx), dy: Math.round(dy) });
   }
+  const labels = [...slide.querySelectorAll(".differs span")].filter(shown).map((el) => el.getBoundingClientRect());
+  if (labels.length) {
+    const meets = (a, b) => Math.min(a.right, b.right) - Math.max(a.left, b.left) > 2 && Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top) > 2;
+    const textRects = (el) => {
+      const r = document.createRange();
+      r.selectNodeContents(el);
+      return [...r.getClientRects()];
+    };
+    for (const el of slide.querySelectorAll("*")) {
+      if (el.closest(".differs, .foot") || !shown(el)) continue;
+      const piece = el.matches(".sd-on");
+      if (!piece && (el.closest(".sd-on") || el.namespaceURI === "http://www.w3.org/2000/svg" || ![...el.childNodes].some((c) => c.nodeType === 3 && c.textContent.trim()))) continue;
+      if ((piece ? [el.getBoundingClientRect()] : textRects(el)).some((r) => labels.some((l) => meets(r, l)))) out.push({ kind: "differs-overlap", piece: pieceOf(el), text: textOf(el), dx: 0, dy: 0 });
+    }
+  }
   for (const el of [slide, ...slide.querySelectorAll("*")]) {
     if (el.hasAttribute("data-loop")) continue;
     if (getComputedStyle(el).animationIterationCount.split(",").some((c) => c.trim() === "infinite")) out.push({ kind: "loose-loop", piece: pieceOf(el), text: textOf(el), dx: 0, dy: 0 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "footprint-storydeck",
-  "version": "0.9.0",
-  "description": "One source, many lenses — render structured content as a Read article, a Scroll (scrollytelling) story, or a Watch deck; and make a deck from a folder with a live dev loop.",
+  "version": "0.11.0",
+  "description": "React views and a deck CLI for turning one structured story into an article, scrollytelling page, slide deck, narrated video or PowerPoint.",
   "type": "module",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -108,7 +108,7 @@
     "test:cov": "vitest run --coverage"
   },
   "peerDependencies": {
-    "footprintjs": "^10.0.0",
+    "footprintjs": "^11.0.0",
     "react": ">=18",
     "react-dom": ">=18"
   },
@@ -128,7 +128,7 @@
     "@vitejs/plugin-react": "^5.0.4",
     "@vitest/coverage-v8": "^4.1.9",
     "esbuild": "^0.28.2",
-    "footprintjs": "^10.0.0",
+    "footprintjs": "11.0.0",
     "jsdom": "^29.1.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

package/plugin/skills/storydeck/SKILL.md

@@ -65,7 +65,10 @@ a map, `<i data-k="w" class="wire pkt" data-arrow="client to server"></i>` is a
 between the two pieces and following them when they move (prefer it to `"x1 y1 x2 y2"` numbers; a wire each way between
 the same pieces gets its own lane; a bend may follow: `"gw to db 40"`); `data-on="gw+"` is gw, its wires and what they
 reach; a wire takes `data-label="name"` (at its middle, on its left), class `halo` (a glow) and `data-packets="2"
-data-speed="5"` (packets that keep running along it on the slide shown — loops); and
+data-speed="5"` (packets that keep running along it on the slide shown — loops); `"explore": true` in deck.json lets a
+viewer click a piece to go to the click about it (Back returns); `<section data-enter="push" data-enter-from="right">`
+makes a part arrive with one of StoryReel's changes (cut, fade, dip, wipe, split, iris, push, slide, whip, zoom; on a
+forward step only); and
 `<i class="ic" data-icon="name"></i>` is icons/name.svg. A piece that comes in lights unless the click is `data-quiet`
 (`check` warns: `lit-on-entry`). Motion that keeps going is a loop: `data-loop="pulse"` (or `float`, `marquee`, with a
 pace: `"float 4s"`) on a piece, or `data-loop` alone with the piece's own `--loop: spin 6s linear infinite` in
@@ -177,8 +180,9 @@ It is pictures + notes + sound, not editable PowerPoint shapes.
   deck says it tours.
 - **A cloned voice is its speaker's**: a page that carries clips stays internal. A public build leaves
   `embedClips` out; listen mode falls back to the browser's voice.
-- **Video frames are deterministic**: each click is made forward, every animation paused and stepped. Looping
-  motion stops when the entrance ends. Compare two renders by `timeline.json` and `captions.srt` (equal) and
+- **Video frames are deterministic**: each click is made forward, every animation paused and stepped. A click whose
+  loops run (data-loop, a wire's packets) is stepped on to its end, the loops at the video's own time, so they keep
+  running from click to click; `loops: false` holds the click's frame instead (a faster draft). Compare two renders by `timeline.json` and `captions.srt` (equal) and
   frames (byte-equal, or within a hair where the GPU blends a backdrop filter).
 - **Paths may be relative; scratch folders are temporary.** `voiceClips` and `renderVideo` resolve every path and
   work in a temporary folder of their own unless you name a `work` folder (which they empty before use) — never

package/site/public/deck-stage.js

@@ -200,9 +200,12 @@
       position: relative;
       transform-origin: center center;
       flex-shrink: 0;
-      background: #fff;
+      /* what shows behind the slides (a change of slide that fades both — a dip — shows it); --deck-canvas from the page */
+      background: var(--deck-canvas, #fff);
       will-change: transform;
     }
+    /* while a change of slide plays (the page sets data-deck-changing), a slide moving in or out stays inside the frame */
+    :host([data-deck-changing]) .canvas { overflow: hidden; }
 
     /* Slides live in light DOM (via <slot>) so authored CSS still applies.
        We absolutely position each slotted child to stack them. */

package/video.d.ts

@@ -15,7 +15,10 @@ export interface VideoDriver {
   open(url: string): Promise<void>;
   step(n: number): Promise<void>;
   freeze(): Promise<number>;
-  seek(ms: number): Promise<void>;
+  /** Whether the click's loops run (deck-stage's data-loop): then its frames go on to its end, the loops at the video's time. */
+  loops?(): Promise<boolean> | boolean;
+  /** Every frozen animation to `ms`; with `loop`, the loops to that instead (ms since the video began). */
+  seek(ms: number, options?: { loop?: number }): Promise<void>;
   shot(file: string): Promise<unknown>;
   close(): Promise<unknown> | unknown;
 }
@@ -45,6 +48,8 @@ export function encodeArgs(options: { frames: string; narration: string; out: st
 export function renderVideo(options: {
   url: string; steps: readonly VideoStep[]; out: string; name?: string; driver: VideoDriver; run?: Run;
   fps?: number; gap?: number; lead?: number; noclip?: number; only?: [number, number] | null; maxEntrance?: number;
+  /** A click whose loops run is stepped on to its end, so they keep running (true); false holds its frame — a faster draft. */
+  loops?: boolean;
   chapters?: (click: PlannedClick) => string | null; intro?: string; thumbnail?: (click: PlannedClick) => boolean;
   /** where frames and sounds are made (its frames/ and audio/ are replaced); by default a temporary folder, removed afterwards */
   work?: string; log?: (line: string) => void;