@liqweed/motion-kit 0.4.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 (38) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +13 -5
  4. package/adapters/element/README.md +5 -0
  5. package/adapters/page/README.md +5 -0
  6. package/cli/motion-kit.mjs +9 -3
  7. package/docs/spec/technique.md +93 -30
  8. package/examples/custom-pulse.scene.mjs +3 -0
  9. package/examples/incident.json +18 -0
  10. package/examples/web-stack.json +17 -0
  11. package/lib/build.mjs +1 -1
  12. package/lib/check.mjs +207 -16
  13. package/lib/export.mjs +104 -7
  14. package/lib/gate.mjs +5 -3
  15. package/package.json +6 -3
  16. package/runtime/kit.mjs +2 -2
  17. package/runtime/links.mjs +314 -0
  18. package/runtime/parts.mjs +15 -0
  19. package/runtime/patch.mjs +297 -0
  20. package/runtime/player.mjs +5 -1
  21. package/runtime/scene.mjs +3 -1
  22. package/runtime/style.mjs +62 -16
  23. package/runtime/types/hub-spoke.mjs +2 -2
  24. package/runtime/types/index.mjs +4 -0
  25. package/runtime/types/sequence.mjs +2 -2
  26. package/runtime/types/stack.mjs +227 -0
  27. package/runtime/types/timeline.mjs +405 -0
  28. package/skills/animated-diagram/SKILL.md +27 -6
  29. package/skills/animated-diagram/references/custom-scenes.md +6 -1
  30. package/skills/animated-diagram/references/interactivity.md +111 -6
  31. package/skills/animated-diagram/references/qc.md +3 -0
  32. package/skills/animated-diagram/references/scene-types.md +45 -2
  33. package/skills/animated-diagram/references/styles.md +45 -5
  34. package/skills/animated-diagram/references/technique.md +9 -4
  35. package/skills/motion-render/SKILL.md +24 -6
  36. package/skills/motion-render/references/formats.md +8 -8
  37. package/skills/project-logo/SKILL.md +15 -4
  38. package/styles/neutral.json +2 -2
@@ -7,7 +7,7 @@
7
7
  "name": "motion-kit",
8
8
  "source": "./",
9
9
  "description": "animated-diagram, motion-render and project-logo skills and the motion-kit runtime/CLI",
10
- "version": "0.4.0"
10
+ "version": "0.5.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Deterministic animated diagrams: scenes as pure functions of time for live pages, Slidev, slide frames, baked SVG and video; plus project logos/icons.",
5
5
  "author": { "name": "Ophir Radnitz" },
6
6
  "repository": "https://github.com/liqweed/motion-kit",
package/README.md CHANGED
@@ -43,7 +43,8 @@ node cli/motion-kit.mjs export examples/smart-home.json -o out/slides --png --qc
43
43
  node cli/motion-kit.mjs bake examples/order-flow.json -o out/order.svg -f wide
44
44
  node cli/motion-kit.mjs video examples/smart-home.json -f 9:16 -o out/reel.mp4 --sheet out/sheet.png
45
45
  node cli/motion-kit.mjs icon brand/logo.scene.mjs -o . # project icon set: assets/ + .idea/
46
- npm test
46
+ npm test # includes PNG snapshots of the examples' step frames
47
+ npm run snapshots:update # after an intended visual change: regenerate test/snapshots/
47
48
  npm run gate # typecheck, versions, tests, scene gate, media freshness
48
49
  ```
49
50
 
@@ -60,18 +61,23 @@ runtime/ dependency-free ES modules (browser + Node)
60
61
  style.mjs tokens, neutral style, contrast checks, token resolution
61
62
  scene.mjs scene contract, formats, renderSvg
62
63
  parts.mjs shared node/label drawing
63
- types/ spec-driven scene types: sequence, hub-spoke
64
+ types/ spec-driven scene types: sequence, hub-spoke, timeline, stack
64
65
  bake.mjs zero-JS animated SVG
65
66
  player.mjs live player (controls, a11y, reduced motion, capture hook)
67
+ links.mjs page links: scroll sections and data-mk-step terms drive the player
68
+ patch.mjs in-place SVG updates for the player's frames
66
69
  lib/ Node-side: check (gate), export, build (HTML inliner), raster, video, icon
67
70
  adapters/ slidev (Vue), astro, element (custom element), page (README)
68
71
  skills/ animated-diagram, motion-render, project-logo (Claude Code / Craft skills)
69
- examples/ order-flow (sequence), smart-home (hub-spoke), custom-pulse (custom module)
72
+ examples/ order-flow (sequence), smart-home (hub-spoke), incident (timeline),
73
+ web-stack (stack), custom-pulse (custom module)
74
+ bench/ heavy scene for npm run bench:player (live-player frame cost)
70
75
  brand/ logo scene (built with motion-kit); renders go to assets/ + .idea/ (npm run media)
71
76
  assets/ generated project icon: icon.svg, icon.png, icon-animated.svg
72
77
  docs/media/ baked README animations (generated: npm run media)
73
78
  docs/ prd.md, roadmap.md, spec/technique.md
74
79
  styles/ neutral.json (the only style shipped; brands live in their repos)
80
+ test/ node:test suites; snapshots/ holds PNG step frames (npm run snapshots:update)
75
81
  ```
76
82
 
77
83
  ## Install the skills
@@ -83,8 +89,10 @@ styles/ neutral.json (the only style shipped; brands live in their repos
83
89
  `~/.agents/skills/motion-render` and `~/.agents/skills/project-logo` to
84
90
  `skills/*` in this clone.
85
91
 
86
- The skills look for this clone at `~/workspace/motion-kit` first (it has
87
- `node_modules`), then fall back to the plugin copy.
92
+ The skills find the CLI in this order: `MOTION_KIT_HOME` (a clone or install
93
+ you choose; run `npm install` there for PNG and video), then the npm package
94
+ through `npx` at the plugin's version (it installs the PNG renderer), then the
95
+ plugin copy, which checks, builds and exports SVG but renders no PNG or video.
88
96
 
89
97
  ## Use in another repo (vendor)
90
98
 
@@ -42,6 +42,11 @@ diagram.addEventListener("motion-error", ({ detail }) => console.error(detail.er
42
42
  diagram.controller?.seek(2);
43
43
  ```
44
44
 
45
+ To drive the diagram from the page (text sections that advance it on scroll,
46
+ terms marked `data-mk-step` that select a step on hover and focus), import
47
+ `scrollSteps` / `linkSteps` from the vendored `runtime/links.mjs` and bind them
48
+ to the controller; see `skills/animated-diagram/references/interactivity.md`.
49
+
45
50
  The player follows its normal visible autoplay and reduced-motion rules.
46
51
  Removing the element destroys its player, cancels pending loading and restores
47
52
  the fallback; reconnecting mounts a fresh controller. Events are dispatched
@@ -21,3 +21,8 @@ step buttons, a scrubber and captions, and respects `prefers-reduced-motion`
21
21
  and `prefers-color-scheme`.
22
22
 
23
23
  Capture hook for renderers: `window.__motionKit[sceneId].seek(t)`.
24
+
25
+ The page-link helpers (`scrollSteps`, `linkSteps`, from `runtime/links.mjs`)
26
+ are bundled on the `MotionKitRuntime` global; bind them to the controller from
27
+ the capture hook when you add text sections or `data-mk-step` terms around
28
+ the diagram.
@@ -10,6 +10,7 @@
10
10
  * motion-kit icon <scene> --out <repo> [--size 512] [--style S] [--no-png] project icon set (assets/, .idea/)
11
11
  * motion-kit vendor <dir> [--adapter page|slidev|astro|element]
12
12
  * motion-kit formats | types
13
+ * motion-kit --version print the version
13
14
  *
14
15
  * <scene> is a spec (.json, any registered type) or a custom module (.mjs).
15
16
  * --options O passes scene options to a custom module's factory, unchanged:
@@ -57,6 +58,7 @@ const { values: a, positionals } = parseArgs({
57
58
  "no-scrubber": { type: "boolean", default: false },
58
59
  "no-heading": { type: "boolean", default: false },
59
60
  help: { type: "boolean", short: "h" },
61
+ version: { type: "boolean", short: "v" },
60
62
  },
61
63
  });
62
64
  const [cmd, ...args] = positionals;
@@ -71,6 +73,10 @@ function need(v, what) {
71
73
  }
72
74
 
73
75
  async function main() {
76
+ if (a.version) {
77
+ console.log(VERSION);
78
+ return;
79
+ }
74
80
  if (!cmd || a.help) {
75
81
  const src = readFileSync(fileURLToPath(import.meta.url), "utf8");
76
82
  console.log(src.slice(src.indexOf("/**") + 3, src.indexOf("*/")).replace(/^ \* ?/gm, ""));
@@ -104,7 +110,7 @@ async function main() {
104
110
  const file = need(args[0], "<scene>");
105
111
  const sopts = await sceneOpts(file);
106
112
  const loaded = await loadScene(file, sopts);
107
- const r = checkScene(loaded.scene);
113
+ const r = checkScene(loaded.scene, { style });
108
114
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
109
115
  const html = buildHtml(loaded, { style, ...where, options: sopts.options, scrubber: !a["no-scrubber"], heading: !a["no-heading"] });
110
116
  if (/<\/script/i.test(html.slice(html.indexOf("<script>") + 8, html.lastIndexOf("</script>")))) fail("bundled code contains </script>");
@@ -118,7 +124,7 @@ async function main() {
118
124
  const file = need(args[0], "<scene>");
119
125
  const sopts = await sceneOpts(file);
120
126
  const { scene } = await loadScene(file, sopts);
121
- const r = checkScene(scene);
127
+ const r = checkScene(scene, { style });
122
128
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
123
129
  if (a.png && !(await rasterizer())) fail("--png needs @resvg/resvg-js or Chrome");
124
130
  // The contact sheet's phone row shows the tall layout, as a phone does.
@@ -168,7 +174,7 @@ async function main() {
168
174
  case "icon": {
169
175
  const file = need(args[0], "<scene>");
170
176
  const { scene } = await loadScene(file, await sceneOpts(file, { ...where, format: format ?? "1:1" }));
171
- const r = checkScene(scene);
177
+ const r = checkScene(scene, { style });
172
178
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
173
179
  const png = !a["no-png"];
174
180
  if (png && !(await rasterizer())) fail("icon PNG needs @resvg/resvg-js or Chrome (or pass --no-png)");
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: motion-kit technique — normative specification
3
3
  status: draft
4
- last_updated: 2026-11-16
4
+ last_updated: 2026-11-17
5
5
  ---
6
6
 
7
7
  # motion-kit technique — normative specification
@@ -38,10 +38,11 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
38
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
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
+ `createScene(spec, {format, locale})` (`runtime/types/index.mjs:25-29`) — or a
45
46
  custom module whose default export is `(opts) → scene`, called by
46
47
  `sceneFromModule` (`runtime/kit.mjs`) with
47
48
  `opts = { ...options, format, locale, kit }`. `options` are the caller's
@@ -63,13 +64,13 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
63
64
 
64
65
  | # | Rule | Enforcement | Rationale |
65
66
  |---|---|---|---|
66
- | 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`). |
67
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. |
68
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". |
69
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`). |
70
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). |
71
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. |
72
- | 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. |
73
74
 
74
75
  ## 3. Formats and layout per format
75
76
 
@@ -92,12 +93,16 @@ Formats map a name to a viewBox (`runtime/scene.mjs:23-30`):
92
93
  - Arrangement by aspect: "narrow" means `tall` or `W/H < 0.8` → column/tree;
93
94
  `W/H ≥ 1.5` → row (or 2-row snake when cells are < 96 px) for `sequence`;
94
95
  otherwise snake grid (`runtime/types/sequence.mjs:35-46`) or radial ellipse
95
- (`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.
96
99
  - **Auto-fit text**: a type MUST try the largest font size and step down by
97
100
  1 px to `FONT_MIN = 14` (`runtime/parts.mjs:12`) until every label wraps
98
101
  into its budget; if none fits it MUST throw. Maxima: `sequence` 22 px fixed /
99
102
  16 px strips (`runtime/types/sequence.mjs:127`); `hub-spoke` 20 / 16
100
- (`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.
101
106
  - **Collisions**: a layout whose boxes overlap (6 px gap) or leave the canvas
102
107
  MUST throw rather than render (`runtime/types/hub-spoke.mjs:33-35,76-84,119`).
103
108
  - Connectors MUST NOT cross labels; snake-grid row turns route as elbows
@@ -215,7 +220,17 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
215
220
 
216
221
  - Scenes MUST NOT contain colour literals [gate] G4. Colours MUST be
217
222
  `tok(name)` → `var(--mk-<name>)`; an unknown name throws
218
- (`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".
219
234
  - Tokens (`runtime/style.mjs:14-23`): `bg`, `surface`, `ink`, `muted`, `line`,
220
235
  `accent`, `onAccent`, `emphasis`. Roles: see
221
236
  [`styles.md`](../../skills/animated-diagram/references/styles.md). Exactly one
@@ -231,11 +246,21 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
231
246
  literal (`runtime/scene.mjs:84`, `runtime/style.mjs:86-93`), because slide
232
247
  apps, rasterizers and image viewers ignore CSS variables; an unresolvable
233
248
  token throws.
234
- - **Contrast** (`runtime/style.mjs:114-134`, WCAG relative luminance): in both
235
- themes, text ≥ 4.5:1 — `ink`/`muted` on `bg` and `surface`, `onAccent` on
236
- `accent`; shapes ≥ 3:1 — `line`, `accent`, `emphasis` on `bg`. `motion-kit
237
- check` MUST fail when the selected style violates any pair [gate] G12
238
- (`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`).
239
264
  - motion-kit ships only `neutral` (`styles/neutral.json`); brand styles MUST
240
265
  live in the consumer repo.
241
266
 
@@ -265,11 +290,17 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
265
290
 
266
291
  - `steps[i].at` is the time step *i* is fully shown; its frame is what a slide,
267
292
  a step button and Slidev show.
268
- - Step frames MUST be settled: nothing moves at `at` [gate] G6
269
- (`frame(at − 1 ms) === frame(at)`, `lib/check.mjs:55-58`).
270
- - Authoring rule: the next motion MUST NOT start before `at`, and anything that
271
- fades out by a step (a travelling dot) MUST reach 0 by `at`. Scene types
272
- 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`
273
304
  (`runtime/types/sequence.mjs:24-29`), step = fill end
274
305
  (`runtime/types/sequence.mjs:147`, `runtime/types/hub-spoke.mjs:149`).
275
306
  Springs and split edges MUST budget their settle time and lag (§4.3, §4.5).
@@ -282,14 +313,18 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
282
313
 
283
314
  ## 9. Scene types
284
315
 
285
- Registered types: `sequence` (2–12 nodes) and `hub-spoke` (2–10 spokes)
286
- (`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:
287
319
  [`scene-types.md`](../../skills/animated-diagram/references/scene-types.md).
288
320
  Normative points:
289
321
 
290
- - 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
291
323
  (`runtime/types/sequence.mjs:123`, `runtime/types/hub-spoke.mjs:89-90`,
292
- `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.
293
328
  - A new type MUST export `(spec, {format, locale}) → scene`, be registered in
294
329
  `SCENE_TYPES`, and get a gate run across every format and locale
295
330
  (`AGENTS.md:59-61`). A custom shape SHOULD be promoted to a type once used twice.
@@ -318,6 +353,7 @@ Every target goes through this one function. It MUST emit `<svg>` with
318
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` |
319
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`) |
320
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` |
321
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`) |
322
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`) |
323
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` |
@@ -357,6 +393,21 @@ The Astro adapter mounts each diagram once, tears the players down on `astro:bef
357
393
  destroy the player and restore the fallback; reconnection mounts afresh.
358
394
  Superseded asynchronous loads MUST NOT mount or publish errors.
359
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
+
360
411
  ### 10.3 Self-contained HTML (`motion-kit build`, `lib/build.mjs`)
361
412
 
362
413
  - MUST be one document with the runtime inlined by `lib/bundle.mjs`, no
@@ -366,6 +417,8 @@ The Astro adapter mounts each diagram once, tears the players down on `astro:bef
366
417
  `themeCss`) and set `<html lang>` to the scene locale (`lib/build.mjs`).
367
418
  - A custom module is built with the caller's `--options` and `kit`: every
368
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`).
369
422
  - The CLI MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:112-113`)
370
423
  and bundled code containing `</script>` (`:115`).
371
424
  - The inlined runtime MUST render the same bytes as Node
@@ -407,10 +460,20 @@ The Astro adapter mounts each diagram once, tears the players down on `astro:bef
407
460
  layout cannot be built, it shows the exported frame and says why.
408
461
  - `manifest.json` MUST contain no timestamps: tool, version, scene, type,
409
462
  format, locale, scene options, size, duration, style, theme, a 16-hex input
410
- hash (source file + style + scene options), source commit, render settings,
411
- file list
412
- (`lib/export.mjs:66-88`). Two exports of the same inputs MUST be equal
413
- (`test/cli.test.mjs:20-30`).
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`).
414
477
 
415
478
  ### 10.6 Video (`motion-kit video`, `lib/video.mjs`)
416
479
 
@@ -467,15 +530,15 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
467
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. |
468
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. |
469
532
  | G3 | No number with ≥ 5 decimals in the full SVG. | `:45-46` | Rounding (T4). |
470
- | G4 | No `#hex`, `rgb(a)(`, `hsl(a)(` in `frame()` output; id references (`url(#…)`, `href="#…"`) are not colours. | `: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. |
471
534
  | G5 | No `NaN`, `undefined`, `Infinity` in `frame()` output. | `:50` | Silent geometry bugs. |
472
- | 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. |
473
536
  | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
474
537
  | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
475
538
  | G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
476
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. |
477
- | 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. |
478
- | G12 | Style passes WCAG contrast in both themes. | `lib/gate.mjs`, `runtime/style.mjs` (`checkContrast`) | Legibility in light and dark. |
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). |
479
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. |
480
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. |
481
544
 
@@ -495,7 +558,7 @@ Recorded, not resolved. Each needs an owner decision.
495
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`). |
496
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. |
497
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`. |
498
- | 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`). |
499
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`). |
500
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`). |
501
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`). |
@@ -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
@@ -27,7 +27,7 @@ const scriptJson = (/** @type {unknown} */ value) => JSON.stringify(value).repla
27
27
  */
28
28
  export function buildHtml(loaded, o) {
29
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"].map((m) => `${RUNTIME}${m}.mjs`);
30
+ const entries = ["motion", "svg", "style", "wrap", "scene", "types/index", "player", "links"].map((m) => `${RUNTIME}${m}.mjs`);
31
31
  const runtimeCount = entries.length;
32
32
  if (loaded.kind === "module") entries.push(loaded.file);
33
33
  // MotionKitRuntime is the runtime alone: a custom module's exports, spread