footprint-storydeck 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 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
+  edge of the other's (6 px clear), so it follows them: move a box, in the file or by Alt-drag, and its wires come
+  along — no four numbers to keep in step. Two or more wires between the same pieces each take a lane (80 px apart at
+  most, always inside both boxes), keeping to their left, so a request going right runs above its answer coming back
+  whatever the pieces are called. A bend may follow the names (`"gw to db 40"`). Words, not `>`, because a `>` would
+  end the tag. A name not placed, a wire to itself and pieces too close for a wire are refused, naming the fix; a
+  numbered wire is drawn byte for byte as before. Alt-dragging a wire between pieces is refused with its fix (move one
+  of its pieces). The starter deck now writes its four wires this way (they land within 5 px of where its numbers put them).
+- **A wire's label, halo and running packets.** Three attributes on any wire: `data-label="InvokeAgentRuntime"` writes
+  its name beside its middle, on its left — above a level wire going right, below one coming back, beside a standing
+  one by half its width — in the wire's colour on an edge of the ground (the wire's box grows to hold it, so a wire
+  showing itself in shows its label too); class `halo` gives the line and its head a soft glow (`--wire-halo`); and
+  `data-packets="2" data-speed="5"` keeps packets running along the curve, evenly spaced, 5 s a run (3 by default;
+  1–6 packets, 0.5–60 s), fading in at the start and out before the head (`--packet`, `--packet-glow`). The packets are
+  loops, so they run only on the slide shown, in step from click to click, and where loops do not run (reduced motion,
+  print, motion off) the first rests at the wire's middle. They are the wire's, not the deck's loops: `review` and
+  `check` do not list them. A wire without these is drawn byte for byte as before; packets it cannot run, and a speed
+  with no packets, are refused naming the fix. They are read as a browser reads the tag (never from inside another
+  attribute's value, in any case, quoted or not); a `>` or `<` in a value is written `&gt;` or `&lt;`, since a tag ends
+  at its first `>`. A deck that already put its own `data-label`, `data-packets` or `data-speed` on a wire (for its
+  own CSS) now gets them drawn: rename them. A loop an icon file carries is now found by `review` and `check` too.
+- **A piece and what it touches: `name+`.** A wire between pieces carries `data-ends` (the pieces it joins; a wire in
+  numbers may carry it too), so a click can name `gw+`: the gateway, the wires with it as an end, and the pieces at
+  their other ends — `data-on="gw+"` lights that neighbourhood and greys the rest. It reads anywhere a click names
+  pieces (`data-in`, `data-out`, `data-on`, `data-hot`, and the groups a mover moves: `subject`, `aside`, `place`,
+  `apart`); `check`'s lit-on-entry reads it the same way, and `review` lists what it lit. A piece actually called `gw+`
+  is itself. On a `path` click it lights the piece, then its wires, then what they reach — for a request's own order,
+  write the route out (`data-focus-route`), where `+` is not read. `footprint-storydeck/focus` exports `expandNames`.
+
+- **Motion that keeps going: loops.** `data-loop="pulse"` on a piece keeps it pulsing while its slide is shown.
+  `pulse`, `float` and `marquee` are the endless moves of the motion table StoryReel's films use
+  (`footprint-story/motion`), sampled from the same curves and drawn into the page only when a deck names them
+  (`data-loop="float 4s"` sets the pace; any other name is refused at build, naming the piece and the loops there are).
+  A named loop moves its element by `transform` (a shape inside a drawing about its own middle), so a tag that sets a
+  transform of its own is refused, naming the fix: put data-loop on an element inside it. `data-loop` alone runs the
+  piece's own animation, `--loop` in theme.css (`.gear { --loop: spin 6s linear infinite; }`); a theme.css rule that
+  gives the element its own `animation` wins, so list `var(--loop)` in it to keep both.
+  <deck-stage> owns where loops run, so it works in any deck on the stage: only on the slide shown and the layers under
+  it (it stamps `data-deck-loop` on them), so a deck of 40 map clicks runs one slide's loops, not 40. Every loop runs
+  on one clock (only a data-loop element's animations are set to it: a deck's other animations are left as they were), so a map drawn again for the next click shows each loop where the last click left it, and a jump or a
+  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.
+- **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.
+- **The checks know loops.** `review` lists each click's loops (`loops (2): db pulse, gear (its own --loop)`). `check`
+  warns (`loop-unset`) about a `data-loop` that neither theme.css nor its own style gives a `--loop` (nothing would
+  loop). `check --layout` reports an endless animation that is not a loop: one running on a slide no one sees is an
+  error (`hidden-loop`, with how many and on which pieces, one problem for all the slides it runs on); one shown on a
+  click is a warning (`loose-loop`: it starts over at each click and stops on a jump).
+
 ## 0.8.1 — footprint-narration is now footprint-story
 
 - **footprint-narration is now footprint-story.** StoryDeck's shared narration code (shown-vs-spoken text, captions,

package/README.md

@@ -413,16 +413,45 @@ npx footprint-storydeck build my-talk     # my-talk/index.html — one page, eve
   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 (it needs Playwright installed beside
+  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
   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="252 352 318 352"></i>` is a wire (an
-  SVG arrow, with an optional bend; class `pkt` adds a packet that rides it on a `path` click, at its turn — along the
-  curve itself, not a straight line across the bend). A wire that comes in shows itself from its start to its tip,
-  its dashes and colours as your theme draws them.
+- **The helpers a diagram needs.** `<i data-k="w1" class="wire pkt" data-arrow="client to server"></i>` is a wire (an
+  SVG arrow) from the edge of one piece's box to the edge of the other's. It follows them: move a box (in the file, or
+  by Alt-drag in the dev page) and its wires go with it. Two wires between the same pieces each take a lane, keeping to
+  their left, so a request going right runs above its answer coming back; a bend may follow the names
+  (`"gw to db 40"`). `data-arrow="252 352 318 352"` places a wire by hand, in slide px. Class `pkt` adds a packet that
+  rides the wire on a `path` click, at its turn — along the curve itself, not a straight line across the bend. A wire
+  that comes in shows itself from its start to its tip, its dashes and colours as your theme draws them. A wire between
+  pieces knows its ends, so a click can be about a piece and everything it touches: `data-on="gw+"` lights the
+  gateway, its wires and the pieces at their other ends, and greys the rest (`review` lists them); it reads in every
+  list of names a click has, the groups a mover moves too (`data-focus-apart="gw+: 0 -200"`). A living system
+  diagram needs three more things on a wire, each an attribute: `data-label="InvokeAgentRuntime"` writes its name at its
+  middle, on its left (a request's above it, its answer's below; in the wire's colour, on an edge of the ground so it
+  reads over anything); class `halo` gives it a soft glow (`--wire-halo`); and `data-packets="2" data-speed="5"` keeps
+  packets running along it, evenly spaced, 5 s a run (`--packet`, `--packet-glow`). The packets are loops (see below):
+  only on the slide shown, in step from click to click, and under reduced motion, in print or with motion off one rests
+  at the wire's middle.
   `<i class="ic" data-icon="server"></i>` is `icons/server.svg`. `deck.css` styles the chrome (kicker, headline, footer
   and count), wires, packets, icons and the theme toggle from the token contract, every rule `:where()`, so your
   theme wins.
+- **Motion that keeps going: a loop.** `data-loop="pulse"` on a piece makes it pulse while its slide is shown;
+  `pulse`, `float` and `marquee` are the endless moves of the motion table StoryReel's films use
+  (`footprint-story/motion`), drawn into the page only when a deck names them (`data-loop="float 4s"` sets the pace).
+  `data-loop` alone runs the piece's own animation from theme.css: `.gear { --loop: spin 6s linear infinite; }`. A
+  named loop moves its element by `transform` (`marquee` slides it 1600 px left and starts over: a ticker), so it goes
+  on an element without a transform of its own — a tag that sets one is refused; one theme.css gives it is replaced
+  while the loop runs. A rule of theme.css that gives the element its own `animation` wins over its loop: list
+  `var(--loop)` in it to keep both. A
+  map is drawn again for every click, yet a loop never starts over: every loop in the deck runs on one clock, so the
+  next click shows it where the last one left it, and a jump or a step back keeps it running. A loop runs only on the
+  slide shown (a deck of 40 map clicks runs one slide's loops, not 40), and never under reduced motion, in print, or
+  with motion off — there the piece rests in its own style. **Motion off** is `?motion=off` after the page's address
+  (or `<deck-stage data-motion="off">`): no loops, and every click lands at once, so a screenshot of a click is the same
+  every time. `review` lists each click's loops; `check` warns about a `data-loop` that nothing gives a `--loop`, and
+  `check --layout` finds an endless animation that is not a loop: one running on a slide no one sees (an error: it
+  costs the whole deck), and one that starts over at each click.
 - **A deck is files, never a program — on your machine.** No deck code runs in Node: no build script, no deck module.
   Playwright (1.48 or newer), for `check --layout`, is loaded only from beside StoryDeck — never from the deck folder or
   the folder you run in — and the page is measured offline: no name resolves, the browser context is offline and routed

package/deck.css

@@ -41,11 +41,11 @@
    click it rides the curve once, at the wire's turn: --sd-t runs 0 → 1 and it stands at B(t) = 2(1-t)t·C + t²·E from
    its start (C: --cdx/--cdy, E: --pdx/--pdy, from transforms.js). */
 @property --sd-t { syntax: '<number>'; inherits: false; initial-value: 0; }
-:where(svg.wire .pkt) {
-  opacity: 0; fill: var(--sd-glow, currentColor); stroke: none;
+:where(svg.wire :is(.pkt, .run)) {
   transform: translate(calc(var(--cdx) * 2 * (1 - var(--sd-t)) * var(--sd-t) + var(--pdx) * var(--sd-t) * var(--sd-t)),
     calc(var(--cdy) * 2 * (1 - var(--sd-t)) * var(--sd-t) + var(--pdy) * var(--sd-t) * var(--sd-t)));
 }
+:where(svg.wire .pkt) { opacity: 0; fill: var(--sd-glow, currentColor); stroke: none; }
 @keyframes sdPkt { from { --sd-t: 0; } to { --sd-t: 1; } }
 @keyframes sdPktShow { 0%, 100% { opacity: 0; } 15%, 80% { opacity: 1; } }
 /* a wire that comes in shows itself start to tip behind a sweeping soft edge (a mask: a theme's dashes stay), square to
@@ -70,6 +70,23 @@
   }
 }
 
+/* a wire's options (transforms.js): its label at its middle, in its colour, on a ground-coloured edge so it reads over
+   anything; class "halo", a soft glow; data-packets, packets that keep running along it — loops (deck-stage.js USAGE
+   (i)): on the slide shown, on one clock, each fading in at the start and out before the head. Where loops do not run
+   (reduced motion, print, motion off) the first packet rests at the wire's middle and the others are hidden. */
+:where(svg.wire text.label) {
+  font: 600 18px/1 var(--mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace); letter-spacing: .06em;
+  text-transform: uppercase; dominant-baseline: central; fill: currentColor;
+  stroke: var(--bg, #ffffff); stroke-width: 6px; stroke-linejoin: round; paint-order: stroke;
+}
+:where(svg.wire.halo path) { filter: drop-shadow(0 0 6px var(--wire-halo, currentColor)); }   /* the line and its head, not the label */
+:where(svg.wire .run) {
+  --sd-t: .5; fill: var(--packet, var(--sd-glow, currentColor)); stroke: none;
+  filter: drop-shadow(0 0 5px var(--packet-glow, var(--packet, var(--sd-glow, currentColor))));
+}
+:where(svg.wire .run + .run) { opacity: 0; }
+@keyframes sdRun { 0% { --sd-t: 0; opacity: 0; } 12%, 85% { opacity: 1; } 100% { --sd-t: 1; opacity: 0; } }
+
 /* icons (data-icon): drawn in currentColor */
 :where(svg.ic) { width: 60px; height: 60px; flex: none; fill: none; stroke: currentColor; stroke-width: 3; stroke-linecap: round; stroke-linejoin: round; }
 

package/deck.d.ts

@@ -67,6 +67,8 @@ export interface DeckSource {
 }
 export function readDeck(dir: string): DeckSource;
 
+/** A loop a click shows (deck-stage: data-loop runs its --loop on the slide shown): its piece's first name (null when the element is not a piece), and its value as written — a named loop ("pulse", "float 4s") or '' for the deck's own (`styled` when its own style sets --loop). */
+export interface DeckLoop { readonly piece: string | null; readonly value: string; readonly styled?: true }
 /** A click of the compiled deck, as review and check read it. */
 export type DeckClick = {
   readonly n: number;
@@ -76,6 +78,8 @@ export type DeckClick = {
   /** The headline as plain text ('' on a plain slide). */
   readonly headline: string;
   readonly notes: readonly string[];
+  /** What loops on the click (on a map: on the pieces it shows). */
+  readonly loops: readonly DeckLoop[];
 } & (
   | { 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 }
@@ -92,6 +96,8 @@ export interface CompiledDeck {
   readonly themeCss: string;
   readonly slides: readonly DeckSlide[];
   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[];
   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. */
@@ -133,10 +139,10 @@ export function formatProblems(problems: readonly DeckProblem[]): string;
 /** The browser port the layout check drives (the video's deckStageDriver, with measure). */
 export interface LayoutDriver {
   open(url: string): Promise<void>;
-  measure(n: number): Promise<readonly { kind: 'spills' | 'outside'; piece: string | null; text: string; dx: number; dy: number }[]>;
+  measure(n: number): Promise<readonly { kind: 'spills' | 'outside' | 'loose-loop' | 'hidden-loop'; piece: string | null; text: string; dx: number; dy: number; slide?: number; count?: number }[]>;
   close(): Promise<unknown> | unknown;
 }
-/** Text that spills out of its box and lit pieces off the slide, measured click by click in a browser. */
+/** Text that spills out of its box, lit pieces off the slide, and endless animations that are not loops, measured click by click in a browser. */
 export function layoutCheck(url: string, options: { clicks: readonly DeckClick[]; driver?: LayoutDriver; chromium?: unknown }): Promise<DeckProblem[]>;
 
 export interface DeckServer {

package/dist/deck/check.js

@@ -1,4 +1,6 @@
 import { wordCount } from "./parse.js";
+import { expandNames } from "../focus.js";
+import { LOOP_NAMES } from "./loops.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 }) {
@@ -9,7 +11,7 @@ function words(c, { maxWords, maxSlideWords }) {
 }
 function litOnEntry(c, pieces) {
   if (c.kind !== "map" || c.step.on === null || c.step.quiet) return [];
-  const on = c.step.on;
+  const on = expandNames(pieces, c.step.on);
   if (on.includes("*")) return [];
   const extra = c.look.pieces.map((p, i) => p.state === "on" && (p.change === "enter" || p.change === "arrive") && !pieces[i].keys.some((k) => on.includes(k)) ? i : null).filter((i) => i !== null);
   if (!extra.length) return [];
@@ -53,6 +55,13 @@ function unstyledThemes(compiled) {
   }
   return out;
 }
+function unsetLoops(compiled) {
+  if (/--loop\s*:/.test(compiled.themeCss ?? "")) return [];
+  const bare = compiled.clicks.flatMap((c) => (c.loops ?? []).filter((l) => l.value === "" && !l.styled).map((l) => ({ c, piece: l.piece ?? "an element" })));
+  if (!bare.length) return [];
+  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 checkDeck(compiled) {
   const out = [];
   compiled.clicks.forEach((c, i) => {
@@ -60,7 +69,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));
+  out.push(...neverShown(compiled), ...missingNotes(compiled), ...unstyledThemes(compiled), ...unsetLoops(compiled));
   return out;
 }
 const failure = (error) => [problem("error", "compile", null, error.message)];

package/dist/deck/compile.js

@@ -1,6 +1,7 @@
 import { focusStep } from "../focus.js";
 import { readPieces, readStep, drawFocus, wrapStage, slideClass, focusOverlay } from "../focusHtml.js";
-import { applyTransforms } from "./transforms.js";
+import { applyTransforms, icons as drawIcons } from "./transforms.js";
+import { loopsIn } from "./loops.js";
 import { plainText } from "./parse.js";
 import { esc, stripComments } from "./html.js";
 import { readAttributes, tagsWith } from "../pieceRules.js";
@@ -31,7 +32,10 @@ function prepareMap(name, html, icons, dev) {
   }
   const { html: out, pieces } = readPieces(drawn);
   if (!pieces.length) throw new Error(`map "${name}" has no pieces \u2014 a piece is an element with data-k="name" and an inline left/top (width/height)`);
-  return { name, html: dev ? numberForDev(out) : out, pieces, state: null };
+  return { name, html: dev ? numberForDev(out) : out, pieces, loops: loopsIn(drawIcons(stripComments(html), icons), `map "${name}"`), state: null };
+}
+function shownLoops(map, look) {
+  return map.loops.filter((l) => l.piece === null || look.pieces.some((p, i) => p.state !== "gone" && map.pieces[i].keys.includes(l.piece)));
 }
 function planClicks(parts, maps, { area, canvas, icons }) {
   let lastMap = null;
@@ -45,7 +49,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, notes: part.notes, headline: "", step: 0, steps: 1 });
+      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 });
       lastMap = null;
       continue;
     }
@@ -60,7 +64,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, 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, loops: shownLoops(map, r.look), headline: s.headline, notes: s.notes, stepIndex: k, steps: part.steps.length });
     });
   }
   const seen = /* @__PURE__ */ new Set();
@@ -113,9 +117,11 @@ function compileDeck(source, { dev = false } = {}) {
     map: c.kind === "map" ? c.map.name : null,
     headline: plainText(c.headline),
     notes: c.notes,
+    loops: c.loops,
     ...c.kind === "map" ? { step: c.step, look: c.look, stepIndex: c.stepIndex, steps: c.steps } : { text: plainText(c.inner) }
   }));
-  return { config, title: config.title, themeCss: source.themeCss ?? "", slides, clicks, maps: Object.fromEntries(Object.values(maps).map((m) => [m.name, { pieces: m.pieces }])) };
+  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 }])) };
 }
 export {
   compileDeck

package/dist/deck/edit.js

@@ -1,6 +1,6 @@
 import { attrValue, pieceTags, readAttributes, styleLength, tagsWith } from "../pieceRules.js";
 import { UNSEEN, commentRanges, stripComments } from "./html.js";
-import { wireTags } from "./transforms.js";
+import { wireEnds, wireTags } from "./transforms.js";
 const FEEDBACK = "feedback.md";
 const MAX_MOVE = 5e3;
 const num = (v) => String(Math.round(v * 100) / 100);
@@ -53,7 +53,8 @@ function moveEdits(html, piece, dx, dy) {
   if (browserValueAt(html, piece, "data-k") !== piece.start + 1 + piece.tag.length + piece.before.length + ' data-k="'.length) throw ambiguous();
   const wire = wiresBySource(html).get(piece.start);
   if (wire) {
-    const spec = wire.m[1], parts = spec.trim().split(/[\s,]+/), nums = parts.map(Number);
+    const spec = wire.m[1], parts = spec.trim().split(/[\s,]+/), nums = parts.map(Number), ends = wireEnds(spec);
+    if (ends) throw new Error(`"${piece.name}" runs from "${ends[0]}" to "${ends[1]}" and follows them \u2014 move one of them`);
     if (parts.length !== 4 && parts.length !== 5 || nums.some((n) => !Number.isFinite(n))) {
       throw new Error(`"${piece.name}": its data-arrow is not "x1 y1 x2 y2 [bend]" \u2014 fix it before moving it`);
     }

package/dist/deck/init.js

@@ -9,16 +9,20 @@ const DECK_JSON = `{
 const MAP = `<!--
   The map: one picture the story is told on, in slide pixels (1920 \xD7 1080).
   Every element with data-k="name" and an inline left/top/width/height is a piece a click can bring in, light,
-  grey or move. Pieces never nest. <i data-arrow="x1 y1 x2 y2 [bend]"> becomes a wire (class "pkt": a packet runs
-  along it on a path click); <i class="ic" data-icon="name"> is icons/name.svg.
+  grey or move. Pieces never nest. <i data-arrow="client to server"> becomes a wire from one piece's edge to the
+  other's (it follows them when they move; "x1 y1 x2 y2" in slide px places it by hand; a bend may follow either),
+  class "pkt": a packet runs along it on a path click. A wire may carry data-label="its name", class "halo", and
+  data-packets="2" data-speed="5" (packets that keep running along it). In a click, "server+" is the server, its wires
+  and what they reach. <i class="ic" data-icon="name"> is icons/name.svg. data-loop="pulse" (float, marquee)
+  keeps a piece moving while its slide is shown; data-loop alone runs its own --loop from theme.css.
 -->
 <div data-k="client" class="box" style="left:160px;top:420px;width:300px;height:210px"><i class="ic" data-icon="client"></i><b>Client</b><small>a browser</small></div>
-<i data-k="req1" class="wire req pkt" data-arrow="464 490 716 490"></i>
+<i data-k="req1" class="wire req pkt" data-arrow="client to server"></i>
 <div data-k="server" class="box" style="left:720px;top:420px;width:300px;height:210px"><i class="ic" data-icon="server"></i><b>Server</b><small>an API</small></div>
-<i data-k="req2" class="wire req pkt" data-arrow="1024 490 1276 490"></i>
+<i data-k="req2" class="wire req pkt" data-arrow="server to db"></i>
 <div data-k="db" class="box" style="left:1280px;top:420px;width:300px;height:210px"><i class="ic" data-icon="database"></i><b>Database</b><small>where the data lives</small></div>
-<i data-k="ret2" class="wire ret pkt" data-arrow="1276 570 1024 570"></i>
-<i data-k="ret1" class="wire ret pkt" data-arrow="716 570 464 570"></i>
+<i data-k="ret2" class="wire ret pkt" data-arrow="db to server"></i>
+<i data-k="ret1" class="wire ret pkt" data-arrow="server to client"></i>
 <div data-k="time" class="chip" style="left:760px;top:670px;width:220px;height:70px"><b>120 ms</b><small>illustration</small></div>
 `;
 const CLICKS = `<!--

package/dist/deck/layout.js

@@ -25,20 +25,26 @@ function clickRuns(ns) {
   }
   return runs.map(([a, b]) => a === b ? `${a}` : `${a}\u2013${b}`).join(", ");
 }
+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`],
+  "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`]
+};
+const size = ({ dx, dy }) => [dx > 0 && `${Math.round(dx)} px wide`, dy > 0 && `${Math.round(dy)} px tall`].filter(Boolean).join(" and ");
 function layoutProblems(found, clicks) {
   const same = /* @__PURE__ */ new Map();
   for (const f of found) {
-    const key = JSON.stringify([f.kind, f.piece, f.text, Math.round(f.dx), Math.round(f.dy)]);
-    if (!same.has(key)) same.set(key, { ...f, ns: [] });
-    same.get(key).ns.push(f.n);
+    const at = f.kind === "hidden-loop" ? f.slide : f.n;
+    const key = JSON.stringify(f.kind === "hidden-loop" ? [f.kind, f.piece, f.count] : [f.kind, f.piece, f.text, Math.round(f.dx), Math.round(f.dy)]);
+    if (!same.has(key)) same.set(key, { ...f, ns: /* @__PURE__ */ new Set() });
+    same.get(key).ns.add(at);
   }
-  return [...same.values()].sort((a, b) => a.ns[0] - b.ns[0]).map(({ ns, kind, piece, text, dx, dy }) => {
-    const c = clicks[ns[0] - 1];
-    const where = piece ? `"${piece}"` : "an element";
-    const by = [dx > 0 && `${Math.round(dx)} px wide`, dy > 0 && `${Math.round(dy)} px tall`].filter(Boolean).join(" and ");
-    const also = ns.length > 1 ? ` (on clicks ${clickRuns(ns)})` : "";
-    const message = kind === "spills" ? `text spills out of ${where} by ${by} ("${text}")${also} \u2014 shorten it, or give the box more room` : `${where} reaches ${by} past the slide's edge ("${text}")${also} \u2014 move it in, or zoom less`;
-    return { level: "warn", rule: kind === "spills" ? "spills" : "outside", click: ns[0], label: c?.label ?? null, message };
+  return [...same.values()].map((f) => ({ ...f, ns: [...f.ns].sort((a, b) => a - b) })).sort((a, b) => a.ns[0] - b.ns[0]).map((f) => {
+    const c = clicks[f.ns[0] - 1];
+    const also = f.ns.length > 1 ? ` (on clicks ${clickRuns(f.ns)})` : "";
+    const [level, message] = KINDS[f.kind](f, f.piece ? `"${f.piece}"` : "an element", also);
+    return { level, rule: f.kind, click: f.ns[0], label: c?.label ?? null, message };
   });
 }
 async function layoutCheck(url, { clicks, driver, chromium }) {

package/dist/deck/loops.js

@@ -0,0 +1,75 @@
+import { moveAt, movesBy, readMove } from "footprint-story/motion";
+import { readAttributes, tagsWith } from "../pieceRules.js";
+const LOOP_NAMES = Object.freeze(movesBy({ kind: "ambient" }).map((m) => m.name));
+const LOOP_SECONDS = Object.freeze([0.2, 60]);
+const STEPS = 24;
+const FORM = /^([a-z][a-z-]*)(?: (\d+(?:\.\d+)?)s)?$/;
+function readLoop(value, where) {
+  if (value === "") return null;
+  const m = FORM.exec(value);
+  if (!m || !LOOP_NAMES.includes(m[1])) {
+    throw new Error(`${where}: data-loop="${value}" is not a loop \u2014 name one of ${LOOP_NAMES.join(", ")}, with its seconds if you like ("float 4s"), or write data-loop alone and give the piece its own --loop in theme.css`);
+  }
+  const seconds = m[2] === void 0 ? readMove(m[1]).seconds : Number(m[2]);
+  if (!(seconds >= LOOP_SECONDS[0] && seconds <= LOOP_SECONDS[1])) {
+    throw new Error(`${where}: data-loop="${value}" \u2014 a cycle lasts ${LOOP_SECONDS[0]} to ${LOOP_SECONDS[1]} s`);
+  }
+  return { name: m[1], seconds };
+}
+function loopsIn(html, where) {
+  const out = [];
+  for (const t of tagsWith(html, /\sdata-loop(?![\w-])/i)) {
+    const attrs = readAttributes(t.before + t.m[0] + t.after);
+    if (!attrs) throw new Error(`${where}: <${t.tag}> with data-loop holds a quote never closed before its ">" \u2014 write a ">" inside a value as &gt;`);
+    const loop = attrs.find((a) => a.name === "data-loop");
+    if (!loop) continue;
+    const k = attrs.find((a) => a.name === "data-k")?.value.trim().split(/\s+/)[0] || null, at = k ? `${where}, piece "${k}"` : where;
+    readLoop(loop.value, at);
+    const style = attrs.find((a) => a.name === "style")?.value ?? "";
+    if (loop.value !== "" && (attrs.some((a) => a.name === "transform") || /(?:^|;)\s*transform\s*:/i.test(style))) {
+      throw new Error(`${at}: data-loop="${loop.value}" moves the element by its transform, which would replace the one it has \u2014 put data-loop on an element inside it`);
+    }
+    const styled = loop.value === "" && /(?:^|;)\s*--loop\s*:/.test(style);
+    out.push({ piece: k, value: loop.value, ...styled ? { styled } : {} });
+  }
+  return out;
+}
+const r4 = (v) => +(+v).toFixed(4) + 0;
+const TRANSFORM = ["x", "y", "rotate", "scale"];
+function frameCss(v, props) {
+  const out = [];
+  if (TRANSFORM.some((p) => p in props)) {
+    const parts = [];
+    if ("x" in props || "y" in props) parts.push(`translate(${r4(v.x)}px, ${r4(v.y)}px)`);
+    if ("rotate" in props) parts.push(`rotate(${r4(v.rotate)}deg)`);
+    if ("scale" in props) parts.push(`scale(${r4(v.scale)})`);
+    out.push(`transform: ${parts.join(" ")}`);
+  }
+  if ("opacity" in props) out.push(`opacity: ${r4(v.opacity)}`);
+  if ("blur" in props) out.push(`filter: blur(${r4(v.blur)}px)`);
+  return out.join("; ");
+}
+function keyframes(name) {
+  const m = readMove(name), at = (i) => moveAt(m, i / STEPS * m.seconds * (1 - 1e-9), { seconds: m.seconds });
+  const frames = Array.from({ length: STEPS + 1 }, (_, i) => `${r4(i / STEPS * 100)}% { ${frameCss(at(i), m.props)}; }`);
+  return `@keyframes sd-loop-${name} { ${frames.join(" ")} }`;
+}
+function loopCss(values) {
+  const named = [...new Set(values)].filter((v) => v !== "").sort(), names = /* @__PURE__ */ new Set();
+  if (!named.length) return "";
+  const rules = named.map((v) => {
+    const { name, seconds } = readLoop(v, "loopCss");
+    names.add(name);
+    return `:where([data-loop="${v}"]) { --loop: sd-loop-${name} ${r4(seconds)}s linear infinite; }`;
+  });
+  const shapes = ':where(svg [data-loop]:not([data-loop=""])) { transform-box: fill-box; transform-origin: center; }';
+  return [...[...names].map(keyframes), ...rules, shapes].join("\n");
+}
+export {
+  LOOP_NAMES,
+  LOOP_SECONDS,
+  frameCss,
+  loopCss,
+  loopsIn,
+  readLoop
+};

package/dist/deck/page.js

@@ -1,6 +1,7 @@
 import { focusRuntime } from "../focusHtml.js";
 import { notesData, notesRuntime, listenRuntime } from "../narrationHtml.js";
 import { esc, scriptSafe, styleSafe } from "./html.js";
+import { loopCss } from "./loops.js";
 function themeRuntime() {
   const root = document.documentElement, btn = document.querySelector(".theme-toggle");
   const set = (dark) => {
@@ -32,7 +33,8 @@ const THEME_FIRST = "(function(){var d;try{var t=localStorage.getItem('theme');d
 const TOGGLE = '<button class="theme-toggle" type="button" aria-label="Switch theme" title="Light / dark (T)"><svg class="sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path stroke-linecap="round" d="M12 2v2M12 20v2M2 12h2M20 12h2M5 5l1.5 1.5M17.5 17.5L19 19M19 5l-1.5 1.5M6.5 17.5L5 19"/></svg><svg class="moon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z"/></svg></button>';
 function deckPage(compiled, assets, { dev = null } = {}) {
   const { config, slides } = compiled;
-  const css = [...assets.css, compiled.themeCss ?? ""].join("\n");
+  const loops = loopCss(compiled.loops ?? []);
+  const css = [...assets.css, ...loops ? [loops] : [], 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>`);
   return `<!doctype html>

package/dist/deck/review.js

@@ -4,6 +4,7 @@ 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 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));
   return {
@@ -59,6 +60,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 (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)}`);
     const hw = wordCount(c.headline);
@@ -82,6 +84,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 (loopsLine(c)) lines.push(loopsLine(c));
   }
   const noteWords = c.notes.reduce((sum, p) => sum + wordCount(p), 0);
   lines.push(c.notes.length ? `notes (${c.notes.length}, ${words(noteWords)}): ${quote(c.notes.join(" "), 240)}` : "notes: \u2014");

package/dist/deck/transforms.js

@@ -1,16 +1,46 @@
 import { stripComments } from "./html.js";
+import { readPieces } from "../focusHtml.js";
+import { readAttributes } from "../pieceRules.js";
 const fixed = (v) => +v.toFixed(1);
+const BETWEEN = /^\s*(\S+)\s+to\s+(\S+)(?:\s+(-?\d+(?:\.\d+)?))?\s*$/;
+const wireEnds = (spec) => {
+  const m = BETWEEN.exec(spec);
+  return m ? [m[1], m[2]] : null;
+};
+const LANE = 80;
+const GAP = 6;
+const MOST_PACKETS = 6;
+const SPEEDS = [0.5, 60];
+const LABEL = { size: 18, char: 12, clear: 8 };
+function wireOptions(attrs, spec) {
+  const where = `wire data-arrow="${spec}"`, read = readAttributes(attrs);
+  if (!read) throw new Error(`${where}: a quote in its tag is never closed \u2014 write a ">" or "<" inside a value as &gt; or &lt;`);
+  const value = (name) => read.find((a) => a.name === name)?.value;
+  const label = value("data-label")?.trim() || null, packets = value("data-packets"), speed = value("data-speed");
+  if (packets !== void 0 && !/^[1-9]\d*$/.test(packets.trim())) throw new Error(`${where}: data-packets="${packets}" \u2014 the packets that run along it are a whole number, 1 to ${MOST_PACKETS}`);
+  const n = packets === void 0 ? 0 : Number(packets);
+  if (n > MOST_PACKETS) throw new Error(`${where}: data-packets="${packets}" \u2014 at most ${MOST_PACKETS} packets run along one wire`);
+  if (speed !== void 0 && !n) throw new Error(`${where}: data-speed sets how fast its packets run \u2014 give it data-packets too`);
+  const s = speed === void 0 ? 3 : /^\s*\d+(?:\.\d+)?s?\s*$/.test(speed) ? parseFloat(speed) : NaN;
+  if (!(s >= SPEEDS[0] && s <= SPEEDS[1])) throw new Error(`${where}: data-speed="${speed}" \u2014 the seconds a packet takes to run the wire, ${SPEEDS[0]} to ${SPEEDS[1]}`);
+  return { label, packets: n, speed: s };
+}
 function wireSvg(attrs, spec) {
   const parts = spec.trim().split(/[\s,]+/).map(Number);
   if (parts.length !== 4 && parts.length !== 5 || parts.some((n) => !Number.isFinite(n))) {
-    throw new Error(`data-arrow="${spec}": a wire is "x1 y1 x2 y2" and an optional bend, in slide px`);
+    throw new Error(`data-arrow="${spec}": a wire is the pieces it joins, "from to to" ("client to server"), or "x1 y1 x2 y2" in slide px \u2014 either with an optional bend`);
   }
-  const [x1, y1, x2, y2, bend = 0] = parts;
+  const [x1, y1, x2, y2, bend = 0] = parts, o = wireOptions(attrs, spec);
   const dx = x2 - x1, dy = y2 - y1, len = Math.hypot(dx, dy) || 1;
   const cx = (x1 + x2) / 2 - dy / len * bend, cy = (y1 + y2) / 2 + dx / len * bend;
   const tl = Math.hypot(x2 - cx, y2 - cy) || 1, ux = (x2 - cx) / tl, uy = (y2 - cy) / tl, hs = 18;
-  const pad = 20, X = Math.min(x1, x2, cx) - pad, Y = Math.min(y1, y2, cy) - pad;
-  const W = Math.max(x1, x2, cx) + pad - X, H = Math.max(y1, y2, cy) + pad - Y, f = fixed;
+  const half = o.label ? [o.label.length * LABEL.char / 2 + 4, LABEL.size / 2 + 4] : null;
+  let off = half ? Math.abs(dy) / len * half[0] + Math.abs(dx) / len * half[1] + LABEL.clear : 0;
+  if (half && bend > 0) off += Math.min(bend / 2, 2 * bend * (Math.abs(dx) / len * half[0] + Math.abs(dy) / len * half[1]) ** 2 / len ** 2);
+  const lx = 0.25 * x1 + 0.5 * cx + 0.25 * x2 + dy / len * off, ly = 0.25 * y1 + 0.5 * cy + 0.25 * y2 - dx / len * off;
+  const xs = [x1, x2, cx, ...half ? [lx - half[0] + 20, lx + half[0] - 20] : []], ys = [y1, y2, cy, ...half ? [ly - half[1] + 20, ly + half[1] - 20] : []];
+  const pad = 20, X = Math.min(...xs) - pad, Y = Math.min(...ys) - pad;
+  const W = Math.max(...xs) + pad - X, H = Math.max(...ys) + pad - Y, f = fixed;
   const ex = x2 - ux * hs * 0.8, ey = y2 - uy * hs * 0.8;
   const d = `M${f(x1 - X)} ${f(y1 - Y)} Q${f(cx - X)} ${f(cy - Y)} ${f(ex - X)} ${f(ey - Y)}`;
   const tip = [x2 - X, y2 - Y], back = [tip[0] - ux * hs, tip[1] - uy * hs], nx = -uy * hs * 0.6, ny = ux * hs * 0.6;
@@ -18,8 +48,11 @@ function wireSvg(attrs, spec) {
   let at = attrs.replace(/\sclass="([^"]*)"/, (_, c) => ` class="${/(^|\s)wire(\s|$)/.test(c) ? c : `wire ${c}`}"`);
   if (!/\sclass="/.test(at)) at += ' class="wire"';
   const pkt = /\bpkt\b/.test(at) ? `<rect class="pkt" x="${f(x1 - X - 8)}" y="${f(y1 - Y - 6)}" width="16" height="12" rx="3" style="--cdx:${f(cx - x1)}px;--cdy:${f(cy - y1)}px;--pdx:${f(ex - x1)}px;--pdy:${f(ey - y1)}px"/>` : "";
+  const ride = `--cdx:${f(cx - x1)}px;--cdy:${f(cy - y1)}px;--pdx:${f(ex - x1)}px;--pdy:${f(ey - y1)}px`;
+  const runs = Array.from({ length: o.packets }, (_, k) => `<circle class="run" data-loop cx="${f(x1 - X)}" cy="${f(y1 - Y)}" r="7" style="${ride};--loop:sdRun ${o.speed}s linear ${+(-k * o.speed / o.packets).toFixed(3) + 0}s infinite"/>`).join("");
+  const label = o.label ? `<text class="label" x="${f(lx - X)}" y="${f(ly - Y)}" text-anchor="middle">${o.label}</text>` : "";
   const angle = f(Math.atan2(dx, -dy) * 180 / Math.PI);
-  return `<svg${at} style="left:${f(X)}px;top:${f(Y)}px;width:${f(W)}px;height:${f(H)}px;--sd-angle:${angle}deg" viewBox="0 0 ${f(W)} ${f(H)}" aria-hidden="true"><path d="${d}"/>${head}${pkt}</svg>`;
+  return `<svg${at} style="left:${f(X)}px;top:${f(Y)}px;width:${f(W)}px;height:${f(H)}px;--sd-angle:${angle}deg" viewBox="0 0 ${f(W)} ${f(H)}" aria-hidden="true"><path d="${d}"/>${head}${pkt}${runs}${label}</svg>`;
 }
 function emptyI(html, rule) {
   const out = [];
@@ -31,15 +64,65 @@ function emptyI(html, rule) {
 }
 function replaceEach(html, found, draw) {
   let out = "", from = 0;
-  for (const f of found) {
-    out += html.slice(from, f.start) + draw(f);
+  found.forEach((f, i) => {
+    out += html.slice(from, f.start) + draw(f, i);
     from = f.end;
-  }
+  });
   return out + html.slice(from);
 }
+function exit(b, [px, py], [ux, uy]) {
+  const tx = ux > 0 ? (b.x + b.w - px) / ux : ux < 0 ? (b.x - px) / ux : Infinity;
+  const ty = uy > 0 ? (b.y + b.h - py) / uy : uy < 0 ? (b.y - py) / uy : Infinity;
+  return Math.min(tx, ty);
+}
+function wiresBetween(html, found) {
+  const read = found.map((f) => BETWEEN.exec(f.m[1]));
+  if (!read.some(Boolean)) return read;
+  const { pieces } = readPieces(html), placed = pieces.filter((p) => p.box && p.box.w > 0 && p.box.h > 0);
+  const boxOf = (name, spec) => {
+    const boxes = placed.filter((p) => p.keys[0] === name).map((p) => p.box);
+    if (!boxes.length) {
+      const names = [...new Set(placed.map((p) => p.keys[0]))];
+      throw new Error(`data-arrow="${spec}": no piece "${name}" with a box (data-k, and an inline left, top, width and height)${names.length ? ` \u2014 the placed pieces are ${names.slice(0, 20).join(", ")}${names.length > 20 ? ", \u2026" : ""}` : ""}`);
+    }
+    const x0 = Math.min(...boxes.map((b) => b.x)), y0 = Math.min(...boxes.map((b) => b.y));
+    return { x: x0, y: y0, w: Math.max(...boxes.map((b) => b.x + b.w)) - x0, h: Math.max(...boxes.map((b) => b.y + b.h)) - y0 };
+  };
+  const pairOf = (m) => [m[1], m[2]].sort().join("\0"), lanes = /* @__PURE__ */ new Map();
+  read.forEach((m, i) => {
+    if (m) lanes.set(pairOf(m), [...lanes.get(pairOf(m)) ?? [], i]);
+  });
+  for (const [key, ids] of lanes) {
+    const along = (i) => read[i][1] === key.split("\0")[0];
+    lanes.set(key, [...ids.filter(along), ...ids.filter((i) => !along(i))]);
+  }
+  return read.map((m, i) => {
+    if (!m) return null;
+    const spec = found[i].m[1];
+    if (m[1] === m[2]) throw new Error(`data-arrow="${spec}": a wire joins two pieces, not "${m[1]}" to itself`);
+    const [a, b] = [m[1], m[2]].sort(), A = boxOf(a, spec), B = boxOf(b, spec);
+    const ca = [A.x + A.w / 2, A.y + A.h / 2], cb = [B.x + B.w / 2, B.y + B.h / 2], len = Math.hypot(cb[0] - ca[0], cb[1] - ca[1]);
+    if (len === 0) throw new Error(`data-arrow="${spec}": "${a}" and "${b}" share a middle \u2014 place them apart, or give the wire numbers`);
+    const u = [(cb[0] - ca[0]) / len, (cb[1] - ca[1]) / len], n = [-u[1], u[0]];
+    const across = (box) => (Math.abs(n[0]) * box.w + Math.abs(n[1]) * box.h) / 2;
+    const lane = lanes.get(pairOf(m)), k = lane.indexOf(i), most = Math.max(0, Math.min(across(A), across(B)) - 8);
+    const step = lane.length > 1 ? Math.min(LANE, 2 * most / (lane.length - 1)) : 0, off = (k - (lane.length - 1) / 2) * step;
+    const pa = [ca[0] + n[0] * off, ca[1] + n[1] * off], pb = [cb[0] + n[0] * off, cb[1] + n[1] * off];
+    const ta = exit(A, pa, u) + GAP, tb = exit(B, pb, [-u[0], -u[1]]) + GAP;
+    if (len - ta - tb < 12) throw new Error(`data-arrow="${spec}": "${a}" and "${b}" are too close for a wire between them (they touch or overlap) \u2014 move them apart, or give the wire numbers`);
+    const start = [pa[0] + u[0] * ta, pa[1] + u[1] * ta], end = [pb[0] - u[0] * tb, pb[1] - u[1] * tb];
+    const [from, to] = m[1] === a ? [start, end] : [end, start];
+    return [...from, ...to, Number(m[3] ?? 0)].map(fixed).join(" ");
+  });
+}
 const wireTags = (html) => emptyI(html, /\sdata-arrow="([^"<>]+)"/);
 function wires(html) {
-  return replaceEach(html, wireTags(html), ({ before, m, after }) => wireSvg(before + after, m[1]));
+  const found = wireTags(html), between = wiresBetween(html, found);
+  return replaceEach(html, found, ({ before, m, after }, i) => {
+    if (!between[i]) return wireSvg(before + after, m[1]);
+    const [, from, to] = BETWEEN.exec(m[1]);
+    return wireSvg(` data-ends="${from} ${to}"${before}${after}`, between[i]);
+  });
 }
 function readIcon(name, svg) {
   const text = stripComments(svg).replace(/^\s*<\?xml[^>]*>/, "").trim();
@@ -66,6 +149,7 @@ export {
   applyTransforms,
   icons,
   readIcon,
+  wireEnds,
   wireTags,
   wires
 };

package/dist/focus.js

@@ -1,4 +1,12 @@
 const KINDS = ["look", "camera", "mover", "overlay", "order"];
+function expandNames(pieces, list) {
+  const own = new Set(pieces.flatMap((p) => p.keys));
+  return list.flatMap((x) => {
+    if (!x.endsWith("+") || x.length < 2 || own.has(x)) return [x];
+    const name = x.slice(0, -1), wires = pieces.filter((p) => p.ends?.includes(name));
+    return [.../* @__PURE__ */ new Set([name, ...wires.map((p) => p.keys[0]), ...wires.flatMap((p) => p.ends.filter((e) => e !== name))])];
+  });
+}
 function union(boxes) {
   const known = boxes.filter(Boolean);
   if (!known.length) return null;
@@ -194,7 +202,7 @@ function changeOf(st, was, look, wasLook, entering, before) {
 function focusStep(prev, step, deck) {
   const { pieces, strategies = {} } = deck, canvas = deck.canvas ?? { w: 1920, h: 1080 };
   const view = deck.view ?? { s: 1, x: 0, y: 0 }, areaSlide = deck.area ?? [0, 0, canvas.w, canvas.h];
-  const names = (l) => (l ?? []).flatMap((x) => String(x).trim().split(/\s+/)).filter(Boolean);
+  const names = (l) => expandNames(pieces, (l ?? []).flatMap((x) => String(x).trim().split(/\s+/)).filter(Boolean));
   const ins = names(step.in), outs = names(step.out), on = step.on === void 0 || step.on === null ? null : names(step.on), hot = names(step.hot);
   const has = (i, l) => l.includes("*") || l.some((x) => pieces[i].keys.includes(x));
   const known = (l, what) => {
@@ -224,14 +232,15 @@ function focusStep(prev, step, deck) {
   const subject = union(subjectIdx.map((i) => pieces[i].box)), context = union(contextIdx.map((i) => pieces[i].box)), area = areaOnMap(areaSlide, view);
   const boxOf = (l) => union(all.filter((i) => states[i] !== "gone" && has(i, known(names([].concat(l)), "focus group: "))).map((i) => pieces[i].box));
   const placed = chosen.mover ? chosen.mover.s.place({ subject, context, area, view, canvas, boxOf, options: chosen.mover.options }) ?? {} : {};
+  const placedGroups = (placed.groups ?? []).map((x) => ({ ...x, names: names(x.names) }));
   const spring = placed.spring === void 0 || placed.spring === null ? null : readSpring(placed.spring, chosen.mover.name);
   const springOf = /* @__PURE__ */ new Map();
-  for (const { names: l, g } of placed.groups ?? []) for (const i of all) if (states[i] !== "gone" && has(i, l)) {
+  for (const { names: l, g } of placedGroups) for (const i of all) if (states[i] !== "gone" && has(i, l)) {
     inGroup.set(i, g ? { g } : "still");
     if (spring && g) springOf.set(i, l.join(" "));
     else springOf.delete(i);
   }
-  const springGroups = [...new Map((spring ? placed.groups ?? [] : []).filter((x) => x.g).map((x) => [x.names.join(" "), [...x.names]]))];
+  const springGroups = [...new Map((spring ? placedGroups : []).filter((x) => x.g).map((x) => [x.names.join(" "), [...x.names]]))];
   const groupOf = (i) => {
     const k = inGroup.get(i);
     return k === "subject" ? placed.subject : k === "context" ? placed.context : k?.g ?? null;
@@ -352,6 +361,7 @@ function planFocus(steps, deck, start = null) {
 }
 export {
   FOCUS,
+  expandNames,
   focusStep,
   planFocus,
   readFocus

package/dist/focusHtml.js

@@ -15,8 +15,8 @@ function readPieces(html, { attr = "data-k" } = {}) {
       return v !== null && /^[\d.]+$/.test(v) ? Number(v) : null;
     };
     const x = px(style, "left"), y = px(style, "top"), w = px(style, "width") ?? attrPx("width"), h = px(style, "height") ?? attrPx("height");
-    const twin = attrOf(at, "data-twin")?.trim().split(/\s+/);
-    pieces.push({ keys: k.trim().split(/\s+/), box: x === null || y === null ? null : { x, y, w: w ?? 0, h: h ?? 0 }, ...twin ? { twin } : {} });
+    const twin = attrOf(at, "data-twin")?.trim().split(/\s+/), ends = attrOf(at, "data-ends")?.trim().split(/\s+/).filter(Boolean);
+    pieces.push({ keys: k.trim().split(/\s+/), box: x === null || y === null ? null : { x, y, w: w ?? 0, h: h ?? 0 }, ...twin ? { twin } : {}, ...ends?.length ? { ends } : {} });
     out += `${html.slice(from, start)}<${tag}${before} ${attr}=${q}${k}${q} data-sd-i="${pieces.length - 1}"${after}>`;
     from = end;
   }

package/dist/video.js

@@ -270,13 +270,23 @@ function deckStageDriver({ chromium, executablePath, viewport = { width: 1920, h
 }
 function measureSlide() {
   const stage = document.querySelector("deck-stage");
+  const all = stage ? [...stage.children].filter((s) => s.tagName === "SECTION") : [];
+  const endless = (a) => a.effect?.getTiming?.().iterations === Infinity;
+  const hidden = /* @__PURE__ */ new Map();
+  for (const a of document.getAnimations?.() ?? []) {
+    const s = a.effect?.target?.closest?.("deck-stage > section");
+    if (!s || s.hasAttribute("data-deck-active") || s.hasAttribute("data-deck-under") || a.playState !== "running" || !endless(a)) continue;
+    if (!hidden.has(s)) hidden.set(s, { count: 0, pieces: /* @__PURE__ */ new Set() });
+    hidden.get(s).count += 1;
+    hidden.get(s).pieces.add(a.effect.target.closest("[data-k]")?.getAttribute("data-k")?.trim().split(/\s+/)[0] ?? a.effect.target.tagName.toLowerCase());
+  }
   for (const a of [...document.getAnimations?.() ?? [], ...stage?.shadowRoot?.getAnimations?.() ?? []]) {
     try {
       a.finish();
     } catch {
     }
   }
-  const slide = stage ? [...stage.children].filter((s) => s.tagName === "SECTION")[stage.index] : null;
+  const slide = all[stage?.index] ?? null;
   if (!slide) return [];
   const W = Number(stage.getAttribute("width") || 1920), H = Number(stage.getAttribute("height") || 1080);
   const box = slide.getBoundingClientRect(), scale = box.width / W || 1;
@@ -306,6 +316,11 @@ 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) });
   }
+  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 });
+  }
+  for (const [s, { count, pieces }] of hidden) out.push({ kind: "hidden-loop", piece: [...pieces].join(", "), text: "", dx: 0, dy: 0, slide: all.indexOf(s) + 1, count });
   return out;
 }
 export {

package/focus.css

@@ -8,6 +8,9 @@
  * Every rule is as weak as it can be (the motion gate is a :where()), so a deck's own rule for a piece —
  * its own entrance, say — wins without !important.
  *
+ * A piece with a loop (deck-stage: data-loop and its --loop) keeps it while it changes: the loop is the last animation
+ * in the piece's list.
+ *
  * Tokens (set them in your theme; each has a fallback): --sd-dim-opacity · --sd-hot · --sd-blur ·
  * --sd-veil · --sd-accent (falls back to storydeck's --yellow) · --sd-ease · --sd-move-time · --sd-glow (a path's
  * pulse, falls back to the accent).
@@ -50,6 +53,7 @@
 @property --sd-a-hot { syntax: '*'; inherits: false; }
 @property --sd-a-path { syntax: '*'; inherits: false; }
 @property --sd-a-more { syntax: '*'; inherits: false; }   /* one more animation a stylesheet may give a piece, on the piece itself (deck.css: a wire showing itself in) */
+@property --sd-a-loop { syntax: '*'; inherits: false; }   /* a piece's loop (deck-stage: data-loop and its --loop), kept while the piece changes */
 @property --sd-turn { syntax: '*'; inherits: false; }   /* a piece's moment on a path; never inherited, so 0 off the route */
 @keyframes sdNone {}
 @keyframes sdEnter { from { opacity: 0; scale: calc(var(--sd-s, 1) * .92); } }
@@ -80,6 +84,7 @@
   .sd-move { --sd-a-move: sdMove var(--sd-move-time, 1s) var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) both; }
   .sd-hot-in { --sd-a-hot: sdRing .6s var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) calc(.3s + var(--sd-turn, 0s)) both; }   /* on a path, .3s after its turn */
   .sd-focus-new .sd-enter { --sd-delay: .4s; }   /* what a click adds waits for its blur */
+  :where([data-deck-loop] [data-loop]) { --sd-a-loop: var(--loop); }   /* only where deck-stage runs loops */
   /* a path: everything on it has one moment, --sd-turn — its delay, and .4s more under a new blur, so the whole path
      waits for the blur and then runs. A piece on the route enters, arrives or lights then, and glows as the route
      reaches it (on every forward click); a piece stepping aside for its lit twin goes then; the line shows then. */
@@ -91,7 +96,7 @@
   .sd-path.sd-light { --sd-a-state: sdLightPulse .9s ease var(--sd-turn) backwards; --sd-a-path: sdNone 0s; }   /* grey until its turn */
   .sd-twin-turn.sd-leave { --sd-a-state: sdLeave .45s ease calc(var(--sd-turn) + var(--sd-twin-lag, 0s)) both; }   /* a stylesheet may let a piece step aside later than its twin arrives (deck.css: a wire, while its twin sweeps in) */
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) :is(.sd-enter, .sd-arrive, .sd-light, .sd-fade, .sd-leave, .sd-relook, .sd-move, .sd-hot-in, .sd-path) {
-    animation: var(--sd-a-state, sdNone 0s), var(--sd-a-move, sdNone 0s), var(--sd-a-hot, sdNone 0s), var(--sd-a-path, sdNone 0s), var(--sd-a-more, sdNone 0s); }
+    animation: var(--sd-a-state, sdNone 0s), var(--sd-a-move, sdNone 0s), var(--sd-a-hot, sdNone 0s), var(--sd-a-path, sdNone 0s), var(--sd-a-more, sdNone 0s), var(--sd-a-loop, sdNone 0s); }
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-path-line { animation: sdArrive .5s ease var(--sd-turn) both; }
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-stage.sd-move { animation: sdStage var(--sd-move-time, 1s) var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) both; }
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-veil-in-new { animation: sdVeilIn .7s cubic-bezier(.4, 0, .2, 1) both; }

package/focus.d.ts

@@ -12,6 +12,8 @@ export interface FocusPiece {
   readonly box: FocusBox | null;
   /** Names of its twin: while a twin is lit, this piece steps aside (a dashed wire under a solid one). */
   readonly twin?: readonly string[];
+  /** A wire's ends: the pieces it joins (data-ends; a wire written "from to to" carries them), for a click's `name+`. */
+  readonly ends?: readonly string[];
 }
 
 /** A focus as written on a click: a strategy name ('left'), several ('left blur'), or {strategy, …options}. */
@@ -162,5 +164,7 @@ export type FocusState = { readonly __focusState: true } & Record<string, unknow
 export const FOCUS: Readonly<Record<'grey' | 'hide' | 'keep' | 'zoom' | 'left' | 'right' | 'up' | 'down' | 'place' | 'apart' | 'path' | 'blur', FocusStrategy>>;
 export function readFocus(spec: FocusSpec | undefined | null, shared?: Readonly<Record<string, unknown>>): { strategy: string; options: Record<string, unknown> }[];
 export function focusStep(prev: FocusState | null, click: FocusClick, deck: FocusDeck): { state: FocusState; look: FocusLook };
+/** Names as a click writes them, each `name+` read as that piece, the wires with it as an end, and the pieces at their other ends. */
+export function expandNames(pieces: readonly FocusPiece[], names: readonly string[]): string[];
 /** `end` is null only when there are no clicks and no `start`. */
 export function planFocus(clicks: readonly FocusClick[], deck: FocusDeck, start?: FocusState | null): { looks: FocusLook[]; end: FocusState | null };

package/package.json

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

package/plugin/skills/storydeck/SKILL.md

@@ -44,7 +44,7 @@ the project that holds the deck, naming its folder (npx would prefer a StoryDeck
 npx footprint-storydeck init my-talk            # a starter: deck.json, clicks.html, map.html, theme.css, icons/
 npx footprint-storydeck outline my-talk         # the whole deck, a line per click — read this before editing
 npx footprint-storydeck review my-talk --click 3    # one click: headline (words), focus, route, lit, greyed, enters, moves, notes
-npx footprint-storydeck check my-talk           # what to fix, each with its click and its fix (--layout: text that spills, in a browser)
+npx footprint-storydeck check my-talk           # what to fix, each with its click and its fix (--layout: text that spills and stray endless animations, in a browser)
 npx footprint-storydeck build my-talk           # my-talk/index.html, self-contained
 npx footprint-storydeck dev my-talk             # for the person: a save reloads on the same click and replays it
 npx footprint-storydeck feedback my-talk        # the notes the person left in the dev page — read these first
@@ -61,9 +61,18 @@ dev page only StoryDeck's own scripts run: a deck's own `<script>` runs in the b
 In clicks.html, a `<section data-label data-kicker>` is a plain slide; with `data-map="map"` each `<step>` in it is one
 click on map.html (`data-in`, `data-out`, `data-on`, `data-quiet`, `data-focus` and `data-focus-*`), holding only its
 `<h2>` and `<aside class="notes">` — anything else in a step is refused, naming where it goes (a piece on the map). On
-a map, `<i data-k="w" class="wire pkt" data-arrow="x1 y1 x2 y2 [bend]"></i>` is a wire with a packet and
+a map, `<i data-k="w" class="wire pkt" data-arrow="client to server"></i>` is a wire with a packet, edge to edge
+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
 `<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`). For an assistant: `claude mcp add storydeck -- npx footprint-storydeck mcp my-talk`
+(`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
+theme.css — never an infinite animation of your own (`check --layout` refuses one running on a hidden slide). A named
+loop moves its element by `transform`: put it on an element without a transform of its own (wrap it). A loop
+runs only on the slide shown, on one clock across clicks, and rests in its own style under reduced motion, in print and
+with `?motion=off` (a still deck, for screenshots). For an assistant: `claude mcp add storydeck -- npx footprint-storydeck mcp my-talk`
 gives it outline, review, feedback, check and build as tools.
 
 **Focus a diagram, click by click.** Every element with `data-k="name …"` and an inline `left/top`

package/site/public/deck-stage.js

@@ -66,6 +66,18 @@
  *      an opaque background of their own. Decks without data-build behave
  *      exactly as before. Rail thumbnails and print show each slide's own
  *      authored content (not the composite).
+ *  (i) loops — an element with data-loop runs the animation in its --loop
+ *      (e.g. style="--loop: spin 4s linear infinite") as ambient motion: only
+ *      on the slide shown and the layers under it (the engine stamps
+ *      data-deck-loop on them), on ONE clock for the whole deck (each
+ *      loop's animation is set to start at the page's start), so
+ *      the next slide of the same picture shows every loop where the last
+ *      one left it, and a jump or a step back keeps them running. Loops
+ *      never run under prefers-reduced-motion, in print, or with motion
+ *      off: there the element rests in its own style (its still pose).
+ *  (j) motion off — <deck-stage data-motion="off">, or ?motion=off in the
+ *      page's address: no loops, and every arrival lands at once (as a
+ *      jump does), so a screenshot of a slide is the same every time.
  *
  * Slides are HIDDEN, not unmounted. Non-active slides stay in the DOM with
  * `visibility: hidden` + `opacity: 0`, so their state (videos, iframes,
@@ -122,7 +134,9 @@
  *     animate *from* hidden, so print and reduced-motion show content.
  *     Gate the animation on [data-deck-active] and the motion query, e.g.
  *     `@media (prefers-reduced-motion:no-preference){ [data-deck-active] .x{animation:fade-in .5s both} }`.
- *     Avoid infinite decorative loops on slide content.
+ *   - Endless motion is a loop (USAGE (i)): data-loop and its --loop, never
+ *     an infinite animation of your own (that one keeps running on hidden
+ *     slides, restarts at each slide and stops on a jump).
  */
 /* END USAGE */
 
@@ -133,6 +147,7 @@
   const VALIDATE_ATTR = 'no_overflowing_text,no_overlapping_text,slide_sized_text';
   const FINE_POINTER_MQ = matchMedia('(hover: hover) and (pointer: fine)');
   const NARROW_MQ = matchMedia('(max-width: 640px)');
+  const REDUCED_MQ = matchMedia('(prefers-reduced-motion: reduce)');
   // Slide-authored controls that should keep a tap instead of it navigating.
   const INTERACTIVE_SEL = 'a[href], button, input, select, textarea, summary, label, video[controls], audio[controls], [role="button"], [onclick], [tabindex]:not([tabindex^="-"]), [contenteditable]:not([contenteditable="false" i])';
 
@@ -596,7 +611,7 @@
   `;
 
   class DeckStage extends HTMLElement {
-    static get observedAttributes() { return ['width', 'height', 'noscale', 'no-rail']; }
+    static get observedAttributes() { return ['width', 'height', 'noscale', 'no-rail', 'data-motion']; }
 
     constructor() {
       super();
@@ -614,6 +629,7 @@
       this._onMouseMove = this._onMouseMove.bind(this);
       this._onTap = this._onTap.bind(this);
       this._onMessage = this._onMessage.bind(this);
+      this._onMotionChange = this._onMotionChange.bind(this);
       // Capture-phase close so a click anywhere dismisses the menu, but
       // ignore clicks that land inside the menu itself — otherwise the
       // capture handler runs before the menu's own (bubble) handler and
@@ -636,10 +652,14 @@
       // next thumbnails — the rail has no business rendering inside those
       // (wrong scale, and it offsets the stage so the thumb shows a gutter).
       if (/[?&]_snthumb=/.test(location.search)) this.setAttribute('no-rail', '');
+      // ?motion=off: a still deck (USAGE (j)), for a screenshot or a person who asks for one
+      if (/[?&]motion=off(?:&|$)/.test(location.search)) this.setAttribute('data-motion', 'off');
       this._render();
       this._loadNotes();
       this._syncPrintPageRule();
       this._syncBuildStyleRule();
+      this._syncLoopStyleRule();
+      if (REDUCED_MQ.addEventListener) REDUCED_MQ.addEventListener('change', this._onMotionChange);
       window.addEventListener('keydown', this._onKey);
       window.addEventListener('resize', this._onResize);
       window.addEventListener('mousemove', this._onMouseMove, { passive: true });
@@ -658,15 +678,18 @@
         this._freezeStyle = document.createElement('style');
         this._freezeStyle.textContent = '*,*::before,*::after{transition-duration:0s !important}';
         document.head.appendChild(this._freezeStyle);
+        this._printing = true;   // a loop prints its still pose
         this._slides.forEach((s) => {
           s.setAttribute('data-deck-active', '');
           // Print pages each slide standalone — no additive layering, and
           // the under-layer chrome-hide rule must not leak into print.
           s.removeAttribute('data-deck-under');
           s.removeAttribute('data-deck-static');
+          s.removeAttribute('data-deck-loop');
         });
       };
       this._onAfterPrint = () => {
+        this._printing = false;
         this._applyIndex({ showOverlay: false, broadcast: false });
         if (this._freezeStyle) { this._freezeStyle.remove(); this._freezeStyle = null; }
       };
@@ -884,6 +907,7 @@
       window.removeEventListener('click', this._onDocClick, true);
       window.removeEventListener('beforeprint', this._onBeforePrint);
       window.removeEventListener('afterprint', this._onAfterPrint);
+      if (REDUCED_MQ.removeEventListener) REDUCED_MQ.removeEventListener('change', this._onMotionChange);
       if (this._freezeStyle) { this._freezeStyle.remove(); this._freezeStyle = null; }
       this.removeEventListener('click', this._onTap);
       if (this._hideTimer) clearTimeout(this._hideTimer);
@@ -897,7 +921,8 @@
       if (this._onTweakChange) window.removeEventListener('tweakchange', this._onTweakChange);
     }
 
-    attributeChangedCallback() {
+    attributeChangedCallback(name) {
+      if (name === 'data-motion') { this._onMotionChange(); return; }
       if (this._canvas) {
         this._canvas.style.width = this.designWidth + 'px';
         this._canvas.style.height = this.designHeight + 'px';
@@ -1107,7 +1132,9 @@
         // in connectedCallback that sets data-deck-active on every slide.
         '*, *::before, *::after { animation-delay: -99s !important; animation-duration: .001s !important; ' +
         'animation-iteration-count: 1 !important; animation-fill-mode: both !important; ' +
-        'animation-play-state: running !important; transition-duration: 0s !important; } }';
+        'animation-play-state: running !important; transition-duration: 0s !important; } ' +
+        // A loop prints its still pose, even in a print taken without beforeprint (USAGE (i)).
+        'deck-stage [data-loop] { animation: none !important; } }';
     }
 
     /** Additive-build support styles. Like the print-page rule, this must
@@ -1140,13 +1167,72 @@
         'deck-stage [data-deck-under] [data-chrome] { visibility: hidden !important; }\n' +
         // Instant arrival (back-step / deep link / jump): entrance
         // animations complete in 0s — fill-mode lands them on their end
-        // state, so the composite appears fully built.
-        'deck-stage [data-deck-static], deck-stage [data-deck-static] * { animation-duration: 0s !important; animation-delay: 0s !important; }\n' +
+        // state, so the composite appears fully built. A loop is not an
+        // entrance: it keeps running (USAGE (i)).
+        'deck-stage [data-deck-static]:not([data-loop]), deck-stage [data-deck-static] :not([data-loop]) { animation-duration: 0s !important; animation-delay: 0s !important; }\n' +
         // Belt for a print snapshot taken without beforeprint having
         // cleared the attributes.
         '@media print { deck-stage [data-deck-under] [data-chrome] { visibility: visible !important; } }';
     }
 
+    /** Loop styles (USAGE (i)), in the DOCUMENT stylesheet for the same
+     *  reason as the build styles. --loop is registered as not inherited,
+     *  so a loop's animation never reaches the elements inside it. The rule
+     *  is :where() — no weight — so a deck's own rule for the element wins
+     *  (a stylesheet that animates pieces can add var(--loop) to its list). */
+    _syncLoopStyleRule() {
+      const id = 'deck-stage-loop-css';
+      let tag = document.getElementById(id);
+      if (!tag) {
+        tag = document.createElement('style');
+        tag.id = id;
+      }
+      (document.body || document.head).appendChild(tag);
+      tag.textContent =
+        '@property --loop { syntax: "*"; inherits: false; }\n' +
+        ':where(deck-stage [data-deck-loop] [data-loop]) { animation: var(--loop, none); }';
+    }
+
+    /** Whether loops run: not with motion off, under reduced motion, or in print. */
+    _loopsRun() {
+      return this.getAttribute('data-motion') !== 'off' && !REDUCED_MQ.matches && !this._printing;
+    }
+
+    /** data-deck-loop on the slides whose loops run: the one shown and the layers under it. */
+    _syncLoops() {
+      const run = this._loopsRun();
+      this._slides.forEach((s) => {
+        if (run && (s.hasAttribute('data-deck-active') || s.hasAttribute('data-deck-under'))) s.setAttribute('data-deck-loop', '');
+        else s.removeAttribute('data-deck-loop');
+      });
+    }
+
+    /** One clock for every loop: each loop (an endless animation of a
+     *  data-loop element) on a slide whose loops run starts at the page's
+     *  start, so the same loop on the next slide (the same picture, drawn
+     *  again) goes on where this one is. Nothing else is touched: a slide
+     *  without loops is never asked for its animations. */
+    _lockLoops() {
+      for (const s of this._slides) {
+        if (!s.hasAttribute('data-deck-loop') || typeof s.getAnimations !== 'function' || !s.querySelector('[data-loop]')) continue;
+        for (const a of s.getAnimations({ subtree: true })) {
+          if (a.playState === 'paused' || a.startTime === 0 || !a.effect) continue;
+          const t = a.effect.target;
+          if (t && t.hasAttribute && t.hasAttribute('data-loop') && a.effect.getTiming().iterations === Infinity) a.startTime = 0;
+        }
+      }
+    }
+
+    /** Motion turned on or off (data-motion, or the reduced-motion setting): the slide shown keeps its place; with
+     *  motion off it lands at once (static), and loops start or stop. */
+    _onMotionChange() {
+      if (!this._slides.length) return;
+      const s = this._slides[this._index];
+      if (s && this.getAttribute('data-motion') === 'off') s.setAttribute('data-deck-static', '');
+      this._syncLoops();
+      this._lockLoops();
+    }
+
     _onSlotChange() {
       // Self-mutate path already reconciled synchronously and emitted
       // slidechange; skip the async slotchange it caused.
@@ -1255,6 +1341,7 @@
         else s.removeAttribute('data-deck-active');
       });
       this._applyChainState(prev, curr);
+      this._syncLoops();
       if (this._countEl) this._countEl.textContent = String(curr + 1);
       // Follow-scroll on every navigation (init deep-link, keyboard, click,
       // tap, external goTo) — the only time we *don't* want the rail to
@@ -1288,6 +1375,8 @@
       }
 
       this._prevIndex = curr;
+      // after the listeners: what they changed on the slide is in step too
+      this._lockLoops();
       if (showOverlay) this._flashOverlay();
     }
 
@@ -1317,9 +1406,10 @@
       const additive = base !== curr;
       const sameChain = prev >= 0 && prev < this._slides.length
         && bases[prev] === bases[curr];
-      let instant = false;
+      // with motion off every arrival lands at once (USAGE (j))
+      let instant = this.getAttribute('data-motion') === 'off';
       if (additive) {
-        instant = !(prev === this._prevPlayable(curr) && prev >= base);
+        instant = instant || !(prev === this._prevPlayable(curr) && prev >= base);
       } else if (sameChain && prev > curr) {
         instant = true;
       }
@@ -1734,6 +1824,7 @@
       // but don't let stale nav attributes ride along either).
       clone.removeAttribute('data-deck-under');
       clone.removeAttribute('data-deck-static');
+      clone.removeAttribute('data-deck-loop');
       clone.querySelectorAll('[id]').forEach((el) => el.removeAttribute('id'));
       // Neuter heavy media; replace <video> with its poster so the box
       // keeps a visual. <iframe>/<audio> become empty placeholders.

package/video.d.ts

@@ -19,8 +19,12 @@ export interface VideoDriver {
   shot(file: string): Promise<unknown>;
   close(): Promise<unknown> | unknown;
 }
-/** What a settled click shows that spills: text out of its box, a lit piece (or the chrome) past the slide's edge. */
-export interface SlideSpill { kind: 'spills' | 'outside'; piece: string | null; text: string; dx: number; dy: number }
+/**
+ * What a settled click shows that spills: text out of its box, a lit piece (or the chrome) past the slide's edge; and
+ * endless animations that are not deck-stage loops: one shown here ('loose-loop'), or running on a slide no one sees
+ * ('hidden-loop': `slide`, 1-based, and `count`; `piece` names their pieces).
+ */
+export interface SlideSpill { kind: 'spills' | 'outside' | 'loose-loop' | 'hidden-loop'; piece: string | null; text: string; dx: number; dy: number; slide?: number; count?: number }
 /** The <deck-stage> driver: the video's port, and `measure(n)` — click n as it settles, measured (the layout check). */
 export interface DeckStageDriver extends VideoDriver {
   measure(n: number): Promise<SlideSpill[]>;
@@ -47,7 +51,7 @@ export function renderVideo(options: {
 }): Promise<{ video: string; length: number; cues: number; chapters: Chapters; plan: PlannedClick[] }>;
 /** The driver for storydeck's <deck-stage> pages, with Playwright's `chromium`. */
 export function deckStageDriver(options: { chromium: unknown; executablePath?: string; viewport?: { width: number; height: number }; hide?: string[]; /** keep the page off the network: it loads only its own file and inline data (OFFLINE) */ offline?: boolean }): DeckStageDriver;
-/** Runs in the page: what spills on the slide shown, its animations finished first (deckStageDriver · measure). */
+/** Runs in the page: what spills on the slide shown (its animations finished first), and endless animations that are not loops (deckStageDriver · measure). */
 export function measureSlide(): SlideSpill[];
 /** How an offline page is run: the browser's launch args and the page context's options (see deckStageDriver's `offline`). */
 export const OFFLINE: { readonly args: readonly string[]; readonly context: { readonly offline: true; readonly serviceWorkers: 'block' } };