footprint-storydeck 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # 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,
+  chapters, the voice cache) comes from `footprint-story` 0.3.0, the same package under its new name: what StoryDeck
+  and footprint-storyreel share, now with a `/motion` door too. Nothing a deck says, shows or voices changes. A project
+  that imports `footprint-narration` itself beside StoryDeck should move to `footprint-story` (the two doors export
+  exactly what they did).
+
 ## 0.8.0 — a part can have its own look (data-theme)
 
 - **A part can have its own look: `data-theme`.** `<section … data-theme="ledger">` in clicks.html puts

package/README.md

@@ -240,7 +240,7 @@ through it the same way.
 A talk lives on after the room: someone opens the deck alone, or it becomes a video. The words were in the
 speaker notes all along, so narration is data on each click, and the library turns it into speech, captions and
 timing — the same words, three uses. The rules underneath — what a voice says for a number or a symbol, the clip
-cache, the captions and YouTube's chapter rule — are [footprint-narration](https://github.com/footprintjs/footprint-narration)'s,
+cache, the captions and YouTube's chapter rule — are [footprint-story](https://github.com/footprintjs/footprint-story)'s,
 shared with footprint-storyreel; StoryDeck adds what is the deck's own:
 
 - **what the voice says** — `narrationText(notes)`: the notes as a voice reads them. An acronym stays as written
@@ -249,7 +249,7 @@ shared with footprint-storyreel; StoryDeck adds what is the deck's own:
   another script its reading), numbers become words, a lone symbol that means something is said (`SAY`: & + = < > ×
   % and Greek letters), any other word without a letter is a pause that keeps its sentence end (a forced aligner
   needs letters in every word), and a line after `[draft]` (a bridge you wrote for the deck) is said, and shown apart;
-- **a clip per click, cached by what it says** — `footprint-narration/voice` (Node). A clip's key is a hash of the
+- **a clip per click, cached by what it says** — `footprint-story/voice` (Node). A clip's key is a hash of the
   voice settings and the exact words, so editing one note re-voices that click and nothing else, and an interrupted
   run keeps every batch it finished. The voice is a port (`{ name, synthesize(scenes, { work }) }`); `chatterboxKit`
   is one adapter — a local voice kit (Chatterbox, words aligned with MMS_FA; nothing is uploaded). `footprint-storydeck/voice`
@@ -259,7 +259,7 @@ shared with footprint-storyreel; StoryDeck adds what is the deck's own:
   the browser's where a click has none — captions lighting sentence by sentence (styles: `footprint-storydeck/narration.css`).
 
 ```js
-import { voiceClips, chatterboxKit } from 'footprint-narration/voice';
+import { voiceClips, chatterboxKit } from 'footprint-story/voice';
 import { narrationText } from 'footprint-storydeck/narration';
 import { embedClips } from 'footprint-storydeck/voice';
 import { notesData, notesRuntime, listenRuntime } from 'footprint-storydeck/narration-html';
@@ -290,7 +290,7 @@ would drop one entrance frame in six at 30 fps, and a test with the real ffmpeg
 ```js
 import { chromium } from 'playwright-core';
 import { renderVideo, deckStageDriver } from 'footprint-storydeck/video';
-import { clipFor } from 'footprint-narration/voice';
+import { clipFor } from 'footprint-story/voice';
 import { narrationText, writtenText } from 'footprint-storydeck/narration';
 
 const steps = clicks.map(c => {
@@ -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
@@ -547,9 +576,9 @@ const { theme, toggle, setTheme } = useTheme();   // flips an html class + persi
 | `planFocus` · `focusStep` · `readFocus` · `FOCUS` | focus: per click, what it is about and what happens to the rest (also `footprint-storydeck/focus`) |
 | `readPieces` · `readStep` · `drawFocus` · `wrapStage` · `slideClass` · `focusOverlay` · `focusRuntime` | focus, written into slide HTML (also `footprint-storydeck/focus-html`; styles in `footprint-storydeck/focus.css`) |
 | `idleTour` · `tourPlan` · `tourText` | tour: a deck (or a figure) that shows its point while nobody is using it, and its plan in data and in one line (also `footprint-storydeck/tour`) |
-| `narrationText` · `writtenText` | narration: what a click says (also `footprint-storydeck/narration`); the rules beneath, sentences, captions and chapters are `footprint-narration`'s |
+| `narrationText` · `writtenText` | narration: what a click says (also `footprint-storydeck/narration`); the rules beneath, sentences, captions and chapters are `footprint-story`'s |
 | `notesData` · `notesRuntime` · `listenRuntime` | narration in the page: notes, presenter window, listen mode (also `footprint-storydeck/narration-html`; styles in `footprint-storydeck/narration.css`) |
-| `embedClips` | `footprint-storydeck/voice` (Node only): a deck's clips inside one page; the clip cache, the voice port and its local-kit adapter are `footprint-narration/voice`'s |
+| `embedClips` | `footprint-storydeck/voice` (Node only): a deck's clips inside one page; the clip cache, the voice port and its local-kit adapter are `footprint-story/voice`'s |
 | `renderVideo` · `planVideo` · `deckStageDriver` · `ffmpegMajor` | `footprint-storydeck/video` (Node only, ffmpeg 5.0+): the deck as a narrated video, with captions and chapters |
 | `exportPptx` · `pptxParts` · `zip` · `unzip` · `checkPptx` | `footprint-storydeck/pptx` (Node only): the deck as a PowerPoint file — a slide per click, its picture, notes and clip — through a footprintjs flowchart that records why |
 | `loadDeck` · `buildDeck` · `serveDeck` · `outline` · `reviewClick` · `checkDeck` · `layoutCheck` · `initDeck` · `serveMcp` · `runCli` | `footprint-storydeck/deck` (Node only): a deck folder made into one page, served for editing, read back as text — the `storydeck` command (also `npx footprint-storydeck`); its page's base styles are `footprint-storydeck/deck.css` |

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");