@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +26 -6
- package/adapters/element/README.md +5 -0
- package/adapters/page/README.md +10 -0
- package/cli/motion-kit.mjs +14 -4
- package/docs/spec/technique.md +129 -51
- package/examples/checkout.json +104 -0
- package/examples/connection.json +80 -0
- package/examples/custom-pulse.scene.mjs +5 -0
- package/examples/incident.json +18 -0
- package/examples/player-states.json +97 -0
- package/examples/web-stack.json +17 -0
- package/lib/build.mjs +1 -1
- package/lib/check.mjs +215 -21
- package/lib/export.mjs +116 -7
- package/lib/gate.mjs +9 -7
- package/lib/load.mjs +15 -0
- package/package.json +6 -3
- package/runtime/kit.mjs +2 -2
- package/runtime/links.mjs +318 -0
- package/runtime/parts.mjs +15 -0
- package/runtime/patch.mjs +297 -0
- package/runtime/player.mjs +45 -2
- package/runtime/scene.mjs +24 -9
- package/runtime/style.mjs +65 -16
- package/runtime/types/hub-spoke.mjs +10 -8
- package/runtime/types/index.mjs +7 -0
- package/runtime/types/sequence.mjs +10 -8
- package/runtime/types/stack.mjs +230 -0
- package/runtime/types/timeline.mjs +407 -0
- package/runtime/types/walk.mjs +162 -0
- package/skills/animated-diagram/SKILL.md +28 -7
- package/skills/animated-diagram/references/custom-scenes.md +20 -1
- package/skills/animated-diagram/references/interactivity.md +129 -6
- package/skills/animated-diagram/references/motion-vocabulary.md +1 -1
- package/skills/animated-diagram/references/qc.md +3 -0
- package/skills/animated-diagram/references/scene-types.md +100 -4
- package/skills/animated-diagram/references/styles.md +55 -6
- package/skills/animated-diagram/references/technique.md +15 -6
- package/skills/motion-render/SKILL.md +31 -6
- package/skills/motion-render/references/formats.md +8 -8
- package/skills/motion-render/references/video.md +1 -1
- package/skills/project-logo/SKILL.md +15 -4
- package/styles/neutral.json +2 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "motion-kit",
|
|
3
|
-
"version": "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),
|
|
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
|
|
87
|
-
`
|
|
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
|
-
≤
|
|
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
|
package/adapters/page/README.md
CHANGED
|
@@ -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.
|
package/cli/motion-kit.mjs
CHANGED
|
@@ -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.
|
package/docs/spec/technique.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: motion-kit technique — normative specification
|
|
3
3
|
status: draft
|
|
4
|
-
last_updated: 2026-11-
|
|
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:
|
|
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
|
|
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
|
|
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`); `
|
|
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
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
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
|
|
257
|
-
|
|
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
|
-
(`
|
|
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
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
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)
|
|
286
|
-
(`
|
|
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/
|
|
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,
|
|
411
|
-
file list
|
|
412
|
-
|
|
413
|
-
|
|
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
|
|
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 −
|
|
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` |
|
|
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`. |
|
|
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
|
-
|
|
551
|
+
### 11.1 Gate policy decisions
|
|
488
552
|
|
|
489
|
-
Recorded
|
|
553
|
+
Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
|
|
490
554
|
|
|
491
|
-
|
|
|
492
|
-
|
|
493
|
-
|
|
|
494
|
-
|
|
|
495
|
-
|
|
|
496
|
-
|
|
|
497
|
-
|
|
|
498
|
-
|
|
|
499
|
-
|
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
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.
|