@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +13 -1
- package/adapters/page/README.md +5 -0
- package/cli/motion-kit.mjs +5 -1
- package/docs/spec/technique.md +40 -25
- package/examples/checkout.json +104 -0
- package/examples/connection.json +80 -0
- package/examples/custom-pulse.scene.mjs +2 -0
- package/examples/player-states.json +97 -0
- package/lib/check.mjs +11 -8
- package/lib/export.mjs +12 -0
- package/lib/gate.mjs +4 -4
- package/lib/load.mjs +15 -0
- package/package.json +2 -2
- package/runtime/links.mjs +5 -1
- package/runtime/player.mjs +40 -1
- package/runtime/scene.mjs +21 -8
- package/runtime/style.mjs +3 -0
- package/runtime/types/hub-spoke.mjs +8 -6
- package/runtime/types/index.mjs +3 -0
- package/runtime/types/sequence.mjs +8 -6
- package/runtime/types/stack.mjs +13 -10
- package/runtime/types/timeline.mjs +14 -12
- package/runtime/types/walk.mjs +162 -0
- package/skills/animated-diagram/SKILL.md +1 -1
- package/skills/animated-diagram/references/custom-scenes.md +14 -0
- package/skills/animated-diagram/references/interactivity.md +18 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +1 -1
- package/skills/animated-diagram/references/scene-types.md +55 -2
- package/skills/animated-diagram/references/styles.md +11 -2
- package/skills/animated-diagram/references/technique.md +6 -2
- package/skills/motion-render/SKILL.md +7 -0
- package/skills/motion-render/references/video.md +1 -1
|
@@ -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
|
@@ -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
|
-
≤
|
|
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.
|
package/adapters/page/README.md
CHANGED
|
@@ -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.
|
package/cli/motion-kit.mjs
CHANGED
|
@@ -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.
|
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
|
|
@@ -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
|
|
282
|
-
|
|
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
|
-
(`
|
|
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)
|
|
318
|
-
|
|
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` |
|
|
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
|
-
|
|
551
|
+
### 11.1 Gate policy decisions
|
|
551
552
|
|
|
552
|
-
Recorded
|
|
553
|
+
Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
|
|
553
554
|
|
|
554
|
-
|
|
|
555
|
-
|
|
556
|
-
|
|
|
557
|
-
|
|
|
558
|
-
|
|
|
559
|
-
|
|
|
560
|
-
|
|
|
561
|
-
|
|
|
562
|
-
|
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
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
|
-
|
|
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 (
|
|
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.
|
|
257
|
-
if (scene.duration > 12) problems.push(`duration ${scene.duration.toFixed(1)}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 `
|
|
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
|
|
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.
|
|
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",
|