@liqweed/motion-kit 0.4.0 → 0.6.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 (45) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +26 -6
  4. package/adapters/element/README.md +5 -0
  5. package/adapters/page/README.md +10 -0
  6. package/cli/motion-kit.mjs +14 -4
  7. package/docs/spec/technique.md +129 -51
  8. package/examples/checkout.json +104 -0
  9. package/examples/connection.json +80 -0
  10. package/examples/custom-pulse.scene.mjs +5 -0
  11. package/examples/incident.json +18 -0
  12. package/examples/player-states.json +97 -0
  13. package/examples/web-stack.json +17 -0
  14. package/lib/build.mjs +1 -1
  15. package/lib/check.mjs +215 -21
  16. package/lib/export.mjs +116 -7
  17. package/lib/gate.mjs +9 -7
  18. package/lib/load.mjs +15 -0
  19. package/package.json +6 -3
  20. package/runtime/kit.mjs +2 -2
  21. package/runtime/links.mjs +318 -0
  22. package/runtime/parts.mjs +15 -0
  23. package/runtime/patch.mjs +297 -0
  24. package/runtime/player.mjs +45 -2
  25. package/runtime/scene.mjs +24 -9
  26. package/runtime/style.mjs +65 -16
  27. package/runtime/types/hub-spoke.mjs +10 -8
  28. package/runtime/types/index.mjs +7 -0
  29. package/runtime/types/sequence.mjs +10 -8
  30. package/runtime/types/stack.mjs +230 -0
  31. package/runtime/types/timeline.mjs +407 -0
  32. package/runtime/types/walk.mjs +162 -0
  33. package/skills/animated-diagram/SKILL.md +28 -7
  34. package/skills/animated-diagram/references/custom-scenes.md +20 -1
  35. package/skills/animated-diagram/references/interactivity.md +129 -6
  36. package/skills/animated-diagram/references/motion-vocabulary.md +1 -1
  37. package/skills/animated-diagram/references/qc.md +3 -0
  38. package/skills/animated-diagram/references/scene-types.md +100 -4
  39. package/skills/animated-diagram/references/styles.md +55 -6
  40. package/skills/animated-diagram/references/technique.md +15 -6
  41. package/skills/motion-render/SKILL.md +31 -6
  42. package/skills/motion-render/references/formats.md +8 -8
  43. package/skills/motion-render/references/video.md +1 -1
  44. package/skills/project-logo/SKILL.md +15 -4
  45. 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.6.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.6.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
 
@@ -160,7 +168,7 @@ for inline specs, styles, lifecycle and error handling.
160
168
 
161
169
  Deterministic bytes · settled step frames · rounded numbers · token-only colours ·
162
170
  escaped labels · labels fit their budget in every locale · holds the final frame ·
163
- ≤ ~8–10 s · no clock or randomness in scenes · ids from the instance prefix. See
171
+ hard limit 12 s (aim for ≤ 8 s) · no clock or randomness in scenes · ids from the instance prefix. See
164
172
  `skills/animated-diagram/references/technique.md`.
165
173
 
166
174
  ## Contributing, changes and stability
@@ -185,3 +193,15 @@ for related tools and when to use them instead.
185
193
  Pull requests here are reviewed with the help of
186
194
  [CodeRabbit](https://coderabbit.ai), which supports open source projects for
187
195
  free. Thank you, CodeRabbit, for the support.
196
+
197
+ See the [Astro consumer guide](docs/guides/astro.md) for dictionaries, server
198
+ rendering, styles, page helpers, CI and upgrades. The six built-in scene types
199
+ include [state-machine and request-journey](skills/animated-diagram/references/scene-types.md).
200
+ The [spec playground](https://motion-kit.dev/playground/) checks, plays and
201
+ shares a JSON spec directly in the browser.
202
+
203
+ Localized dictionaries must contain the requested locale; plain strings are
204
+ shared. Custom modules can export `locales = ["en", "nl"]` for gate coverage.
205
+ Narrative scenes may set `stepLabelsInFrame: false`; otherwise every step label
206
+ must appear in the final frame. `controller.onStep(callback)` observes changes
207
+ without polling and returns an unsubscribe function.
@@ -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,13 @@ 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.
29
+
30
+ The capture-hook key is `options.id ?? scene.id`; built-in scene ids include
31
+ the format (for example `order-flow-16x9`). Page integrations should retain
32
+ the returned controller. `controller.onStep(callback)` reports the current
33
+ step immediately, then changed indices, and returns an unsubscribe function.
@@ -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.
@@ -139,6 +145,8 @@ async function main() {
139
145
  case "bake": {
140
146
  const file = need(args[0], "<scene>");
141
147
  const { scene } = await loadScene(file, await sceneOpts(file));
148
+ const gate = checkScene(scene, { style });
149
+ if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
142
150
  const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
143
151
  const out = need(a.out, "--out");
144
152
  writeFileSync(out, svg);
@@ -149,6 +157,8 @@ async function main() {
149
157
  case "video": {
150
158
  const file = need(args[0], "<scene>");
151
159
  const { scene } = await loadScene(file, await sceneOpts(file));
160
+ const gate = checkScene(scene, { style });
161
+ if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
152
162
  const out = need(a.out, "--out");
153
163
  const r = await renderVideo(scene, {
154
164
  out,
@@ -168,7 +178,7 @@ async function main() {
168
178
  case "icon": {
169
179
  const file = need(args[0], "<scene>");
170
180
  const { scene } = await loadScene(file, await sceneOpts(file, { ...where, format: format ?? "1:1" }));
171
- const r = checkScene(scene);
181
+ const r = checkScene(scene, { style });
172
182
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
173
183
  const png = !a["no-png"];
174
184
  if (png && !(await rasterizer())) fail("icon PNG needs @resvg/resvg-js or Chrome (or pass --no-png)");
@@ -203,7 +213,7 @@ const VENDOR_CHECK = `#!/usr/bin/env node
203
213
  // node check.mjs <scene.json|scene.mjs …> [--format F]… [--locale L]… [--style style.json] [--options O]
204
214
  //
205
215
  // Every format unless --format; for a spec every locale its strings carry, for
206
- // a custom module "en", unless --locale. The style (neutral by default) must
216
+ // a custom module its exported locales (default "en"), unless --locale. The style (neutral by default) must
207
217
  // pass the contrast check. --options passes scene options to custom modules:
208
218
  // a .json file, inline JSON, or an .mjs module exporting ({ format, locale }) => options.
209
219
  // Exits 1 if anything fails; a file that cannot be loaded fails on its own.
@@ -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-18
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
 
@@ -253,23 +278,30 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
253
278
  `runtime/types/hub-spoke.mjs:31`, `runtime/wrap.mjs:40-42`). Layouts SHOULD
254
279
  budget for Dutch/German being ~30 % longer than English.
255
280
  - Any string MAY be localized: `{en: "…", nl: "…"}`. `localize(value, locale)`
256
- returns the plain string, the requested locale, else the first value, else ""
257
- (`runtime/scene.mjs:33-40`).
281
+ returns a plain string unchanged or the exact requested translation. A missing
282
+ or empty translation throws; null/undefined optional copy returns "".
258
283
  - Labels are labels; sentences go in `detail`. Font size MUST NOT go below
259
284
  14 px at 1× (§3).
260
285
  - Every shipped locale × format MUST pass the gate. `check` derives locales
261
286
  from a `.json` spec's localized objects (keys `xx` or `xx-YY`)
262
- (`cli/motion-kit.mjs:89,209-220`); see §12 D3 for modules.
287
+ (`lib/gate.mjs`). Modules export a non-empty unique `locales` array (default
288
+ `["en"]`); explicit `--locale` flags override either source.
263
289
 
264
290
  ## 8. Steps and settled frames
265
291
 
266
292
  - `steps[i].at` is the time step *i* is fully shown; its frame is what a slide,
267
293
  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`
294
+ - Step frames MUST be settled: nothing moves at `at` [gate] G6. The step's
295
+ own motion MAY end exactly at `at` but MUST be at rest there
296
+ (`frame(at − 1 ms) === frame(at)`), and nothing MAY change in the 50 ms
297
+ after it (`frame(at + δ) === frame(at)` for δ = 1, 15, 30 and 45 ms, up to
298
+ the next step; `SETTLE_AFTER` in `lib/check.mjs`). The look-ahead is what
299
+ catches slow motion passing through `at`, which rounding hides over 1 ms.
300
+ - Authoring rule: the next motion MUST NOT start earlier than 50 ms after
301
+ `at` (the "pause between beats" in
302
+ [`motion-vocabulary.md`](../../skills/animated-diagram/references/motion-vocabulary.md)),
303
+ and anything that fades out by a step (a travelling dot) MUST reach 0 by
304
+ `at`. Scene types satisfy this by construction: `PERIOD = HOP + FILL + 0.05`
273
305
  (`runtime/types/sequence.mjs:24-29`), step = fill end
274
306
  (`runtime/types/sequence.mjs:147`, `runtime/types/hub-spoke.mjs:149`).
275
307
  Springs and split edges MUST budget their settle time and lag (§4.3, §4.5).
@@ -282,14 +314,18 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
282
314
 
283
315
  ## 9. Scene types
284
316
 
285
- Registered types: `sequence` (2–12 nodes) and `hub-spoke` (2–10 spokes)
286
- (`runtime/types/index.mjs:14-17`). Fields and storyboards:
317
+ Registered types: `sequence` (2–12 nodes), `hub-spoke` (2–10 spokes),
318
+ `timeline` (2–8 events), `stack` (2–8 layers), `state-machine` and
319
+ `request-journey` (2–8 nodes; graph bounds in §11.1). Fields and storyboards:
287
320
  [`scene-types.md`](../../skills/animated-diagram/references/scene-types.md).
288
321
  Normative points:
289
322
 
290
- - Out-of-range node/spoke counts, a missing hub and an unknown type MUST throw
323
+ - Out-of-range node/spoke/event/layer counts, a missing hub and an unknown type MUST throw
291
324
  (`runtime/types/sequence.mjs:123`, `runtime/types/hub-spoke.mjs:89-90`,
292
- `runtime/types/index.mjs:21`).
325
+ `runtime/types/timeline.mjs:203-231`, `runtime/types/stack.mjs:117-126`,
326
+ `runtime/types/index.mjs:27`). A timeline event without `when` or `label`, a
327
+ past event after a planned one, planned events without `now`, a stack layer
328
+ without `label` and a stack `direction` other than `down`/`up` MUST throw.
293
329
  - A new type MUST export `(spec, {format, locale}) → scene`, be registered in
294
330
  `SCENE_TYPES`, and get a gate run across every format and locale
295
331
  (`AGENTS.md:59-61`). A custom shape SHOULD be promoted to a type once used twice.
@@ -308,7 +344,7 @@ Every target goes through this one function. It MUST emit `<svg>` with
308
344
  | `theme` | `light`/`dark` for resolution or inline vars. |
309
345
  | `live` | Omits inline vars; the container supplies them. |
310
346
  | `background` | Paints a full-size `bg` rect behind the diagram. |
311
- | `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. |
347
+ | `idPrefix` | Prefix for every id in the output: `<title>`/`<desc>`, and the scene's own through `frame(t, { idPrefix, style })`. Made a safe id token (`safeId`: letters, digits, `_`, `-`). MUST be unique per page when several diagrams share it. |
312
348
 
313
349
  ### 10.2 Live player (`runtime/player.mjs`)
314
350
 
@@ -318,6 +354,7 @@ Every target goes through this one function. It MUST emit `<svg>` with
318
354
  | 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
355
  | 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
356
  | 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`) |
357
+ | 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
358
  | 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
359
  | 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
360
  | 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 +394,21 @@ The Astro adapter mounts each diagram once, tears the players down on `astro:bef
357
394
  destroy the player and restore the fallback; reconnection mounts afresh.
358
395
  Superseded asynchronous loads MUST NOT mount or publish errors.
359
396
 
397
+ ### 10.2.2 Page links (`runtime/links.mjs`)
398
+
399
+ Helpers that drive a player controller from the page around it. They MUST
400
+ touch the DOM only when called, never move focus, never change layout (the
401
+ only marks are `aria-current="step"` attributes), and return a `dispose()`
402
+ that removes every listener, observer and mark they added.
403
+
404
+ | Requirement | Source |
405
+ |---|---|
406
+ | 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` |
407
+ | `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`) |
408
+ | 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` |
409
+ | `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` |
410
+ | Without IntersectionObserver, `scrollSteps` MUST do nothing (the text still reads). | `runtime/links.mjs` |
411
+
360
412
  ### 10.3 Self-contained HTML (`motion-kit build`, `lib/build.mjs`)
361
413
 
362
414
  - MUST be one document with the runtime inlined by `lib/bundle.mjs`, no
@@ -366,6 +418,8 @@ The Astro adapter mounts each diagram once, tears the players down on `astro:bef
366
418
  `themeCss`) and set `<html lang>` to the scene locale (`lib/build.mjs`).
367
419
  - A custom module is built with the caller's `--options` and `kit`: every
368
420
  runtime module is a bundle entry, so the `MotionKit` global is the kit.
421
+ The page-link helpers (§10.2.2) are bundled too (`MotionKitRuntime.scrollSteps`,
422
+ `MotionKitRuntime.linkSteps`).
369
423
  - The CLI MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:112-113`)
370
424
  and bundled code containing `</script>` (`:115`).
371
425
  - The inlined runtime MUST render the same bytes as Node
@@ -407,10 +461,20 @@ The Astro adapter mounts each diagram once, tears the players down on `astro:bef
407
461
  layout cannot be built, it shows the exported frame and says why.
408
462
  - `manifest.json` MUST contain no timestamps: tool, version, scene, type,
409
463
  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`).
464
+ hash (source file + style + scene options), source commit, source dirty
465
+ flag, render settings, file list (`lib/export.mjs`). Two exports of the
466
+ same inputs MUST be equal (`test/cli.test.mjs`).
467
+ - `sourceCommit` is the short `HEAD` of the repository holding the source
468
+ file. `sourceDirty` is `true` when that file differs from it (modified,
469
+ staged or untracked: `status --porcelain -- <file>` is not empty), `false`
470
+ when it does not, and `null`, like `sourceCommit`, outside a repository.
471
+ Only the source file counts: modules a custom scene imports, the style file
472
+ and the options file do not (the input hash covers the style and options).
473
+ - A re-export into the same folder MUST replace the previous one: files the
474
+ folder's previous `manifest.json` listed and the new one does not are
475
+ removed, so the folder holds what the new manifest lists. Files no manifest
476
+ listed MUST NOT be touched; the export names them in a warning on stderr
477
+ (`lib/export.mjs`, `test/cli.test.mjs`).
414
478
 
415
479
  ### 10.6 Video (`motion-kit video`, `lib/video.mjs`)
416
480
 
@@ -467,15 +531,15 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
467
531
  | 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
532
  | 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
533
  | 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. |
534
+ | 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
535
  | 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). |
536
+ | 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
537
  | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
474
538
  | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
475
- | G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
539
+ | G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
476
540
  | 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. |
541
+ | 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. |
542
+ | 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
543
  | 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
544
  | 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
545
 
@@ -484,22 +548,36 @@ phone size, real-time playback, dark mode) is required by
484
548
  [`qc.md`](../../skills/animated-diagram/references/qc.md), and a human signs
485
549
  off.
486
550
 
487
- ## 12. Discrepancies
551
+ ### 11.1 Gate policy decisions
488
552
 
489
- Recorded, not resolved. Each needs an owner decision.
553
+ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
490
554
 
491
- | # | Topic | Code says | Docs say |
492
- |---|---|---|---|
493
- | D1 | Duration budget | Gate fails only above **12 s** (`lib/check.mjs:68`). | "≤ ~8–10 s" (`README.md:98`, `AGENTS.md:47`); "≤ ~8 s" (`skills/animated-diagram/SKILL.md:50`, `motion-vocabulary.md:21`). |
494
- | D2 | Exporters refuse failing scenes | Only `build` and `export` run the gate; `bake` and `video` render any loadable scene (`cli/motion-kit.mjs:132-157`). | "Exporters refuse scenes that fail the gate" (`skills/motion-render/SKILL.md:17`). |
495
- | 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
- | 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
- | 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`). |
499
- | 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
- | 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
- | 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`). |
502
- | 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`). |
503
- | 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. |
504
- | 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`). |
505
- | 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`). |
555
+ | Question | Contract and reason |
556
+ |---|---|
557
+ | Duration | 12 s is the hard gate limit; ≤ 8 s is the design target. Keep valid existing scenes while making the two numbers explicit. |
558
+ | Export coverage | CLI build, export, bake, video and icon MUST run the same scene and style gate before writing output. Library render primitives remain composable. |
559
+ | Module locales | Modules MAY export `locales`; all declared locales MUST be checked by default. Undeclared modules retain `en` for compatibility. Explicit `--locale` overrides. |
560
+ | Translations | A localized object MUST supply the exact requested locale. Plain strings are shared. Silent cross-language fallback is forbidden. |
561
+ | Shape styles | Built-in scenes MUST use radius 0–24 (default 10) for rectangular node corners and stroke 1–4 (default 2) as their base width. Accent lines are 1.5×; timeline stems 0.75×. Circles, region borders and pills retain their shapes. Custom scenes MAY read normalized `style` from the frame context. |
562
+ | Vendored parity | CLI and vendored checks MUST call the same `lib/gate.mjs` and `lib/check.mjs`, including contrast, locales and caller options. |
563
+ | Neutral contrast | Keep emphasis-on-accent at 3:1, the darker light accent and lighter dark emphasis. The site chrome follows the corresponding neutral tokens. |
564
+
565
+ The controller also exposes `onStep(callback) → unsubscribe`, with an immediate
566
+ current index and subsequent changed indices (`-1` before the first step).
567
+ Destroy releases subscribers. `seek(t)` requires a finite time, clamps it,
568
+ pauses playback and cancels pending autoplay; external drivers use the controller
569
+ and must implement their own reduced-motion policy.
570
+
571
+ Registered graph walks are `state-machine` and `request-journey` (2–8 nodes,
572
+ 1–12 edges, 1–10 explicit path edges). Their fields, narrative steps, region
573
+ boundaries and limits are in the [scene type reference](../../skills/animated-diagram/references/scene-types.md).
574
+
575
+ Export manifests include `runtimeHash` (SHA-256 of sorted runtime module paths
576
+ and contents); `inputHash` includes it, source, style, scene options, format,
577
+ locale and rendering settings. Custom modules' arbitrary imported dependencies
578
+ are not recursively hashed; inspect regenerated output when those change.
579
+
580
+ ## 12. Discrepancies
581
+
582
+ No known discrepancies remain from the November 2026 gate audit. The gate
583
+ is sampled validation, not a proof of purity or visual quality.