footprint-storydeck 0.8.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,92 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.10.0 — a part arrives with a change of picture, and a deck a viewer can explore
4
+
5
+ - **A part arrives with a change of picture: `data-enter`.** `<section … data-enter="push" data-enter-from="right">`
6
+ plays one of the editor's changes StoryReel's films use (footprint-story/motion's table: the same names, settings,
7
+ lengths and eases) as the deck steps into the part: cut, fade, dip, wipe, split, iris, push, slide, whip or zoom,
8
+ each with its settings as `data-enter-*` (`from`, `line`, `at` as "x y" in slide px or "centre", `color`) and
9
+ `data-enter-seconds` / `data-enter-ease`. The build samples each distinct change once into keyframes for both slides
10
+ (30 a second, the same curves a film draws); the page plays them with Web Animations only on a forward step into the
11
+ part — a jump, a step back, reduced motion and motion off land at once — keeping the slide it leaves in view until
12
+ it ends, and a video steps them like any animation. A dip shows its colour behind both slides (black unless
13
+ `data-enter-color` says otherwise): `<deck-stage>` now paints what shows behind its slides with `--deck-canvas` (white,
14
+ as before, when unset). A change a page cannot play (clock, page, through, match: they need a canvas), a setting the
15
+ change does not take and a value out of range are refused at build, naming the part and the fix. `review` says how
16
+ each part arrives. While a change plays the frame clips both slides (a push never crosses the letterbox: `<deck-stage>`
17
+ clips its canvas while it carries `data-deck-changing`), the slide being left keeps its loops running, and printing
18
+ puts everything back first. Settings are read as a browser reads the tag. A deck without `data-enter` carries none
19
+ of it (no keyframes, rule or runtime); the `<deck-stage>` every page carries gained the two hooks, and draws as
20
+ before without them.
21
+
22
+ - **Explore: a viewer clicks a piece to go to the click about it.** With `"explore": true` in deck.json, a click on a
23
+ piece goes to the click that is about it — the first click whose `data-on` names it (`gw+`'s gw too), or, when none
24
+ does, the first that takes it in through a `name+` — and a "Back to click N" control (or Backspace) returns, a step
25
+ at a time, as a browser's Back does (to where the viewer was before each jump, whatever they stepped through since).
26
+ Pieces that lead somewhere get a pointer and a ring on hover; a piece whose click is the one shown, or one that
27
+ cannot be seen, leads nowhere; a link or control inside a piece keeps its click; a drag (the dev page's Alt-drag) is
28
+ never a click. On a touch screen a tap on a piece that leads somewhere explores — tap beside the pieces to step. The
29
+ pieces are reached by pointer, not by keyboard: arrow keys still step through the clicks in order. The presenter
30
+ window does not explore (it follows the room's deck). The authored order never changes: explore is a way through the
31
+ same clicks. A deck without `"explore"` carries none of it (its look comes with it, not in deck.css).
32
+
33
+ ## 0.9.0 — living system diagrams: loops, wires between pieces, a wire's label, halo and running packets
34
+
35
+ - **A wire between pieces: `data-arrow="client to server"`.** The wire runs from the edge of one piece's box to the
36
+ 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
37
+ along — no four numbers to keep in step. Two or more wires between the same pieces each take a lane (80 px apart at
38
+ most, always inside both boxes), keeping to their left, so a request going right runs above its answer coming back
39
+ whatever the pieces are called. A bend may follow the names (`"gw to db 40"`). Words, not `>`, because a `>` would
40
+ end the tag. A name not placed, a wire to itself and pieces too close for a wire are refused, naming the fix; a
41
+ numbered wire is drawn byte for byte as before. Alt-dragging a wire between pieces is refused with its fix (move one
42
+ of its pieces). The starter deck now writes its four wires this way (they land within 5 px of where its numbers put them).
43
+ - **A wire's label, halo and running packets.** Three attributes on any wire: `data-label="InvokeAgentRuntime"` writes
44
+ its name beside its middle, on its left — above a level wire going right, below one coming back, beside a standing
45
+ 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
46
+ showing itself in shows its label too); class `halo` gives the line and its head a soft glow (`--wire-halo`); and
47
+ `data-packets="2" data-speed="5"` keeps packets running along the curve, evenly spaced, 5 s a run (3 by default;
48
+ 1–6 packets, 0.5–60 s), fading in at the start and out before the head (`--packet`, `--packet-glow`). The packets are
49
+ loops, so they run only on the slide shown, in step from click to click, and where loops do not run (reduced motion,
50
+ print, motion off) the first rests at the wire's middle. They are the wire's, not the deck's loops: `review` and
51
+ `check` do not list them. A wire without these is drawn byte for byte as before; packets it cannot run, and a speed
52
+ with no packets, are refused naming the fix. They are read as a browser reads the tag (never from inside another
53
+ attribute's value, in any case, quoted or not); a `>` or `<` in a value is written `&gt;` or `&lt;`, since a tag ends
54
+ at its first `>`. A deck that already put its own `data-label`, `data-packets` or `data-speed` on a wire (for its
55
+ own CSS) now gets them drawn: rename them. A loop an icon file carries is now found by `review` and `check` too.
56
+ - **A piece and what it touches: `name+`.** A wire between pieces carries `data-ends` (the pieces it joins; a wire in
57
+ numbers may carry it too), so a click can name `gw+`: the gateway, the wires with it as an end, and the pieces at
58
+ their other ends — `data-on="gw+"` lights that neighbourhood and greys the rest. It reads anywhere a click names
59
+ pieces (`data-in`, `data-out`, `data-on`, `data-hot`, and the groups a mover moves: `subject`, `aside`, `place`,
60
+ `apart`); `check`'s lit-on-entry reads it the same way, and `review` lists what it lit. A piece actually called `gw+`
61
+ is itself. On a `path` click it lights the piece, then its wires, then what they reach — for a request's own order,
62
+ write the route out (`data-focus-route`), where `+` is not read. `footprint-storydeck/focus` exports `expandNames`.
63
+
64
+ - **Motion that keeps going: loops.** `data-loop="pulse"` on a piece keeps it pulsing while its slide is shown.
65
+ `pulse`, `float` and `marquee` are the endless moves of the motion table StoryReel's films use
66
+ (`footprint-story/motion`), sampled from the same curves and drawn into the page only when a deck names them
67
+ (`data-loop="float 4s"` sets the pace; any other name is refused at build, naming the piece and the loops there are).
68
+ A named loop moves its element by `transform` (a shape inside a drawing about its own middle), so a tag that sets a
69
+ transform of its own is refused, naming the fix: put data-loop on an element inside it. `data-loop` alone runs the
70
+ piece's own animation, `--loop` in theme.css (`.gear { --loop: spin 6s linear infinite; }`); a theme.css rule that
71
+ gives the element its own `animation` wins, so list `var(--loop)` in it to keep both.
72
+ <deck-stage> owns where loops run, so it works in any deck on the stage: only on the slide shown and the layers under
73
+ 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
74
+ 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
75
+ step back keeps it running (a static arrival no longer zeroes a loop, only entrances). A loop never runs under
76
+ reduced motion (switched live), in print, or with motion off: there the piece rests in its own style. A piece that
77
+ loops and changes on the same click (comes in, lights up) does both: focus.css keeps the loop as the last animation
78
+ of the piece's list. Loop CSS is drawn only for decks that use loops, so a deck without one gains none; the
79
+ `<deck-stage>` every page carries changed, and a deck without loops draws as before. (Corrected after release: this
80
+ line first said such a deck builds byte for byte as before — its page carries the changed stage.)
81
+ - **Motion off: a still deck.** `?motion=off` after the page's address, or `<deck-stage data-motion="off">` (switched
82
+ live too): no loops, and every click lands at once, as a jump does — so a screenshot of a click is the same every
83
+ time.
84
+ - **The checks know loops.** `review` lists each click's loops (`loops (2): db pulse, gear (its own --loop)`). `check`
85
+ warns (`loop-unset`) about a `data-loop` that neither theme.css nor its own style gives a `--loop` (nothing would
86
+ loop). `check --layout` reports an endless animation that is not a loop: one running on a slide no one sees is an
87
+ error (`hidden-loop`, with how many and on which pieces, one problem for all the slides it runs on); one shown on a
88
+ click is a warning (`loose-loop`: it starts over at each click and stops on a jump).
89
+
3
90
  ## 0.8.1 — footprint-narration is now footprint-story
4
91
 
5
92
  - **footprint-narration is now footprint-story.** StoryDeck's shared narration code (shown-vs-spoken text, captions,
package/README.md CHANGED
@@ -408,21 +408,61 @@ npx footprint-storydeck build my-talk # my-talk/index.html — one page, eve
408
408
  follow the part on screen as well, select the active slide in the same rule:
409
409
  `[data-theme="ledger"], :root:has([data-deck-active][data-theme="ledger"]) { … }`. `check` warns about a theme
410
410
  that theme.css never selects (a misspelt name changes nothing), and `review` names each click's theme.
411
+ - **A part arrives with a change of picture.** `<section … data-enter="push" data-enter-from="right">` plays one of
412
+ the editor's changes StoryReel's films use — cut, fade, dip, wipe, split, iris, push, slide, whip, zoom — with its
413
+ settings as `data-enter-*` (`from`, `line`, `at` "x y" or "centre", `color` — a dip goes through black unless it
414
+ says otherwise — `seconds`, `ease`), as the deck steps into the part; the frame clips both slides while it plays. Only on a forward step: a jump or a step back lands at once, and so does every step under reduced
415
+ motion or with motion off. `review` says how each part arrives.
416
+ - **Explore: click a piece, go to the click about it.** `"explore": true` in deck.json lets a viewer wander the
417
+ deck: a click on a piece goes to the click that is about it (the first whose `data-on` names it, else the first that
418
+ takes it in through a `name+`), and "Back to click N" (or Backspace) returns, as a browser's Back does. Pieces that
419
+ lead somewhere show a pointer and a ring on hover; on a touch screen a tap on one explores (tap beside the pieces to
420
+ step), and the keyboard keeps stepping in order. The order you wrote is
421
+ untouched — explore is a way through the same clicks, for a deck left open on a screen or sent to someone.
411
422
  - **Read first, look last.** A reviewer — a person, or a model that pays for every screenshot — reads the deck as text:
412
423
  `outline` (a line per click), `review --click 14` (its headline and words, what it lights, greys, brings in and moves,
413
424
  its route, its notes), `check` (what to fix, each with its click and its fix: a headline over 12 words, pieces that
414
425
  light just by coming in, a click that changes nothing, a piece never shown, clicks without notes, a theme theme.css
415
426
  never styles). `check --layout`
416
- opens the page in a browser, offline, and finds text that spills out of its box (it needs Playwright installed beside
427
+ opens the page in a browser, offline, and finds text that spills out of its box and endless animations that are not
428
+ loops (it needs Playwright installed beside
417
429
  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:
418
430
  `claude mcp add storydeck -- npx footprint-storydeck mcp my-talk`.
419
- - **The helpers a diagram needs.** `<i data-k="w1" class="wire pkt" data-arrow="252 352 318 352"></i>` is a wire (an
420
- SVG arrow, with an optional bend; class `pkt` adds a packet that rides it on a `path` click, at its turn — along the
421
- curve itself, not a straight line across the bend). A wire that comes in shows itself from its start to its tip,
422
- its dashes and colours as your theme draws them.
431
+ - **The helpers a diagram needs.** `<i data-k="w1" class="wire pkt" data-arrow="client to server"></i>` is a wire (an
432
+ 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
433
+ 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
434
+ their left, so a request going right runs above its answer coming back; a bend may follow the names
435
+ (`"gw to db 40"`). `data-arrow="252 352 318 352"` places a wire by hand, in slide px. Class `pkt` adds a packet that
436
+ rides the wire on a `path` click, at its turn — along the curve itself, not a straight line across the bend. A wire
437
+ that comes in shows itself from its start to its tip, its dashes and colours as your theme draws them. A wire between
438
+ pieces knows its ends, so a click can be about a piece and everything it touches: `data-on="gw+"` lights the
439
+ gateway, its wires and the pieces at their other ends, and greys the rest (`review` lists them); it reads in every
440
+ list of names a click has, the groups a mover moves too (`data-focus-apart="gw+: 0 -200"`). A living system
441
+ diagram needs three more things on a wire, each an attribute: `data-label="InvokeAgentRuntime"` writes its name at its
442
+ 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
443
+ reads over anything); class `halo` gives it a soft glow (`--wire-halo`); and `data-packets="2" data-speed="5"` keeps
444
+ packets running along it, evenly spaced, 5 s a run (`--packet`, `--packet-glow`). The packets are loops (see below):
445
+ only on the slide shown, in step from click to click, and under reduced motion, in print or with motion off one rests
446
+ at the wire's middle.
423
447
  `<i class="ic" data-icon="server"></i>` is `icons/server.svg`. `deck.css` styles the chrome (kicker, headline, footer
424
448
  and count), wires, packets, icons and the theme toggle from the token contract, every rule `:where()`, so your
425
449
  theme wins.
450
+ - **Motion that keeps going: a loop.** `data-loop="pulse"` on a piece makes it pulse while its slide is shown;
451
+ `pulse`, `float` and `marquee` are the endless moves of the motion table StoryReel's films use
452
+ (`footprint-story/motion`), drawn into the page only when a deck names them (`data-loop="float 4s"` sets the pace).
453
+ `data-loop` alone runs the piece's own animation from theme.css: `.gear { --loop: spin 6s linear infinite; }`. A
454
+ named loop moves its element by `transform` (`marquee` slides it 1600 px left and starts over: a ticker), so it goes
455
+ on an element without a transform of its own — a tag that sets one is refused; one theme.css gives it is replaced
456
+ while the loop runs. A rule of theme.css that gives the element its own `animation` wins over its loop: list
457
+ `var(--loop)` in it to keep both. A
458
+ map is drawn again for every click, yet a loop never starts over: every loop in the deck runs on one clock, so the
459
+ 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
460
+ slide shown (a deck of 40 map clicks runs one slide's loops, not 40), and never under reduced motion, in print, or
461
+ with motion off — there the piece rests in its own style. **Motion off** is `?motion=off` after the page's address
462
+ (or `<deck-stage data-motion="off">`): no loops, and every click lands at once, so a screenshot of a click is the same
463
+ every time. `review` lists each click's loops; `check` warns about a `data-loop` that nothing gives a `--loop`, and
464
+ `check --layout` finds an endless animation that is not a loop: one running on a slide no one sees (an error: it
465
+ costs the whole deck), and one that starts over at each click.
426
466
  - **A deck is files, never a program — on your machine.** No deck code runs in Node: no build script, no deck module.
427
467
  Playwright (1.48 or newer), for `check --layout`, is loaded only from beside StoryDeck — never from the deck folder or
428
468
  the folder you run in — and the page is measured offline: no name resolves, the browser context is offline and routed
package/deck.css CHANGED
@@ -41,11 +41,11 @@
41
41
  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
42
42
  its start (C: --cdx/--cdy, E: --pdx/--pdy, from transforms.js). */
43
43
  @property --sd-t { syntax: '<number>'; inherits: false; initial-value: 0; }
44
- :where(svg.wire .pkt) {
45
- opacity: 0; fill: var(--sd-glow, currentColor); stroke: none;
44
+ :where(svg.wire :is(.pkt, .run)) {
46
45
  transform: translate(calc(var(--cdx) * 2 * (1 - var(--sd-t)) * var(--sd-t) + var(--pdx) * var(--sd-t) * var(--sd-t)),
47
46
  calc(var(--cdy) * 2 * (1 - var(--sd-t)) * var(--sd-t) + var(--pdy) * var(--sd-t) * var(--sd-t)));
48
47
  }
48
+ :where(svg.wire .pkt) { opacity: 0; fill: var(--sd-glow, currentColor); stroke: none; }
49
49
  @keyframes sdPkt { from { --sd-t: 0; } to { --sd-t: 1; } }
50
50
  @keyframes sdPktShow { 0%, 100% { opacity: 0; } 15%, 80% { opacity: 1; } }
51
51
  /* 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 @@
70
70
  }
71
71
  }
72
72
 
73
+ /* a wire's options (transforms.js): its label at its middle, in its colour, on a ground-coloured edge so it reads over
74
+ anything; class "halo", a soft glow; data-packets, packets that keep running along it — loops (deck-stage.js USAGE
75
+ (i)): on the slide shown, on one clock, each fading in at the start and out before the head. Where loops do not run
76
+ (reduced motion, print, motion off) the first packet rests at the wire's middle and the others are hidden. */
77
+ :where(svg.wire text.label) {
78
+ font: 600 18px/1 var(--mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace); letter-spacing: .06em;
79
+ text-transform: uppercase; dominant-baseline: central; fill: currentColor;
80
+ stroke: var(--bg, #ffffff); stroke-width: 6px; stroke-linejoin: round; paint-order: stroke;
81
+ }
82
+ :where(svg.wire.halo path) { filter: drop-shadow(0 0 6px var(--wire-halo, currentColor)); } /* the line and its head, not the label */
83
+ :where(svg.wire .run) {
84
+ --sd-t: .5; fill: var(--packet, var(--sd-glow, currentColor)); stroke: none;
85
+ filter: drop-shadow(0 0 5px var(--packet-glow, var(--packet, var(--sd-glow, currentColor))));
86
+ }
87
+ :where(svg.wire .run + .run) { opacity: 0; }
88
+ @keyframes sdRun { 0% { --sd-t: 0; opacity: 0; } 12%, 85% { opacity: 1; } 100% { --sd-t: 1; opacity: 0; } }
89
+
73
90
  /* icons (data-icon): drawn in currentColor */
74
91
  :where(svg.ic) { width: 60px; height: 60px; flex: none; fill: none; stroke: currentColor; stroke-width: 3; stroke-linecap: round; stroke-linejoin: round; }
75
92
 
package/deck.d.ts CHANGED
@@ -29,6 +29,8 @@ export interface DeckConfig {
29
29
  readonly deckData: string | null;
30
30
  /** What `storydeck check` asks: words in a map click's headline (12), on a plain slide (40). */
31
31
  readonly checks: { readonly maxWords: number; readonly maxSlideWords: number };
32
+ /** A viewer may click a piece to go to the click about it, and come back (false). */
33
+ readonly explore: boolean;
32
34
  /** The keys deck.json wrote (a file it names must be there; a default may be absent). */
33
35
  readonly given: readonly string[];
34
36
  }
@@ -37,10 +39,12 @@ export function readConfig(json: string | object): DeckConfig;
37
39
 
38
40
  /** One click on a map, as written: its attributes (focus-html · readStep reads them), headline (HTML) and notes. */
39
41
  export interface DeckStepSource { readonly attrs: string; readonly headline: string; readonly notes: readonly string[] }
42
+ /** How a part arrives, as written: data-enter and its data-enter-* settings, as text (compile reads them against the shared table). */
43
+ export interface DeckEnterSource { readonly type: string; readonly given: Readonly<Record<string, string>> }
40
44
  /** A part of the deck: a plain slide (map null) or clicks told on a map. */
41
- export type DeckPart =
45
+ export type DeckPart = { readonly theme: string | null; readonly enter: DeckEnterSource | null } & (
42
46
  | { readonly label: string; readonly kicker: string; readonly map: null; readonly body: string; readonly notes: readonly string[] }
43
- | { readonly label: string; readonly kicker: string; readonly map: string; readonly steps: readonly DeckStepSource[] };
47
+ | { readonly label: string; readonly kicker: string; readonly map: string; readonly steps: readonly DeckStepSource[] });
44
48
  /**
45
49
  * The clicks file read into parts, scanned once. A step holds only its <h2> and notes (anything else is refused, naming
46
50
  * where it goes); a <section> or <step> left open, or opened inside another, is refused.
@@ -67,6 +71,8 @@ export interface DeckSource {
67
71
  }
68
72
  export function readDeck(dir: string): DeckSource;
69
73
 
74
+ /** 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). */
75
+ export interface DeckLoop { readonly piece: string | null; readonly value: string; readonly styled?: true }
70
76
  /** A click of the compiled deck, as review and check read it. */
71
77
  export type DeckClick = {
72
78
  readonly n: number;
@@ -76,6 +82,10 @@ export type DeckClick = {
76
82
  /** The headline as plain text ('' on a plain slide). */
77
83
  readonly headline: string;
78
84
  readonly notes: readonly string[];
85
+ /** What loops on the click (on a map: on the pieces it shows). */
86
+ readonly loops: readonly DeckLoop[];
87
+ /** How the click's part arrives, on its first click (null elsewhere, or when it just appears): footprint-story/motion's change, read. */
88
+ readonly enter: { readonly type: string; readonly seconds: number; readonly ease: string; readonly p: Readonly<Record<string, unknown>> } | null;
79
89
  } & (
80
90
  | { readonly kind: 'plain'; readonly map: null; readonly text: string }
81
91
  | { readonly kind: 'map'; readonly map: string; readonly step: FocusClick; readonly look: FocusLook; readonly stepIndex: number; readonly steps: number }
@@ -92,6 +102,12 @@ export interface CompiledDeck {
92
102
  readonly themeCss: string;
93
103
  readonly slides: readonly DeckSlide[];
94
104
  readonly clicks: readonly DeckClick[];
105
+ /** The named loops the clicks show (data-loop values), drawn into the page's CSS once each. */
106
+ readonly loops: readonly string[];
107
+ /** With deck.json "explore": the map each click is on (null on a plain slide), and where each piece leads on its map — the first click whose data-on names it, else the first that takes it in through a name+ (0-based). */
108
+ readonly explore: { readonly slides: readonly (string | null)[]; readonly targets: Readonly<Record<string, Readonly<Record<string, number>>>> } | null;
109
+ /** The parts' entrances as the page plays them: each distinct change sampled once (kinds), and its key per slide — or null when no part has one. */
110
+ readonly transitions: { readonly kinds: Readonly<Record<string, unknown>>; readonly enter: readonly (string | null)[] } | null;
95
111
  readonly maps: Readonly<Record<string, { readonly pieces: readonly FocusPiece[] }>>;
96
112
  }
97
113
  /** The deck's clicks planned (each map's state carried click to click) and drawn as <deck-stage> slides. */
@@ -133,10 +149,10 @@ export function formatProblems(problems: readonly DeckProblem[]): string;
133
149
  /** The browser port the layout check drives (the video's deckStageDriver, with measure). */
134
150
  export interface LayoutDriver {
135
151
  open(url: string): Promise<void>;
136
- measure(n: number): Promise<readonly { kind: 'spills' | 'outside'; piece: string | null; text: string; dx: number; dy: number }[]>;
152
+ 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 }[]>;
137
153
  close(): Promise<unknown> | unknown;
138
154
  }
139
- /** Text that spills out of its box and lit pieces off the slide, measured click by click in a browser. */
155
+ /** 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. */
140
156
  export function layoutCheck(url: string, options: { clicks: readonly DeckClick[]; driver?: LayoutDriver; chromium?: unknown }): Promise<DeckProblem[]>;
141
157
 
142
158
  export interface DeckServer {
@@ -1,4 +1,6 @@
1
1
  import { wordCount } from "./parse.js";
2
+ import { expandNames } from "../focus.js";
3
+ import { LOOP_NAMES } from "./loops.js";
2
4
  const names = (pieces, idx) => [...new Set(idx.map((i) => pieces[i].keys[0]))];
3
5
  const problem = (level, rule, click, message) => ({ level, rule, click: click?.n ?? null, label: click?.label ?? null, message });
4
6
  function words(c, { maxWords, maxSlideWords }) {
@@ -9,7 +11,7 @@ function words(c, { maxWords, maxSlideWords }) {
9
11
  }
10
12
  function litOnEntry(c, pieces) {
11
13
  if (c.kind !== "map" || c.step.on === null || c.step.quiet) return [];
12
- const on = c.step.on;
14
+ const on = expandNames(pieces, c.step.on);
13
15
  if (on.includes("*")) return [];
14
16
  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);
15
17
  if (!extra.length) return [];
@@ -53,6 +55,13 @@ function unstyledThemes(compiled) {
53
55
  }
54
56
  return out;
55
57
  }
58
+ function unsetLoops(compiled) {
59
+ if (/--loop\s*:/.test(compiled.themeCss ?? "")) return [];
60
+ const bare = compiled.clicks.flatMap((c) => (c.loops ?? []).filter((l) => l.value === "" && !l.styled).map((l) => ({ c, piece: l.piece ?? "an element" })));
61
+ if (!bare.length) return [];
62
+ const list = [...new Set(bare.map((b) => b.piece))], one = list.length === 1;
63
+ 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(", ")})`)];
64
+ }
56
65
  function checkDeck(compiled) {
57
66
  const out = [];
58
67
  compiled.clicks.forEach((c, i) => {
@@ -60,7 +69,7 @@ function checkDeck(compiled) {
60
69
  if (c.kind === "map") out.push(...litOnEntry(c, compiled.maps[c.map].pieces));
61
70
  out.push(...noChange(c, compiled.clicks[i - 1]));
62
71
  });
63
- out.push(...neverShown(compiled), ...missingNotes(compiled), ...unstyledThemes(compiled));
72
+ out.push(...neverShown(compiled), ...missingNotes(compiled), ...unstyledThemes(compiled), ...unsetLoops(compiled));
64
73
  return out;
65
74
  }
66
75
  const failure = (error) => [problem("error", "compile", null, error.message)];
@@ -1,6 +1,9 @@
1
1
  import { focusStep } from "../focus.js";
2
2
  import { readPieces, readStep, drawFocus, wrapStage, slideClass, focusOverlay } from "../focusHtml.js";
3
- import { applyTransforms } from "./transforms.js";
3
+ import { applyTransforms, icons as drawIcons } from "./transforms.js";
4
+ import { loopsIn } from "./loops.js";
5
+ import { exploreTargets } from "./explore.js";
6
+ import { readEnter, transitionTable } from "./transitions.js";
4
7
  import { plainText } from "./parse.js";
5
8
  import { esc, stripComments } from "./html.js";
6
9
  import { readAttributes, tagsWith } from "../pieceRules.js";
@@ -31,12 +34,16 @@ function prepareMap(name, html, icons, dev) {
31
34
  }
32
35
  const { html: out, pieces } = readPieces(drawn);
33
36
  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)`);
34
- return { name, html: dev ? numberForDev(out) : out, pieces, state: null };
37
+ return { name, html: dev ? numberForDev(out) : out, pieces, loops: loopsIn(drawIcons(stripComments(html), icons), `map "${name}"`), state: null };
38
+ }
39
+ function shownLoops(map, look) {
40
+ return map.loops.filter((l) => l.piece === null || look.pieces.some((p, i) => p.state !== "gone" && map.pieces[i].keys.includes(l.piece)));
35
41
  }
36
42
  function planClicks(parts, maps, { area, canvas, icons }) {
37
43
  let lastMap = null;
38
44
  const clicks = [];
39
45
  for (const part of parts) {
46
+ const enter = readEnter(part.enter, `"${part.label}"`, { frame: canvas });
40
47
  if (!part.map) {
41
48
  refuseOwnNumbers(`"${part.label}"`, part.body);
42
49
  let inner;
@@ -45,7 +52,7 @@ function planClicks(parts, maps, { area, canvas, icons }) {
45
52
  } catch (e) {
46
53
  throw new Error(`"${part.label}": ${e.message}`, { cause: e });
47
54
  }
48
- clicks.push({ label: part.label, part, kind: "plain", inner, notes: part.notes, headline: "", step: 0, steps: 1 });
55
+ clicks.push({ label: part.label, part, kind: "plain", inner, enter, loops: loopsIn(drawIcons(part.body, icons), `"${part.label}"`), notes: part.notes, headline: "", step: 0, steps: 1 });
49
56
  lastMap = null;
50
57
  continue;
51
58
  }
@@ -60,7 +67,7 @@ function planClicks(parts, maps, { area, canvas, icons }) {
60
67
  }
61
68
  map.state = r.state;
62
69
  lastMap = map;
63
- 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 });
70
+ clicks.push({ label: `${part.label} \xB7 ${k + 1}`, part, kind: "map", map, step, look: r.look, enter: k === 0 ? enter : null, loops: shownLoops(map, r.look), headline: s.headline, notes: s.notes, stepIndex: k, steps: part.steps.length });
64
71
  });
65
72
  }
66
73
  const seen = /* @__PURE__ */ new Set();
@@ -113,9 +120,22 @@ function compileDeck(source, { dev = false } = {}) {
113
120
  map: c.kind === "map" ? c.map.name : null,
114
121
  headline: plainText(c.headline),
115
122
  notes: c.notes,
123
+ loops: c.loops,
124
+ enter: c.enter,
116
125
  ...c.kind === "map" ? { step: c.step, look: c.look, stepIndex: c.stepIndex, steps: c.steps } : { text: plainText(c.inner) }
117
126
  }));
118
- return { config, title: config.title, themeCss: source.themeCss ?? "", slides, clicks, maps: Object.fromEntries(Object.values(maps).map((m) => [m.name, { pieces: m.pieces }])) };
127
+ const loops = [...new Set(planned.flatMap((c) => c.loops.map((l) => l.value)))].filter(Boolean).sort();
128
+ return {
129
+ config,
130
+ title: config.title,
131
+ themeCss: source.themeCss ?? "",
132
+ slides,
133
+ clicks,
134
+ loops,
135
+ explore: config.explore ? exploreTargets(planned) : null,
136
+ transitions: transitionTable(planned.map((c) => c.enter), config.canvas),
137
+ maps: Object.fromEntries(Object.values(maps).map((m) => [m.name, { pieces: m.pieces }]))
138
+ };
119
139
  }
120
140
  export {
121
141
  compileDeck
@@ -9,7 +9,7 @@ const DEFAULTS = Object.freeze({
9
9
  out: "index.html",
10
10
  checks: Object.freeze({ maxWords: 12, maxSlideWords: 40 })
11
11
  });
12
- const KEYS = ["title", "description", "lang", "footer", "area", "canvas", "clicks", "theme", "icons", "maps", "out", "post", "deckData", "checks"];
12
+ const KEYS = ["title", "description", "lang", "footer", "area", "canvas", "clicks", "theme", "icons", "maps", "out", "post", "deckData", "checks", "explore"];
13
13
  const CHECK_KEYS = ["maxWords", "maxSlideWords"];
14
14
  const isText = (v) => typeof v === "string" && v.trim().length > 0;
15
15
  const numbers = (v, n) => Array.isArray(v) && v.length === n && v.every((x) => typeof x === "number" && Number.isFinite(x));
@@ -43,6 +43,7 @@ function readConfig(json) {
43
43
  return v;
44
44
  };
45
45
  const maxWords = count("maxWords"), maxSlideWords = count("maxSlideWords");
46
+ if (raw.explore !== void 0 && typeof raw.explore !== "boolean") throw new Error(`deck.json "explore" is true or false, not ${JSON.stringify(raw.explore)}`);
46
47
  return Object.freeze({
47
48
  title: raw.title.trim(),
48
49
  description: raw.description ?? "",
@@ -58,6 +59,7 @@ function readConfig(json) {
58
59
  post: raw.post === void 0 ? null : deckPath(raw.post, "post"),
59
60
  deckData: raw.deckData === void 0 ? null : deckPath(raw.deckData, "deckData"),
60
61
  checks: Object.freeze({ maxWords, maxSlideWords }),
62
+ explore: raw.explore === true,
61
63
  given: Object.freeze(Object.keys(raw))
62
64
  // the keys deck.json wrote: a file it names must be there; a default may be absent
63
65
  });
package/dist/deck/edit.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { attrValue, pieceTags, readAttributes, styleLength, tagsWith } from "../pieceRules.js";
2
2
  import { UNSEEN, commentRanges, stripComments } from "./html.js";
3
- import { wireTags } from "./transforms.js";
3
+ import { wireEnds, wireTags } from "./transforms.js";
4
4
  const FEEDBACK = "feedback.md";
5
5
  const MAX_MOVE = 5e3;
6
6
  const num = (v) => String(Math.round(v * 100) / 100);
@@ -53,7 +53,8 @@ function moveEdits(html, piece, dx, dy) {
53
53
  if (browserValueAt(html, piece, "data-k") !== piece.start + 1 + piece.tag.length + piece.before.length + ' data-k="'.length) throw ambiguous();
54
54
  const wire = wiresBySource(html).get(piece.start);
55
55
  if (wire) {
56
- const spec = wire.m[1], parts = spec.trim().split(/[\s,]+/), nums = parts.map(Number);
56
+ const spec = wire.m[1], parts = spec.trim().split(/[\s,]+/), nums = parts.map(Number), ends = wireEnds(spec);
57
+ if (ends) throw new Error(`"${piece.name}" runs from "${ends[0]}" to "${ends[1]}" and follows them \u2014 move one of them`);
57
58
  if (parts.length !== 4 && parts.length !== 5 || nums.some((n) => !Number.isFinite(n))) {
58
59
  throw new Error(`"${piece.name}": its data-arrow is not "x1 y1 x2 y2 [bend]" \u2014 fix it before moving it`);
59
60
  }
@@ -0,0 +1,88 @@
1
+ import { expandNames } from "../focus.js";
2
+ function exploreTargets(planned) {
3
+ const targets = {}, through = {}, table = () => /* @__PURE__ */ Object.create(null);
4
+ planned.forEach((c, i) => {
5
+ if (c.kind !== "map" || !c.step.on) return;
6
+ const own = targets[c.map.name] ??= table(), near = through[c.map.name] ??= table();
7
+ for (const name of c.step.on.map((x) => expandNames(c.map.pieces, [x])[0])) if (name !== "*" && !Object.hasOwn(own, name)) own[name] = i;
8
+ for (const name of expandNames(c.map.pieces, c.step.on)) if (name !== "*" && !Object.hasOwn(near, name)) near[name] = i;
9
+ });
10
+ for (const [map, near] of Object.entries(through)) for (const [name, i] of Object.entries(near)) if (!Object.hasOwn(targets[map], name)) targets[map][name] = i;
11
+ return { slides: planned.map((c) => c.kind === "map" ? c.map.name : null), targets };
12
+ }
13
+ const exploreData = (explore) => `<script type="application/json" id="deck-explore">${JSON.stringify(explore).replace(/</g, "\\u003c")}<\/script>`;
14
+ const EXPLORE_CSS = `:where(deck-stage[data-explore] .sd-leads) { cursor: pointer; }
15
+ :where(deck-stage[data-explore] .sd-leads:hover) { outline: 3px solid var(--sd-accent, var(--accent-ink, #0b6e99)); outline-offset: 6px; }
16
+ :where(.explore-back) {
17
+ position: fixed; left: 12px; top: 12px; z-index: 10; padding: 8px 14px; border-radius: 20px; cursor: pointer;
18
+ border: 1.5px solid var(--line, #c9d0d9); background: var(--bg-elev, #f6f8fa); color: var(--fg, #14181f);
19
+ font: 600 14px/1 var(--sans, system-ui, sans-serif);
20
+ }
21
+ @media print { :where(.explore-back) { display: none; } }`;
22
+ function exploreRuntime() {
23
+ const stage = document.querySelector("deck-stage[data-explore]"), data = document.getElementById("deck-explore");
24
+ if (!stage || !data || window.name === "deck-presenter" || /[?&]_snthumb=/.test(location.search)) return;
25
+ const { slides, targets } = JSON.parse(data.textContent), back = [];
26
+ const button = document.createElement("button");
27
+ button.type = "button";
28
+ button.className = "explore-back";
29
+ button.hidden = true;
30
+ document.body.appendChild(button);
31
+ const shown = () => [...stage.children].filter((s) => s.tagName === "SECTION")[stage.index];
32
+ const unseen = ".sd-gone, .sd-hide, .sd-twin-off";
33
+ const controls = 'a[href], button, input, select, textarea, summary, label, video[controls], audio[controls], [role="button"], [onclick], [contenteditable]:not([contenteditable="false" i])';
34
+ const leads = (piece) => {
35
+ if (piece.closest(unseen)) return null;
36
+ const own = targets[slides[stage.index]] ?? {};
37
+ const to = piece.getAttribute("data-k").trim().split(/\s+/).map((k) => Object.hasOwn(own, k) ? own[k] : void 0).find((i) => i !== void 0);
38
+ return to === void 0 || to === stage.index ? null : to;
39
+ };
40
+ const mark = () => {
41
+ document.querySelectorAll(".sd-leads").forEach((p) => p.classList.remove("sd-leads"));
42
+ for (const p of shown().querySelectorAll("[data-k]")) if (leads(p) !== null) p.classList.add("sd-leads");
43
+ button.hidden = !back.length;
44
+ if (back.length) button.textContent = `\u2190 Back to click ${back.at(-1) + 1}`;
45
+ };
46
+ const go = (i) => {
47
+ stage.goTo(i);
48
+ mark();
49
+ };
50
+ const goBack = () => {
51
+ if (back.length) go(back.pop());
52
+ };
53
+ let down = null;
54
+ document.addEventListener("pointerdown", (e) => {
55
+ down = [e.clientX, e.clientY];
56
+ }, true);
57
+ document.addEventListener("click", (e) => {
58
+ const dragged = down && Math.hypot(e.clientX - down[0], e.clientY - down[1]) > 4;
59
+ down = null;
60
+ if (e.altKey || e.button !== 0 || dragged || !stage.isConnected) return;
61
+ const piece = e.target.closest?.("[data-k]");
62
+ if (!piece || !shown().contains(piece) || e.target.closest(controls)) return;
63
+ const to = leads(piece);
64
+ if (to === null) return;
65
+ e.preventDefault();
66
+ back.push(stage.index);
67
+ go(to);
68
+ }, true);
69
+ button.addEventListener("click", (e) => {
70
+ e.stopPropagation();
71
+ button.blur();
72
+ goBack();
73
+ });
74
+ window.addEventListener("keydown", (e) => {
75
+ if (e.key !== "Backspace" || !back.length || !stage.isConnected || e.defaultPrevented || e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
76
+ if (/^(INPUT|TEXTAREA|SELECT)$/.test(e.target?.tagName) || e.target?.isContentEditable) return;
77
+ e.preventDefault();
78
+ goBack();
79
+ });
80
+ stage.addEventListener("slidechange", mark);
81
+ mark();
82
+ }
83
+ export {
84
+ EXPLORE_CSS,
85
+ exploreData,
86
+ exploreRuntime,
87
+ exploreTargets
88
+ };
package/dist/deck/init.js CHANGED
@@ -9,22 +9,27 @@ const DECK_JSON = `{
9
9
  const MAP = `<!--
10
10
  The map: one picture the story is told on, in slide pixels (1920 \xD7 1080).
11
11
  Every element with data-k="name" and an inline left/top/width/height is a piece a click can bring in, light,
12
- grey or move. Pieces never nest. <i data-arrow="x1 y1 x2 y2 [bend]"> becomes a wire (class "pkt": a packet runs
13
- along it on a path click); <i class="ic" data-icon="name"> is icons/name.svg.
12
+ grey or move. Pieces never nest. <i data-arrow="client to server"> becomes a wire from one piece's edge to the
13
+ other's (it follows them when they move; "x1 y1 x2 y2" in slide px places it by hand; a bend may follow either),
14
+ class "pkt": a packet runs along it on a path click. A wire may carry data-label="its name", class "halo", and
15
+ data-packets="2" data-speed="5" (packets that keep running along it). In a click, "server+" is the server, its wires
16
+ and what they reach. <i class="ic" data-icon="name"> is icons/name.svg. data-loop="pulse" (float, marquee)
17
+ keeps a piece moving while its slide is shown; data-loop alone runs its own --loop from theme.css.
14
18
  -->
15
19
  <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>
16
- <i data-k="req1" class="wire req pkt" data-arrow="464 490 716 490"></i>
20
+ <i data-k="req1" class="wire req pkt" data-arrow="client to server"></i>
17
21
  <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>
18
- <i data-k="req2" class="wire req pkt" data-arrow="1024 490 1276 490"></i>
22
+ <i data-k="req2" class="wire req pkt" data-arrow="server to db"></i>
19
23
  <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>
20
- <i data-k="ret2" class="wire ret pkt" data-arrow="1276 570 1024 570"></i>
21
- <i data-k="ret1" class="wire ret pkt" data-arrow="716 570 464 570"></i>
24
+ <i data-k="ret2" class="wire ret pkt" data-arrow="db to server"></i>
25
+ <i data-k="ret1" class="wire ret pkt" data-arrow="server to client"></i>
22
26
  <div data-k="time" class="chip" style="left:760px;top:670px;width:220px;height:70px"><b>120 ms</b><small>illustration</small></div>
23
27
  `;
24
28
  const CLICKS = `<!--
25
29
  The deck, click by click.
26
30
  <section data-label="\u2026" data-kicker="\u2026"> one part of the story; without data-map it is one plain slide
27
31
  <section \u2026 data-theme="ledger"> optional: its slides carry data-theme, so theme.css can dress that part
32
+ <section \u2026 data-enter="push" data-enter-from="right"> optional: how the part arrives (cut fade dip wipe split iris push slide whip zoom)
28
33
  <section \u2026 data-map="map"> a part told on map.html: every <step> inside is ONE click
29
34
  <step data-in="\u2026" data-out="\u2026" data-on="\u2026" data-focus="\u2026">
30
35
  data-in pieces that come in (they stay) data-out pieces that leave
@@ -25,20 +25,26 @@ function clickRuns(ns) {
25
25
  }
26
26
  return runs.map(([a, b]) => a === b ? `${a}` : `${a}\u2013${b}`).join(", ");
27
27
  }
28
+ const KINDS = {
29
+ 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`],
30
+ outside: (f, where, also) => ["warn", `${where} reaches ${size(f)} past the slide's edge ("${f.text}")${also} \u2014 move it in, or zoom less`],
31
+ "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")`],
32
+ "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`]
33
+ };
34
+ const size = ({ dx, dy }) => [dx > 0 && `${Math.round(dx)} px wide`, dy > 0 && `${Math.round(dy)} px tall`].filter(Boolean).join(" and ");
28
35
  function layoutProblems(found, clicks) {
29
36
  const same = /* @__PURE__ */ new Map();
30
37
  for (const f of found) {
31
- const key = JSON.stringify([f.kind, f.piece, f.text, Math.round(f.dx), Math.round(f.dy)]);
32
- if (!same.has(key)) same.set(key, { ...f, ns: [] });
33
- same.get(key).ns.push(f.n);
38
+ const at = f.kind === "hidden-loop" ? f.slide : f.n;
39
+ 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)]);
40
+ if (!same.has(key)) same.set(key, { ...f, ns: /* @__PURE__ */ new Set() });
41
+ same.get(key).ns.add(at);
34
42
  }
35
- return [...same.values()].sort((a, b) => a.ns[0] - b.ns[0]).map(({ ns, kind, piece, text, dx, dy }) => {
36
- const c = clicks[ns[0] - 1];
37
- const where = piece ? `"${piece}"` : "an element";
38
- const by = [dx > 0 && `${Math.round(dx)} px wide`, dy > 0 && `${Math.round(dy)} px tall`].filter(Boolean).join(" and ");
39
- const also = ns.length > 1 ? ` (on clicks ${clickRuns(ns)})` : "";
40
- 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`;
41
- return { level: "warn", rule: kind === "spills" ? "spills" : "outside", click: ns[0], label: c?.label ?? null, message };
43
+ 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) => {
44
+ const c = clicks[f.ns[0] - 1];
45
+ const also = f.ns.length > 1 ? ` (on clicks ${clickRuns(f.ns)})` : "";
46
+ const [level, message] = KINDS[f.kind](f, f.piece ? `"${f.piece}"` : "an element", also);
47
+ return { level, rule: f.kind, click: f.ns[0], label: c?.label ?? null, message };
42
48
  });
43
49
  }
44
50
  async function layoutCheck(url, { clicks, driver, chromium }) {