@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,115 @@
1
+ /**
2
+ * motion-kit logo: the standard easing curve, cubic-bezier(0.4, 0, 0.2, 1),
3
+ * drawn as a design tool shows it — two keyframes, their handles, and the path
4
+ * between them — on a rounded accent tile. It animates as motion-kit animates
5
+ * anything: the tile settles, the handles appear, the curve draws on, a packet
6
+ * runs the curve and the end keyframe lands.
7
+ *
8
+ * The final frame is the static mark. Square and readable down to ~32 px.
9
+ *
10
+ * node cli/motion-kit.mjs icon brand/logo.scene.mjs -o . (or: npm run media)
11
+ *
12
+ * Also the template the project-logo skill starts from for other projects:
13
+ * it takes the runtime from `kit` (passed by motion-kit's CLI) instead of
14
+ * importing it, so a copy works from any repository without vendoring.
15
+ */
16
+
17
+ const S = 720; // square viewBox; every format renders the same square mark
18
+ const TILE = { inset: 40, radius: 168 };
19
+ // Curve box: keyframe A bottom-left, keyframe B top-right (y grows downward).
20
+ const BOX = { x0: 196, y0: 524, x1: 524, y1: 196 };
21
+ const map = (u, v) => ({ x: BOX.x0 + u * (BOX.x1 - BOX.x0), y: BOX.y0 + v * (BOX.y1 - BOX.y0) });
22
+ const A = map(0, 0);
23
+ const B = map(1, 1);
24
+ const H1 = map(0.4, 0); // handle out of A (x1, y1)
25
+ const H2 = map(0.2, 1); // handle into B (x2, y2)
26
+
27
+ const STROKE = 30;
28
+ const DOT = 40;
29
+ const HANDLE = 9;
30
+ const KNOB = 26;
31
+
32
+ const T_TILE = 0;
33
+ const T_HANDLES = 0.35;
34
+ const T_DRAW = 0.6;
35
+ const DRAW = 0.9;
36
+ const T_PACKET = T_DRAW + DRAW + 0.05;
37
+ const TRAVEL = 0.8;
38
+ const LAG = 0.12;
39
+ const T_LAND = T_PACKET + TRAVEL + LAG;
40
+ const OMEGA = 16; // settles in 9.24 / 16 ≈ 0.58 s
41
+ const DURATION = T_LAND + 0.65;
42
+
43
+ /** @param {{kit: any}} opts */
44
+ export default function make({ kit }) {
45
+ const { easeOut, easeStandard, progress, splitEdge, springTo, tok, cubic, drawOn, el, fade, num, scaleAbout } = kit;
46
+ const CURVE = cubic(A, H1, H2, B);
47
+
48
+ function frame(t) {
49
+ const out = [];
50
+ // Tile: springs from 0.86 to full size while fading in.
51
+ const grow = springTo(t, 0.86, [{ at: T_TILE, to: 1 }], OMEGA);
52
+ const tileIn = progress(t, T_TILE, 0.3, easeOut);
53
+ out.push(
54
+ fade(
55
+ tileIn,
56
+ { transform: grow < 0.9995 ? scaleAbout(grow, S / 2, S / 2) : undefined },
57
+ el("rect", {
58
+ x: TILE.inset,
59
+ y: TILE.inset,
60
+ width: S - 2 * TILE.inset,
61
+ height: S - 2 * TILE.inset,
62
+ rx: TILE.radius,
63
+ fill: tok("accent"),
64
+ }),
65
+ ),
66
+ );
67
+
68
+ // Bézier handles: thin lines with square knobs.
69
+ const handles = progress(t, T_HANDLES, 0.35, easeOut);
70
+ const handle = (from, to) =>
71
+ el(
72
+ "g",
73
+ {},
74
+ el("line", { x1: num(from.x), y1: num(from.y), x2: num(to.x), y2: num(to.y), stroke: tok("onAccent"), "stroke-width": HANDLE, "stroke-linecap": "round" }),
75
+ el("rect", { x: num(to.x - KNOB / 2), y: num(to.y - KNOB / 2), width: KNOB, height: KNOB, rx: 5, fill: tok("onAccent") }),
76
+ );
77
+ out.push(fade(handles * 0.55, {}, handle(A, H1), handle(B, H2)));
78
+
79
+ // The curve draws on.
80
+ const dash = drawOn(CURVE.length, progress(t, T_DRAW, DRAW, easeStandard));
81
+ if (dash) out.push(el("path", { d: CURVE.d, fill: "none", stroke: tok("onAccent"), "stroke-width": STROKE, "stroke-linecap": "round", ...dash }));
82
+
83
+ // Start keyframe: a ring that appears with the handles.
84
+ out.push(
85
+ fade(handles, {}, el("circle", { cx: A.x, cy: A.y, r: DOT, fill: tok("accent"), stroke: tok("onAccent"), "stroke-width": 14 })),
86
+ );
87
+
88
+ // Packet: a capsule that stretches as it runs the curve (split edges).
89
+ const { lead, trail } = splitEdge(t, T_PACKET, TRAVEL, LAG);
90
+ if (lead > 0 && trail < 1) {
91
+ const a = CURVE.at(trail);
92
+ const b = CURVE.at(lead);
93
+ out.push(el("line", { x1: num(a.x), y1: num(a.y), x2: num(b.x), y2: num(b.y), stroke: tok("emphasis"), "stroke-width": STROKE + 6, "stroke-linecap": "round" }));
94
+ }
95
+
96
+ // End keyframe lands in the emphasis colour with a spring pop.
97
+ if (t >= T_LAND) {
98
+ const pop = springTo(t, 0.4, [{ at: T_LAND, to: 1 }], OMEGA);
99
+ out.push(el("circle", { cx: B.x, cy: B.y, r: num(DOT * pop), fill: tok("emphasis"), stroke: tok("onAccent"), "stroke-width": 14 }));
100
+ }
101
+ return out.join("");
102
+ }
103
+
104
+ return {
105
+ id: "motion-kit-logo",
106
+ width: S,
107
+ height: S,
108
+ duration: DURATION,
109
+ title: "motion-kit",
110
+ description: "An easing curve between two keyframes on a blue tile: the motion-kit logo.",
111
+ stepLabelsInFrame: false,
112
+ steps: [{ at: DURATION, label: "Logo" }],
113
+ frame,
114
+ };
115
+ }
@@ -0,0 +1,239 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * motion-kit CLI.
4
+ *
5
+ * motion-kit check <scene...> [--format F] [--locale L] gate (all formats/locales by default)
6
+ * motion-kit build <scene> --out x.html [--format F] [--locale L] [--style S] [--no-scrubber] [--no-heading]
7
+ * motion-kit export <scene> --out dir [--format F] [--locale L] [--style S] [--theme light|dark] [--png] [--scale 2] [--qc] [--background]
8
+ * motion-kit bake <scene> --out x.svg [--fps 15] [--theme ...] [--style S]
9
+ * motion-kit video <scene> --out x.mp4|.gif|.webm [--fps 30] [--scale 2] [--hold 1.5] [--sheet sheet.png]
10
+ * motion-kit icon <scene> --out <repo> [--size 512] [--style S] [--no-png] project icon set (assets/, .idea/)
11
+ * motion-kit vendor <dir> [--adapter page|slidev|astro|element]
12
+ * motion-kit formats | types
13
+ *
14
+ * <scene> is a spec (.json, any registered type) or a custom module (.mjs).
15
+ */
16
+ import { cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
17
+ import { dirname, join, resolve } from "node:path";
18
+ import { fileURLToPath } from "node:url";
19
+ import { parseArgs } from "node:util";
20
+ import { bake, bakeStats } from "../runtime/bake.mjs";
21
+ import { FORMATS } from "../runtime/scene.mjs";
22
+ import { checkContrast } from "../runtime/style.mjs";
23
+ import { SCENE_TYPES } from "../runtime/types/index.mjs";
24
+ import { checkScene } from "../lib/check.mjs";
25
+ import { buildHtml } from "../lib/build.mjs";
26
+ import { writeIconSet } from "../lib/icon.mjs";
27
+ import { exportSteps } from "../lib/export.mjs";
28
+ import { loadScene, loadStyle } from "../lib/load.mjs";
29
+ import { rasterizer } from "../lib/raster.mjs";
30
+ import { probe, renderVideo, videoContactSheet } from "../lib/video.mjs";
31
+
32
+ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
33
+ const VERSION = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
34
+
35
+ const { values: a, positionals } = parseArgs({
36
+ allowPositionals: true,
37
+ options: {
38
+ out: { type: "string", short: "o" },
39
+ format: { type: "string", short: "f" },
40
+ locale: { type: "string", short: "l" },
41
+ style: { type: "string", short: "s" },
42
+ theme: { type: "string", default: "light" },
43
+ png: { type: "boolean", default: false },
44
+ scale: { type: "string", default: "2" },
45
+ qc: { type: "boolean", default: false },
46
+ background: { type: "boolean", default: false },
47
+ fps: { type: "string" },
48
+ hold: { type: "string", default: "1.5" },
49
+ sheet: { type: "string" },
50
+ adapter: { type: "string", default: "page" },
51
+ size: { type: "string", default: "512" },
52
+ "no-png": { type: "boolean", default: false },
53
+ "no-scrubber": { type: "boolean", default: false },
54
+ "no-heading": { type: "boolean", default: false },
55
+ help: { type: "boolean", short: "h" },
56
+ },
57
+ });
58
+ const [cmd, ...args] = positionals;
59
+
60
+ function fail(msg) {
61
+ console.error(`motion-kit: ${msg}`);
62
+ process.exit(1);
63
+ }
64
+ function need(v, what) {
65
+ if (!v) fail(`${cmd}: ${what} is required`);
66
+ return v;
67
+ }
68
+
69
+ async function main() {
70
+ if (!cmd || a.help) {
71
+ const src = readFileSync(fileURLToPath(import.meta.url), "utf8");
72
+ console.log(src.slice(src.indexOf("/**") + 3, src.indexOf("*/")).replace(/^ \* ?/gm, ""));
73
+ return;
74
+ }
75
+ const style = loadStyle(a.style);
76
+ const opts = { format: a.format ?? "16:9", locale: a.locale ?? "en" };
77
+
78
+ switch (cmd) {
79
+ case "formats":
80
+ for (const [k, v] of Object.entries(FORMATS)) console.log(`${k.padEnd(6)} ${v.width}×${v.height || "auto"}`);
81
+ return;
82
+ case "types":
83
+ console.log(Object.keys(SCENE_TYPES).join("\n"));
84
+ return;
85
+ case "check": {
86
+ if (!args.length) fail("check: give at least one scene file");
87
+ const styleProblems = checkContrast(style);
88
+ for (const p of styleProblems) console.error(`✗ style: ${p}`);
89
+ let bad = styleProblems.length;
90
+ for (const file of args) {
91
+ const formats = a.format ? [a.format] : Object.keys(FORMATS);
92
+ const raw = file.endsWith(".json") ? JSON.parse(readFileSync(file, "utf8")) : null;
93
+ const locales = a.locale ? [a.locale] : raw ? detectLocales(raw) : ["en"];
94
+ for (const format of formats) {
95
+ for (const locale of locales) {
96
+ try {
97
+ const { scene } = await loadScene(file, { format, locale });
98
+ const r = checkScene(scene);
99
+ if (r.ok) console.log(`✓ ${file} · ${format} · ${locale} · ${scene.duration.toFixed(2)} s · ${scene.steps.length} steps`);
100
+ else {
101
+ bad++;
102
+ console.error(`✗ ${file} · ${format} · ${locale}\n - ${r.problems.join("\n - ")}`);
103
+ }
104
+ } catch (e) {
105
+ bad++;
106
+ console.error(`✗ ${file} · ${format} · ${locale}: ${e instanceof Error ? e.message : e}`);
107
+ }
108
+ }
109
+ }
110
+ }
111
+ if (bad) process.exit(1);
112
+ return;
113
+ }
114
+ case "build": {
115
+ const loaded = await loadScene(need(args[0], "<scene>"), opts);
116
+ const r = checkScene(loaded.scene);
117
+ if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
118
+ const html = buildHtml(loaded, { style, ...opts, scrubber: !a["no-scrubber"], heading: !a["no-heading"] });
119
+ if (/<\/script/i.test(html.slice(html.indexOf("<script>") + 8, html.lastIndexOf("</script>")))) fail("bundled code contains </script>");
120
+ const out = need(a.out, "--out");
121
+ mkdirSync(dirname(resolve(out)), { recursive: true });
122
+ writeFileSync(out, html);
123
+ console.log(`wrote ${out} (${(html.length / 1024).toFixed(1)} KB, self-contained)`);
124
+ return;
125
+ }
126
+ case "export": {
127
+ const file = need(args[0], "<scene>");
128
+ const { scene } = await loadScene(file, opts);
129
+ const r = checkScene(scene);
130
+ if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
131
+ if (a.png && !(await rasterizer())) fail("--png needs @resvg/resvg-js or Chrome");
132
+ const m = await exportSteps(scene, { out: need(a.out, "--out"), style, theme: a.theme, png: a.png, scale: Number(a.scale), qc: a.qc, background: a.background, sourceFile: resolve(file), version: VERSION });
133
+ console.log(`wrote ${m.files.length} frames + index.html + manifest.json to ${a.out}`);
134
+ return;
135
+ }
136
+ case "bake": {
137
+ const { scene } = await loadScene(need(args[0], "<scene>"), opts);
138
+ const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
139
+ const out = need(a.out, "--out");
140
+ writeFileSync(out, svg);
141
+ const s = bakeStats(svg);
142
+ console.log(`wrote ${out} (${s.frames} frames, ${(s.bytes / 1024).toFixed(0)} KB, zero JS)`);
143
+ return;
144
+ }
145
+ case "video": {
146
+ const { scene } = await loadScene(need(args[0], "<scene>"), opts);
147
+ const out = need(a.out, "--out");
148
+ const r = await renderVideo(scene, {
149
+ out,
150
+ fps: Number(a.fps ?? 30),
151
+ scale: Number(a.scale),
152
+ hold: Number(a.hold),
153
+ style,
154
+ theme: a.theme,
155
+ onProgress: (f, n) => process.stderr.write(`\rframe ${f}/${n}`),
156
+ });
157
+ process.stderr.write("\n");
158
+ const p = probe(out);
159
+ console.log(`wrote ${out}: ${p.width}×${p.height}, ${p.duration.toFixed(2)} s, ${p.fps} fps (${r.frames} frames)`);
160
+ if (a.sheet) console.log(`contact sheet: ${videoContactSheet(out, a.sheet)}`);
161
+ return;
162
+ }
163
+ case "icon": {
164
+ const { scene } = await loadScene(need(args[0], "<scene>"), { ...opts, format: a.format ?? "1:1" });
165
+ const r = checkScene(scene);
166
+ if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
167
+ const png = !a["no-png"];
168
+ if (png && !(await rasterizer())) fail("icon PNG needs @resvg/resvg-js or Chrome (or pass --no-png)");
169
+ const root = resolve(need(a.out, "--out"));
170
+ const files = await writeIconSet(scene, { root, style, size: Number(a.size), png });
171
+ console.log(`wrote to ${root}:\n ${files.join("\n ")}`);
172
+ 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");
173
+ return;
174
+ }
175
+ case "vendor": {
176
+ const dir = resolve(need(args[0], "<dir>"));
177
+ mkdirSync(dir, { recursive: true });
178
+ cpSync(join(ROOT, "LICENSE"), join(dir, "LICENSE"));
179
+ cpSync(join(ROOT, "runtime"), join(dir, "runtime"), { recursive: true });
180
+ const adapter = join(ROOT, "adapters", a.adapter);
181
+ cpSync(adapter, join(dir, "adapter"), { recursive: true });
182
+ mkdirSync(join(dir, "lib"), { recursive: true });
183
+ cpSync(join(ROOT, "lib", "check.mjs"), join(dir, "lib", "check.mjs"));
184
+ writeFileSync(join(dir, "check.mjs"), VENDOR_CHECK);
185
+ writeFileSync(join(dir, "MOTION_KIT_VERSION"), `motion-kit ${VERSION}\nadapter ${a.adapter}\nvendored from liqweed/motion-kit; do not edit here, re-vendor instead.\n`);
186
+ console.log(`vendored runtime + ${a.adapter} adapter (motion-kit ${VERSION}) into ${dir}`);
187
+ return;
188
+ }
189
+ default:
190
+ fail(`unknown command "${cmd}" (try --help)`);
191
+ }
192
+ }
193
+
194
+ const VENDOR_CHECK = `#!/usr/bin/env node
195
+ // motion-kit gate for vendored copies: node check.mjs <spec.json...> [--format F]
196
+ // Checks every listed spec in every format (or --format) and every locale it contains.
197
+ import { readFileSync } from "node:fs";
198
+ import { checkScene } from "./lib/check.mjs";
199
+ import { FORMATS } from "./runtime/scene.mjs";
200
+ import { createScene } from "./runtime/types/index.mjs";
201
+
202
+ const args = process.argv.slice(2);
203
+ const fi = args.indexOf("--format");
204
+ const formats = fi >= 0 ? [args.splice(fi, 2)[1]] : Object.keys(FORMATS);
205
+ let bad = 0;
206
+ for (const file of args) {
207
+ const spec = JSON.parse(readFileSync(file, "utf8"));
208
+ const locales = new Set();
209
+ JSON.stringify(spec, (k, v) => {
210
+ if (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length && Object.keys(v).every((x) => /^[a-z]{2}$/.test(x))) Object.keys(v).forEach((l) => locales.add(l));
211
+ return v;
212
+ });
213
+ for (const format of formats) {
214
+ for (const locale of locales.size ? locales : ["en"]) {
215
+ try {
216
+ const r = checkScene(createScene(spec, { format, locale }));
217
+ if (r.ok) console.log(\`✓ \${file} · \${format} · \${locale}\`);
218
+ else { bad++; console.error(\`✗ \${file} · \${format} · \${locale}\\n - \${r.problems.join("\\n - ")}\`); }
219
+ } catch (e) { bad++; console.error(\`✗ \${file} · \${format} · \${locale}: \${e.message}\`); }
220
+ }
221
+ }
222
+ }
223
+ process.exit(bad ? 1 : 0);
224
+ `;
225
+
226
+ function detectLocales(spec) {
227
+ const found = new Set();
228
+ const walk = (v) => {
229
+ if (v && typeof v === "object" && !Array.isArray(v)) {
230
+ const keys = Object.keys(v);
231
+ if (keys.length && keys.every((k) => /^[a-z]{2}(-[A-Z]{2})?$/.test(k) && typeof v[k] === "string")) keys.forEach((k) => found.add(k));
232
+ else Object.values(v).forEach(walk);
233
+ } else if (Array.isArray(v)) v.forEach(walk);
234
+ };
235
+ walk(spec);
236
+ return found.size ? [...found] : ["en"];
237
+ }
238
+
239
+ main().catch((e) => fail(e.stack ?? e.message));