@liqweed/motion-kit 0.4.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.
Files changed (45) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +26 -6
  4. package/adapters/element/README.md +5 -0
  5. package/adapters/page/README.md +10 -0
  6. package/cli/motion-kit.mjs +14 -4
  7. package/docs/spec/technique.md +129 -51
  8. package/examples/checkout.json +104 -0
  9. package/examples/connection.json +80 -0
  10. package/examples/custom-pulse.scene.mjs +5 -0
  11. package/examples/incident.json +18 -0
  12. package/examples/player-states.json +97 -0
  13. package/examples/web-stack.json +17 -0
  14. package/lib/build.mjs +1 -1
  15. package/lib/check.mjs +215 -21
  16. package/lib/export.mjs +116 -7
  17. package/lib/gate.mjs +9 -7
  18. package/lib/load.mjs +15 -0
  19. package/package.json +6 -3
  20. package/runtime/kit.mjs +2 -2
  21. package/runtime/links.mjs +318 -0
  22. package/runtime/parts.mjs +15 -0
  23. package/runtime/patch.mjs +297 -0
  24. package/runtime/player.mjs +45 -2
  25. package/runtime/scene.mjs +24 -9
  26. package/runtime/style.mjs +65 -16
  27. package/runtime/types/hub-spoke.mjs +10 -8
  28. package/runtime/types/index.mjs +7 -0
  29. package/runtime/types/sequence.mjs +10 -8
  30. package/runtime/types/stack.mjs +230 -0
  31. package/runtime/types/timeline.mjs +407 -0
  32. package/runtime/types/walk.mjs +162 -0
  33. package/skills/animated-diagram/SKILL.md +28 -7
  34. package/skills/animated-diagram/references/custom-scenes.md +20 -1
  35. package/skills/animated-diagram/references/interactivity.md +129 -6
  36. package/skills/animated-diagram/references/motion-vocabulary.md +1 -1
  37. package/skills/animated-diagram/references/qc.md +3 -0
  38. package/skills/animated-diagram/references/scene-types.md +100 -4
  39. package/skills/animated-diagram/references/styles.md +55 -6
  40. package/skills/animated-diagram/references/technique.md +15 -6
  41. package/skills/motion-render/SKILL.md +31 -6
  42. package/skills/motion-render/references/formats.md +8 -8
  43. package/skills/motion-render/references/video.md +1 -1
  44. package/skills/project-logo/SKILL.md +15 -4
  45. package/styles/neutral.json +2 -2
@@ -1,3 +1,4 @@
1
+ /** @import { Style } from "../style.mjs" */
1
2
  // SPDX-License-Identifier: MIT
2
3
  // Copyright (c) 2026 Ophir Radnitz
3
4
  /**
@@ -17,9 +18,9 @@
17
18
  * Strings may be localized objects: { en: "...", nl: "..." }.
18
19
  */
19
20
  import { easeOut, easeStandard, progress } from "../motion.mjs";
20
- import { circleNode, FONT_MIN, stateLabel } from "../parts.mjs";
21
+ import { circleNode, FONT_MIN, maxFontSize, stateLabel } from "../parts.mjs";
21
22
  import { FORMATS, localize, withId } from "../scene.mjs";
22
- import { tok } from "../style.mjs";
23
+ import { NEUTRAL, tok } from "../style.mjs";
23
24
  import { drawOn, el, polyline, trimSegment } from "../svg.mjs";
24
25
  import { wrapLabel } from "../wrap.mjs";
25
26
 
@@ -126,7 +127,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
126
127
  const f = typeof format === "string" ? { name: format, ...FORMATS[format] } : format;
127
128
  if (!f.width) throw new Error(`unknown format "${format}"`);
128
129
  const n = nodes.length;
129
- const maxFs = spec.fontSize ?? (f.height > 0 ? 22 : 16);
130
+ const maxFs = maxFontSize(spec, f.height > 0 ? 22 : 16, `sequence "${spec.id}"`);
130
131
  let fitted;
131
132
  try {
132
133
  fitted = fit(f, nodes, locale, maxFs);
@@ -154,7 +155,8 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
154
155
  // never crosses a label.
155
156
  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
 
157
- function frame(t) {
158
+ /** @param {number} t @param {{style?: Style}} [ctx] */
159
+ function frame(t, { style = NEUTRAL } = {}) {
158
160
  const enter = (k) => progress(t, k * ENTER_GAP, ENTER, easeOut);
159
161
  const active = (k) => progress(t, fillStart(k), FILL, easeStandard);
160
162
  const out = [];
@@ -162,13 +164,13 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
162
164
  segs.forEach((s, k) => {
163
165
  const shown = Math.min(enter(k), enter(k + 1));
164
166
  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 }));
167
+ if (shown > 0) out.push(el("path", { ...common, stroke: tok("line"), "stroke-width": style.stroke, opacity: shown }));
166
168
  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 }));
169
+ if (dash) out.push(el("path", { ...common, stroke: tok("accent"), "stroke-width": style.stroke * 1.5, ...dash }));
168
170
  });
169
171
  items.forEach((it, k) => {
170
172
  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 }));
173
+ out.push(circleNode({ strokeWidth: style.stroke, cx: c.x, cy: c.y, r: L.r, enter: enter(k), active: active(k), node: it.node }));
172
174
  out.push(stateLabel({ ...L.label(c), lines: it.lines, fontSize: L.fs, enter: enter(k), active: active(k) }));
173
175
  });
174
176
  // Emphasis ring: appears on node 1, then hops.
@@ -180,7 +182,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
180
182
  if (p <= 0) break;
181
183
  pos = segs[k].ring.at(p);
182
184
  }
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 }));
185
+ out.push(el("circle", { cx: pos.x, cy: pos.y, r: ringR * (0.85 + 0.15 * appear), fill: "none", stroke: tok("emphasis"), "stroke-width": style.stroke * 1.5, opacity: appear }));
184
186
  }
185
187
  return out.join("");
186
188
  }
@@ -0,0 +1,230 @@
1
+ /** @import { Style } from "../style.mjs" */
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) 2026 Ophir Radnitz
4
+ /**
5
+ * motion-kit · scene type "stack".
6
+ *
7
+ * Helps the viewer understand: layers that build on each other (an
8
+ * architecture, security layers, a protocol stack), and what passes through
9
+ * them. Storyboard: the layers rise into place bottom-up (skeleton first),
10
+ * then a packet (the one emphasis element) enters on a rail beside the stack
11
+ * and travels layer to layer; each layer it reaches fills with the accent
12
+ * colour, and the rail behind the packet turns accent.
13
+ *
14
+ * Spec:
15
+ * { type: "stack", id, title, description,
16
+ * layers: [{ label, detail?, id? }], // 2–8, listed top to bottom; id names the step
17
+ * direction?: "down" | "up", // default "down": the packet enters at the top
18
+ * fontSize?: number }
19
+ * Strings may be localized objects: { en: "...", nl: "..." }.
20
+ *
21
+ * Layout: one column of full-width layers with the rail on their right, in
22
+ * every format; layers get taller (up to a limit) where the format has room.
23
+ */
24
+ import { easeOut, easeStandard, lerp, progress } from "../motion.mjs";
25
+ import { FONT_MIN, maxFontSize } from "../parts.mjs";
26
+ import { FORMATS, localize, withId } from "../scene.mjs";
27
+ import { NEUTRAL, tok } from "../style.mjs";
28
+ import { drawOn, el, fade, num, text, translate } from "../svg.mjs";
29
+ import { wrapLabel } from "../wrap.mjs";
30
+
31
+ /** @import { Scene } from "../scene.mjs" */
32
+
33
+ // Timeline (seconds). Steps are settled because PERIOD ≥ HOP + FILL.
34
+ const RISE_GAP = 0.1;
35
+ const RISE = 0.4;
36
+ const RAIL = 0.45;
37
+ const APPEAR = 0.25;
38
+ const HOP = 0.4;
39
+ const FILL = 0.25;
40
+ const PERIOD = HOP + FILL + 0.05;
41
+ const TAIL = 0.4;
42
+
43
+ const PAD = 24;
44
+ const CHAR = 0.56;
45
+ const GAP = 10; // between two layers
46
+ const RAIL_GAP = 26; // layer edge → rail
47
+ const LEAD = 34; // rail beyond the outer layers, where the packet enters and leaves
48
+ const DOT = 7;
49
+ const MAX_LAYERS = 8;
50
+ const RISE_BY = 14; // a layer rises this far into place
51
+
52
+ /**
53
+ * One layer in three states, cross-faded: pending (surface), current (accent
54
+ * fill) and passed (surface with an accent outline), so the finished stack
55
+ * shows the packet's path without a wall of accent.
56
+ * @param {{ x: number, y: number, w: number, h: number }} b
57
+ * @param {string[]} lines
58
+ * @param {number} fs
59
+ * @param {number} enter
60
+ * @param {number} active
61
+ * @param {number} passed
62
+ * @param {Style} style
63
+ */
64
+ function layer(b, lines, fs, enter, active, passed, style) {
65
+ if (enter <= 0) return "";
66
+ const dy = (1 - enter) * RISE_BY;
67
+ const label = (fill) => text({ x: b.x + b.w / 2, y: b.y + b.h / 2, "text-anchor": "middle", "dominant-baseline": "central", "font-size": fs, "font-weight": 500, fill }, lines);
68
+ const box = (fill, stroke, width) => el("rect", { x: b.x, y: b.y, width: b.w, height: b.h, rx: style.radius, fill, stroke, "stroke-width": width * style.stroke / 2 });
69
+ return fade(
70
+ enter,
71
+ { transform: dy > 0.004 ? translate(0, dy) : undefined },
72
+ fade(1 - active, {}, box(tok("surface"), tok("line"), 2), label(tok("ink"))),
73
+ fade(active * (1 - passed), {}, box(tok("accent"), tok("accent"), 2), label(tok("onAccent"))),
74
+ fade(passed, {}, box(tok("surface"), tok("accent"), 3), label(tok("ink"))),
75
+ );
76
+ }
77
+
78
+ /**
79
+ * Geometry for `n` layers at font size `fs` with up to `maxLines` label lines,
80
+ * or the reason it does not fit.
81
+ * @param {{ name: string, width: number, height: number }} f
82
+ * @param {number} n
83
+ * @param {number} fs
84
+ * @param {number} maxLines
85
+ */
86
+ function layout(f, n, fs, maxLines) {
87
+ const W = f.width;
88
+ const fixed = f.height > 0;
89
+ const lineH = fs * 1.25;
90
+ const minH = maxLines * lineH + 20;
91
+ const railSpace = RAIL_GAP + DOT + 2;
92
+ const boxW = Math.min(W - 2 * PAD - railSpace, fs * 24);
93
+ let boxH = minH;
94
+ if (fixed) {
95
+ const room = (f.height - 2 * PAD - 2 * LEAD - (n - 1) * GAP) / n;
96
+ if (room < minH) return { problem: `${n} layers of ${maxLines} line(s) need ${Math.ceil(n * minH + (n - 1) * GAP + 2 * LEAD + 2 * PAD)}px of height, the format has ${f.height}` };
97
+ boxH = Math.min(room, Math.max(minH, fs * 3.4));
98
+ }
99
+ const stackH = n * boxH + (n - 1) * GAP;
100
+ const H = fixed ? f.height : Math.ceil(stackH + 2 * LEAD + 2 * PAD);
101
+ const x = (W - (boxW + railSpace)) / 2;
102
+ const top = (H - stackH) / 2;
103
+ const boxes = Array.from({ length: n }, (_, i) => ({ x, y: top + i * (boxH + GAP), w: boxW, h: boxH }));
104
+ const railX = x + boxW + RAIL_GAP;
105
+ return { W, H, fs, lineH, maxLines, boxes, railX, railTop: top - LEAD, railBottom: top + stackH + LEAD, maxChars: Math.floor((boxW - 24) / (fs * CHAR)) };
106
+ }
107
+
108
+ /**
109
+ * Build a stack scene from its spec.
110
+ * @param {any} spec
111
+ * @param {{ format?: string | { name: string, width: number, height: number }, locale?: string }} [opts]
112
+ * @returns {Scene}
113
+ */
114
+ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
115
+ const name = `stack "${spec.id}"`;
116
+ const f = typeof format === "string" ? { name: format, ...FORMATS[format] } : format;
117
+ if (!f.width) throw new Error(`unknown format "${format}"`);
118
+ const layers = spec.layers;
119
+ if (!Array.isArray(layers)) throw new Error(`${name}: needs "layers", a list of { label }, top to bottom`);
120
+ const n = layers.length;
121
+ if (n < 2 || n > MAX_LAYERS) throw new Error(`${name}: needs 2–${MAX_LAYERS} layers, got ${n}`);
122
+ const direction = spec.direction ?? "down";
123
+ if (direction !== "down" && direction !== "up") throw new Error(`${name}: "direction" must be "down" or "up", got ${JSON.stringify(spec.direction)}`);
124
+ const labels = layers.map((l, i) => {
125
+ const label = localize(l?.label, locale);
126
+ if (!label) throw new Error(`${name}: layer ${i + 1} needs a "label"`);
127
+ return label;
128
+ });
129
+
130
+ // Largest font (≤ max) at which every label wraps; one line before two.
131
+ const maxFs = maxFontSize(spec, f.height > 0 ? 22 : 16, name);
132
+ let L;
133
+ let lines;
134
+ let why = "";
135
+ search: for (let fs = maxFs; fs >= FONT_MIN; fs--) {
136
+ for (const maxLines of [1, 2]) {
137
+ const cand = layout(f, n, fs, maxLines);
138
+ if ("problem" in cand) {
139
+ why = cand.problem ?? why;
140
+ continue;
141
+ }
142
+ try {
143
+ lines = labels.map((l) => wrapLabel(l, cand.maxChars, maxLines));
144
+ L = cand;
145
+ break search;
146
+ } catch (e) {
147
+ why = e instanceof Error ? e.message : String(e);
148
+ }
149
+ }
150
+ }
151
+ if (!L || !lines) throw new Error(`${name}: ${n} layers do not fit format ${f.name} at ≥ ${FONT_MIN}px (${why}); use fewer layers, shorter labels or a larger format`);
152
+ const fitted = L;
153
+ const wrapped = lines;
154
+
155
+ // Travel order: the packet visits layers top → bottom ("down") or bottom → top ("up").
156
+ const order = direction === "down" ? labels.map((_, i) => i) : labels.map((_, i) => n - 1 - i);
157
+ const visit = new Array(n); // layer index → position in the travel order
158
+ order.forEach((li, k) => (visit[li] = k));
159
+ const centerY = (li) => fitted.boxes[li].y + fitted.boxes[li].h / 2;
160
+ const entryY = direction === "down" ? fitted.railTop : fitted.railBottom;
161
+ const exitY = direction === "down" ? fitted.railBottom : fitted.railTop;
162
+ const stops = [entryY, ...order.map(centerY)];
163
+
164
+ // Rise bottom-up; then the packet appears at the entry and hops.
165
+ const riseAt = (li) => (n - 1 - li) * RISE_GAP;
166
+ const START = RISE_GAP * (n - 1) + RISE + 0.1;
167
+ const hopStart = (k) => START + APPEAR + 0.05 + k * PERIOD;
168
+ const fillStart = (k) => hopStart(k) + HOP;
169
+ const stepAt = (k) => fillStart(k) + FILL;
170
+ const duration = stepAt(n - 1) + TAIL;
171
+
172
+ function packetY(t) {
173
+ let y = stops[0];
174
+ for (let k = 0; k < n; k++) {
175
+ const p = progress(t, hopStart(k), HOP, easeStandard);
176
+ if (p <= 0) break;
177
+ y = lerp(stops[k], stops[k + 1], p);
178
+ }
179
+ return y;
180
+ }
181
+
182
+ const vline = (x, y0, y1, attrs) => el("path", { d: `M${num(x)} ${num(y0)} V${num(y1)}`, fill: "none", "stroke-linecap": "round", ...attrs });
183
+
184
+ /** @param {number} t @param {{style?: Style}} [ctx] */
185
+ function frame(t, { style = NEUTRAL } = {}) {
186
+ const out = [];
187
+ const { railX } = fitted;
188
+ // Rail: draws on from the entry end while the layers rise; an arrowhead marks the exit.
189
+ const railLen = Math.abs(exitY - entryY);
190
+ const railDash = drawOn(railLen, progress(t, 0.2, RAIL, easeStandard));
191
+ if (railDash) out.push(vline(railX, entryY, exitY, { stroke: tok("line"), "stroke-width": style.stroke, ...railDash }));
192
+ const head = progress(t, 0.2 + RAIL - 0.15, 0.2, easeOut);
193
+ if (head > 0) {
194
+ const s = direction === "down" ? -1 : 1;
195
+ out.push(el("path", { d: `M${num(railX - 6)} ${num(exitY + s * 9)} L${num(railX)} ${num(exitY)} L${num(railX + 6)} ${num(exitY + s * 9)}`, fill: "none", stroke: tok("line"), "stroke-width": style.stroke, "stroke-linecap": "round", "stroke-linejoin": "round", opacity: head }));
196
+ }
197
+ const y = packetY(t);
198
+ if (Math.abs(y - entryY) > 0.5) out.push(vline(railX, entryY, y, { stroke: tok("accent"), "stroke-width": style.stroke * 1.5 }));
199
+ fitted.boxes.forEach((b, li) => {
200
+ const enter = progress(t, riseAt(li), RISE, easeOut);
201
+ const k = visit[li];
202
+ const active = progress(t, fillStart(k), FILL, easeStandard);
203
+ // Once the packet moves on, the layer keeps an accent outline.
204
+ const passed = k < n - 1 ? progress(t, hopStart(k + 1), FILL, easeStandard) : 0;
205
+ // Tick from the layer to the rail: pending once the layer is in, accent once reached.
206
+ const cy = b.y + b.h / 2;
207
+ if (enter > 0) out.push(el("path", { d: `M${num(b.x + b.w + 4)} ${num(cy)} H${num(railX - 4)}`, stroke: tok("line"), "stroke-width": style.stroke, "stroke-linecap": "round", opacity: enter * (1 - active) }));
208
+ if (active > 0) out.push(el("path", { d: `M${num(b.x + b.w + 4)} ${num(cy)} H${num(railX - 4)}`, stroke: tok("accent"), "stroke-width": style.stroke * 1.5, "stroke-linecap": "round", opacity: active }));
209
+ out.push(layer(b, wrapped[li], fitted.fs, enter, active, passed, style));
210
+ });
211
+ // The packet: appears at the entry, then rides the rail.
212
+ const appear = progress(t, START, APPEAR, easeOut);
213
+ if (appear > 0) out.push(el("circle", { cx: railX, cy: y, r: DOT * (0.6 + 0.4 * appear), fill: tok("emphasis"), opacity: appear }));
214
+ return out.join("");
215
+ }
216
+
217
+ return {
218
+ id: `${spec.id}-${f.name.replace(":", "x")}`,
219
+ type: "stack",
220
+ format: f.name,
221
+ locale,
222
+ width: fitted.W,
223
+ height: fitted.H,
224
+ duration,
225
+ title: localize(spec.title, locale),
226
+ description: localize(spec.description, locale),
227
+ steps: order.map((li, k) => withId({ at: stepAt(k), label: labels[li], detail: localize(layers[li].detail, locale) }, layers[li].id)),
228
+ frame,
229
+ };
230
+ }