@liqweed/motion-kit 0.3.0 → 0.5.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.
Files changed (46) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +63 -10
  4. package/adapters/astro/AnimatedDiagram.astro +150 -24
  5. package/adapters/element/README.md +6 -1
  6. package/adapters/element/motion-diagram.mjs +4 -3
  7. package/adapters/page/README.md +8 -2
  8. package/adapters/slidev/AnimatedDiagram.vue +24 -0
  9. package/cli/motion-kit.mjs +85 -81
  10. package/docs/spec/technique.md +166 -63
  11. package/examples/custom-pulse.scene.mjs +3 -0
  12. package/examples/incident.json +18 -0
  13. package/examples/web-stack.json +17 -0
  14. package/lib/build.mjs +26 -12
  15. package/lib/bundle.mjs +9 -2
  16. package/lib/check.mjs +219 -15
  17. package/lib/export.mjs +135 -16
  18. package/lib/gate.mjs +90 -0
  19. package/lib/load.mjs +49 -19
  20. package/package.json +6 -3
  21. package/runtime/bake.mjs +18 -4
  22. package/runtime/kit.mjs +59 -0
  23. package/runtime/links.mjs +314 -0
  24. package/runtime/page.mjs +52 -0
  25. package/runtime/parts.mjs +15 -0
  26. package/runtime/patch.mjs +297 -0
  27. package/runtime/player.mjs +334 -130
  28. package/runtime/scene.mjs +82 -5
  29. package/runtime/style.mjs +64 -16
  30. package/runtime/types/hub-spoke.mjs +7 -7
  31. package/runtime/types/index.mjs +4 -0
  32. package/runtime/types/sequence.mjs +5 -5
  33. package/runtime/types/stack.mjs +227 -0
  34. package/runtime/types/timeline.mjs +405 -0
  35. package/skills/animated-diagram/SKILL.md +30 -7
  36. package/skills/animated-diagram/references/custom-scenes.md +64 -9
  37. package/skills/animated-diagram/references/interactivity.md +150 -15
  38. package/skills/animated-diagram/references/qc.md +5 -2
  39. package/skills/animated-diagram/references/scene-types.md +45 -2
  40. package/skills/animated-diagram/references/styles.md +45 -5
  41. package/skills/animated-diagram/references/targets.md +7 -5
  42. package/skills/animated-diagram/references/technique.md +14 -4
  43. package/skills/motion-render/SKILL.md +31 -8
  44. package/skills/motion-render/references/formats.md +8 -8
  45. package/skills/project-logo/SKILL.md +15 -4
  46. package/styles/neutral.json +2 -2
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: motion-kit technique — normative specification
3
3
  status: draft
4
- last_updated: 2026-11-15
4
+ last_updated: 2026-11-17
5
5
  ---
6
6
 
7
7
  # motion-kit technique — normative specification
@@ -35,18 +35,28 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
35
35
  | `duration` | number, s | MUST | Time of the final state. |
36
36
  | `title` | string | MUST | Accessible name (`<title>`) [throws if empty]. |
37
37
  | `description` | string | MUST | Accessible description (`<desc>`) [throws if empty]. |
38
- | `steps` | `{at, label, detail?}[]` | MUST | ≥ 1 step; `at` strictly increasing; `at ≤ duration` (+1e-9); every `label` non-empty [throws] (`runtime/scene.mjs:46-53`). The last step is the finished diagram. |
39
- | `frame(t)` | `(number) → string` | MUST | Inner SVG markup at `t` (§2). |
38
+ | `steps` | `{at, label, detail?, id?}[]` | MUST | ≥ 1 step; `at` strictly increasing; `at ≤ duration` (+1e-9); every `label` non-empty; an `id`, if present, is a non-empty string unique within the scene [throws] (`validateScene`). The last step is the finished diagram. Page scripts address steps by `id` (§10.2); scene types copy a spec node's, hub's or spoke's `id`. |
39
+ | `frame(t, ctx)` | `(number, {idPrefix}) → string` | MUST | Inner SVG markup at `t` (§2). `ctx.idPrefix` is unique to the rendered instance; every id the frame defines (clip paths, gradients, masks, markers, filters) MUST start with it, as `${idPrefix}-name` [gate] G14. A frame that defines no ids MAY ignore `ctx`. |
40
40
  | `stepLabelsInFrame` | boolean | MAY | `false` declares narrative steps whose labels are not drawn; exempts the scene from gate rule G10 (`lib/check.mjs:74`; used by `examples/custom-pulse.scene.mjs:137`, `brand/logo.scene.mjs:108`). |
41
+ | `contrastPairs` | `{fg, bg, min, use?}[]` | MAY | Token pairs the scene draws beyond `CONTRAST_PAIRS` (§6); the gate checks the style against them in both themes [gate] G12 (`lib/check.mjs`, rule 8; used by `examples/custom-pulse.scene.mjs`). Tokens MUST be known and `min` in [1, 21]. |
41
42
  | `type`, `format`, `locale` | string | MAY | Set by scene types; recorded in the export manifest (`lib/export.mjs:75-77`). |
42
43
 
43
44
  - A scene MUST be produced by either a registered scene type —
44
- `createScene(spec, {format, locale})` (`runtime/types/index.mjs:19-23`) — or a
45
- custom module whose default export is `(opts) → scene`
46
- (`lib/load.mjs:29-32`). Both paths run `validateScene`.
47
- - A custom module MUST import only from `runtime/` with single-line relative
48
- `import { … } from "./x.mjs";` statements and use only the export forms the
49
- inliner supports, or `build` throws (`lib/bundle.mjs:8-11,33,59`).
45
+ `createScene(spec, {format, locale})` (`runtime/types/index.mjs:25-29`) — or a
46
+ custom module whose default export is `(opts) → scene`, called by
47
+ `sceneFromModule` (`runtime/kit.mjs`) with
48
+ `opts = { ...options, format, locale, kit }`. `options` are the caller's
49
+ serializable scene options, passed unchanged; option names `format`,
50
+ `locale` and `kit` throw. `kit` is the flat exports of the `motion`, `svg`, `style`, `scene` and `wrap` runtime modules (`KIT`); it has no `createScene`, scene types or player. Both paths
51
+ run `validateScene`. The CLI (`--options`), the vendored gate and the Astro
52
+ adapter call `sceneFromModule`, so one module with the same options, format
53
+ and locale gives the same scene everywhere. A `build` page calls the factory
54
+ with the same object, its `kit` being the bundled runtime, after the CLI has
55
+ built the scene once through `sceneFromModule`.
56
+ - A custom module MUST take the runtime from `kit`, or import only from
57
+ `runtime/` with single-line relative `import { … } from "./x.mjs";`
58
+ statements and use only the export forms the inliner supports, or `build`
59
+ throws (`lib/bundle.mjs:8-11,33,59`).
50
60
  - `detail` SHOULD hold sentences; labels stay short (§7). `detail` feeds the
51
61
  player caption and screen-reader list (§10.2).
52
62
 
@@ -54,13 +64,13 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
54
64
 
55
65
  | # | Rule | Enforcement | Rationale |
56
66
  |---|---|---|---|
57
- | T1 | `frame(t)` MUST depend only on `t` and the scene's constants: no `Date`, `Math.random`, `performance.now`, no state carried between calls, no module-level mutable state. | [gate] G1 re-renders each `t`; G11 scans the source (`lib/check.mjs:42,80-81`) | Random access: a player can jump, an exporter can write exactly one frame, video samples `t = f/fps` (`runtime/scene.mjs:14-17`). |
67
+ | T1 | `frame(t)` MUST depend only on `t` and the scene's constants: no `Date`, `Math.random`, `performance.now`, no state carried between calls, no module-level mutable state. | [gate] G1 re-renders each `t`; G11 renders under stubbed clocks and scans the source (`lib/check.mjs`) | Random access: a player can jump, an exporter can write exactly one frame, video samples `t = f/fps` (`runtime/scene.mjs:14-17`). |
58
68
  | T2 | Same `t` (and same style/options) MUST give byte-identical output. | [gate] G1 | Tests, diffs, caching and committed media all depend on it. |
59
69
  | T3 | Callers MUST clamp `t` to `[0, duration]`; `renderSvg` does (`runtime/scene.mjs:70`). `frame` MAY assume a clamped `t`. | — | Defines "before start" and "hold". |
60
70
  | T4 | Every number interpolated into markup MUST be rounded: `num(n, 2)` by default, 3 digits for `opacity`, 4 for scale factors (`runtime/svg.mjs:17-22,29,64`). `num` MUST throw on non-finite input and never emit `-0`. | [gate] G3; non-finite → G5 | 17-digit floats made "settled" frames differ by 1 ms (`skills/animated-diagram/references/technique.md:128-129`). |
61
71
  | T5 | Visibility MUST be decided on rounded values: an element whose opacity rounds to 0 is omitted; an opacity that rounds to 1 is not written (`runtime/svg.mjs:28,39,68-72`). | by construction (`el`, `fade`) | Identical-looking frames must be identical bytes (opacity 0.9999 vs omitted). |
62
72
  | T6 | Scenes MUST NOT use CSS transitions/animations or timers; the renderer owns the clock (`runtime/player.mjs:15`). | — | Exported frames would not match what plays. |
63
- | T7 | Variation, if any, MUST derive from constants and `t` (seeded), never from runtime randomness. | [gate] G11 (heuristic) | Same as T2. |
73
+ | T7 | Variation, if any, MUST derive from constants and `t` (seeded), never from runtime randomness. | [gate] G1, G11 | Same as T2. |
64
74
 
65
75
  ## 3. Formats and layout per format
66
76
 
@@ -83,12 +93,16 @@ Formats map a name to a viewBox (`runtime/scene.mjs:23-30`):
83
93
  - Arrangement by aspect: "narrow" means `tall` or `W/H < 0.8` → column/tree;
84
94
  `W/H ≥ 1.5` → row (or 2-row snake when cells are < 96 px) for `sequence`;
85
95
  otherwise snake grid (`runtime/types/sequence.mjs:35-46`) or radial ellipse
86
- (`runtime/types/hub-spoke.mjs:40,59-73`).
96
+ (`runtime/types/hub-spoke.mjs:40,59-73`). `timeline` runs its axis
97
+ vertically when narrow and horizontally otherwise (`runtime/types/timeline.mjs:239`);
98
+ `stack` is one column of layers with a rail on the right in every format.
87
99
  - **Auto-fit text**: a type MUST try the largest font size and step down by
88
100
  1 px to `FONT_MIN = 14` (`runtime/parts.mjs:12`) until every label wraps
89
101
  into its budget; if none fits it MUST throw. Maxima: `sequence` 22 px fixed /
90
102
  16 px strips (`runtime/types/sequence.mjs:127`); `hub-spoke` 20 / 16
91
- (`runtime/types/hub-spoke.mjs:97`); `spec.fontSize` overrides the maximum.
103
+ (`runtime/types/hub-spoke.mjs:97`); `timeline` 22 / 16
104
+ (`runtime/types/timeline.mjs:280`); `stack` 22 / 16
105
+ (`runtime/types/stack.mjs:129`); `spec.fontSize` overrides the maximum.
92
106
  - **Collisions**: a layout whose boxes overlap (6 px gap) or leave the canvas
93
107
  MUST throw rather than render (`runtime/types/hub-spoke.mjs:33-35,76-84,119`).
94
108
  - Connectors MUST NOT cross labels; snake-grid row turns route as elbows
@@ -206,7 +220,17 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
206
220
 
207
221
  - Scenes MUST NOT contain colour literals [gate] G4. Colours MUST be
208
222
  `tok(name)` → `var(--mk-<name>)`; an unknown name throws
209
- (`runtime/style.mjs:52-55`).
223
+ (`runtime/style.mjs:52-55`). Besides tokens, a colour attribute (`fill`,
224
+ `stroke`, `stop-color`, `color`, `flood-color`, `lighting-color`) or colour
225
+ property (in `style="…"` or a `<style>` element: those, `background` and
226
+ any `*-color`) MAY hold only `url(#…)` references and the keywords `none`,
227
+ `currentColor`, `transparent`, `inherit`, `initial`, `unset`, `revert`,
228
+ `revert-layer`, `context-fill` and `context-stroke`. None of them names a
229
+ colour, so they look the same under every style and theme; `transparent`
230
+ is allowed because it paints nothing in either theme. Named colours
231
+ (`red`), hex, colour functions and other custom properties (`var(--brand)`,
232
+ `var(--mk-accent, red)`) are literals. Text content is not checked: a label
233
+ may say "#1".
210
234
  - Tokens (`runtime/style.mjs:14-23`): `bg`, `surface`, `ink`, `muted`, `line`,
211
235
  `accent`, `onAccent`, `emphasis`. Roles: see
212
236
  [`styles.md`](../../skills/animated-diagram/references/styles.md). Exactly one
@@ -222,11 +246,21 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
222
246
  literal (`runtime/scene.mjs:84`, `runtime/style.mjs:86-93`), because slide
223
247
  apps, rasterizers and image viewers ignore CSS variables; an unresolvable
224
248
  token throws.
225
- - **Contrast** (`runtime/style.mjs:114-134`, WCAG relative luminance): in both
226
- themes, text ≥ 4.5:1 — `ink`/`muted` on `bg` and `surface`, `onAccent` on
227
- `accent`; shapes ≥ 3:1 — `line`, `accent`, `emphasis` on `bg`. `motion-kit
228
- check` MUST fail when the selected style violates any pair [gate] G12
229
- (`cli/motion-kit.mjs:83-85`). `neutral` MUST pass (`test/runtime.test.mjs:96-98`).
249
+ - **Contrast** (`runtime/style.mjs`, `checkContrast`, WCAG relative
250
+ luminance): in both themes, every pair in `CONTRAST_PAIRS`, the token pairs
251
+ the scene types and shared parts draw where the pair carries meaning in a
252
+ step frame. Text ≥ 4.5:1 — `ink`/`muted` on `bg` and `surface`, `onAccent`
253
+ on `accent`; shapes ≥ 3:1 — `line`, `accent`, `emphasis` on `bg`, and
254
+ `emphasis` on `accent` (the ring marking the current node sits 3.5 units
255
+ from the reached node it surrounds, and tells "here" from "reached" without
256
+ hue). `CONTRAST_EXEMPT` lists, with a reason each, the pairs left out:
257
+ `line` on `surface` (an outline is told from the canvas outside it),
258
+ `accent` on `surface` and `emphasis` on `surface` and `accent` on `line`
259
+ (only in motion), `onAccent` on `emphasis` (only the logo; logos are exempt
260
+ from WCAG 1.4.11). A scene adds the pairs it draws besides through
261
+ `contrastPairs` (§1). `motion-kit check` MUST fail when the selected style
262
+ violates any shared pair, once per run, or a scene's own, per scene [gate]
263
+ G12 (`lib/gate.mjs`). `neutral` MUST pass (`test/runtime.test.mjs`).
230
264
  - motion-kit ships only `neutral` (`styles/neutral.json`); brand styles MUST
231
265
  live in the consumer repo.
232
266
 
@@ -256,11 +290,17 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
256
290
 
257
291
  - `steps[i].at` is the time step *i* is fully shown; its frame is what a slide,
258
292
  a step button and Slidev show.
259
- - Step frames MUST be settled: nothing moves at `at` [gate] G6
260
- (`frame(at − 1 ms) === frame(at)`, `lib/check.mjs:55-58`).
261
- - Authoring rule: the next motion MUST NOT start before `at`, and anything that
262
- fades out by a step (a travelling dot) MUST reach 0 by `at`. Scene types
263
- satisfy this by construction: `PERIOD ≥ HOP + FILL`
293
+ - Step frames MUST be settled: nothing moves at `at` [gate] G6. The step's
294
+ own motion MAY end exactly at `at` but MUST be at rest there
295
+ (`frame(at − 1 ms) === frame(at)`), and nothing MAY change in the 50 ms
296
+ after it (`frame(at + δ) === frame(at)` for δ = 1, 15, 30 and 45 ms, up to
297
+ the next step; `SETTLE_AFTER` in `lib/check.mjs`). The look-ahead is what
298
+ catches slow motion passing through `at`, which rounding hides over 1 ms.
299
+ - Authoring rule: the next motion MUST NOT start earlier than 50 ms after
300
+ `at` (the "pause between beats" in
301
+ [`motion-vocabulary.md`](../../skills/animated-diagram/references/motion-vocabulary.md)),
302
+ and anything that fades out by a step (a travelling dot) MUST reach 0 by
303
+ `at`. Scene types satisfy this by construction: `PERIOD = HOP + FILL + 0.05`
264
304
  (`runtime/types/sequence.mjs:24-29`), step = fill end
265
305
  (`runtime/types/sequence.mjs:147`, `runtime/types/hub-spoke.mjs:149`).
266
306
  Springs and split edges MUST budget their settle time and lag (§4.3, §4.5).
@@ -273,14 +313,18 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
273
313
 
274
314
  ## 9. Scene types
275
315
 
276
- Registered types: `sequence` (2–12 nodes) and `hub-spoke` (2–10 spokes)
277
- (`runtime/types/index.mjs:14-17`). Fields and storyboards:
316
+ Registered types: `sequence` (2–12 nodes), `hub-spoke` (2–10 spokes),
317
+ `timeline` (2–8 events) and `stack` (2–8 layers)
318
+ (`runtime/types/index.mjs:18-23`). Fields and storyboards:
278
319
  [`scene-types.md`](../../skills/animated-diagram/references/scene-types.md).
279
320
  Normative points:
280
321
 
281
- - Out-of-range node/spoke counts, a missing hub and an unknown type MUST throw
322
+ - Out-of-range node/spoke/event/layer counts, a missing hub and an unknown type MUST throw
282
323
  (`runtime/types/sequence.mjs:123`, `runtime/types/hub-spoke.mjs:89-90`,
283
- `runtime/types/index.mjs:21`).
324
+ `runtime/types/timeline.mjs:203-231`, `runtime/types/stack.mjs:117-126`,
325
+ `runtime/types/index.mjs:27`). A timeline event without `when` or `label`, a
326
+ past event after a planned one, planned events without `now`, a stack layer
327
+ without `label` and a stack `direction` other than `down`/`up` MUST throw.
284
328
  - A new type MUST export `(spec, {format, locale}) → scene`, be registered in
285
329
  `SCENE_TYPES`, and get a gate run across every format and locale
286
330
  (`AGENTS.md:59-61`). A custom shape SHOULD be promoted to a type once used twice.
@@ -299,28 +343,39 @@ Every target goes through this one function. It MUST emit `<svg>` with
299
343
  | `theme` | `light`/`dark` for resolution or inline vars. |
300
344
  | `live` | Omits inline vars; the container supplies them. |
301
345
  | `background` | Paints a full-size `bg` rect behind the diagram. |
302
- | `idPrefix` | MUST be unique per page when several diagrams share it. |
346
+ | `idPrefix` | Prefix for every id in the output: `<title>`/`<desc>`, and the scene's own through `frame(t, { idPrefix })`. Made a safe id token (`safeId`: letters, digits, `_`, `-`). MUST be unique per page when several diagrams share it. |
303
347
 
304
348
  ### 10.2 Live player (`runtime/player.mjs`)
305
349
 
306
350
  | Requirement | Source |
307
351
  |---|---|
308
352
  | MUST touch the DOM only when mounted; scenes stay pure, the player owns the clock (`requestAnimationFrame`, wall time). | `runtime/player.mjs` (`mountPlayer`, `tick`), `AGENTS.md` |
309
- | Initial state MUST be the final frame; a server/no-JS fallback SHOULD put the final frame in the container. | `runtime/player.mjs` (initial-state block), `lib/build.mjs:25`, `adapters/astro/AnimatedDiagram.astro:31` |
310
- | Autoplay `visible` (default): plays once from 0 when ≥ 40 % in view, then holds; `none` disables. MUST NOT loop. | `runtime/player.mjs` (`autoplay`, `autoplayPending`) |
311
- | Play/pause MUST always be present when motion can play (WCAG 2.2.2); label shows Play/Pause/Replay. | `runtime/player.mjs` (`playBtn`, `draw`) |
353
+ | Initial state MUST be the final frame. A server/no-JS fallback SHOULD be `playerMarkup(scene, { id, … })` inside a `.mk-player` container, with `PLAYER_CSS` in a `style[data-mk-player-css]` and the tokens from `themeCss(selector, style, theme)`: the markup the player builds, with the controls `inert`. The step list and the colours then exist without JavaScript, and mounting moves nothing. A plain final-frame SVG MAY be used instead. | `runtime/player.mjs` (`view`, `playerMarkup`, `themeCss`), `lib/build.mjs`, `adapters/astro/AnimatedDiagram.astro`, `test/player.test.mjs` |
354
+ | Autoplay `visible` (default): plays once from 0 when ≥ 40 % of the diagram, or ≥ 40 % of the viewport's height, is in view (decided from the intersection, not `isIntersecting` alone), then holds; `none` disables. MUST NOT loop. | `runtime/player.mjs` (`shown`, `THRESHOLDS`) |
355
+ | While a playing diagram does not intersect the viewport (scrolled away, `display: none`), its clock MUST stop and no frame be drawn; when it intersects again, playback resumes from the same time. Visibility is observed until `destroy()`. | `runtime/player.mjs` (`onVisibility`, `run`) |
356
+ | Each frame MUST update the stage's SVG in place (`patchMarkup`): nodes that persist between frames are kept, only changed attributes and text are written, and nodes are added, removed or replaced (by position; a different tag replaces the subtree) only where the markup's structure changes. The DOM after each frame MUST equal what `innerHTML` would build from the same markup. Markup outside the subset the patch reproduces exactly (comments, CDATA, single-quoted or bare attributes, named entities beyond the XML five, elements inside `<title>`, `<desc>` or `<foreignObject>`, HTML elements that leave SVG) MUST fall back to `innerHTML` for that frame. Because nodes persist, a CSS transition on the diagram would run between frames: T6 keeps them out of scenes, and pages MUST NOT add them. | `runtime/patch.mjs`, `runtime/player.mjs` (`draw`), `test/patch.test.mjs`, `test/player.test.mjs`, `scripts/bench-player.mjs` |
357
+ | Play/pause MUST always be present when motion can play (WCAG 2.2.2); label shows Play/Pause/Replay. | `runtime/player.mjs` (`playLabel`, `draw`) |
358
+ | Every control (buttons, scrubber) MUST be at least 44 × 44 px. The caption and the play button MUST keep the size of their longest content, so playback does not shift the layout. | `PLAYER_CSS` (`.mk-btn`, `.mk-scrub`, `.mk-caption`, `.mk-play`) |
312
359
  | One `<button>` per step, labelled `N. label`; activating it jumps by default. `animateSteps: true` opts buttons and keyboard navigation into `playToStep`. `aria-current="step"` marks the active step. | `runtime/player.mjs` |
313
360
  | Optional range scrubber (`aria-label`, default "Timeline"); input pauses and seeks. | `runtime/player.mjs` (`options.scrubber`) |
314
361
  | Caption shows the active step's `detail` and is `aria-hidden`; a visually hidden ordered list of all steps (`label: detail`) MUST be present for screen readers. | `runtime/player.mjs` (`caption`, `sr`) |
315
- | Keyboard on the focusable stage: ←/→ step, Home/End first/last, Space play/pause. | `runtime/player.mjs` (`stage.tabIndex`, `keydown` handler) |
316
- | Visible focus style for every control. | `runtime/player.mjs` (`.mk-btn:focus-visible` rule) |
362
+ | Keyboard on the focusable stage, a `role="group"` named by the scene title and described by a visually hidden hint (`labels.keys`): ←/→ step, Home/End first/last, Space play/pause. Every element with `tabindex="0"` has a role. | `runtime/player.mjs` (`view`, `keydown` handler) |
363
+ | Visible focus style for the stage and every control. | `PLAYER_CSS` (`:focus-visible` rule) |
317
364
  | `prefers-reduced-motion: reduce`: final frame, no autoplay, no play button, Space ignored. | `runtime/player.mjs` (`reduced`) |
318
- | Theme: `options.theme`, else follows `prefers-color-scheme` live. | `runtime/player.mjs` (`applyTheme`, `themeQuery`) |
319
- | `playToStep(i)` MUST play forward from the current time, clamp to the target step's exact `at` and hold. Backward, same-time and reduced-motion calls MUST jump. Indices are zero-based; invalid indices throw `RangeError`. Retargeting replaces the target; `play()` continues to duration; `seek(t)` cancels playback. | `runtime/player.mjs`, `test/player.test.mjs` |
365
+ | Theme: `options.theme`, else follows `prefers-color-scheme` live. Tokens MUST be set one custom property at a time, keeping the container's other inline CSS. | `runtime/player.mjs` (`applyTheme`, `themeQuery`) |
366
+ | The player stylesheet MUST be in the document whenever a player mounts: it is added to `<head>` unless a `style[data-mk-player-css]` is present, so a page swap that removed it cannot leave players unstyled. `injectCss: false` opts out. | `runtime/player.mjs` (`ensureStyle`), `test/player.test.mjs` |
367
+ | Ids: each player renders with its own prefix, `options.id`, else `scene.id` plus a per-page counter, so two players of one scene share no ids. | `runtime/player.mjs` (`prefix`) |
368
+ | `playToStep(ref)` MUST play forward from the current time, clamp to the target step's exact `at` and hold. Backward, same-time and reduced-motion calls MUST jump. `seekStep(ref)` jumps. `ref` is a zero-based index or a step `id`; an invalid index or unknown id throws `RangeError` (`stepIndex`). Retargeting replaces the target; `play()` continues to duration; `seek(t)` cancels playback. | `runtime/player.mjs`, `runtime/scene.mjs`, `test/player.test.mjs` |
320
369
  | `destroy()` MUST cancel the animation frame, disconnect visibility observation, remove theme listening and remove this controller's capture entry. | `runtime/player.mjs`, `test/player.test.mjs` |
321
370
  | **Capture hook**: the controller `{seek, play, pause, seekStep, playToStep, destroy, time, scene}` MUST be exposed at `globalThis.__motionKit[options.id ?? scene.id]`. | `runtime/player.mjs` |
322
371
 
323
- UI strings MAY be localized via `options.labels`.
372
+ UI strings MAY be localized via `options.labels`: a flat `{ play, pause, replay, steps, scrubber, keys }` object (`steps` names the controls group, `keys` is the stage's keyboard hint), or a dictionary keyed by locale (`{ en: {…}, nl: {…} }`) resolved with `options.locale`, then its language subtag, then `en`, then the first entry. Missing keys keep the English defaults (`resolveLabels`, `runtime/player.mjs`).
373
+
374
+ Keyboard step changes (←/→/Home/End) MUST be announced through a visually hidden `role="status"` polite live region (`N. label: detail`); autoplay, pointer and scrubber use stay silent.
375
+
376
+ `mountPlayer` MUST release any player already mounted on the same container (`destroy()`), so remounting never leaks clocks, observers or capture entries. The build output passes `locale` through, so label dictionaries resolve there too; the Slidev adapter announces each click's step through the same kind of live region.
377
+
378
+ The Astro adapter mounts each diagram once, tears the players down on `astro:before-swap` and mounts the new page's diagrams on `astro:page-load`. Its root element exposes the controller as `.controller` from mount, and dispatches `motion-ready` (bubbling, `detail.controller`) or `motion-error` (`detail.error`) once the page's own scripts and their `DOMContentLoaded` and `astro:page-load` handlers have run, so a script placed after the diagram can still listen. Its `id` prop sets the element id, the capture-hook key and the id prefix; it MUST be a safe id token, used once per page, or the build fails.
324
379
 
325
380
  ### 10.2.1 Custom element (`adapters/element/motion-diagram.mjs`)
326
381
 
@@ -338,13 +393,32 @@ UI strings MAY be localized via `options.labels`.
338
393
  destroy the player and restore the fallback; reconnection mounts afresh.
339
394
  Superseded asynchronous loads MUST NOT mount or publish errors.
340
395
 
396
+ ### 10.2.2 Page links (`runtime/links.mjs`)
397
+
398
+ Helpers that drive a player controller from the page around it. They MUST
399
+ touch the DOM only when called, never move focus, never change layout (the
400
+ only marks are `aria-current="step"` attributes), and return a `dispose()`
401
+ that removes every listener, observer and mark they added.
402
+
403
+ | Requirement | Source |
404
+ |---|---|
405
+ | A step reference (`data-mk-step`, or a number) MUST resolve to the step with that `id`, else to a whole-number index; an unknown id or an index out of range throws `RangeError` when the helper binds. | `runtime/links.mjs` (`stepRef`, `sectionSteps`), `test/links.test.mjs` |
406
+ | `scrollSteps(controller, sections, options)`: a section's step is its `data-mk-step`, else its position. The active section MUST be the last one, in order, whose top has reached a line at `line` (default 0.5) of the viewport's or `root`'s height (`activeSection`), observed with one IntersectionObserver whose root margin ends at that line. Before the first section nothing changes. | `runtime/links.mjs` (`scrollSteps`, `activeSection`) |
407
+ | Moving one section forward to a later step MUST play to it (`playToStep`); every other change (back, skipping, the first section, `animate: false`, `prefers-reduced-motion: reduce`) MUST jump (`seekStep`); a change to the same step calls nothing (`scrollMove`). The diagram MUST only rest on settled steps: no continuous scrubbing. | `runtime/links.mjs` (`scrollMove`), `test/links.test.mjs` |
408
+ | `linkSteps(controller, rootOrElements, options)`: every element with `data-mk-step` (under the root, or given) MUST select its step on `pointerenter` (not touch), `focusin` and `click`, so keyboard focus selects the same step as hover. A selection jumps; `animate: true` plays forward unless reduced motion. With `restore: true`, once neither hover nor focus is on a term, the frame shown before the preview returns (`seek`), unless a click committed a step. | `runtime/links.mjs` (`linkSteps`), `test/links.test.mjs` |
409
+ | Without IntersectionObserver, `scrollSteps` MUST do nothing (the text still reads). | `runtime/links.mjs` |
410
+
341
411
  ### 10.3 Self-contained HTML (`motion-kit build`, `lib/build.mjs`)
342
412
 
343
413
  - MUST be one document with the runtime inlined by `lib/bundle.mjs`, no
344
414
  external scripts, stylesheets or fetches (`test/cli.test.mjs:31-37`), so it
345
415
  works under `connect-src 'none'` and from `file://`.
346
- - MUST pre-render the final frame (`lib/build.mjs:25`) and set `<html lang>`
347
- to the scene locale (`:31-33`).
416
+ - MUST pre-render the player's first state (`playerMarkup`, `PLAYER_CSS`,
417
+ `themeCss`) and set `<html lang>` to the scene locale (`lib/build.mjs`).
418
+ - A custom module is built with the caller's `--options` and `kit`: every
419
+ runtime module is a bundle entry, so the `MotionKit` global is the kit.
420
+ The page-link helpers (§10.2.2) are bundled too (`MotionKitRuntime.scrollSteps`,
421
+ `MotionKitRuntime.linkSteps`).
348
422
  - The CLI MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:112-113`)
349
423
  and bundled code containing `</script>` (`:115`).
350
424
  - The inlined runtime MUST render the same bytes as Node
@@ -361,6 +435,8 @@ UI strings MAY be localized via `options.labels`.
361
435
  animation delayed `0.3 s + start`; the last slice holds (`mk-hold`, fill
362
436
  forwards) (`:35-47`). Plays once; MUST hold the final frame.
363
437
  - Under `prefers-reduced-motion: reduce` only the final slice is visible (`:39`).
438
+ - Slices share one document: a slice whose markup defines ids is rendered with
439
+ its own prefix (`<idPrefix>-<n>`, base `mk-bake` or `options.idPrefix`).
364
440
  - One theme per file; for theme-following embeds publish a light and dark file
365
441
  (`README.md:21-29`, `scripts/render-media.sh`).
366
442
  - Size grows with fps × duration; README use SHOULD lower fps to 10–12.
@@ -377,13 +453,27 @@ UI strings MAY be localized via `options.labels`.
377
453
  makes the canvas opaque (transparent by default).
378
454
  - `--qc`: frames at `max(0, at − 0.2)` and `at + 0.2` (not after the last step)
379
455
  under `qc/` (`lib/export.mjs:58-65`).
380
- - `index.html` contact sheet: steps, QC row, a 360 px phone row and the human
381
- review checklist (`lib/export.mjs:93-108`).
456
+ - `index.html` contact sheet: steps, QC row, a phone row and the human review
457
+ checklist (`lib/export.mjs`, `contactSheet`). The phone row MUST show the
458
+ scene built for the `tall` format, in the same locale, options, style and
459
+ theme, at 360 px (`qc/phone.svg`, manifest `kind: "phone"`); when the tall
460
+ layout cannot be built, it shows the exported frame and says why.
382
461
  - `manifest.json` MUST contain no timestamps: tool, version, scene, type,
383
- format, locale, size, duration, style, theme, a 16-hex input hash
384
- (source file + style), source commit, render settings, file list
385
- (`lib/export.mjs:66-88`). Two exports of the same inputs MUST be equal
386
- (`test/cli.test.mjs:20-30`).
462
+ format, locale, scene options, size, duration, style, theme, a 16-hex input
463
+ hash (source file + style + scene options), source commit, source dirty
464
+ flag, render settings, file list (`lib/export.mjs`). Two exports of the
465
+ same inputs MUST be equal (`test/cli.test.mjs`).
466
+ - `sourceCommit` is the short `HEAD` of the repository holding the source
467
+ file. `sourceDirty` is `true` when that file differs from it (modified,
468
+ staged or untracked: `status --porcelain -- <file>` is not empty), `false`
469
+ when it does not, and `null`, like `sourceCommit`, outside a repository.
470
+ Only the source file counts: modules a custom scene imports, the style file
471
+ and the options file do not (the input hash covers the style and options).
472
+ - A re-export into the same folder MUST replace the previous one: files the
473
+ folder's previous `manifest.json` listed and the new one does not are
474
+ removed, so the folder holds what the new manifest lists. Files no manifest
475
+ listed MUST NOT be touched; the export names them in a warning on stderr
476
+ (`lib/export.mjs`, `test/cli.test.mjs`).
387
477
 
388
478
  ### 10.6 Video (`motion-kit video`, `lib/video.mjs`)
389
479
 
@@ -405,21 +495,34 @@ UI strings MAY be localized via `options.labels`.
405
495
  itself (`:67-72`); forward by one click animates from the previous step's
406
496
  `at` to the next, any other move seeks (`:93-100`); print/export, overview
407
497
  and reduced motion show the settled step frame (`:65`).
408
- - **Astro** (`adapters/astro/AnimatedDiagram.astro`): server-renders the final
409
- frame and mounts the player; props MUST be serializable (a spec, not a scene).
498
+ - **Astro** (`adapters/astro/AnimatedDiagram.astro`): server-renders the
499
+ player's first state (§10.2) and mounts the player. It takes a `spec`, or a
500
+ custom module by path (`module`, a `/src/…/*.scene.mjs|js` file found with
501
+ `import.meta.glob`, loaded on demand in the browser) with its `options`;
502
+ `theme` (`light`/`dark`, else the system), `style` (token data), `id`,
503
+ `scrubber`, `labels`, `class`. Props MUST be serializable (a spec or a module
504
+ path, not a scene). The player stylesheet is emitted once per page; each
505
+ instance carries its tokens and a page-unique id (`mk-<scene.id>-<n>` unless
506
+ `id` is given). It fails the build for a missing module, options with a spec,
507
+ or an invalid theme.
410
508
  - **Vendor** (`cli/motion-kit.mjs`, `vendor` command): copies `runtime/`, one
411
- adapter, `lib/check.mjs` and the full MIT `LICENSE`; writes a spec-only gate
412
- script and `MOTION_KIT_VERSION`. Consumers MUST retain `LICENSE` and the
509
+ adapter, `lib/check.mjs`, `lib/gate.mjs`, `lib/load.mjs` and the full MIT
510
+ `LICENSE`; writes `check.mjs`, which runs the same gate as `motion-kit
511
+ check` (§11) with `--format`, `--locale`, `--style` and `--options`, and
512
+ `MOTION_KIT_VERSION`. Consumers MUST retain `LICENSE` and the
413
513
  SPDX headers when redistributing vendored files. Vendored files MUST NOT
414
514
  be edited in the consumer.
415
515
 
416
516
  ## 11. The gate
417
517
 
418
- `checkScene(scene)` (`lib/check.mjs:33-84`) samples 121 evenly spaced times
419
- (`SAMPLES = 120`, `:9`) and stops collecting after 13 problems (`:51`).
420
- `motion-kit check` runs it for every file × format (all six unless `--format`)
421
- × locale (§7) and adds the style contrast check; it exits 1 on any failure or
422
- construction error (`cli/motion-kit.mjs:81-108`). `npm run gate` = unit tests +
518
+ `checkScene(scene)` (`lib/check.mjs`) samples 121 evenly spaced times
519
+ (`SAMPLES = 120`) and stops collecting after 13 problems.
520
+ `motion-kit check` and the vendored `check.mjs` both run `checkFiles`
521
+ (`lib/gate.mjs`): every file × format (all six unless `--format`, repeatable)
522
+ × locale (`--locale`, repeatable; else every locale a spec's strings carry, and
523
+ `en` for a module, §7), with `--options` for modules, plus the style contrast
524
+ check. A file that cannot be read, parsed or built fails on its own and the
525
+ remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = unit tests +
423
526
  `check` over `examples/` and `brand/` (`package.json:15-18`).
424
527
 
425
528
  | ID | Rule | Code | Rationale |
@@ -427,16 +530,17 @@ construction error (`cli/motion-kit.mjs:81-108`). `npm run gate` = unit tests +
427
530
  | G1 | Rendering the same `t` twice MUST yield identical bytes. | `lib/check.mjs:41-42` | Determinism (T1/T2). Catches clocks/randomness and call-to-call state; cannot catch state that is consistent between two calls. |
428
531
  | G2 | Each sampled frame MUST be well-formed (balanced tags, no stray `<`, entities only `amp lt gt quot #39 #n`). | `:12-31,43-44` | Escaping failures and broken markup break every target. |
429
532
  | G3 | No number with ≥ 5 decimals in the full SVG. | `:45-46` | Rounding (T4). |
430
- | G4 | No `#hex`, `rgb(a)(`, `hsl(a)(` in `frame()` output. | `:47-49` | Token-only colours: themes and brand styles must work everywhere. |
533
+ | G4 | No colour literal in `frame()` markup: colour attributes and properties hold only tokens, `url(#…)` and the colourless keywords of §6; no hex or colour function (`rgb()`, `hsl()`, `oklch()`, …) in any attribute or `<style>`. Id references (`url(#…)`, `href="#…"`) are not colours; text content is not checked. | `lib/check.mjs` (`findColourLiteral`) | Token-only colours: themes and brand styles must work everywhere. |
431
534
  | G5 | No `NaN`, `undefined`, `Infinity` in `frame()` output. | `:50` | Silent geometry bugs. |
432
- | G6 | `render(at − 0.001) === render(at)` for every step. | `:55-58` | Settled step frames (§8). |
535
+ | G6 | For every step, `render(at)` equals `render(at − 1 ms)` and `render(at + δ)` for δ = 1, 15, 30, 45 ms (before the next step). | `lib/check.mjs` (rule 2, `SETTLE_AFTER`) | Settled step frames (§8); the 45 ms look-ahead sees slow motion that rounding hides over 1 ms. |
433
536
  | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
434
537
  | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
435
538
  | G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
436
539
  | G10 | Every word of every step label (escaped, trailing `/` stripped) appears in the final frame's text, unless `stepLabelsInFrame === false`. | `:72-77` | Step buttons and slides refer to things the viewer can see. Word-level, so it does not prove the label is contiguous. |
437
- | G11 | `frame.toString()` MUST NOT contain `Date.now`, `new Date`, `Math.random`, `performance.now`. | `:80-81` | T1. Textual heuristic: helpers defined outside `frame` are not scanned. |
438
- | G12 | Style passes WCAG contrast in both themes. | `cli/motion-kit.mjs:83-85`, `runtime/style.mjs:114-134` | Legibility in light and dark. |
439
- | G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `cli/motion-kit.mjs:92-103` | Reject, don't invent: a broken picture never renders. |
540
+ | G11 | Every sampled frame MUST render the same bytes under two stubbed clocks as under the real one: `Date`, `performance.now`, `Temporal.Now` and `Math.random` fixed at 1970 and 0, then at 2100 and ≈ 1, the globals restored afterwards. `frame.toString()` MUST NOT contain `Date.now`, `new Date`, `Math.random`, `performance.now`, `Temporal.Now`. | `lib/check.mjs` (rules 1 and 6) | T1. The stubbed render catches reads in the helpers a frame calls; the source scan, code paths the samples miss. A reference taken before the check runs (`const D = Date` at import) escapes the stub. |
541
+ | G12 | Style passes WCAG contrast in both themes for every pair in `CONTRAST_PAIRS` (once per run) and for each scene's `contrastPairs` (per scene). | `lib/gate.mjs`, `lib/check.mjs` (rule 8), `runtime/style.mjs` (`checkContrast`) | Legibility in light and dark, for the pairs actually drawn (§6). |
542
+ | G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `lib/gate.mjs` | Reject, don't invent: a broken picture never renders. |
543
+ | G14 | Rendered with two different `idPrefix` values, sampled frames share no `id`. | `lib/check.mjs` (rule 7) | Two instances on one page (wide and tall, or one diagram twice) must not share ids: `url(#x)` resolves to the first element with that id, and WCAG 2.1 SC 4.1.1 forbids duplicates. |
440
544
 
441
545
  The gate checks structure, not looks. Visual review (before/after frames,
442
546
  phone size, real-time playback, dark mode) is required by
@@ -454,12 +558,11 @@ Recorded, not resolved. Each needs an owner decision.
454
558
  | D3 | Every locale is checked | `.mjs` modules are checked in `en` only (`cli/motion-kit.mjs:89`), although `examples/custom-pulse.scene.mjs` ships `nl`. | "Labels fit … in every locale" (`README.md:97`, `AGENTS.md:48-49`). |
455
559
  | D4 | Missing copy | `localize` silently falls back to the first available language (`runtime/scene.mjs:36-39`). | "Missing label → throw" (`skills/animated-diagram/references/technique.md:111`). Only an empty *step* label throws. |
456
560
  | D5 | Gate rule G10 and `stepLabelsInFrame` | Enforced (`lib/check.mjs:70-77`). | Absent from the scene contract comment (`runtime/scene.mjs:4-12`), `custom-scenes.md`, and the rule lists in `README.md:94-99` and `AGENTS.md:38-49`. |
457
- | D6 | "Enforced by `motion-kit check`" | G1 and G11 only partly verify purity (no cross-call state detection; source scan limited to `frame`'s own text); CSS-transition and "no earlier-frame state" rules are not checked. Escaping is guaranteed by `esc`/`text`, and only detected by G2 for `<` and `&`. | All 11 determinism rules listed as "enforced by `motion-kit check`" (`skills/animated-diagram/references/technique.md:23-39`). |
561
+ | D6 | "Enforced by `motion-kit check`" | G1 and G11 only partly verify purity: no cross-call state detection, and a clock reference taken at import time escapes G11's stub; CSS-transition and "no earlier-frame state" rules are not checked. Escaping is guaranteed by `esc`/`text`, and only detected by G2 for `<` and `&`. | All 11 determinism rules listed as "enforced by `motion-kit check`" (`skills/animated-diagram/references/technique.md:23-39`). |
458
562
  | D7 | Style `radius` / `stroke` | Normalized (`runtime/style.mjs:63-64`) but never read; parts default to radius 10, stroke 2 (`runtime/parts.mjs:52,75`). | Documented as style fields (`styles.md:28-29`). |
459
563
  | D8 | Dark fallback | A style with no `dark` applies its **light** overrides to dark (`runtime/style.mjs:66`). | "Missing tokens fall back to neutral" (`styles.md:35`). |
460
564
  | D9 | Video frame reuse | PNGs are reused only when `t` repeats (lead and hold) (`lib/video.mjs:46`). | "Identical consecutive frames are rasterized once" (`skills/motion-render/references/video.md:9`). |
461
- | D10 | Capture-hook key | Key is `options.id ?? scene.id`, i.e. format-suffixed (`order-flow-16x9`); the Astro adapter appends a random suffix (`adapters/astro/AnimatedDiagram.astro:51`); the Slidev adapter exposes none. | `window.__motionKit[sceneId]` / `[id]` (`adapters/page/README.md:22`, `interactivity.md:14-15`). |
462
- | D11 | Vendored gate | `check.mjs` written by `vendor` handles `.json` only, skips the contrast check, and detects locales with `^[a-z]{2}$` (no region, no string-value test) (`cli/motion-kit.mjs:177-207`). | Implied parity with `motion-kit check` (`README.md:90-92`). |
565
+ | D10 | Capture-hook key | Key is `options.id ?? scene.id`, i.e. format-suffixed (`order-flow-16x9`); the Astro adapter uses its `id` prop or `mk-<scene.id>-<n>`; the Slidev adapter exposes none. | `window.__motionKit[sceneId]` / `[id]` (`adapters/page/README.md:22`, `interactivity.md`). |
463
566
  | D12 | Auto-fit maximum | Sequence 22 px, hub-spoke 20 px (`runtime/types/hub-spoke.mjs:97`). | "Fixed formats ≤ 22 px" without type distinction (`technique.md:90`); `formats.md:12` is correct. |
464
567
  | D13 | Timing budgets | `ENTRANCE_MAX` is exported but unused; stagger and entrance limits are not checked. | Listed as "Hard rules" (`skills/animated-diagram/SKILL.md:50`). |
465
- | D14 | Manifest reproducibility | `inputHash` covers the source file and style only, not the runtime; a runtime change keeps the hash while frames change (only `version` hints at it) (`lib/export.mjs:66-70`). | "A stale export is easy to spot" (`skills/motion-render/SKILL.md:66-68`). |
568
+ | D14 | Manifest reproducibility | `inputHash` covers the source file, style and scene options, not the runtime; a runtime change keeps the hash while frames change (only `version` hints at it) (`lib/export.mjs:66-70`). | "A stale export is easy to spot" (`skills/motion-render/SKILL.md:66-68`). |
@@ -135,6 +135,9 @@ export default function make({ format = "16:9", locale = "en" } = {}) {
135
135
  // Steps here are events, not nodes: their labels live in the player's
136
136
  // step buttons and captions, not in the drawing.
137
137
  stepLabelsInFrame: false,
138
+ // Beyond the pairs every scene draws: the progress bar's accent fill on
139
+ // its surface track. The gate checks the style against it too.
140
+ contrastPairs: [{ fg: "accent", bg: "surface", min: 3, use: "the progress bar's fill on its track" }],
138
141
  steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
139
142
  frame,
140
143
  };
@@ -0,0 +1,18 @@
1
+ {
2
+ "type": "timeline",
3
+ "id": "incident",
4
+ "title": { "en": "An incident, start to review", "nl": "Een storing, van begin tot evaluatie" },
5
+ "description": {
6
+ "en": "An outage from the first alert to the all-clear, with the review still to come.",
7
+ "nl": "Een storing van het eerste alarm tot het sein veilig, met de evaluatie nog te gaan."
8
+ },
9
+ "events": [
10
+ { "when": "09:02", "label": { "en": "Alert fires", "nl": "Alarm gaat af" }, "detail": { "en": "Error rates cross the threshold and on-call is paged.", "nl": "Het foutpercentage gaat over de drempel en de dienstdoende wordt opgeroepen." } },
11
+ { "when": "09:06", "label": { "en": "On-call responds", "nl": "Dienstdoende reageert" }, "detail": { "en": "The engineer on call acknowledges and opens an incident channel.", "nl": "De dienstdoende engineer bevestigt en opent een storingskanaal." } },
12
+ { "when": "09:24", "label": { "en": "Cause found", "nl": "Oorzaak gevonden" }, "detail": { "en": "A configuration change from the morning release is the cause.", "nl": "Een configuratiewijziging uit de ochtendrelease is de oorzaak." } },
13
+ { "when": "09:41", "label": { "en": "Fix deployed", "nl": "Herstel uitgerold" }, "detail": { "en": "The change is rolled back and error rates fall.", "nl": "De wijziging wordt teruggedraaid en het foutpercentage daalt." } },
14
+ { "when": "10:15", "label": { "en": "All clear", "nl": "Sein veilig" }, "detail": { "en": "Metrics are back to normal and the incident is closed.", "nl": "De metrieken zijn weer normaal en de storing is gesloten." } },
15
+ { "when": { "en": "Thursday", "nl": "Donderdag" }, "label": { "en": "Review", "nl": "Evaluatie" }, "planned": true, "detail": { "en": "The team writes down what happened and what changes, without blame.", "nl": "Het team legt vast wat er gebeurde en wat er verandert, zonder schuldvraag." } }
16
+ ],
17
+ "now": { "label": { "en": "Now", "nl": "Nu" }, "detail": { "en": "The service is healthy; the review is still to come.", "nl": "De dienst is gezond; de evaluatie moet nog komen." } }
18
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "type": "stack",
3
+ "id": "web-stack",
4
+ "title": { "en": "A request through the layers", "nl": "Een verzoek door de lagen" },
5
+ "description": {
6
+ "en": "A request from the browser passes the CDN, the API gateway and the service before it reaches the database.",
7
+ "nl": "Een verzoek uit de browser passeert het CDN, de API-gateway en de dienst voordat het de database bereikt."
8
+ },
9
+ "layers": [
10
+ { "label": { "en": "Browser", "nl": "Browser" }, "detail": { "en": "The user's click becomes an HTTPS request.", "nl": "De klik van de gebruiker wordt een HTTPS-verzoek." } },
11
+ { "label": { "en": "CDN", "nl": "CDN" }, "detail": { "en": "The edge answers cached pages and passes everything else on.", "nl": "De rand beantwoordt gecachete pagina's en geeft de rest door." } },
12
+ { "label": { "en": "API gateway", "nl": "API-gateway" }, "detail": { "en": "Checks who is asking and how often.", "nl": "Controleert wie er vraagt en hoe vaak." } },
13
+ { "label": { "en": "Order service", "nl": "Bestelservice" }, "detail": { "en": "The business logic decides what the request means.", "nl": "De bedrijfslogica bepaalt wat het verzoek betekent." } },
14
+ { "label": { "en": "Database", "nl": "Database" }, "detail": { "en": "The data is read or written, and the answer travels back.", "nl": "De gegevens worden gelezen of geschreven, en het antwoord gaat terug." } }
15
+ ],
16
+ "direction": "down"
17
+ }
package/lib/build.mjs CHANGED
@@ -2,32 +2,44 @@
2
2
  * motion-kit · build a self-contained interactive HTML file.
3
3
  *
4
4
  * One document, runtime inlined, no network requests: safe for Craft Pages
5
- * (connect-src 'none'), file:// and any static host. The final frame is
6
- * pre-rendered into the markup, so it reads correctly before (or without) JS.
5
+ * (connect-src 'none'), file:// and any static host. The player's first state
6
+ * (final frame, step list, colours) is pre-rendered into the markup, so it
7
+ * reads correctly before (or without) JS, and mounting moves nothing.
8
+ *
9
+ * A custom module gets its scene options and `kit` (every runtime export),
10
+ * as it does from the CLI.
7
11
  */
8
12
  import { fileURLToPath } from "node:url";
9
13
  import { bundle } from "./bundle.mjs";
10
14
  import { escapeHtml } from "./export.mjs";
11
- import { renderSvg } from "../runtime/scene.mjs";
15
+ import { PLAYER_CSS, playerMarkup, themeCss } from "../runtime/player.mjs";
12
16
  import { cssVars } from "../runtime/style.mjs";
13
17
 
14
18
  const RUNTIME = fileURLToPath(new URL("../runtime/", import.meta.url));
15
19
 
20
+ /** JSON for an inline script: `<` escaped, so no value can close the script element. */
21
+ const scriptJson = (/** @type {unknown} */ value) => JSON.stringify(value).replace(/</g, "\\u003c");
22
+
16
23
  /**
17
24
  * @param {import("./load.mjs").LoadedScene} loaded
18
- * @param {{style:import("../runtime/style.mjs").Style, format:string, locale:string, scrubber?:boolean, heading?:boolean, theme?:string, labels?:Record<string,string>}} o
25
+ * @param {{style:import("../runtime/style.mjs").Style, format:string, locale:string, scrubber?:boolean, heading?:boolean, theme?:string, labels?:Record<string,string|Record<string,string>>, options?:Record<string,unknown>}} o
26
+ * options: scene options for a custom module's factory
19
27
  */
20
28
  export function buildHtml(loaded, o) {
21
- const entries = [`${RUNTIME}types/index.mjs`, `${RUNTIME}scene.mjs`, `${RUNTIME}player.mjs`];
29
+ // Every runtime module is an entry, so the MotionKit global is the whole kit.
30
+ const entries = ["motion", "svg", "style", "wrap", "scene", "types/index", "player", "links"].map((m) => `${RUNTIME}${m}.mjs`);
31
+ const runtimeCount = entries.length;
22
32
  if (loaded.kind === "module") entries.push(loaded.file);
23
- const code = bundle(entries);
33
+ // MotionKitRuntime is the runtime alone: a custom module's exports, spread
34
+ // after it into MotionKit, may reuse a runtime name without breaking `kit`.
35
+ const code = bundle(entries, { runtimeName: "MotionKitRuntime", runtimeCount });
24
36
  const { scene } = loaded;
25
- const fallback = renderSvg(scene, scene.duration, { style: o.style, live: true, idPrefix: "mk-fallback" });
37
+ const options = { style: o.style, scrubber: o.scrubber !== false, theme: o.theme, labels: o.labels, locale: o.locale };
38
+ const fallback = playerMarkup(scene, { ...options, id: "mk-fallback" });
26
39
  const make =
27
40
  loaded.kind === "spec"
28
- ? `MotionKit.createScene(${JSON.stringify(loaded.spec)}, ${JSON.stringify({ format: o.format, locale: o.locale })})`
29
- : `MotionKit.default(${JSON.stringify({ format: o.format, locale: o.locale })})`;
30
- const options = { style: o.style, scrubber: o.scrubber !== false, theme: o.theme, labels: o.labels };
41
+ ? `MotionKit.createScene(${scriptJson(loaded.spec)}, ${scriptJson({ format: o.format, locale: o.locale })})`
42
+ : `MotionKitRuntime.validateScene(MotionKit.default(Object.assign(${scriptJson(o.options ?? {})}, ${scriptJson({ format: o.format, locale: o.locale })}, { kit: MotionKitRuntime })))`;
31
43
  const lang = scene.locale ?? o.locale ?? "en";
32
44
  return `<!doctype html>
33
45
  <html lang="${escapeHtml(lang)}">
@@ -42,18 +54,20 @@ body{margin:0;padding:24px;background:var(--mk-bg);color:var(--mk-ink);font-fami
42
54
  main{max-width:${Math.max(scene.width, 360)}px;margin:0 auto}
43
55
  h1{font-size:20px;line-height:1.3;margin:0 0 4px}
44
56
  .lede{margin:0 0 16px;color:var(--mk-muted);font-size:15px;line-height:1.45}
57
+ ${themeCss("#mk", o.style, o.theme)}
45
58
  </style>
59
+ <style data-mk-player-css>${PLAYER_CSS}</style>
46
60
  </head>
47
61
  <body>
48
62
  <main>
49
63
  ${o.heading === false ? "" : `<h1>${escapeHtml(scene.title)}</h1>\n<p class="lede">${escapeHtml(scene.description)}</p>`}
50
- <div id="mk">${fallback}</div>
64
+ <div id="mk" class="mk-player">${fallback}</div>
51
65
  </main>
52
66
  <script>
53
67
  ${code}
54
68
  (function () {
55
69
  var scene = ${make};
56
- MotionKit.mountPlayer(document.getElementById("mk"), scene, ${JSON.stringify(options)});
70
+ MotionKitRuntime.mountPlayer(document.getElementById("mk"), scene, ${scriptJson(options)});
57
71
  })();
58
72
  </script>
59
73
  </body>
package/lib/bundle.mjs CHANGED
@@ -15,7 +15,11 @@ import { dirname, resolve } from "node:path";
15
15
 
16
16
  const IMPORT_RE = /^import\s*\{([^}]*)\}\s*from\s*["'](\.{1,2}\/[^"']+)["'];?\s*$/;
17
17
 
18
- export function bundle(entries, { globalName = "MotionKit" } = {}) {
18
+ /**
19
+ * @param {string[]} entries
20
+ * @param {{ globalName?: string, runtimeName?: string, runtimeCount?: number }} [o]
21
+ */
22
+ export function bundle(entries, { globalName = "MotionKit", runtimeName = "", runtimeCount = entries.length } = {}) {
19
23
  const order = [];
20
24
  const seen = new Map();
21
25
  function visit(file) {
@@ -64,5 +68,8 @@ export function bundle(entries, { globalName = "MotionKit" } = {}) {
64
68
  }
65
69
  const ids = entries.map((e) => visit(e));
66
70
  const merged = ids.map((id) => `...${id}`).join(", ");
67
- return `(() => {\n"use strict";\n${order.join("\n")}\nglobalThis.${globalName} = Object.freeze({ ${merged} });\n})();\n`;
71
+ // runtimeName: a second global of the first `runtimeCount` entries only, so a
72
+ // later entry's exports cannot shadow theirs.
73
+ const runtime = runtimeName ? `\nglobalThis.${runtimeName} = Object.freeze({ ${ids.slice(0, runtimeCount).map((id) => `...${id}`).join(", ")} });` : "";
74
+ return `(() => {\n"use strict";\n${order.join("\n")}\nglobalThis.${globalName} = Object.freeze({ ${merged} });${runtime}\n})();\n`;
68
75
  }