@liqweed/motion-kit 0.5.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.
@@ -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.6.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.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
@@ -168,7 +168,7 @@ for inline specs, styles, lifecycle and error handling.
168
168
 
169
169
  Deterministic bytes · settled step frames · rounded numbers · token-only colours ·
170
170
  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
171
+ hard limit 12 s (aim for ≤ 8 s) · no clock or randomness in scenes · ids from the instance prefix. See
172
172
  `skills/animated-diagram/references/technique.md`.
173
173
 
174
174
  ## Contributing, changes and stability
@@ -193,3 +193,15 @@ for related tools and when to use them instead.
193
193
  Pull requests here are reviewed with the help of
194
194
  [CodeRabbit](https://coderabbit.ai), which supports open source projects for
195
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.
@@ -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.
@@ -145,6 +145,8 @@ async function main() {
145
145
  case "bake": {
146
146
  const file = need(args[0], "<scene>");
147
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 - ")}`);
148
150
  const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
149
151
  const out = need(a.out, "--out");
150
152
  writeFileSync(out, svg);
@@ -155,6 +157,8 @@ async function main() {
155
157
  case "video": {
156
158
  const file = need(args[0], "<scene>");
157
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 - ")}`);
158
162
  const out = need(a.out, "--out");
159
163
  const r = await renderVideo(scene, {
160
164
  out,
@@ -209,7 +213,7 @@ const VENDOR_CHECK = `#!/usr/bin/env node
209
213
  // node check.mjs <scene.json|scene.mjs …> [--format F]… [--locale L]… [--style style.json] [--options O]
210
214
  //
211
215
  // 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
216
+ // a custom module its exported locales (default "en"), unless --locale. The style (neutral by default) must
213
217
  // pass the contrast check. --options passes scene options to custom modules:
214
218
  // a .json file, inline JSON, or an .mjs module exporting ({ format, locale }) => options.
215
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-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,8 @@ 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). Fields and storyboards:
319
320
  [`scene-types.md`](../../skills/animated-diagram/references/scene-types.md).
320
321
  Normative points:
321
322
 
@@ -343,7 +344,7 @@ Every target goes through this one function. It MUST emit `<svg>` with
343
344
  | `theme` | `light`/`dark` for resolution or inline vars. |
344
345
  | `live` | Omits inline vars; the container supplies them. |
345
346
  | `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. |
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. |
347
348
 
348
349
  ### 10.2 Live player (`runtime/player.mjs`)
349
350
 
@@ -535,7 +536,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
535
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. |
536
537
  | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
537
538
  | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
538
- | G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
539
+ | G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
539
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. |
540
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. |
541
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). |
@@ -547,22 +548,36 @@ phone size, real-time playback, dark mode) is required by
547
548
  [`qc.md`](../../skills/animated-diagram/references/qc.md), and a human signs
548
549
  off.
549
550
 
550
- ## 12. Discrepancies
551
+ ### 11.1 Gate policy decisions
551
552
 
552
- Recorded, not resolved. Each needs an owner decision.
553
+ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
553
554
 
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`). |
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.
@@ -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
+ }
package/lib/check.mjs CHANGED
@@ -8,8 +8,8 @@
8
8
  *
9
9
  * Over files, formats and locales (the CLI and the vendored gate): lib/gate.mjs.
10
10
  */
11
- import { renderSvg } from "../runtime/scene.mjs";
12
- import { checkContrast } from "../runtime/style.mjs";
11
+ import { renderSvg, validateScene } from "../runtime/scene.mjs";
12
+ import { checkContrast, normalizeStyle } from "../runtime/style.mjs";
13
13
 
14
14
  const SAMPLES = 120;
15
15
 
@@ -197,7 +197,10 @@ export const SETTLE_AFTER = Object.freeze([0.001, 0.015, 0.03, 0.045]);
197
197
  */
198
198
  export function checkScene(scene, { samples = SAMPLES, style } = {}) {
199
199
  const problems = [];
200
- const render = (/** @type {number} */ t) => renderSvg(scene, t);
200
+ style = normalizeStyle(style);
201
+ try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)] }; }
202
+ for (const p of checkContrast(style)) problems.push(`contrast: ${p}`);
203
+ const render = (/** @type {number} */ t) => renderSvg(scene, t, { style });
201
204
  const at = (/** @type {number} */ i) => (scene.duration * i) / samples;
202
205
 
203
206
  // 1. Deterministic + well-formed + rounded + token-only, across the timeline,
@@ -212,7 +215,7 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
212
215
  if (wf) problems.push(`malformed at t=${t.toFixed(3)}: ${wf}`);
213
216
  const long = a.match(/-?\d+\.\d{5,}/);
214
217
  if (long) problems.push(`unrounded number ${long[0]} at t=${t.toFixed(3)} (use num())`);
215
- const frame = scene.frame(Math.min(t, scene.duration), { idPrefix: scene.id });
218
+ const frame = scene.frame(Math.min(t, scene.duration), { idPrefix: scene.id, style });
216
219
  const lit = findColourLiteral(frame);
217
220
  if (lit) problems.push(`colour literal ${lit} at t=${t.toFixed(3)} (use tok())`);
218
221
  if (/NaN|undefined|Infinity/.test(frame)) problems.push(`NaN/undefined/Infinity in frame at t=${t.toFixed(3)}`);
@@ -251,10 +254,10 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
251
254
  const lastFrame = render(scene.duration);
252
255
  if (first === lastFrame) problems.push("first and last frame are identical: nothing animates");
253
256
  if (scene.steps[scene.steps.length - 1].at > scene.duration) problems.push("last step is after duration");
254
- if (render(scene.duration + 5) !== lastFrame) problems.push("frames after the end differ from the final frame (must hold)");
257
+ if (scene.frame(scene.duration + 5, { idPrefix: scene.id, style }) !== scene.frame(scene.duration, { idPrefix: scene.id, style })) problems.push("frames after the end differ from the final frame (must hold)");
255
258
 
256
- // 4. Budget: whole scene under ~10 s (design guidance: ≤ 8 s for explainers).
257
- if (scene.duration > 12) problems.push(`duration ${scene.duration.toFixed(1)}s is long for an explainer (≤ 8–10 s)`);
259
+ // 4. Hard limit: 12 s. Authoring target: 8 s; these are distinct.
260
+ if (scene.duration > 12) problems.push(`duration ${scene.duration.toFixed(1)}s exceeds the 12 s limit (aim for ≤ 8 s)`);
258
261
 
259
262
  // 5. Every step label is visible in the final frame (escaped form), unless
260
263
  // the scene declares narrative steps (stepLabelsInFrame: false).
@@ -274,7 +277,7 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
274
277
  // never share one: render with two prefixes and look for common ids.
275
278
  const fixed = new Set();
276
279
  for (let i = 0; i <= samples; i += 10) {
277
- const ids = (/** @type {string} */ prefix) => new Set([...renderSvg(scene, at(i), { idPrefix: prefix }).matchAll(/\sid="([^"]*)"/g)].map((m) => m[1]));
280
+ const ids = (/** @type {string} */ prefix) => new Set([...renderSvg(scene, at(i), { idPrefix: prefix, style }).matchAll(/\sid="([^"]*)"/g)].map((m) => m[1]));
278
281
  const second = ids("mk-gate-b");
279
282
  for (const id of ids("mk-gate-a")) if (second.has(id)) fixed.add(id);
280
283
  }
package/lib/export.mjs CHANGED
@@ -16,6 +16,7 @@
16
16
  * them, unless the new export writes a file of the same name: that one is
17
17
  * overwritten.
18
18
  */
19
+ import { fileURLToPath } from "node:url";
19
20
  import { createHash } from "node:crypto";
20
21
  import { execFileSync } from "node:child_process";
21
22
  import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
@@ -148,7 +149,17 @@ export async function exportSteps(scene, { out, style, theme = "light", png = fa
148
149
  phoneError = e instanceof Error ? e.message : String(e);
149
150
  }
150
151
  }
152
+ // Include the actual runtime bytes, not only its package version: local
153
+ // runtime edits must invalidate an export even before a release is made.
154
+ const runtimeDir = fileURLToPath(new URL("../runtime/", import.meta.url));
155
+ const runtimeDigest = createHash("sha256");
156
+ for (const file of listFiles(runtimeDir).filter((f) => f.endsWith(".mjs"))) {
157
+ runtimeDigest.update(file).update("\0").update(readFileSync(join(runtimeDir, file))).update("\0");
158
+ }
159
+ const runtimeHash = runtimeDigest.digest("hex");
151
160
  const inputHash = createHash("sha256")
161
+ .update(runtimeHash)
162
+ .update(JSON.stringify({ format: scene.format ?? format, locale: scene.locale ?? locale, theme, png, scale, qc, background }))
152
163
  .update(sourceFile ? readFileSync(sourceFile) : scene.frame.toString())
153
164
  .update(JSON.stringify(style ?? "neutral"))
154
165
  .update(JSON.stringify(options ?? null))
@@ -169,6 +180,7 @@ export async function exportSteps(scene, { out, style, theme = "light", png = fa
169
180
  style: style?.name ?? "neutral",
170
181
  theme,
171
182
  inputHash,
183
+ runtimeHash,
172
184
  sourceCommit: source.commit,
173
185
  sourceDirty: source.dirty,
174
186
  render: { png, scale: png ? scale : null, background, qc },
package/lib/gate.mjs CHANGED
@@ -11,7 +11,7 @@
11
11
  * - Every file × format (all of FORMATS unless given) × locale passes
12
12
  * checkScene, which also checks the style against the pairs that scene
13
13
  * declares it draws besides (`scene.contrastPairs`). Locales: the given ones; else, for a spec, every locale its
14
- * strings carry, and `en` for a module.
14
+ * strings carry, and a module’s exported `locales` (default `en`).
15
15
  * - A file that cannot be read, parsed or built is a failure for that file
16
16
  * only; the remaining files are still checked.
17
17
  */
@@ -19,7 +19,7 @@ import { readFileSync } from "node:fs";
19
19
  import { FORMATS } from "../runtime/scene.mjs";
20
20
  import { checkContrast } from "../runtime/style.mjs";
21
21
  import { checkScene } from "./check.mjs";
22
- import { isModule, loadScene } from "./load.mjs";
22
+ import { isModule, loadScene, moduleLocales } from "./load.mjs";
23
23
 
24
24
  /** @param {unknown} e */
25
25
  const message = (e) => (e instanceof Error ? e.message : String(e));
@@ -59,9 +59,9 @@ export async function checkFiles(files, { formats, locales, style, options, log
59
59
  for (const file of files) {
60
60
  const module = isModule(file);
61
61
  let fileLocales = locales?.length ? locales : ["en"];
62
- if (!locales?.length && !module) {
62
+ if (!locales?.length) {
63
63
  try {
64
- fileLocales = detectLocales(JSON.parse(readFileSync(file, "utf8")));
64
+ fileLocales = module ? await moduleLocales(file) : detectLocales(JSON.parse(readFileSync(file, "utf8")));
65
65
  } catch (e) {
66
66
  bad++;
67
67
  error(`✗ ${file}: ${message(e)}`);
package/lib/load.mjs CHANGED
@@ -81,3 +81,18 @@ export async function loadOptions(arg) {
81
81
  if (typeof mod.default === "function") return (ctx) => mod.default(ctx);
82
82
  return fixed(mod.default);
83
83
  }
84
+
85
+ /**
86
+ * Locales a custom module promises to ship. Undeclared modules keep the
87
+ * backwards-compatible English default; --locale explicitly overrides this.
88
+ * @param {string} file
89
+ * @returns {Promise<string[]>}
90
+ */
91
+ export async function moduleLocales(file) {
92
+ const mod = await import(pathToFileURL(resolve(file)).href);
93
+ if (mod.locales === undefined) return ["en"];
94
+ if (!Array.isArray(mod.locales) || !mod.locales.length || mod.locales.some((l) => typeof l !== "string" || !/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(l)) || new Set(mod.locales).size !== mod.locales.length) {
95
+ throw new Error(`${file}: locales must be a non-empty array of unique locale tags`);
96
+ }
97
+ return mod.locales;
98
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@liqweed/motion-kit",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Deterministic animated diagrams: scenes as pure functions of time, for live pages, slides, baked SVG and video.",
5
5
  "keywords": [
6
6
  "animation",
@@ -47,7 +47,7 @@
47
47
  "prepare": "lefthook install || true",
48
48
  "test": "node --test test/*.test.mjs",
49
49
  "typecheck": "tsc -p .",
50
- "check": "node cli/motion-kit.mjs check examples/order-flow.json examples/smart-home.json examples/release-pipeline.json examples/agent-loop.json examples/integrations.json examples/incident.json examples/web-stack.json examples/custom-pulse.scene.mjs brand/logo.scene.mjs",
50
+ "check": "node cli/motion-kit.mjs check examples/order-flow.json examples/smart-home.json examples/release-pipeline.json examples/agent-loop.json examples/integrations.json examples/incident.json examples/web-stack.json examples/custom-pulse.scene.mjs brand/logo.scene.mjs examples/player-states.json examples/checkout.json examples/connection.json",
51
51
  "media": "scripts/render-media.sh",
52
52
  "media:check": "scripts/render-media.sh --check",
53
53
  "site": "npm run -w website build",