footprint-storydeck 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 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 +75,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

@@ -408,6 +408,17 @@ 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

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,12 @@ 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>> }
 /** 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 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 +84,8 @@ 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 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 +104,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/compile.js

@@ -2,6 +2,8 @@ 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";
@@ -41,6 +43,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 +52,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 +67,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();
@@ -118,10 +121,21 @@ function compileDeck(source, { dev = false } = {}) {
     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/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/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/page.js

@@ -2,6 +2,8 @@ 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 { 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 +36,9 @@ 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 css = [...assets.css, ...loops ? [loops] : [], ...compiled.explore ? [EXPLORE_CSS] : [], ...compiled.transitions ? [TRANSITION_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 +53,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,5 @@
 import { closing, elements, stripComments } from "./html.js";
+import { readAttributes } from "../pieceRules.js";
 const NOTES_CLASS = /\sclass=(["'])(?:[^"']*\s)?notes(?:\s[^"']*)?\1/;
 const BLOCK = /* @__PURE__ */ new Set([
   "br",
@@ -106,6 +107,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 +129,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);
     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, 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 +146,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, 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,11 @@
 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 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 +62,7 @@ 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 (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 +87,7 @@ 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 (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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprint-storydeck",
-  "version": "0.9.0",
+  "version": "0.10.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.",
   "type": "module",
   "license": "MIT",

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

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. */