footprint-storydeck 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.0 — a path: the subject piece after piece along a route
+
+- **A fourth kind of focus strategy, the order — how the subject comes on — and its first strategy, `path`.**
+  A click lights its subject piece after piece along a route, as a request travels it (node, wire, node): each lit
+  piece on it lights at its turn, `step` seconds apart (0.35), and glows as it is reached — on every forward click,
+  so the request travels again; `route` names the order (default, and for an empty `route`: the click's `on`, or its
+  `in`), a name shared by several pieces is one turn, a name with nothing lit takes none (a greyed piece never waits
+  or glows grey), and a lit piece off the route lights at once. A click that asks for a path with no order at all
+  (`on: ['*']`) is refused, naming the fix: write the pieces in the order they light. A `line` names the route, shown
+  as the last turn starts (`lineAt` places it; default the area's bottom left; a blank one is none). Borrowed from the isometric figures where a
+  request lights its path.
+- Everything on a path keeps its turn. A piece lit from grey plays one animation, `sdLightPulse`, whose filter lists
+  the same functions at every keyframe, so it glides into colour and the glow (a light and a pulse on one filter
+  would flash); a ring (`hot`) comes .3 s after its piece's turn; a dashed twin stays until its solid twin's turn,
+  then steps aside, so the wire is never missing; and under a new blur the whole path, line included, waits .4 s for
+  it, as what a click adds does. One variable carries a piece's moment, `--sd-turn`.
+- `focusStep` gives each piece its `path` (its turn's delay, or null) and `twinTurn` (stepping aside for a lit twin
+  on the route: that twin's turn, or null), and the look its `path` ({turns, step, done, line, lineAt}; `line` '' and
+  `lineAt` null when none is given). What an order's `route()` gives — a deck's own too — is checked (names, a
+  `step` of 0–5 s, a text `line`, a `lineAt` of 'x y' or null) and refused with the strategy's name and the fix,
+  and is only read, never written to (a frozen result is fine). `focusOverlay` writes the line; `focus.css` animates
+  the path only on a forward click, never under reduced motion (`--sd-glow` colours the pulse). A click without a
+  path is drawn byte for byte as 0.3.0 drew it.
+
 ## 0.3.0 — `footprint-storydeck`; the narration rules move into footprint-narration
 
 - **The package is renamed `footprint-storydeck`** — the footprintjs family's name, as footprint-storyreel and

package/README.md

@@ -74,9 +74,24 @@ decision every click makes again, so it is data on the click, and the library do
 | mover | `left` · `right` · `up` · `down` | the context steps aside that way, smaller (`scale`), and the subject grows into the room it leaves (`grow`, `fill`, `gap`, `align`; `move: 'aside'` keeps the subject where it is) |
 | mover | `place` | named groups moved by the amounts you give (`groups: 'page floor: -90 -200 0.5 \| tl: 0 -230 1.1 @ 960 968'`): a layout you art-direct, still animated from wherever the last click left it |
 | overlay | `blur` | everything outside the subject's frame is blurred; a frame (and a `label`) on it, or on the `rect`s you give |
+| order | `path` | the subject comes on piece after piece along a route, as a request travels it — node, wire, node: each lit piece on it lights at its turn (`step` seconds apart, 0.35) and glows as it is reached; `route` names the order (default — and for an empty `route` — the click's `on`, or its `in`); a greyed piece on it takes no turn, and a route with no order at all (`on: ['*']`) is refused; a `line` ("agent → MCP → gateway") names the route, shown as the last turn starts. A deck's own `filter` on a path piece is not carried through the glow: it steps where the glow starts and ends |
 
 `'left blur'` reads: the context steps aside to the left, greyed, under a blur, and the subject grows on
-the right, framed. Bring your own strategy of any kind (`strategies: { name: { kind, … } }`).
+the right, framed. `'path grey'` lights a route in turn and greys the rest. Bring your own strategy of any kind
+(`strategies: { name: { kind, … } }`); what your own order's `route()` gives is checked like the built-in's — piece
+names, a `step` of 0–5 s, a text `line`, a `lineAt` of `'x y'` — and refused with the fix when it is not.
+
+**A path, on a diagram of an app.** An architecture slide is a route more often than a picture: who calls whom.
+Write the click's `on` in the order a request travels it, wires included, and the path lights it that way:
+
+```html
+<step data-on="agent link-mcp mcp link-gw gw" data-focus="path" data-focus-line="agent → MCP → gateway"></step>
+```
+
+Everything on a path keeps its turn: a piece lit from grey glides into colour and the glow in one animation (two
+on one `filter` would flash), its ring (`hot`) comes .3 s after its turn, and a dashed twin stays until its solid
+twin's turn and only then steps aside, so the wire is never missing. Under a new blur the whole path, line included,
+waits .4 s for it, as what a click adds does.
 
 The plan is plain data (each piece's state, what changed since the last click, how far it moved), so a
 renderer only draws it. `footprint-storydeck/focus-html` writes it into slide HTML at build time and

package/focus.css

@@ -9,7 +9,8 @@
  * its own entrance, say — wins without !important.
  *
  * 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-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).
  */
 
 /* a piece's state: on (in colour), dim (the context: greyed in place, or hidden, or kept), gone */
@@ -37,10 +38,16 @@
   color: var(--sd-accent, var(--yellow, #facc15)); }
 @media print { .sd-veil { display: none; } }
 
+/* a path: its line, naming the route, in slide px (it shows once the route is done) */
+.sd-path-line { position: absolute; pointer-events: none; white-space: nowrap; font: 600 22px/1 var(--mono, ui-monospace, monospace);
+  letter-spacing: .04em; color: var(--sd-accent, var(--yellow, #facc15)); }
+
 /* motion: each change fills its own slot, so a piece that moves AND lights does both */
 @property --sd-a-state { syntax: '*'; inherits: false; }
 @property --sd-a-move { syntax: '*'; inherits: false; }
 @property --sd-a-hot { syntax: '*'; inherits: false; }
+@property --sd-a-path { syntax: '*'; inherits: false; }
+@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); } }
 @keyframes sdArrive { from { opacity: 0; } }
@@ -52,6 +59,12 @@
 @keyframes sdStage { from { translate: var(--sd-tx0, 0px) var(--sd-ty0, 0px); scale: var(--sd-ts0, 1); } }
 @keyframes sdVeilIn { from { opacity: 0; } }
 @keyframes sdVeilOut { from { opacity: 1; } to { opacity: 0; } }
+@keyframes sdPulse { 40% { filter: drop-shadow(0 0 14px var(--sd-glow, var(--sd-accent, var(--yellow, #facc15)))) brightness(1.2); } }
+/* a piece that lights from grey at its turn: sdLight and sdPulse as ONE animation. Two on one filter swap their lists
+   (grayscale ↔ drop-shadow brightness) at a jump — a flash; here every keyframe lists the same functions in the same
+   order, so the filter glides from grey into colour and the glow, and back to the plain style (the implicit end) */
+@keyframes sdLightPulse { from { opacity: var(--sd-dim-opacity, .32); filter: grayscale(1) drop-shadow(0 0 0 transparent) brightness(1); }
+  40% { filter: grayscale(0) drop-shadow(0 0 14px var(--sd-glow, var(--sd-accent, var(--yellow, #facc15)))) brightness(1.2); } }
 @media screen and (prefers-reduced-motion: no-preference) {
   .sd-enter { --sd-a-state: sdEnter .6s var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) var(--sd-delay, 0s) both; }
   .sd-arrive { --sd-a-state: sdArrive .6s ease both; }
@@ -62,10 +75,21 @@
   .sd-relook.sd-from-hide { --sd-a-state: sdArrive .6s ease both; }
   .sd-relook.sd-from-keep { --sd-a-state: sdFade .7s ease both; }
   .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)) .3s 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-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) {
-    animation: var(--sd-a-state, sdNone 0s), var(--sd-a-move, sdNone 0s), var(--sd-a-hot, sdNone 0s); }
+  /* 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. */
+  :is(.sd-path, .sd-twin-turn, .sd-path-line) { --sd-turn: var(--sd-path-delay, 0s); }
+  .sd-focus-new :is(.sd-path, .sd-twin-turn, .sd-path-line) { --sd-turn: calc(var(--sd-path-delay, 0s) + .4s); }
+  .sd-path { --sd-a-path: sdPulse .9s ease var(--sd-turn); }
+  .sd-path.sd-enter { --sd-a-state: sdEnter .6s var(--sd-ease, cubic-bezier(.2, .7, .2, 1)) var(--sd-turn) both; }
+  .sd-path.sd-arrive { --sd-a-state: sdArrive .6s ease var(--sd-turn) both; }
+  .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 var(--sd-turn) both; }
+  :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); }
+  :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; }
   :where([data-deck-active]:not([data-sd-instant]):not([data-deck-static])) .sd-frame.sd-new { animation: sdArrive .5s ease .35s both; }

package/focus.d.ts

@@ -53,11 +53,19 @@ export interface FocusContext {
   readonly options: Readonly<Record<string, unknown>>;
 }
 
-/** A focus strategy: a look (how the context looks), a mover (where things go) or an overlay (what lies over the slide). */
+/**
+ * A route, as an order strategy gives it — checked, and refused (naming the strategy and the fix) when it is not this:
+ * the names in turn (each one's LIT pieces take the next turn; a name with nothing lit takes none), the seconds between
+ * two turns (0–5), and the line that names it, with where it goes ('x y', slide px). The strategy's object is only read.
+ */
+export interface FocusRoute { readonly names: readonly string[]; readonly step: number; readonly line?: string; readonly lineAt?: string | null }
+
+/** A focus strategy: a look (how the context looks), a mover (where things go), an overlay (what lies over the slide) or an order (how the subject comes on). */
 export type FocusStrategy =
   | { readonly name?: string; readonly kind: 'look'; readonly look: 'grey' | 'hide' | 'keep' }
   | { readonly name?: string; readonly kind: 'mover'; place(ctx: FocusContext): { stage?: FocusGroup; subject?: FocusGroup; context?: FocusGroup; groups?: { names: readonly string[]; g: FocusGroup | null }[] } }
-  | { readonly name?: string; readonly kind: 'overlay'; cover(ctx: { subjectOnSlide: FocusBox | null; canvas: { w: number; h: number }; options: Readonly<Record<string, unknown>> }): { rects: number[][]; label?: string; out?: number[][] } | null };
+  | { readonly name?: string; readonly kind: 'overlay'; cover(ctx: { subjectOnSlide: FocusBox | null; canvas: { w: number; h: number }; options: Readonly<Record<string, unknown>> }): { rects: number[][]; label?: string; out?: number[][] } | null }
+  | { readonly name?: string; readonly kind: 'order'; route(ctx: { names: readonly string[]; options: Readonly<Record<string, unknown>> }): FocusRoute };
 
 export interface FocusDeck {
   readonly pieces: readonly FocusPiece[];
@@ -89,6 +97,10 @@ export interface FocusPieceLook {
   readonly from: FocusMove | null;
   /** It stepped aside for its lit twin. */
   readonly twinOff: boolean;
+  /** Stepping aside for a lit twin on a path: the seconds until that twin's turn, when it goes (the first, for several); null when it goes at once (a lit twin off the route) or does not step aside on this click. */
+  readonly twinTurn: number | null;
+  /** On a path: the seconds its turn waits (0 for the first); null when it takes no turn — not on the route, or not lit. */
+  readonly path: number | null;
 }
 
 export interface FocusLook {
@@ -97,6 +109,8 @@ export interface FocusLook {
   readonly stage: { readonly move: { s: number; x: number; y: number } | null; readonly from: { s: number; x: number; y: number } | null } | null;
   /** The blur: 'in-new' when the last click had none, 'in' while it stays, 'out' as it melts away; frameNew when its frame moved or appeared. */
   readonly overlay: { readonly rects: readonly (readonly number[])[]; readonly label: string; readonly phase: 'in-new' | 'in' | 'out'; readonly frameNew: boolean } | null;
+  /** A path: how many turns, the seconds between two, when the last starts (done), and its line ('' for none) and where it goes (null: the area's bottom left); null when no lit piece took a turn. */
+  readonly path: { readonly turns: number; readonly step: number; readonly done: number; readonly line: string; readonly lineAt: string | null } | null;
   readonly strategies: readonly string[];
   /** The subject where it ends up, on the slide. */
   readonly subject: FocusBox | null;
@@ -105,7 +119,7 @@ export interface FocusLook {
 /** The state a click leaves, to start the next from. Opaque. */
 export type FocusState = { readonly __focusState: true } & Record<string, unknown>;
 
-export const FOCUS: Readonly<Record<'grey' | 'hide' | 'keep' | 'zoom' | 'left' | 'right' | 'up' | 'down' | 'place' | 'blur', FocusStrategy>>;
+export const FOCUS: Readonly<Record<'grey' | 'hide' | 'keep' | 'zoom' | 'left' | 'right' | 'up' | 'down' | 'place' | 'path' | 'blur', FocusStrategy>>;
 export function readFocus(spec: FocusSpec | undefined | null, shared?: Readonly<Record<string, unknown>>): { strategy: string; options: Record<string, unknown> }[];
 export function focusStep(prev: FocusState | null, click: FocusClick, deck: FocusDeck): { state: FocusState; look: FocusLook };
 /** `end` is null only when there are no clicks and no `start`. */

package/focus.js

@@ -2,7 +2,7 @@
 //
 // A slide of this kind is drawn once: a set of named PIECES that keep their places (a diagram, a page,
 // a timeline). Each CLICK says which pieces are there and which ones it is about — its SUBJECT; the
-// rest of what is shown is the CONTEXT. A FOCUS STRATEGY says how the two are shown. There are three
+// rest of what is shown is the CONTEXT. A FOCUS STRATEGY says how the two are shown. There are four
 // kinds, and a click takes one of each at most:
 //
 //   look     how the context looks     grey (greyed in place — the default) · hide · keep
@@ -13,6 +13,9 @@
 //                                      art-direct, still animated from wherever the last click left it)
 //   overlay  what lies over the slide  blur (everything outside the subject's frame is blurred; a frame,
 //                                      and a label if given, on the subject)
+//   order    how the subject comes on  all at once (the default) · path (piece after piece along a route —
+//                                      a request travelling node, wire, node — each lighting in turn, with
+//                                      a line that names the route if given)
 //
 // So `'left blur'` is: the context steps aside to the left, greyed, under a blur, and the subject grows on
 // the right inside a frame. A deck can bring strategies of its own (`strategies`), of any kind.
@@ -25,7 +28,7 @@
 // slide (p' = s·p + [x, y]; the identity unless the map is drawn scaled or shifted); `area` is the part
 // of the slide (slide pixels) where moved things may go — below a headline, above a footer.
 
-const KINDS = ['look', 'mover', 'overlay'];
+const KINDS = ['look', 'mover', 'overlay', 'order'];
 
 /** A box {x, y, w, h} around a list of boxes (null for none). */
 function union(boxes) {
@@ -111,6 +114,21 @@ export const FOCUS = Object.freeze({
       return {names, g: {o, s, t: [dx / view.s, dy / view.s]}};
     })};
   }}),
+  /**
+   * The subject comes on piece after piece along a route, as a request travels it: `route` names the pieces in
+   * order (default — and for an empty `route` too — the click's `on`, or its `in`, in the order written), each lit
+   * one lights `step` (0.35) s after the one before and glows as it is reached; `line` is text that names the route
+   * ("agent → MCP → gateway"), shown when the route is done, at `lineAt` (x y, slide px; default the area's bottom
+   * left). A lit piece not on the route lights at once. A route still empty (`on: ['*']` names no order) is refused.
+   */
+  path: Object.freeze({name: 'path', kind: 'order', route({names, options}) {
+    const step = num(options.step, .35);
+    if (!(step >= 0 && step <= 5)) throw new Error(`focus "path": step is the seconds between two pieces of the route (0–5), not "${options.step}"`);
+    const route = options.route === undefined || options.route === null ? [] : [].concat(options.route).flatMap(x => String(x).trim().split(/\s+/)).filter(x => x && x !== '*');
+    const order = route.length ? route : names;
+    if (!order.length) throw new Error('focus "path": the route is empty — write the pieces in the order they light, in `on` or `route` (\'*\' names no order)');
+    return {names: order, step, line: options.line ?? '', lineAt: options.lineAt ?? null};
+  }}),
   /**
    * Everything outside the frame is blurred. The frame is `rect` (slide px, x y w h; several are fine — the
    * first gets the frame and the label, the others are clear holes too) or, without one, the subject where it
@@ -145,13 +163,29 @@ function pick(focus, strategies) {
   for (const {strategy, options} of focus) {
     const s = all[strategy];
     if (!s) throw new Error(`no focus strategy "${strategy}" (there are ${Object.keys(all).join(', ')})`);
-    if (!KINDS.includes(s.kind)) throw new Error(`focus strategy "${strategy}" has kind ${JSON.stringify(s.kind)}: a strategy is a look, a mover or an overlay`);
+    if (!KINDS.includes(s.kind)) throw new Error(`focus strategy "${strategy}" has kind ${JSON.stringify(s.kind)}: a strategy is a look, a mover, an overlay or an order`);
     if (byKind[s.kind]) throw new Error(`a click takes one ${s.kind} at most: "${byKind[s.kind].name}" and "${strategy}" are both ${s.kind}s`);
     byKind[s.kind] = {s: {...s, name: s.name ?? strategy}, options, name: strategy};
   }
   return byKind;
 }
 
+/**
+ * What an order's `route()` gave, checked like its kind — a deck's own order is held to what the built-in gives —
+ * and read into a new object (the strategy's own is never written to): line '' and lineAt null when it gives none.
+ */
+function readRoute(r, strategy) {
+  const shown = v => (typeof v === 'number' || v === undefined ? String(v) : JSON.stringify(v));
+  const refuse = fix => { throw new Error(`focus "${strategy}": ${fix}`); };
+  if (!r || typeof r !== 'object') refuse(`route() gives {names, step, line?, lineAt?}, not ${shown(r)}`);
+  const {names, step, line, lineAt} = r;
+  if (!Array.isArray(names) || names.some(n => typeof n !== 'string')) refuse(`a route's names are a list of piece names, in the order they light — not ${shown(names)}`);
+  if (typeof step !== 'number' || !Number.isFinite(step) || step < 0 || step > 5) refuse(`a route's step is the seconds between two turns, a number from 0 to 5 — not ${shown(step)}`);
+  if (line !== undefined && typeof line !== 'string') refuse(`a route's line is text that names it, or left out — not ${shown(line)}`);
+  if (lineAt !== undefined && lineAt !== null && typeof lineAt !== 'string') refuse(`a route's lineAt is 'x y' in slide px, null, or left out — not ${shown(lineAt)}`);
+  return {names: [...names], step, line: line ?? '', lineAt: lineAt?.trim() ? lineAt : null};   // (a blank lineAt, an empty data-focus-line-at, is none)
+}
+
 /** Where a group move puts one piece: its reference point (the centre, or the top-left when it has no size) moves by [dx, dy], and it scales by s around it. */
 function placePiece(g, box) {
   if (!g || !box) return null;
@@ -182,7 +216,9 @@ function changeOf(st, was, look, wasLook, entering, before) {
  * One click. `prev` is the state the last click left (null on a slide's first click when the map arrives
  * fresh). `deck`: {pieces: [{keys, box, twin?}], strategies?, area?, view?, canvas?}. Returns {state, look}:
  * the state to hand the next click, and the look to draw — per piece {state, was, change, look, fromLook, hot,
- * hotIn, move, from, twinOff}, the stage's move, the overlay, and which strategies were used.
+ * hotIn, move, from, twinOff, twinTurn (stepping aside for a lit twin on a route: the seconds until that twin's
+ * turn; else null), path (a lit piece on a route: the seconds until its turn; else null)}, the stage's move, the
+ * overlay, the path ({turns, step, done, line, lineAt}, or null) and which strategies were used.
  */
 export function focusStep(prev, step, deck) {
   const {pieces, strategies = {}} = deck, canvas = deck.canvas ?? {w: 1920, h: 1080};
@@ -196,7 +232,8 @@ export function focusStep(prev, step, deck) {
   pieces.forEach((_, i) => { if (has(i, ins)) vis.add(i); if (has(i, outs)) vis.delete(i); });
   const states = pieces.map((_, i) => !vis.has(i) ? 'gone' : !on || has(i, on) || (!step.quiet && has(i, ins)) ? 'on' : 'dim');
   // A piece with a twin (a dashed wire under a solid one) steps aside while its twin is lit, so the two never show at once.
-  const twinOff = new Set(pieces.map((_, i) => i).filter(i => pieces[i].twin?.length && states[i] !== 'gone' && pieces.some((q, j) => states[j] === 'on' && j !== i && pieces[i].twin.some(t => q.keys.includes(t)))));
+  const litTwins = pieces.map((p, i) => p.twin?.length ? pieces.map((_, j) => j).filter(j => j !== i && states[j] === 'on' && p.twin.some(t => pieces[j].keys.includes(t))) : []);
+  const twinOff = new Set(pieces.map((_, i) => i).filter(i => states[i] !== 'gone' && litTwins[i].length));
   twinOff.forEach(i => { states[i] = 'gone'; });
   const chosen = pick(readFocus(step.focus, step.options), strategies);
   const look = chosen.look?.s.look ?? 'grey';
@@ -222,6 +259,21 @@ export function focusStep(prev, step, deck) {
   const subjectOnSlide = ends ? {x: ends.x * view.s + view.x, y: ends.y * view.s + view.y, w: ends.w * view.s, h: ends.h * view.s} : null;
   const cover = chosen.overlay ? chosen.overlay.s.cover({subjectOnSlide, canvas, options: chosen.overlay.options}) : null;
   const looks = pieces.map((_, i) => states[i] === 'dim' ? look : null);
+  // An order: the subject piece after piece along a route. The LIT pieces of each name on it take the next turn
+  // together — a name with nothing lit takes none, so a greyed piece never waits or glows grey; a piece named twice
+  // keeps its first turn.
+  const order = chosen.order ? readRoute(chosen.order.s.route({names: (on ?? ins).filter(x => x !== '*'), options: chosen.order.options}), chosen.order.name) : null;
+  const turnOf = new Map();
+  let turns = 0;
+  for (const name of order ? known(order.names, 'focus route: ') : []) {
+    const reached = all.filter(i => states[i] === 'on' && pieces[i].keys.includes(name) && !turnOf.has(i));
+    reached.forEach(i => turnOf.set(i, turns));
+    if (reached.length) turns += 1;
+  }
+  const delayOf = i => (turnOf.has(i) ? round(turnOf.get(i) * order.step, 3) : null);
+  // A piece stepping aside for a lit twin on the route stays until that twin's turn (the first of them to come), then
+  // goes — so the wire never goes missing while its twin waits; a lit twin off the route lights at once, and so it goes.
+  const twinTurn = i => (litTwins[i].length && litTwins[i].every(j => turnOf.has(j)) ? Math.min(...litTwins[i].map(delayOf)) : null);
   // What changed since the last click: only that moves. A piece that leaves keeps how it looked and where it
   // stood, so it fades out from there instead of jumping home in colour first.
   const before = prev && !step.fresh ? prev : null;
@@ -233,7 +285,8 @@ export function focusStep(prev, step, deck) {
     const from = stood, moved = st !== 'gone' && was !== 'gone' && !!before && !sameMove(from, moves[i]);
     return {state: st, was, change, look: leaving ? wasLook : looks[i], fromLook: change === 'relook' ? wasLook : null,
       hot: hotNow.has(i), hotIn: hotNow.has(i) && (!before || !before.hot.has(i)),
-      move: leaving ? stood : st === 'gone' ? null : moves[i], from: moved ? from ?? {dx: 0, dy: 0, s: 1} : null, twinOff: twinOff.has(i)};
+      move: leaving ? stood : st === 'gone' ? null : moves[i], from: moved ? from ?? {dx: 0, dy: 0, s: 1} : null, twinOff: twinOff.has(i),
+      twinTurn: leaving && twinOff.has(i) ? twinTurn(i) : null, path: delayOf(i)};
   });
   const stageMoved = !!before && !sameStage(before.stage, stage);
   // The blur: new only when the last click had none (a blur that moves to another subject stays, and only its
@@ -243,6 +296,7 @@ export function focusStep(prev, step, deck) {
   return {
     state: {vis, states, moves, stage, hot: hotNow, cover, looks},
     look: {pieces: out, stage: stage || stageMoved ? {move: stage, from: stageMoved ? before.stage ?? {s: 1, x: 0, y: 0} : null} : null, overlay,
+      path: turns ? {turns, step: order.step, done: round((turns - 1) * order.step, 3), line: order.line, lineAt: order.lineAt} : null,
       strategies: Object.values(chosen).map(c => c.name), subject: subjectOnSlide},
   };
 }

package/focusHtml.d.ts

@@ -7,13 +7,17 @@ import type { FocusClick, FocusLook, FocusPiece } from './focus';
 export function readPieces(html: string, options?: { attr?: string }): { html: string; pieces: FocusPiece[] };
 /** A click written as attributes (data-in, data-out, data-on, data-hot, data-quiet, data-focus, data-focus-* → camelCased options). */
 export function readStep(attrs: string): FocusClick;
-/** That HTML, each piece dressed for this click's look (classes from focus.css, its move as CSS variables). */
+/**
+ * That HTML, each piece dressed for this click's look (classes from focus.css, its move as CSS variables). On a path, a
+ * piece's moment rides as `--sd-path-delay`: its turn (`sd-path`), or, stepping aside for its lit twin, that twin's
+ * (`sd-twin-turn`); focus.css adds .4 s under a new blur. A click without a path is drawn exactly as before.
+ */
 export function drawFocus(html: string, look: FocusLook): string;
 /** The pieces inside the stage the view moves (a zoom); unchanged when nothing moves the view. Put it in the map's own box. */
 export function wrapStage(inner: string, look: FocusLook): string;
 /** Classes for the slide around a click: 'sd-focus-new' while its blur comes in, else ''. */
 export function slideClass(look: FocusLook): string;
-/** The click's blur, holes and labelled frame, in slide px — outside the map's box (empty when it has none). */
+/** The overlay of a click in slide px — the blur, its frame and label, and a path's line (once its route is done, .4 s later under a new blur) — put outside the map's box; '' when the click has none. */
 export function focusOverlay(look: FocusLook, options?: { canvas?: { w: number; h: number }; area?: readonly [number, number, number, number] }): string;
 /** Runs in the page; call it once, at any time: only a forward click animates; a jump or a step back lands at once. */
 export function focusRuntime(): void;

package/focusHtml.js

@@ -8,7 +8,8 @@
 //
 // Pieces are read from their inline style (left/top/width/height in px, or 0; an <svg>'s width/height
 // attributes too): a piece without left/top keeps its place whatever the strategy, and one without a
-// size moves by its top-left corner. data-twin="name …" makes a piece step aside while its twin is lit.
+// size moves by its top-left corner. data-twin="name …" makes a piece step aside while its twin is lit (on a
+// path, at that twin's turn).
 // focus.css draws the classes; call focusRuntime() once in the page, so only a forward click animates.
 
 const PIECE = attr => new RegExp(`<([a-zA-Z][\\w-]*)\\b([^>]*?)\\s${attr}=(["'])(.*?)\\3([^>]*)>`, 'g');
@@ -69,9 +70,13 @@ function pieceLook(p) {
   if (p.hot) cls.push('sd-hot');
   if (p.hotIn) cls.push('sd-hot-in');
   if (p.twinOff) cls.push('sd-twin-off');
+  const onPath = p.path !== null && p.path !== undefined, twinTurn = p.twinTurn !== null && p.twinTurn !== undefined;
+  if (twinTurn) cls.push('sd-twin-turn');   // it steps aside at its lit twin's turn on the route
+  if (onPath) cls.push('sd-path');
   const vars = [];
   if (p.move) { cls.push('sd-moved'); vars.push(`--sd-dx:${p.move.dx}px`, `--sd-dy:${p.move.dy}px`, `--sd-s:${p.move.s}`); }
   if (p.from) { cls.push('sd-move'); vars.push(`--sd-dx0:${p.from.dx}px`, `--sd-dy0:${p.from.dy}px`, `--sd-s0:${p.from.s}`); }
+  if (onPath || twinTurn) vars.push(`--sd-path-delay:${onPath ? p.path : p.twinTurn}s`);   // its moment on the route: its turn, or its twin's
   // The point it scales around, inline, so no stylesheet's transform-origin can move it off the planned place.
   const ref = p.move ?? p.from;
   if (ref) { if (ref.origin === 'top-left') cls.push('sd-origin-tl'); vars.push(`transform-origin:${ref.origin === 'top-left' ? '0 0' : '50% 50%'}`); }
@@ -124,19 +129,28 @@ function veilPath([x0, y0, x1, y1], rects) {
   return runs.join(' ');
 }
 
+/** A path's line — the text naming its route — in slide pixels, shown once the route is done (its moment is `done`). */
+function pathLine(look, [x0, , , y1]) {
+  const p = look.path;
+  if (!p?.line) return '';
+  const at = p.lineAt ? String(p.lineAt).trim().split(/[\s,]+/).map(Number) : [x0 + 24, y1 - 56];
+  if (at.length !== 2 || at.some(n => !Number.isFinite(n))) throw new Error(`focus "path": lineAt is x y in slide px, not "${p.lineAt}"`);
+  return `<div class="sd-path-line" style="left:${at[0]}px;top:${at[1]}px;--sd-path-delay:${p.done}s">${esc(p.line)}</div>`;
+}
+
 /**
- * The overlay of a click — a blur with holes, a frame and its label — in slide pixels: put it outside the
- * map's box. `area` ([x0, y0, x1, y1]) limits the blur, so a headline above it stays clear. Empty when the
- * click has none.
+ * The overlay of a click — a blur with holes, a frame and its label, and a path's line — in slide pixels: put
+ * it outside the map's box. `area` ([x0, y0, x1, y1]) limits the blur, so a headline above it stays clear.
+ * Empty when the click has none.
  */
 export function focusOverlay(look, {canvas = {w: 1920, h: 1080}, area} = {}) {
-  const o = look.overlay;
-  if (!o || !o.rects.length) return '';
+  const o = look.overlay, line = pathLine(look, area ?? [0, 0, canvas.w, canvas.h]);
+  if (!o || !o.rects.length) return line;
   const path = veilPath(area ?? [0, 0, canvas.w, canvas.h], o.rects);
   const veil = `<div class="sd-veil sd-veil-${o.phase}" style="width:${canvas.w}px;height:${canvas.h}px;clip-path:path(nonzero,'${path}')"></div>`;
-  if (o.phase === 'out') return veil;
+  if (o.phase === 'out') return veil + line;
   const [x, y, w, h] = o.rects[0];
-  return `${veil}<div class="sd-frame${o.frameNew ? ' sd-new' : ''}" style="left:${x}px;top:${y}px;width:${w}px;height:${h}px">${o.label ? `<span>${esc(o.label)}</span>` : ''}</div>`;
+  return `${veil}<div class="sd-frame${o.frameNew ? ' sd-new' : ''}" style="left:${x}px;top:${y}px;width:${w}px;height:${h}px">${o.label ? `<span>${esc(o.label)}</span>` : ''}</div>${line}`;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprint-storydeck",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "One source, many lenses — render structured content as a Read article, a Scroll (scrollytelling) story, or a Watch deck.",
   "type": "module",
   "license": "MIT",

package/plugin/skills/storydeck/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: storydeck
-description: Build, focus, narrate and film talks and posts with StoryDeck — one source shown as a Read article, a Scroll story or a Watch deck; per-click focus on a diagram (grey, zoom, left/right, place, blur); narration from the speaker notes (a clip per click in a voice, cached by its words; notes, presenter and listen mode in the page; captions and chapters); and a narrated video for YouTube. Use when creating or editing a StoryDeck post or deck, adding focus to a diagram slide, voicing a talk, or rendering a talk as a video.
+description: Build, focus, narrate and film talks and posts with StoryDeck — one source shown as a Read article, a Scroll story or a Watch deck; per-click focus on a diagram (grey, zoom, left/right, place, blur, path); narration from the speaker notes (a clip per click in a voice, cached by its words; notes, presenter and listen mode in the page; captions and chapters); and a narrated video for YouTube. Use when creating or editing a StoryDeck post or deck, adding focus to a diagram slide, voicing a talk, or rendering a talk as a video.
 ---
 
 # StoryDeck: one source, many lenses — and a deck that tells itself
@@ -48,10 +48,15 @@ const { looks } = planFocus([
 ], { pieces, area });
 const slides = looks.map(look => `<section class="${slideClass(look)}"><div class="map">${wrapStage(drawFocus(html, look), look)}</div>${focusOverlay(look, { area })}</section>`);
 // in the page, once: `(${focusRuntime})()` — only a forward click animates; a jump lands at once
+// A route (who calls whom): `{ on: ['agent', 'link-mcp', 'mcp', 'link-gw', 'gw'], focus: 'path', options: { line: 'agent → MCP → gateway' } }`
+// lights it piece after piece, wires included, in the order written — lit pieces only; `on: ['*']` names no order and is refused.
 ```
 
 Strategies, one of each kind at most: look `grey` (default) · `hide` · `keep`; mover `zoom` · `left` ·
-`right` · `up` · `down` · `place` (named groups moved by amounts you art-direct); overlay `blur`.
+`right` · `up` · `down` · `place` (named groups moved by amounts you art-direct); overlay `blur`; order `path` (the
+subject lit piece after piece along a route, a `line` naming it; write `on` — or `route` — in the order the pieces
+light: only lit pieces take a turn, a ring and a dashed twin keep their piece's turn, and a new blur delays the
+whole path .4 s).
 
 **Narrate a deck in a voice.**