@liqweed/motion-kit 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.claude-plugin/marketplace.json +13 -0
  2. package/.claude-plugin/plugin.json +9 -0
  3. package/LICENSE +21 -0
  4. package/README.md +141 -2
  5. package/adapters/astro/AnimatedDiagram.astro +55 -0
  6. package/adapters/element/README.md +49 -0
  7. package/adapters/element/motion-diagram.mjs +123 -0
  8. package/adapters/page/README.md +22 -0
  9. package/adapters/slidev/AnimatedDiagram.vue +137 -0
  10. package/brand/logo.scene.mjs +115 -0
  11. package/cli/motion-kit.mjs +239 -0
  12. package/docs/spec/technique.md +465 -0
  13. package/examples/agent-loop.json +18 -0
  14. package/examples/custom-pulse.scene.mjs +141 -0
  15. package/examples/integrations.json +20 -0
  16. package/examples/order-flow.json +17 -0
  17. package/examples/release-pipeline.json +17 -0
  18. package/examples/smart-home.json +17 -0
  19. package/lib/build.mjs +62 -0
  20. package/lib/bundle.mjs +68 -0
  21. package/lib/check.mjs +86 -0
  22. package/lib/export.mjs +113 -0
  23. package/lib/icon.mjs +41 -0
  24. package/lib/load.mjs +53 -0
  25. package/lib/raster.mjs +69 -0
  26. package/lib/video.mjs +77 -0
  27. package/package.json +69 -5
  28. package/runtime/bake.mjs +61 -0
  29. package/runtime/motion.mjs +154 -0
  30. package/runtime/parts.mjs +123 -0
  31. package/runtime/player.mjs +255 -0
  32. package/runtime/scene.mjs +101 -0
  33. package/runtime/style.mjs +142 -0
  34. package/runtime/svg.mjs +165 -0
  35. package/runtime/types/hub-spoke.mjs +215 -0
  36. package/runtime/types/index.mjs +25 -0
  37. package/runtime/types/sequence.mjs +201 -0
  38. package/runtime/wrap.mjs +44 -0
  39. package/skills/animated-diagram/SKILL.md +90 -0
  40. package/skills/animated-diagram/references/custom-scenes.md +56 -0
  41. package/skills/animated-diagram/references/ecosystem.md +28 -0
  42. package/skills/animated-diagram/references/interactivity.md +51 -0
  43. package/skills/animated-diagram/references/motion-vocabulary.md +70 -0
  44. package/skills/animated-diagram/references/qc.md +41 -0
  45. package/skills/animated-diagram/references/scene-types.md +59 -0
  46. package/skills/animated-diagram/references/styles.md +55 -0
  47. package/skills/animated-diagram/references/targets.md +27 -0
  48. package/skills/animated-diagram/references/technique.md +148 -0
  49. package/skills/motion-render/SKILL.md +79 -0
  50. package/skills/motion-render/references/formats.md +18 -0
  51. package/skills/motion-render/references/slides.md +18 -0
  52. package/skills/motion-render/references/video.md +61 -0
  53. package/skills/project-logo/SKILL.md +72 -0
  54. package/skills/project-logo/references/design.md +22 -0
  55. package/skills/project-logo/references/discovery.md +15 -0
  56. package/skills/project-logo/references/external-prompt.md +23 -0
  57. package/styles/neutral.json +26 -0
@@ -0,0 +1,201 @@
1
+ // SPDX-License-Identifier: MIT
2
+ // Copyright (c) 2026 Ophir Radnitz
3
+ /**
4
+ * motion-kit · scene type "sequence".
5
+ *
6
+ * Helps the viewer understand: one thing passes through ordered stages.
7
+ * Storyboard: every node appears in reading order (skeleton first, so the whole
8
+ * structure is visible), then an emphasis ring — the thing itself — travels
9
+ * node to node; each node it reaches fills with the accent colour and the path
10
+ * behind it turns accent. Every step frame reads as "you are here".
11
+ *
12
+ * Spec:
13
+ * { type: "sequence", id, title, description,
14
+ * nodes: [{ label, detail?, glyph?, icon? }], // 2–12 nodes
15
+ * glyphs?: "numbers" | "none" // default "numbers"
16
+ * fontSize?: number }
17
+ * Strings may be localized objects: { en: "...", nl: "..." }.
18
+ */
19
+ import { easeOut, easeStandard, progress } from "../motion.mjs";
20
+ import { circleNode, FONT_MIN, stateLabel } from "../parts.mjs";
21
+ import { FORMATS, localize } from "../scene.mjs";
22
+ import { tok } from "../style.mjs";
23
+ import { drawOn, el, polyline, trimSegment } from "../svg.mjs";
24
+ import { wrapLabel } from "../wrap.mjs";
25
+
26
+ // Timeline (seconds). Steps are settled because PERIOD ≥ HOP + FILL.
27
+ const ENTER_GAP = 0.1;
28
+ const ENTER = 0.4;
29
+ const FILL = 0.25;
30
+ const HOP = 0.4;
31
+ const PERIOD = HOP + FILL + 0.05;
32
+ const TAIL = 0.4;
33
+
34
+ const PAD = 24;
35
+ const CHAR = 0.56; // average glyph width / font size
36
+
37
+ function pickArrangement(format, n) {
38
+ const { width: W, height: H } = format;
39
+ if (format.name === "tall" || (H > 0 && W / H < 0.8)) return { rows: n, cols: 1, labels: "right" };
40
+ const aspect = H > 0 ? W / H : 4;
41
+ if (aspect >= 1.5) {
42
+ const cellW = (W - 2 * PAD) / n;
43
+ if (cellW >= 96) return { rows: 1, cols: n, labels: "below" };
44
+ return { rows: 2, cols: Math.ceil(n / 2), labels: "below" };
45
+ }
46
+ const rows = n <= 3 ? 1 : n <= 8 ? 2 : 3;
47
+ return { rows, cols: Math.ceil(n / rows), labels: "below" };
48
+ }
49
+
50
+ function layout(format, n, fs) {
51
+ const arr = pickArrangement(format, n);
52
+ const W = format.width;
53
+ const fixed = format.height > 0;
54
+ const lineH = fs * 1.25;
55
+ if (arr.labels === "right") {
56
+ const r = fixed ? Math.round(fs * 1.4) : 20;
57
+ const cellH = fixed ? Math.min(fs * 9, (format.height - 2 * PAD) / n) : 76;
58
+ const H = fixed ? format.height : cellH * (n - 1) + 2 * r + 2 * PAD + 8;
59
+ const top = (H - cellH * (n - 1)) / 2;
60
+ const cx = PAD + r + 4;
61
+ const labelX = cx + r + 14;
62
+ const maxChars = Math.floor((W - labelX - PAD) / (fs * CHAR));
63
+ const centers = Array.from({ length: n }, (_, i) => ({ x: cx, y: top + i * cellH }));
64
+ return { W, H, r, fs, lineH, maxChars, maxLines: 2, centers, cols: 1, label: (c) => ({ x: labelX, y: c.y, anchor: "start", baseline: "central" }) };
65
+ }
66
+ const { rows, cols } = arr;
67
+ const cellW = (W - 2 * PAD) / cols;
68
+ const r = Math.max(16, Math.min(fs * 1.9, cellW * 0.2));
69
+ const maxLines = 2;
70
+ const blockH = 2 * r + 12 + maxLines * lineH;
71
+ const gapY = fixed ? Math.max(28, Math.min(fs * 4, (format.height - 2 * PAD - rows * blockH) / Math.max(1, rows - 1) / 2)) : 28;
72
+ const H = fixed ? format.height : rows * blockH + (rows - 1) * gapY + 2 * PAD + 8;
73
+ const usedH = rows * blockH + (rows - 1) * gapY;
74
+ const top = (H - usedH) / 2 + r;
75
+ // Leave room on both sides for the elbow connectors of a snake grid.
76
+ const maxChars = Math.floor((cellW - 10) / (fs * CHAR));
77
+ const centers = [];
78
+ for (let k = 0; k < n; k++) {
79
+ const row = Math.floor(k / cols);
80
+ const inRow = k % cols;
81
+ const col = row % 2 === 0 ? inRow : cols - 1 - inRow; // snake
82
+ centers.push({ x: PAD + cellW * (col + 0.5), y: top + row * (blockH + gapY) });
83
+ }
84
+ return { W, H, r, fs, lineH, maxChars, maxLines, centers, cols, cellW, label: (c) => ({ x: c.x, y: c.y + r + 12, anchor: "middle", baseline: "hanging" }) };
85
+ }
86
+
87
+ /** Largest font (≤ max) at which every label fits its budget. */
88
+ function fit(f, nodes, locale, maxFs) {
89
+ let lastErr;
90
+ for (let fs = maxFs; fs >= FONT_MIN; fs--) {
91
+ const L = layout(f, nodes.length, fs);
92
+ if (L.maxChars < 6) continue;
93
+ try {
94
+ const lines = nodes.map((node) => wrapLabel(localize(node.label, locale), L.maxChars, L.maxLines));
95
+ return { L, lines };
96
+ } catch (e) {
97
+ lastErr = e;
98
+ }
99
+ }
100
+ throw lastErr ?? new Error("does not fit");
101
+ }
102
+
103
+ /**
104
+ * Connector between consecutive nodes. Same row/column: a straight segment.
105
+ * A snake-grid row turn: an elbow routed outside the column, clear of labels.
106
+ */
107
+ function connector(a, b, r, W, grid, cellW) {
108
+ if (grid && Math.abs(a.x - b.x) < 1) {
109
+ const side = a.x > W / 2 ? 1 : -1;
110
+ // Beyond the widest possible label (cellW − 10), inside the canvas padding.
111
+ const out = a.x + side * (cellW / 2 + PAD / 2);
112
+ const p = { x: a.x + side * (r + 6), y: a.y };
113
+ const q = { x: b.x + side * (r + 6), y: b.y };
114
+ return {
115
+ path: polyline([p, { x: out, y: a.y }, { x: out, y: b.y }, q]),
116
+ ring: polyline([a, { x: out, y: a.y }, { x: out, y: b.y }, b]),
117
+ };
118
+ }
119
+ const [p, q] = trimSegment(a, b, r + 6);
120
+ return { path: polyline([p, q]), ring: polyline([a, b]) };
121
+ }
122
+
123
+ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
124
+ const nodes = spec.nodes ?? [];
125
+ if (nodes.length < 2 || nodes.length > 12) throw new Error(`sequence "${spec.id}": needs 2–12 nodes, got ${nodes.length}`);
126
+ const f = typeof format === "string" ? { name: format, ...FORMATS[format] } : format;
127
+ if (!f.width) throw new Error(`unknown format "${format}"`);
128
+ const n = nodes.length;
129
+ const maxFs = spec.fontSize ?? (f.height > 0 ? 22 : 16);
130
+ let fitted;
131
+ try {
132
+ fitted = fit(f, nodes, locale, maxFs);
133
+ } catch (e) {
134
+ throw new Error(`sequence "${spec.id}": labels do not fit format ${f.name} at ≥ ${FONT_MIN}px: ${e instanceof Error ? e.message : e}`);
135
+ }
136
+ const { L } = fitted;
137
+
138
+ const items = nodes.map((node, i) => ({
139
+ label: localize(node.label, locale),
140
+ detail: localize(node.detail, locale),
141
+ lines: fitted.lines[i],
142
+ node: { ...node, glyph: node.icon ? undefined : (node.glyph ?? (spec.glyphs === "none" ? "" : String(i + 1))) },
143
+ }));
144
+
145
+ const START = ENTER_GAP * (n - 1) + ENTER + 0.1;
146
+ const FIRST_HOP = START + FILL + 0.25;
147
+ const hopStart = (k) => FIRST_HOP + k * PERIOD;
148
+ const fillStart = (k) => (k === 0 ? START : hopStart(k - 1) + HOP);
149
+ const stepAt = (k) => fillStart(k) + FILL;
150
+ const duration = stepAt(n - 1) + TAIL;
151
+ const ringR = L.r + 6;
152
+
153
+ // Elbows run on the canvas edge side, so the vertical turn of a snake grid
154
+ // never crosses a label.
155
+ const segs = L.centers.slice(1).map((c, i) => connector(L.centers[i], c, L.r, L.W, L.cols > 1, L.cellW));
156
+
157
+ function frame(t) {
158
+ const enter = (k) => progress(t, k * ENTER_GAP, ENTER, easeOut);
159
+ const active = (k) => progress(t, fillStart(k), FILL, easeStandard);
160
+ const out = [];
161
+ // Connectors: pending line once both ends are in, accent draw-on during the hop.
162
+ segs.forEach((s, k) => {
163
+ const shown = Math.min(enter(k), enter(k + 1));
164
+ const common = { d: s.path.d, fill: "none", "stroke-linecap": "round", "stroke-linejoin": "round" };
165
+ if (shown > 0) out.push(el("path", { ...common, stroke: tok("line"), "stroke-width": 2, opacity: shown }));
166
+ const dash = drawOn(s.path.length, progress(t, hopStart(k), HOP, easeStandard));
167
+ if (dash) out.push(el("path", { ...common, stroke: tok("accent"), "stroke-width": 3, ...dash }));
168
+ });
169
+ items.forEach((it, k) => {
170
+ const c = L.centers[k];
171
+ out.push(circleNode({ cx: c.x, cy: c.y, r: L.r, enter: enter(k), active: active(k), node: it.node }));
172
+ out.push(stateLabel({ ...L.label(c), lines: it.lines, fontSize: L.fs, enter: enter(k), active: active(k) }));
173
+ });
174
+ // Emphasis ring: appears on node 1, then hops.
175
+ const appear = progress(t, START, FILL, easeOut);
176
+ if (appear > 0) {
177
+ let pos = L.centers[0];
178
+ for (let k = 0; k < n - 1; k++) {
179
+ const p = progress(t, hopStart(k), HOP, easeStandard);
180
+ if (p <= 0) break;
181
+ pos = segs[k].ring.at(p);
182
+ }
183
+ out.push(el("circle", { cx: pos.x, cy: pos.y, r: ringR * (0.85 + 0.15 * appear), fill: "none", stroke: tok("emphasis"), "stroke-width": 3, opacity: appear }));
184
+ }
185
+ return out.join("");
186
+ }
187
+
188
+ return {
189
+ id: `${spec.id}-${f.name.replace(":", "x")}`,
190
+ type: "sequence",
191
+ format: f.name,
192
+ locale,
193
+ width: L.W,
194
+ height: L.H,
195
+ duration,
196
+ title: localize(spec.title, locale),
197
+ description: localize(spec.description, locale),
198
+ steps: items.map((it, k) => ({ at: stepAt(k), label: it.label, detail: it.detail })),
199
+ frame,
200
+ };
201
+ }
@@ -0,0 +1,44 @@
1
+ // SPDX-License-Identifier: MIT
2
+ // Copyright (c) 2026 Ophir Radnitz
3
+ /**
4
+ * motion-kit · label wrapping.
5
+ *
6
+ * SVG text does not wrap, so every layout declares a character budget. Labels
7
+ * break at spaces and after a slash ("Archive/Dispose" → "Archive/", "Dispose").
8
+ * Overflow throws, so a long translation fails the checks instead of spilling
9
+ * out of its box. Budget for Dutch/German being ~30 % longer than English.
10
+ */
11
+ export function wrapLabel(label, maxChars, maxLines = 2) {
12
+ const tokens = String(label)
13
+ .split(/\s+/)
14
+ .filter(Boolean)
15
+ // A standalone separator ("A / B", "A – B") sticks to the word before it,
16
+ // so no line ever starts with "/" or "–".
17
+ .reduce((acc, w) => {
18
+ if (/^[\/–—&+|]$/.test(w) && acc.length) acc[acc.length - 1] += ` ${w}`;
19
+ else acc.push(w);
20
+ return acc;
21
+ }, /** @type {string[]} */ ([]))
22
+ .flatMap((word) => word.split(/(?<=\/)(?=[^\s])/).map((part, i) => ({ part, space: i === 0 })));
23
+ const lines = [];
24
+ let cur = "";
25
+ for (const { part, space } of tokens) {
26
+ if (part.length > maxChars) throw new Error(`label "${label}": "${part}" is longer than ${maxChars} characters`);
27
+ const joined = cur === "" ? part : `${cur}${space ? " " : ""}${part}`;
28
+ if (joined.length <= maxChars) cur = joined;
29
+ else {
30
+ lines.push(cur);
31
+ cur = part;
32
+ }
33
+ }
34
+ if (cur) lines.push(cur);
35
+ if (lines.length > maxLines) {
36
+ throw new Error(`label "${label}" needs ${lines.length} lines at ${maxChars} chars; the layout allows ${maxLines}`);
37
+ }
38
+ return lines;
39
+ }
40
+
41
+ /** Rough rendered width of a line, in px, for a sans-serif face. */
42
+ export function estimateWidth(line, fontSize) {
43
+ return line.length * fontSize * 0.56;
44
+ }
@@ -0,0 +1,90 @@
1
+ ---
2
+ name: animated-diagram
3
+ description: "Build animated, interactive explanatory diagrams (process flows, hub-and-spoke integrations, build-up sequences) as deterministic scenes — pure functions of time — with motion-kit. One scene serves a live web page or Craft Page, Slidev slides (one build step per click), standalone SVG/PNG slide frames, a zero-JS baked SVG, and MP4/GIF video. Use when asked to 'animate a diagram', 'make an animated/interactive diagram or explainer', 'build-up slide', 'diagram that plays step by step', or to turn a process/architecture description into motion. For exporting/rendering an existing scene (PNG, video, social formats) use motion-render."
4
+ ---
5
+
6
+ # Animated diagram (motion-kit)
7
+
8
+ A scene is `frame(t) → SVG markup`, a pure function of time. Players own the
9
+ clock; exporters sample exact times; video samples `t = f / fps`. Read
10
+ `references/technique.md` before writing a custom scene or changing the runtime.
11
+
12
+ ## Locate the toolkit
13
+
14
+ ```bash
15
+ MK="$HOME/workspace/motion-kit" # canonical clone (has node_modules)
16
+ [ -d "$MK" ] || MK="$(cd "<this skill's base directory>/../.." && pwd)" # plugin copy
17
+ node "$MK/cli/motion-kit.mjs" --help
18
+ ```
19
+ Node ≥ 22. PNG/video need `@resvg/resvg-js` (`npm install` in `$MK`) and `ffmpeg`.
20
+
21
+ ## Workflow
22
+
23
+ 1. **Brief: ask before building** (one message, skip what's already known):
24
+ - What should the viewer *understand* after watching? (one sentence)
25
+ - Where will it be shown? → target, see `references/targets.md`
26
+ (Craft Page · in-chat preview · Slidev/Marp/PowerPoint · website · README/vault · video)
27
+ - Which formats? (16:9, 4:3, 1:1, 9:16, wide strip, tall phone column)
28
+ - Languages? (labels may be `{ "en": "...", "nl": "..." }`)
29
+ - **Visual style:** neutral (default) / a style file (`--style brand.json`) /
30
+ describe one → I write a style file. See `references/styles.md`.
31
+ - Approved copy and claims. **Never invent numbers, metrics or claims.**
32
+ 2. **Storyboard → approval.** Pick a scene type (`references/scene-types.md`).
33
+ Write the spec, then render the step contact sheet and show it:
34
+ `motion-kit export spec.json -o <scratch>/sb --png --qc` → open `index.html`
35
+ or show the PNGs. Get a yes on the *story* before polishing.
36
+ 3. **Build.** Spec-driven types first (`sequence`, `hub-spoke`). Only write a
37
+ custom scene module when no type fits (`references/custom-scenes.md`).
38
+ 4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
39
+ shipped: deterministic, settled steps, rounded numbers, token-only colours,
40
+ escaped labels, labels fit, holds the final frame.
41
+ 5. **QC.** `references/qc.md`: before/after frames around each step, phone
42
+ size, real-time playback (never trust virtual-time screenshots), reduced
43
+ motion, dark mode. **A human approves the look**: green checks don't show it.
44
+ 6. **Deliver** per target (`references/targets.md`) and write down where the
45
+ spec lives so it can be edited and re-rendered later.
46
+
47
+ ## Hard rules
48
+
49
+ - Plays once and holds the final frame (loops only for ambient status displays).
50
+ - One entrance ≤ 600 ms, siblings staggered 80–150 ms, whole scene ≤ ~8 s.
51
+ - No bounce/elastic, no parallax, no ambient motion inside an explainer.
52
+ - Every motion must answer "what does this help the viewer understand?".
53
+ - Skeleton first, then fill: show the whole structure, then walk through it.
54
+ - One emphasis colour, one emphasis element.
55
+ - Step frames are settled: the next motion starts at or after the step's `at`.
56
+ - Long text belongs in HTML captions (`detail`), not in the SVG.
57
+ - Always a pause control (WCAG 2.2.2); reduced motion = final frame, no autoplay.
58
+ - No `Date`, `Math.random`, `performance.now` inside a scene.
59
+
60
+ ## Quick recipes
61
+
62
+ ```bash
63
+ mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
64
+ mk types; mk formats
65
+ mk check diagram.json # all formats × locales
66
+ mk build diagram.json -o diagram.html -f wide -l nl # Craft Page / standalone
67
+ mk export diagram.json -o out/ --png --qc # slides + review sheet
68
+ mk bake diagram.json -o diagram.svg -f wide # zero-JS animated SVG
69
+ mk video diagram.json -f 9:16 -o reel.mp4 --sheet sheet.png
70
+ mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page
71
+ ```
72
+
73
+ Vendoring includes the full MIT `LICENSE`. Keep that file and the SPDX
74
+ headers when redistributing the vendored runtime and adapters.
75
+
76
+ ## References
77
+
78
+ | File | Read when |
79
+ |---|---|
80
+ | `references/technique.md` | Always for custom scenes or runtime changes: the model, determinism rules, timeline authoring, lessons learned |
81
+ | `references/scene-types.md` | Choosing a type; spec fields; storyboards for types not built yet |
82
+ | `references/motion-vocabulary.md` | Easing, timing budgets, springs, split edges, container/text timing |
83
+ | `references/interactivity.md` | Player controls, scrubber, hover-linking, scroll-driven, explorables, a11y |
84
+ | `references/targets.md` | Where it will be shown and what each target allows |
85
+ | `references/styles.md` | Neutral default, style files, brand presets, contrast |
86
+ | `references/qc.md` | Review stages, checklist, review-report template |
87
+ | `references/custom-scenes.md` | Writing a one-off scene module |
88
+ | `references/ecosystem.md` | When GSAP, HyperFrames, Remotion, Motion Canvas, Manim, Mermaid or ELK are the better tool |
89
+
90
+ For rendering, slide packaging and video, see the **motion-render** skill.
@@ -0,0 +1,56 @@
1
+ # Custom scenes
2
+
3
+ When no scene type fits, write a module. Template: `examples/custom-pulse.scene.mjs`.
4
+
5
+ ```js
6
+ // my-diagram.scene.mjs. Import ONLY from motion-kit's runtime, single-line
7
+ // relative imports (the HTML builder inlines modules line by line).
8
+ import { easeOut, easeStandard, progress } from "../runtime/motion.mjs";
9
+ import { FORMATS, localize } from "../runtime/scene.mjs";
10
+ import { tok } from "../runtime/style.mjs";
11
+ import { el, fade, num, text } from "../runtime/svg.mjs";
12
+
13
+ export default function make({ format = "16:9", locale = "en" } = {}) {
14
+ const { width, height } = FORMATS[format];
15
+ // timeline constants …
16
+ return {
17
+ id: `my-diagram-${format.replace(":", "x")}`, width, height,
18
+ duration: 4.2,
19
+ title: localize({ en: "…", nl: "…" }, locale),
20
+ description: localize({ en: "…", nl: "…" }, locale),
21
+ steps: [{ at: 1.2, label: "…", detail: "…" }, …],
22
+ frame(t) { /* return inner SVG markup for time t */ },
23
+ };
24
+ }
25
+ ```
26
+
27
+ Rules:
28
+
29
+ - Pure: the frame depends only on `t` and constants. No clock, no randomness,
30
+ no module-level mutable state.
31
+ - Colours only via `tok()`; numbers in strings via `num()`.
32
+ - Use `fade()`/`el()` so invisible elements disappear; `drawOn()` for lines.
33
+ - Lay out per format; throw if labels don't fit (`wrapLabel`).
34
+ - Gate: `motion-kit check my-diagram.scene.mjs` (all formats you support; pass
35
+ `--format` to limit).
36
+ - Imports must be single-line `import { a, b } from "./relative.mjs";` and the
37
+ default export a function; the HTML builder supports only that subset.
38
+ - If the same shape is needed twice, promote it to a scene type in
39
+ `runtime/types/` with a spec and tests.
40
+
41
+ ## Scenes outside this repository: `kit`
42
+
43
+ The CLI calls `make({ format, locale, kit })`, where `kit` is the whole
44
+ runtime in one flat namespace (`lib/load.mjs` `KIT`). A scene file kept in
45
+ another repository can destructure what it needs instead of importing:
46
+
47
+ ```js
48
+ export default function make({ format = "1:1", kit }) {
49
+ const { tok, el, num, progress, easeOut } = kit;
50
+ …
51
+ }
52
+ ```
53
+
54
+ Every Node-side command (check, export, bake, icon, video) supports this.
55
+ `motion-kit build` bundles the module for the browser and needs relative
56
+ imports; vendor the runtime for that.
@@ -0,0 +1,28 @@
1
+ # Ecosystem: when another tool is the better choice
2
+
3
+ Checked Nov 2026. Re-verify licences before commercial use.
4
+
5
+ | Tool | Licence | Use it when | Fit with motion-kit |
6
+ |---|---|---|---|
7
+ | **HyperFrames** (heygen-com/hyperframes) | Apache-2.0 | Video with media, screen recordings, audio, longer edits, captions; HTML compositions rendered deterministically (headless Chrome + FFmpeg); ships Claude Code skills | Same seek(t) principle. A motion-kit scene can be a clip: the player exposes `window.__motionKit[id].seek(t)` for a custom-runtime adapter. Install its skills only in repos that need video editing: `npx skills add heygen-com/hyperframes` or the Claude Code plugin marketplace |
8
+ | **Remotion** | source-available; free for individuals and companies ≤ 3 people, paid company licence otherwise | React-based video compositions, rich templates, Lambda rendering | Official agent skills: `npx skills add remotion-dev/skills`. Prefer HyperFrames for licence simplicity unless the team already uses React video |
9
+ | **GSAP** (incl. DrawSVG, MorphSVG, MotionPath, SplitText) | free incl. commercial since 3.13 (not for competing no-code builders) | Rich page motion, morphing, text splitting | Paused timelines are seekable (`tl.seek(t)`), so determinism holds. ~70 KB must be inlined for Craft Pages. Use for website polish; keep explainers in motion-kit |
10
+ | **Motion Canvas / Revideo** | MIT | Hand-crafted technical explainer *videos* with generator timelines | Good for one-off videos; no live-page reuse |
11
+ | **Manim CE** | MIT | Mathematics and science visuals, equations | Python; video only |
12
+ | **Mermaid** | MIT | Static diagrams from text; quick structure | Use as *input notation* (flowchart/state), then lay out and animate in motion-kit |
13
+ | **ELK.js / dagre** | EPL-2.0 / MIT | Automatic layout of larger graphs | Run at build time in Node, store coordinates in the spec |
14
+ | **Lottie / Rive** | MIT runtimes | Designer-authored animation assets | Embed as media; not data-driven |
15
+ | **resvg-js** | MPL-2.0 | SVG → PNG without a browser | motion-kit's rasterizer |
16
+
17
+ ## Related agent skills worth borrowing ideas from
18
+
19
+ - **visual-explainer** (nicobailon, MIT): fixed visual registers, hover-linking
20
+ between text and figure, contact-sheet self-check.
21
+ - **Dashmotion** (csthink, MIT): Mermaid → animated SVG with CSS/SMIL, zero
22
+ dependencies; a pause toggle and reduced-motion handling inside the SVG.
23
+
24
+ ## Further reading
25
+
26
+ - Bret Victor, "Explorable Explanations"; Nicky Case's explorables: interaction
27
+ that teaches.
28
+ - WCAG 2.2: 2.2.2 Pause, Stop, Hide; 2.3.3 Animation from Interactions.
@@ -0,0 +1,51 @@
1
+ # Interactivity and accessibility
2
+
3
+ ## The player (`runtime/player.mjs`, used by `build`, the Astro adapter, Craft Pages)
4
+
5
+ - Starts on the **final frame** (also the no-JS / server-rendered fallback).
6
+ - Replays once when ~40 % visible, then holds.
7
+ - Controls: play/pause (always present, WCAG 2.2.2), one button per step (jumps
8
+ by default), optional scrubber, caption with the active step's `detail`.
9
+ - Keyboard on the diagram: ← / → step, Home / End, Space play/pause.
10
+ - `prefers-reduced-motion`: final frame, no autoplay, no play button.
11
+ - `prefers-color-scheme`: light/dark tokens switch live.
12
+ - Screen readers: `role="img"` + `<title>`/`<desc>`, a visually hidden ordered
13
+ list of all steps with details; the visible caption is `aria-hidden`.
14
+ - Capture hook: `window.__motionKit[id].seek(t)` (for Playwright/HyperFrames-
15
+ style renderers).
16
+
17
+ The controller's step indices are zero-based. `controller.seekStep(i)` jumps;
18
+ `controller.playToStep(i)` plays forward from the current time and stops at the
19
+ step's exact settled time. Backward and same-step calls jump, and reduced
20
+ motion always jumps. A new call replaces the previous target; `pause()` holds
21
+ the current frame, `seek(t)` cancels playback, and `play()` continues to the end.
22
+ Invalid indices throw `RangeError`.
23
+
24
+ Pass `{ animateSteps: true }` to `mountPlayer(container, scene, options)` to
25
+ enable this behavior for the step buttons and arrow/Home/End keys. The default
26
+ keeps instant navigation. Call `controller.destroy()` before removing or
27
+ replacing a player: it cancels playback, visibility observation, theme listening
28
+ and its capture-hook entry.
29
+
30
+ ## Patterns worth adding per diagram (in the page around the player)
31
+
32
+ - **Hover/focus linking:** terms in the surrounding text highlight the matching
33
+ part of the diagram (and back). Wrap the term in
34
+ `<span data-mk-step="3">`; on hover, `controller.seekStep(3)`.
35
+ - **Scroll-driven steps:** for long-form explainers, map section visibility to
36
+ steps (IntersectionObserver per text section → `seekStep(i)`). Don't scrub
37
+ continuously on scroll; jump to settled steps.
38
+ - **Details on demand:** step buttons + caption first; tooltips only for
39
+ secondary facts.
40
+ - **Explorables:** a parameter slider can change the *spec* (e.g. number of
41
+ spokes, a rate), re-create the scene and seek to the same step. Keep the
42
+ scene pure: the parameter is input, not state.
43
+
44
+ ## Rules
45
+
46
+ - Never autoplay sound. Never loop an explainer.
47
+ - Every interactive control is a real `<button>`/`<input>` with a visible focus
48
+ style and an accessible name.
49
+ - Don't hide information only in hover states; touch devices have no hover.
50
+ - Test: keyboard only, a screen reader pass (VoiceOver: the step list is read),
51
+ phone width, reduced motion, dark mode.
@@ -0,0 +1,70 @@
1
+ # Motion vocabulary
2
+
3
+ ## Easing (`runtime/motion.mjs`, exact cubic-bézier solve, no overshoot)
4
+
5
+ | Name | Curve | Use |
6
+ |---|---|---|
7
+ | `easeOut` | `cubic-bezier(0, 0, .2, 1)` | entrances, appearing |
8
+ | `easeStandard` | `cubic-bezier(.4, 0, .2, 1)` | movement between two visible states, fills, draw-on |
9
+ | `easeIn` | `cubic-bezier(.4, 0, 1, 1)` | exits (rare in explainers) |
10
+ | `linear` | — | only for things that should feel mechanical (progress bars) |
11
+
12
+ ## Timing budget
13
+
14
+ | Event | Duration |
15
+ |---|---|
16
+ | One entrance | 300–600 ms |
17
+ | Sibling stagger | 80–150 ms, reading order |
18
+ | State fill (pending → active) | 200–300 ms |
19
+ | Travel between nodes | 350–500 ms |
20
+ | Pause between beats | ≥ 50 ms, so step frames settle |
21
+ | Whole explainer | ≤ ~8 s, then hold |
22
+
23
+ ## Springs, without breaking random access (derived)
24
+
25
+ Frame-by-frame spring simulation depends on earlier frames. Use the closed form.
26
+ A **critically damped** spring never overshoots:
27
+
28
+ ```
29
+ s(τ) = 1 − (1 + ωτ)·e^(−ωτ) τ > 0, else 0 (springStep)
30
+ ```
31
+
32
+ ω ≈ 8–16 rad/s for UI-scale motion (settles in `9.24 / ω` s). The value snaps to
33
+ exactly 1 at ωτ ≥ 9.24 (error ≤ 0.1 %), so settled frames are byte-stable.
34
+
35
+ **Retargeting** (a value that changes target mid-flight) is exact superposition,
36
+ because the spring is linear and time-invariant:
37
+
38
+ ```
39
+ value(t) = from + Σ (to_i − to_{i−1}) · s(t − at_i) (springTo)
40
+ ```
41
+
42
+ Continuous at every change, still random-access. Underdamped (bouncy) springs
43
+ are out of scope for explainers.
44
+
45
+ ## Split edges (derived)
46
+
47
+ A moving shape's leading edge moves first and the trailing edge follows a
48
+ little later with the same curve: the shape stretches in flight and settles at
49
+ its own length. `splitEdge(t, start, dur, lag = 0.07)` → `{ lead, trail }`.
50
+ Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
51
+
52
+ ## Container and text timing
53
+
54
+ - The container (box, card) starts moving immediately; new text appears only
55
+ once there is room for it; the old text is gone before the next transition.
56
+ - Labels never move while being read: animate the node, not its label.
57
+ - Cross-fade text colour (muted → ink) together with the node's fill.
58
+
59
+ ## Banned in explainers
60
+
61
+ Bounce and elastic easing · parallax · looping or auto-advancing carousels ·
62
+ ambient motion · `transition: all` · anything whose only purpose is decoration.
63
+
64
+ ## Sound (video only)
65
+
66
+ Attach visual events (a node lighting, a link completing) to beat or peak
67
+ times in the soundtrack: put the times in the spec and derive the timeline
68
+ from them. Use licensed or original audio only, and review audio like visuals.
69
+ motion-kit's own video path is silent. For audio-synced edits use HyperFrames
70
+ (see `ecosystem.md`).
@@ -0,0 +1,41 @@
1
+ # Quality control
2
+
3
+ Model screenshots are evidence, not approval. **A human signs off on the look.**
4
+ "Checks are green" says nothing about how it looks.
5
+
6
+ ## Five stages
7
+
8
+ 1. **Storyboard:** step contact sheet (`export --png --qc` → `index.html`).
9
+ Does the sequence tell the story without narration? Approve before polishing.
10
+ 2. **Timing:** QC frames 0.2 s before/after each step: overlapping text, abrupt
11
+ jumps, elements vanishing, half-drawn lines, stray dots. Regular sampling
12
+ misses broken transitions; look *around* the transitions.
13
+ 3. **Phone size:** the 360 px row in the sheet; the `tall`/`9:16` layout; no
14
+ text under 14 px at 1×.
15
+ 4. **Brand and facts:** tokens only, approved style, approved copy, no invented
16
+ numbers or superlatives, every locale checked.
17
+ 5. **Final file:**
18
+ - Live: real-time playback at desktop and phone width; reduced motion
19
+ (`--force-prefers-reduced-motion`); dark mode; keyboard; screen reader
20
+ reads the step list.
21
+ - Video: `video --sheet` contact sheet; duration, aspect and size via the
22
+ printed probe; watch it once at full size.
23
+
24
+ **Don't trust virtual time.** Headless `--virtual-time-budget` doesn't advance
25
+ the player's animation clock faithfully. Use `--timeout=<ms>` (real time) or a
26
+ DevTools/Playwright session, or force reduced motion to check the final frame.
27
+
28
+ ## Review report (paste into the PR / task)
29
+
30
+ ```markdown
31
+ ### Diagram review: <scene id> (<formats>, <locales>, <style>)
32
+ - Gate: `motion-kit check` ✓ (n formats × m locales)
33
+ - Timestamps inspected: steps 1–N; before/after each transition; phone row
34
+ - Issues found:
35
+ - …
36
+ - Fixes applied:
37
+ - …
38
+ - Remaining concerns:
39
+ - …
40
+ - Human approval: ☐ <name>, <date>
41
+ ```
@@ -0,0 +1,59 @@
1
+ # Scene types
2
+
3
+ Prefer a spec-driven type; a new diagram is then data, not code. Strings can be
4
+ plain or localized (`{ "en": "...", "nl": "..." }`). Every node may have a
5
+ `detail` sentence (player caption + screen-reader text).
6
+
7
+ ## Built
8
+
9
+ ### `sequence`: one thing through ordered stages
10
+
11
+ ```json
12
+ { "type": "sequence", "id": "order-flow",
13
+ "title": "How an order reaches the customer",
14
+ "description": "Six stages in order: …",
15
+ "nodes": [ { "label": "Order", "detail": "The customer places an order." }, … ],
16
+ "glyphs": "numbers", // or "none"; per node: "glyph": "A" or "icon": "<path d>"
17
+ "fontSize": 18 } // optional max; auto-fit otherwise
18
+ ```
19
+
20
+ 2–12 nodes. Storyboard: nodes appear in reading order → an emphasis ring lands
21
+ on node 1 → it travels node to node; each reached node fills accent and the
22
+ path behind turns accent. Steps = one per node.
23
+ Layouts: row (wide aspects), snake grid with outside elbows (1:1, 4:3, crowded
24
+ 16:9), column with labels on the right (9:16, tall).
25
+
26
+ ### `hub-spoke`: one centre connected to many
27
+
28
+ ```json
29
+ { "type": "hub-spoke", "id": "integrations",
30
+ "title": "…", "description": "…",
31
+ "hub": { "label": "Platform", "detail": "…" },
32
+ "spokes": [ { "label": "E-mail", "detail": "…" }, … ],
33
+ "direction": "out" } // "in" = spokes feed the hub
34
+ ```
35
+
36
+ 2–10 spokes. Storyboard: hub + spokes appear → the hub activates → one link at a
37
+ time draws (carrying an emphasis dot) and the spoke fills. Steps = hub, then
38
+ each spoke. Layouts: radial ellipse (wide/square), tree with an outside trunk
39
+ (9:16, tall). Throws when boxes would overlap: fewer spokes or a larger format.
40
+
41
+ ## Storyboards for types not built yet
42
+
43
+ Build these as custom scenes (`custom-scenes.md`) first. Promote one to a type
44
+ once it has been used twice.
45
+
46
+ | Type | Helps the viewer understand | Storyboard |
47
+ |---|---|---|
48
+ | `stack` | layers build on each other (architecture, security layers) | layers rise bottom-up; then a request/data packet travels down/up, each layer lighting as it passes |
49
+ | `before-after` | what changes | left state fully shown → a divider sweeps → right state builds; differences highlighted with the emphasis colour |
50
+ | `timeline` | events in time | axis draws on → milestones drop in order → "now" marker settles |
51
+ | `comparison` | option A vs B on criteria | two columns appear → criteria rows fill one at a time → the deciding row emphasised |
52
+ | `state-machine` | states and transitions | all states (pending) → a token walks a path of transitions, the current state accent |
53
+ | `request-journey` | a request crossing system components | components in regions/boundaries → a dot travels the path, each hop lights, async edges dashed |
54
+ | `funnel` / `data-flow` | volume or data narrowing/merging | sources appear → streams draw on and merge → result fills |
55
+
56
+ Auto-layout for larger graphs: lay out with ELK.js or dagre once (Node, at
57
+ build time), store coordinates in the spec, then animate. Mermaid flowchart or
58
+ state syntax can serve as input notation (parse nodes/edges, recompute layout).
59
+ Don't convert sequence or ER diagrams lossily.