@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +17 -2
- package/adapters/page/README.md +5 -0
- package/cli/motion-kit.mjs +91 -4
- package/docs/spec/technique.md +49 -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/examples/pull-request.json +93 -0
- package/examples/pull-request.mmd +15 -0
- package/lib/check.mjs +11 -8
- package/lib/export.mjs +12 -0
- package/lib/gate.mjs +4 -4
- package/lib/layout.mjs +236 -0
- package/lib/load.mjs +15 -0
- package/lib/mermaid.mjs +382 -0
- package/lib/outdated.mjs +122 -0
- package/package.json +6 -3
- 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/flowchart.mjs +402 -0
- package/runtime/types/hub-spoke.mjs +8 -6
- package/runtime/types/index.mjs +5 -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 +8 -3
- package/skills/animated-diagram/references/custom-scenes.md +14 -0
- package/skills/animated-diagram/references/ecosystem.md +2 -2
- 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 +118 -6
- 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.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.
|
|
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
|
-
≤
|
|
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.
|
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
|
@@ -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.
|
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,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)
|
|
318
|
-
|
|
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` |
|
|
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
|
-
|
|
552
|
+
### 11.1 Gate policy decisions
|
|
551
553
|
|
|
552
|
-
Recorded
|
|
554
|
+
Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
|
|
553
555
|
|
|
554
|
-
|
|
|
555
|
-
|
|
556
|
-
|
|
|
557
|
-
|
|
|
558
|
-
|
|
|
559
|
-
|
|
|
560
|
-
|
|
|
561
|
-
|
|
|
562
|
-
|
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
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
|
+
}
|