@liqweed/motion-kit 0.5.0 → 0.7.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 (41) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +17 -2
  4. package/adapters/page/README.md +5 -0
  5. package/cli/motion-kit.mjs +91 -4
  6. package/docs/spec/technique.md +49 -25
  7. package/examples/checkout.json +104 -0
  8. package/examples/connection.json +80 -0
  9. package/examples/custom-pulse.scene.mjs +2 -0
  10. package/examples/player-states.json +97 -0
  11. package/examples/pull-request.json +93 -0
  12. package/examples/pull-request.mmd +15 -0
  13. package/lib/check.mjs +11 -8
  14. package/lib/export.mjs +12 -0
  15. package/lib/gate.mjs +4 -4
  16. package/lib/layout.mjs +236 -0
  17. package/lib/load.mjs +15 -0
  18. package/lib/mermaid.mjs +382 -0
  19. package/lib/outdated.mjs +122 -0
  20. package/package.json +6 -3
  21. package/runtime/links.mjs +5 -1
  22. package/runtime/player.mjs +40 -1
  23. package/runtime/scene.mjs +21 -8
  24. package/runtime/style.mjs +3 -0
  25. package/runtime/types/flowchart.mjs +402 -0
  26. package/runtime/types/hub-spoke.mjs +8 -6
  27. package/runtime/types/index.mjs +5 -0
  28. package/runtime/types/sequence.mjs +8 -6
  29. package/runtime/types/stack.mjs +13 -10
  30. package/runtime/types/timeline.mjs +14 -12
  31. package/runtime/types/walk.mjs +162 -0
  32. package/skills/animated-diagram/SKILL.md +8 -3
  33. package/skills/animated-diagram/references/custom-scenes.md +14 -0
  34. package/skills/animated-diagram/references/ecosystem.md +2 -2
  35. package/skills/animated-diagram/references/interactivity.md +18 -0
  36. package/skills/animated-diagram/references/motion-vocabulary.md +1 -1
  37. package/skills/animated-diagram/references/scene-types.md +118 -6
  38. package/skills/animated-diagram/references/styles.md +11 -2
  39. package/skills/animated-diagram/references/technique.md +6 -2
  40. package/skills/motion-render/SKILL.md +7 -0
  41. package/skills/motion-render/references/video.md +1 -1
@@ -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.5.0"
10
+ "version": "0.7.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.5.0",
3
+ "version": "0.7.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
@@ -102,7 +102,8 @@ node cli/motion-kit.mjs vendor <repo>/components/motion-kit --adapter slidev #
102
102
 
103
103
  Copies `runtime/`, the adapter, the gate (`lib/check.mjs`, `lib/gate.mjs`,
104
104
  `lib/load.mjs`) and `LICENSE`; writes `check.mjs` and `MOTION_KIT_VERSION`.
105
- Don't edit vendored files; change motion-kit and re-vendor. Vendoring keeps
105
+ Don't edit vendored files; change motion-kit and re-vendor.
106
+ `motion-kit outdated <dir>` tells you when a newer release exists. Vendoring keeps
106
107
  consumer CI self-contained (no install step, no network): the vendored gate
107
108
  runs the same checks as `motion-kit check`.
108
109
 
@@ -168,7 +169,7 @@ for inline specs, styles, lifecycle and error handling.
168
169
 
169
170
  Deterministic bytes · settled step frames · rounded numbers · token-only colours ·
170
171
  escaped labels · labels fit their budget in every locale · holds the final frame ·
171
- ≤ ~8–10 s · no clock or randomness in scenes · ids from the instance prefix. See
172
+ hard limit 12 s (aim for ≤ 8 s) · no clock or randomness in scenes · ids from the instance prefix. See
172
173
  `skills/animated-diagram/references/technique.md`.
173
174
 
174
175
  ## Contributing, changes and stability
@@ -193,3 +194,17 @@ for related tools and when to use them instead.
193
194
  Pull requests here are reviewed with the help of
194
195
  [CodeRabbit](https://coderabbit.ai), which supports open source projects for
195
196
  free. Thank you, CodeRabbit, for the support.
197
+
198
+ See the [Astro consumer guide](docs/guides/astro.md) for dictionaries, server
199
+ rendering, styles, page helpers, CI and upgrades. The seven built-in scene types
200
+ include [state-machine, request-journey and flowchart](skills/animated-diagram/references/scene-types.md);
201
+ `motion-kit import flow.mmd --out flow.json` turns a Mermaid flowchart into a
202
+ spec, laid out once at build time.
203
+ The [spec playground](https://motion-kit.dev/playground/) checks, plays and
204
+ shares a JSON spec directly in the browser.
205
+
206
+ Localized dictionaries must contain the requested locale; plain strings are
207
+ shared. Custom modules can export `locales = ["en", "nl"]` for gate coverage.
208
+ Narrative scenes may set `stepLabelsInFrame: false`; otherwise every step label
209
+ must appear in the final frame. `controller.onStep(callback)` observes changes
210
+ without polling and returns an unsubscribe function.
@@ -26,3 +26,8 @@ The page-link helpers (`scrollSteps`, `linkSteps`, from `runtime/links.mjs`)
26
26
  are bundled on the `MotionKitRuntime` global; bind them to the controller from
27
27
  the capture hook when you add text sections or `data-mk-step` terms around
28
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.
@@ -8,7 +8,9 @@
8
8
  * motion-kit bake <scene> --out x.svg [--fps 15] [--theme ...] [--style S]
9
9
  * motion-kit video <scene> --out x.mp4|.gif|.webm [--fps 30] [--scale 2] [--hold 1.5] [--sheet sheet.png]
10
10
  * motion-kit icon <scene> --out <repo> [--size 512] [--style S] [--no-png] project icon set (assets/, .idea/)
11
+ * motion-kit import <flow.mmd|-> [--out spec.json] [--id ID] [--title T] [--description D] Mermaid flowchart → spec
11
12
  * motion-kit vendor <dir> [--adapter page|slidev|astro|element]
13
+ * motion-kit outdated <dir> is a vendored copy behind npm's latest? (exit 1 when it is)
12
14
  * motion-kit formats | types
13
15
  * motion-kit --version print the version
14
16
  *
@@ -16,9 +18,14 @@
16
18
  * --options O passes scene options to a custom module's factory, unchanged:
17
19
  * inline JSON ('{"view":"short"}'), a .json file, or an .mjs module whose
18
20
  * default export is the options or ({ format, locale }) => options.
21
+ *
22
+ * import: a chain becomes a `sequence` spec; a chart with branches, joins,
23
+ * link labels or dotted links becomes a `flowchart` spec, laid out here once.
24
+ * Without --out the spec goes to stdout; with it, the spec is also checked in
25
+ * every format (or only the --format ones). Unsupported Mermaid syntax fails with its line.
19
26
  */
20
- import { cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
21
- import { dirname, join, resolve } from "node:path";
27
+ import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
28
+ import { basename, dirname, join, resolve } from "node:path";
22
29
  import { fileURLToPath } from "node:url";
23
30
  import { parseArgs } from "node:util";
24
31
  import { bake, bakeStats } from "../runtime/bake.mjs";
@@ -26,6 +33,8 @@ import { FORMATS } from "../runtime/scene.mjs";
26
33
  import { SCENE_TYPES } from "../runtime/types/index.mjs";
27
34
  import { checkScene } from "../lib/check.mjs";
28
35
  import { checkFiles } from "../lib/gate.mjs";
36
+ import { mermaidToSpec } from "../lib/mermaid.mjs";
37
+ import { compareVersions, isAdapterName, latestVersion, PACKAGE, shellQuote, vendoredVersion } from "../lib/outdated.mjs";
29
38
  import { buildHtml } from "../lib/build.mjs";
30
39
  import { writeIconSet } from "../lib/icon.mjs";
31
40
  import { exportSteps } from "../lib/export.mjs";
@@ -53,6 +62,9 @@ const { values: a, positionals } = parseArgs({
53
62
  hold: { type: "string", default: "1.5" },
54
63
  sheet: { type: "string" },
55
64
  adapter: { type: "string", default: "page" },
65
+ id: { type: "string" },
66
+ title: { type: "string" },
67
+ description: { type: "string" },
56
68
  size: { type: "string", default: "512" },
57
69
  "no-png": { type: "boolean", default: false },
58
70
  "no-scrubber": { type: "boolean", default: false },
@@ -145,6 +157,8 @@ async function main() {
145
157
  case "bake": {
146
158
  const file = need(args[0], "<scene>");
147
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 - ")}`);
148
162
  const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
149
163
  const out = need(a.out, "--out");
150
164
  writeFileSync(out, svg);
@@ -155,6 +169,8 @@ async function main() {
155
169
  case "video": {
156
170
  const file = need(args[0], "<scene>");
157
171
  const { scene } = await loadScene(file, await sceneOpts(file));
172
+ const gate = checkScene(scene, { style });
173
+ if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
158
174
  const out = need(a.out, "--out");
159
175
  const r = await renderVideo(scene, {
160
176
  out,
@@ -184,12 +200,63 @@ async function main() {
184
200
  if (files.includes(".idea/icon.svg")) console.log("note: if .idea/ is git-ignored, add !.idea/icon*.svg after it to commit the IDE icon");
185
201
  return;
186
202
  }
203
+ case "import": {
204
+ const file = need(args[0], "<flow.mmd> (or - for stdin)");
205
+ const source = readFileSync(file === "-" ? 0 : file, "utf8");
206
+ const id = a.id ?? (file === "-" ? "flowchart" : basename(file).replace(/\.[^.]*$/, "").replace(/[^\w-]+/g, "-").replace(/^[^A-Za-z]+/, "") || "flowchart");
207
+ let result;
208
+ try {
209
+ result = mermaidToSpec(source, { id, title: a.title, description: a.description });
210
+ } catch (e) {
211
+ fail(`import ${file}: ${e instanceof Error ? e.message : e}`);
212
+ }
213
+ for (const w of result.warnings) console.error(`motion-kit: import ${file}: ${w}`);
214
+ const json = `${JSON.stringify(result.spec, null, "\t")}\n`;
215
+ if (!a.out) {
216
+ process.stdout.write(json);
217
+ return;
218
+ }
219
+ const dest = resolve(a.out);
220
+ if (isModule(dest)) fail(`import: --out ${a.out} is a scene module path, so check and build would not load it as a spec; use a .json path`);
221
+ mkdirSync(dirname(dest), { recursive: true });
222
+ // Gate a candidate beside the destination; an existing spec is replaced only once it passes.
223
+ // Created exclusively (a planted symlink cannot redirect the write) and never more readable than the file it replaces.
224
+ // The name is short and fixed-length so a long destination basename cannot push it past the filesystem's limit.
225
+ const candidate = join(dirname(dest), `.import-${process.pid}-${Date.now().toString(36)}.json`);
226
+ let mode = 0o666;
227
+ try {
228
+ mode = statSync(dest).mode & 0o777;
229
+ } catch {}
230
+ let created = false;
231
+ let bad;
232
+ try {
233
+ const fd = openSync(candidate, "wx", mode);
234
+ created = true;
235
+ try {
236
+ writeFileSync(fd, json);
237
+ } finally {
238
+ closeSync(fd);
239
+ }
240
+ bad = await checkFiles([candidate], { formats: a.format, locales: a.locale, style });
241
+ if (!bad) renameSync(candidate, dest);
242
+ } finally {
243
+ if (created) rmSync(candidate, { force: true });
244
+ }
245
+ if (bad) {
246
+ console.error(`motion-kit: the import does not pass the gate (every format, or only those named by --format), so ${a.out} was not written; shorten labels, split the chart, or ship only the formats that pass (--format)`);
247
+ process.exit(1);
248
+ }
249
+ const { spec } = result;
250
+ console.log(`wrote ${a.out}: ${spec.type} "${spec.id}", ${spec.nodes.length} nodes${spec.edges ? `, ${spec.edges.length} links` : ""}`);
251
+ return;
252
+ }
187
253
  case "vendor": {
188
254
  const dir = resolve(need(args[0], "<dir>"));
255
+ if (!isAdapterName(a.adapter) || !existsSync(join(ROOT, "adapters", a.adapter))) fail(`unknown adapter "${a.adapter}" (page, slidev, astro or element)`);
256
+ const adapter = join(ROOT, "adapters", a.adapter);
189
257
  mkdirSync(dir, { recursive: true });
190
258
  cpSync(join(ROOT, "LICENSE"), join(dir, "LICENSE"));
191
259
  cpSync(join(ROOT, "runtime"), join(dir, "runtime"), { recursive: true });
192
- const adapter = join(ROOT, "adapters", a.adapter);
193
260
  cpSync(adapter, join(dir, "adapter"), { recursive: true });
194
261
  mkdirSync(join(dir, "lib"), { recursive: true });
195
262
  for (const f of ["check.mjs", "gate.mjs", "load.mjs"]) cpSync(join(ROOT, "lib", f), join(dir, "lib", f));
@@ -198,6 +265,26 @@ async function main() {
198
265
  console.log(`vendored runtime + ${a.adapter} adapter (motion-kit ${VERSION}) into ${dir}`);
199
266
  return;
200
267
  }
268
+ case "outdated": {
269
+ const dir = resolve(need(args[0], "<dir>"));
270
+ let vendored;
271
+ let latest;
272
+ try {
273
+ vendored = vendoredVersion(dir);
274
+ latest = await latestVersion();
275
+ } catch (e) {
276
+ console.error(`motion-kit: outdated: ${e instanceof Error ? e.message : e}`);
277
+ process.exit(2);
278
+ }
279
+ if (compareVersions(vendored.version, latest) < 0) {
280
+ console.log(`${dir}: motion-kit ${vendored.version} is vendored; ${latest} is the latest release.`);
281
+ console.log(`re-vendor: npx ${PACKAGE}@${latest} vendor ${shellQuote(dir)} --adapter ${vendored.adapter}`);
282
+ console.log(`changes: https://github.com/liqweed/motion-kit/blob/main/CHANGELOG.md`);
283
+ process.exit(1);
284
+ }
285
+ console.log(`${dir}: motion-kit ${vendored.version} is up to date (latest ${latest}).`);
286
+ return;
287
+ }
201
288
  default:
202
289
  fail(`unknown command "${cmd}" (try --help)`);
203
290
  }
@@ -209,7 +296,7 @@ const VENDOR_CHECK = `#!/usr/bin/env node
209
296
  // node check.mjs <scene.json|scene.mjs …> [--format F]… [--locale L]… [--style style.json] [--options O]
210
297
  //
211
298
  // Every format unless --format; for a spec every locale its strings carry, for
212
- // a custom module "en", unless --locale. The style (neutral by default) must
299
+ // a custom module its exported locales (default "en"), unless --locale. The style (neutral by default) must
213
300
  // pass the contrast check. --options passes scene options to custom modules:
214
301
  // a .json file, inline JSON, or an .mjs module exporting ({ format, locale }) => options.
215
302
  // 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-17
4
+ last_updated: 2026-11-18
5
5
  ---
6
6
 
7
7
  # motion-kit technique — normative specification
@@ -278,13 +278,14 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
278
278
  `runtime/types/hub-spoke.mjs:31`, `runtime/wrap.mjs:40-42`). Layouts SHOULD
279
279
  budget for Dutch/German being ~30 % longer than English.
280
280
  - Any string MAY be localized: `{en: "…", nl: "…"}`. `localize(value, locale)`
281
- returns the plain string, the requested locale, else the first value, else ""
282
- (`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 "".
283
283
  - Labels are labels; sentences go in `detail`. Font size MUST NOT go below
284
284
  14 px at 1× (§3).
285
285
  - Every shipped locale × format MUST pass the gate. `check` derives locales
286
286
  from a `.json` spec's localized objects (keys `xx` or `xx-YY`)
287
- (`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.
288
289
 
289
290
  ## 8. Steps and settled frames
290
291
 
@@ -314,8 +315,9 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
314
315
  ## 9. Scene types
315
316
 
316
317
  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:
318
+ `timeline` (2–8 events), `stack` (2–8 layers), `state-machine` and
319
+ `request-journey` (2–8 nodes; graph bounds in §11.1), and `flowchart` (2–12
320
+ nodes, 1–20 edges, layout stored in the spec). Fields and storyboards:
319
321
  [`scene-types.md`](../../skills/animated-diagram/references/scene-types.md).
320
322
  Normative points:
321
323
 
@@ -343,7 +345,7 @@ Every target goes through this one function. It MUST emit `<svg>` with
343
345
  | `theme` | `light`/`dark` for resolution or inline vars. |
344
346
  | `live` | Omits inline vars; the container supplies them. |
345
347
  | `background` | Paints a full-size `bg` rect behind the diagram. |
346
- | `idPrefix` | Prefix for every id in the output: `<title>`/`<desc>`, and the scene's own through `frame(t, { idPrefix })`. Made a safe id token (`safeId`: letters, digits, `_`, `-`). MUST be unique per page when several diagrams share it. |
348
+ | `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. |
347
349
 
348
350
  ### 10.2 Live player (`runtime/player.mjs`)
349
351
 
@@ -535,7 +537,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
535
537
  | 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. |
536
538
  | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
537
539
  | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
538
- | G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
540
+ | G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
539
541
  | 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. |
540
542
  | 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
543
  | 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). |
@@ -547,22 +549,44 @@ phone size, real-time playback, dark mode) is required by
547
549
  [`qc.md`](../../skills/animated-diagram/references/qc.md), and a human signs
548
550
  off.
549
551
 
550
- ## 12. Discrepancies
552
+ ### 11.1 Gate policy decisions
551
553
 
552
- Recorded, not resolved. Each needs an owner decision.
554
+ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
553
555
 
554
- | # | Topic | Code says | Docs say |
555
- |---|---|---|---|
556
- | 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`). |
557
- | 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`). |
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`). |
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. |
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`. |
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`). |
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`). |
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`). |
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`). |
565
- | D10 | Capture-hook key | Key is `options.id ?? scene.id`, i.e. format-suffixed (`order-flow-16x9`); the Astro adapter uses its `id` prop or `mk-<scene.id>-<n>`; the Slidev adapter exposes none. | `window.__motionKit[sceneId]` / `[id]` (`adapters/page/README.md:22`, `interactivity.md`). |
566
- | D12 | Auto-fit maximum | Sequence 22 px, hub-spoke 20 px (`runtime/types/hub-spoke.mjs:97`). | "Fixed formats ≤ 22 px" without type distinction (`technique.md:90`); `formats.md:12` is correct. |
567
- | D13 | Timing budgets | `ENTRANCE_MAX` is exported but unused; stagger and entrance limits are not checked. | Listed as "Hard rules" (`skills/animated-diagram/SKILL.md:50`). |
568
- | D14 | Manifest reproducibility | `inputHash` covers the source file, style and scene options, not the runtime; a runtime change keeps the hash while frames change (only `version` hints at it) (`lib/export.mjs:66-70`). | "A stale export is easy to spot" (`skills/motion-render/SKILL.md:66-68`). |
556
+ | Question | Contract and reason |
557
+ |---|---|
558
+ | Duration | 12 s is the hard gate limit; ≤ 8 s is the design target. Keep valid existing scenes while making the two numbers explicit. |
559
+ | 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. |
560
+ | Module locales | Modules MAY export `locales`; all declared locales MUST be checked by default. Undeclared modules retain `en` for compatibility. Explicit `--locale` overrides. |
561
+ | Translations | A localized object MUST supply the exact requested locale. Plain strings are shared. Silent cross-language fallback is forbidden. |
562
+ | 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. |
563
+ | Vendored parity | CLI and vendored checks MUST call the same `lib/gate.mjs` and `lib/check.mjs`, including contrast, locales and caller options. |
564
+ | 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. |
565
+
566
+ The controller also exposes `onStep(callback) → unsubscribe`, with an immediate
567
+ current index and subsequent changed indices (`-1` before the first step).
568
+ Destroy releases subscribers. `seek(t)` requires a finite time, clamps it,
569
+ pauses playback and cancels pending autoplay; external drivers use the controller
570
+ and must implement their own reduced-motion policy.
571
+
572
+ Registered graph walks are `state-machine` and `request-journey` (2–8 nodes,
573
+ 1–12 edges, 1–10 explicit path edges). Their fields, narrative steps, region
574
+ boundaries and limits are in the [scene type reference](../../skills/animated-diagram/references/scene-types.md).
575
+
576
+ A `flowchart` spec carries its layout: integer `rank` and `pos` ≥ 0 per node,
577
+ one `via` waypoint per rank an edge crosses. The type MUST NOT lay a graph out;
578
+ it scales the stored layout per format and MUST throw on overlapping nodes,
579
+ waypoints through a node, self-loops, edges that skip ranks, and labels or
580
+ connectors that collide in a format (`runtime/types/flowchart.mjs`). The
581
+ layout is computed at build time by `motion-kit import` (`lib/mermaid.mjs`,
582
+ `lib/layout.mjs`), deterministically: the same chart gives the same spec.
583
+
584
+ Export manifests include `runtimeHash` (SHA-256 of sorted runtime module paths
585
+ and contents); `inputHash` includes it, source, style, scene options, format,
586
+ locale and rendering settings. Custom modules' arbitrary imported dependencies
587
+ are not recursively hashed; inspect regenerated output when those change.
588
+
589
+ ## 12. Discrepancies
590
+
591
+ No known discrepancies remain from the November 2026 gate audit. The gate
592
+ is sampled validation, not a proof of purity or visual quality.
@@ -0,0 +1,104 @@
1
+ {
2
+ "type": "request-journey",
3
+ "id": "checkout",
4
+ "title": {
5
+ "en": "A checkout request",
6
+ "nl": "Een betaalverzoek"
7
+ },
8
+ "description": {
9
+ "en": "The browser calls the shop, which asks for payment and queues a receipt.",
10
+ "nl": "De browser roept de winkel aan, die betaling vraagt en een ontvangstbewijs klaarzet."
11
+ },
12
+ "components": [
13
+ {
14
+ "id": "browser",
15
+ "label": {
16
+ "en": "Browser",
17
+ "nl": "Browser"
18
+ },
19
+ "region": {
20
+ "en": "Customer",
21
+ "nl": "Klant"
22
+ }
23
+ },
24
+ {
25
+ "id": "shop",
26
+ "label": {
27
+ "en": "Shop API",
28
+ "nl": "Winkel-API"
29
+ },
30
+ "region": {
31
+ "en": "Shop",
32
+ "nl": "Winkel"
33
+ }
34
+ },
35
+ {
36
+ "id": "payment",
37
+ "label": {
38
+ "en": "Payment API",
39
+ "nl": "Betaal-API"
40
+ },
41
+ "region": {
42
+ "en": "Provider",
43
+ "nl": "Aanbieder"
44
+ }
45
+ },
46
+ {
47
+ "id": "queue",
48
+ "label": {
49
+ "en": "Receipt queue",
50
+ "nl": "Bonnenwachtrij"
51
+ },
52
+ "region": {
53
+ "en": "Shop",
54
+ "nl": "Winkel"
55
+ }
56
+ }
57
+ ],
58
+ "hops": [
59
+ {
60
+ "id": "submit",
61
+ "from": "browser",
62
+ "to": "shop",
63
+ "label": {
64
+ "en": "Submit order",
65
+ "nl": "Bestelling sturen"
66
+ }
67
+ },
68
+ {
69
+ "id": "pay",
70
+ "from": "shop",
71
+ "to": "payment",
72
+ "label": {
73
+ "en": "Request payment",
74
+ "nl": "Betaling vragen"
75
+ }
76
+ },
77
+ {
78
+ "id": "paid",
79
+ "from": "payment",
80
+ "to": "shop",
81
+ "label": {
82
+ "en": "Payment accepted",
83
+ "nl": "Betaling aanvaard"
84
+ }
85
+ },
86
+ {
87
+ "id": "enqueue",
88
+ "from": "shop",
89
+ "to": "queue",
90
+ "label": {
91
+ "en": "Queue receipt",
92
+ "nl": "Bon klaarzetten"
93
+ },
94
+ "async": true
95
+ }
96
+ ],
97
+ "initial": "browser",
98
+ "path": [
99
+ "submit",
100
+ "pay",
101
+ "paid",
102
+ "enqueue"
103
+ ]
104
+ }
@@ -0,0 +1,80 @@
1
+ {
2
+ "type": "state-machine",
3
+ "id": "connection",
4
+ "title": {
5
+ "en": "A connection recovers",
6
+ "nl": "Een verbinding herstelt"
7
+ },
8
+ "description": {
9
+ "en": "Connect, retry after failure, then disconnect.",
10
+ "nl": "Verbinden, opnieuw proberen na uitval en verbreken."
11
+ },
12
+ "states": [
13
+ {
14
+ "id": "offline",
15
+ "label": {
16
+ "en": "Offline",
17
+ "nl": "Offline"
18
+ }
19
+ },
20
+ {
21
+ "id": "connecting",
22
+ "label": {
23
+ "en": "Connecting",
24
+ "nl": "Verbinden"
25
+ }
26
+ },
27
+ {
28
+ "id": "online",
29
+ "label": {
30
+ "en": "Online",
31
+ "nl": "Online"
32
+ }
33
+ }
34
+ ],
35
+ "transitions": [
36
+ {
37
+ "id": "connect",
38
+ "from": "offline",
39
+ "to": "connecting",
40
+ "label": {
41
+ "en": "Connect",
42
+ "nl": "Verbinden"
43
+ }
44
+ },
45
+ {
46
+ "id": "retry",
47
+ "from": "connecting",
48
+ "to": "connecting",
49
+ "label": {
50
+ "en": "Retry",
51
+ "nl": "Opnieuw proberen"
52
+ }
53
+ },
54
+ {
55
+ "id": "ready",
56
+ "from": "connecting",
57
+ "to": "online",
58
+ "label": {
59
+ "en": "Connected",
60
+ "nl": "Verbonden"
61
+ }
62
+ },
63
+ {
64
+ "id": "close",
65
+ "from": "online",
66
+ "to": "offline",
67
+ "label": {
68
+ "en": "Disconnect",
69
+ "nl": "Verbreken"
70
+ }
71
+ }
72
+ ],
73
+ "initial": "offline",
74
+ "path": [
75
+ "connect",
76
+ "retry",
77
+ "ready",
78
+ "close"
79
+ ]
80
+ }
@@ -12,6 +12,8 @@ import { tok } from "../runtime/style.mjs";
12
12
  import { cubic, drawOn, el, fade, num, text } from "../runtime/svg.mjs";
13
13
  import { wrapLabel } from "../runtime/wrap.mjs";
14
14
 
15
+ export const locales = ["en", "nl"];
16
+
15
17
  const COPY = {
16
18
  title: { en: "A request, there and back", nl: "Een verzoek, heen en terug" },
17
19
  description: {
@@ -0,0 +1,97 @@
1
+ {
2
+ "type": "state-machine",
3
+ "id": "player-states",
4
+ "title": {
5
+ "en": "The player, as states",
6
+ "nl": "De speler als toestanden"
7
+ },
8
+ "description": {
9
+ "en": "Play, pause, resume and finish. Replay returns to playing.",
10
+ "nl": "Afspelen, pauzeren, hervatten en afronden. Opnieuw keert terug naar afspelen."
11
+ },
12
+ "states": [
13
+ {
14
+ "id": "ready",
15
+ "label": {
16
+ "en": "Ready",
17
+ "nl": "Gereed"
18
+ }
19
+ },
20
+ {
21
+ "id": "playing",
22
+ "label": {
23
+ "en": "Playing",
24
+ "nl": "Speelt"
25
+ }
26
+ },
27
+ {
28
+ "id": "paused",
29
+ "label": {
30
+ "en": "Paused",
31
+ "nl": "Gepauzeerd"
32
+ }
33
+ },
34
+ {
35
+ "id": "finished",
36
+ "label": {
37
+ "en": "Finished",
38
+ "nl": "Afgerond"
39
+ }
40
+ }
41
+ ],
42
+ "transitions": [
43
+ {
44
+ "id": "play",
45
+ "from": "ready",
46
+ "to": "playing",
47
+ "label": {
48
+ "en": "Play",
49
+ "nl": "Afspelen"
50
+ }
51
+ },
52
+ {
53
+ "id": "pause",
54
+ "from": "playing",
55
+ "to": "paused",
56
+ "label": {
57
+ "en": "Pause",
58
+ "nl": "Pauzeren"
59
+ }
60
+ },
61
+ {
62
+ "id": "resume",
63
+ "from": "paused",
64
+ "to": "playing",
65
+ "label": {
66
+ "en": "Resume",
67
+ "nl": "Hervatten"
68
+ }
69
+ },
70
+ {
71
+ "id": "finish",
72
+ "from": "playing",
73
+ "to": "finished",
74
+ "label": {
75
+ "en": "Finish",
76
+ "nl": "Afronden"
77
+ }
78
+ },
79
+ {
80
+ "id": "replay",
81
+ "from": "finished",
82
+ "to": "playing",
83
+ "label": {
84
+ "en": "Replay",
85
+ "nl": "Opnieuw"
86
+ }
87
+ }
88
+ ],
89
+ "initial": "ready",
90
+ "path": [
91
+ "play",
92
+ "pause",
93
+ "resume",
94
+ "finish",
95
+ "replay"
96
+ ]
97
+ }