@liqweed/motion-kit 0.3.0 → 0.5.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 (46) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +63 -10
  4. package/adapters/astro/AnimatedDiagram.astro +150 -24
  5. package/adapters/element/README.md +6 -1
  6. package/adapters/element/motion-diagram.mjs +4 -3
  7. package/adapters/page/README.md +8 -2
  8. package/adapters/slidev/AnimatedDiagram.vue +24 -0
  9. package/cli/motion-kit.mjs +85 -81
  10. package/docs/spec/technique.md +166 -63
  11. package/examples/custom-pulse.scene.mjs +3 -0
  12. package/examples/incident.json +18 -0
  13. package/examples/web-stack.json +17 -0
  14. package/lib/build.mjs +26 -12
  15. package/lib/bundle.mjs +9 -2
  16. package/lib/check.mjs +219 -15
  17. package/lib/export.mjs +135 -16
  18. package/lib/gate.mjs +90 -0
  19. package/lib/load.mjs +49 -19
  20. package/package.json +6 -3
  21. package/runtime/bake.mjs +18 -4
  22. package/runtime/kit.mjs +59 -0
  23. package/runtime/links.mjs +314 -0
  24. package/runtime/page.mjs +52 -0
  25. package/runtime/parts.mjs +15 -0
  26. package/runtime/patch.mjs +297 -0
  27. package/runtime/player.mjs +334 -130
  28. package/runtime/scene.mjs +82 -5
  29. package/runtime/style.mjs +64 -16
  30. package/runtime/types/hub-spoke.mjs +7 -7
  31. package/runtime/types/index.mjs +4 -0
  32. package/runtime/types/sequence.mjs +5 -5
  33. package/runtime/types/stack.mjs +227 -0
  34. package/runtime/types/timeline.mjs +405 -0
  35. package/skills/animated-diagram/SKILL.md +30 -7
  36. package/skills/animated-diagram/references/custom-scenes.md +64 -9
  37. package/skills/animated-diagram/references/interactivity.md +150 -15
  38. package/skills/animated-diagram/references/qc.md +5 -2
  39. package/skills/animated-diagram/references/scene-types.md +45 -2
  40. package/skills/animated-diagram/references/styles.md +45 -5
  41. package/skills/animated-diagram/references/targets.md +7 -5
  42. package/skills/animated-diagram/references/technique.md +14 -4
  43. package/skills/motion-render/SKILL.md +31 -8
  44. package/skills/motion-render/references/formats.md +8 -8
  45. package/skills/project-logo/SKILL.md +15 -4
  46. package/styles/neutral.json +2 -2
@@ -2,7 +2,7 @@
2
2
  /**
3
3
  * motion-kit CLI.
4
4
  *
5
- * motion-kit check <scene...> [--format F] [--locale L] gate (all formats/locales by default)
5
+ * motion-kit check <scene...> [--format F]… [--locale L]… [--style S] gate (all formats/locales by default)
6
6
  * motion-kit build <scene> --out x.html [--format F] [--locale L] [--style S] [--no-scrubber] [--no-heading]
7
7
  * motion-kit export <scene> --out dir [--format F] [--locale L] [--style S] [--theme light|dark] [--png] [--scale 2] [--qc] [--background]
8
8
  * motion-kit bake <scene> --out x.svg [--fps 15] [--theme ...] [--style S]
@@ -10,8 +10,12 @@
10
10
  * motion-kit icon <scene> --out <repo> [--size 512] [--style S] [--no-png] project icon set (assets/, .idea/)
11
11
  * motion-kit vendor <dir> [--adapter page|slidev|astro|element]
12
12
  * motion-kit formats | types
13
+ * motion-kit --version print the version
13
14
  *
14
15
  * <scene> is a spec (.json, any registered type) or a custom module (.mjs).
16
+ * --options O passes scene options to a custom module's factory, unchanged:
17
+ * inline JSON ('{"view":"short"}'), a .json file, or an .mjs module whose
18
+ * default export is the options or ({ format, locale }) => options.
15
19
  */
16
20
  import { cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
17
21
  import { dirname, join, resolve } from "node:path";
@@ -19,13 +23,13 @@ import { fileURLToPath } from "node:url";
19
23
  import { parseArgs } from "node:util";
20
24
  import { bake, bakeStats } from "../runtime/bake.mjs";
21
25
  import { FORMATS } from "../runtime/scene.mjs";
22
- import { checkContrast } from "../runtime/style.mjs";
23
26
  import { SCENE_TYPES } from "../runtime/types/index.mjs";
24
27
  import { checkScene } from "../lib/check.mjs";
28
+ import { checkFiles } from "../lib/gate.mjs";
25
29
  import { buildHtml } from "../lib/build.mjs";
26
30
  import { writeIconSet } from "../lib/icon.mjs";
27
31
  import { exportSteps } from "../lib/export.mjs";
28
- import { loadScene, loadStyle } from "../lib/load.mjs";
32
+ import { isModule, loadOptions, loadScene, loadStyle } from "../lib/load.mjs";
29
33
  import { rasterizer } from "../lib/raster.mjs";
30
34
  import { probe, renderVideo, videoContactSheet } from "../lib/video.mjs";
31
35
 
@@ -36,9 +40,10 @@ const { values: a, positionals } = parseArgs({
36
40
  allowPositionals: true,
37
41
  options: {
38
42
  out: { type: "string", short: "o" },
39
- format: { type: "string", short: "f" },
40
- locale: { type: "string", short: "l" },
43
+ format: { type: "string", short: "f", multiple: true },
44
+ locale: { type: "string", short: "l", multiple: true },
41
45
  style: { type: "string", short: "s" },
46
+ options: { type: "string" },
42
47
  theme: { type: "string", default: "light" },
43
48
  png: { type: "boolean", default: false },
44
49
  scale: { type: "string", default: "2" },
@@ -53,6 +58,7 @@ const { values: a, positionals } = parseArgs({
53
58
  "no-scrubber": { type: "boolean", default: false },
54
59
  "no-heading": { type: "boolean", default: false },
55
60
  help: { type: "boolean", short: "h" },
61
+ version: { type: "boolean", short: "v" },
56
62
  },
57
63
  });
58
64
  const [cmd, ...args] = positionals;
@@ -67,13 +73,25 @@ function need(v, what) {
67
73
  }
68
74
 
69
75
  async function main() {
76
+ if (a.version) {
77
+ console.log(VERSION);
78
+ return;
79
+ }
70
80
  if (!cmd || a.help) {
71
81
  const src = readFileSync(fileURLToPath(import.meta.url), "utf8");
72
82
  console.log(src.slice(src.indexOf("/**") + 3, src.indexOf("*/")).replace(/^ \* ?/gm, ""));
73
83
  return;
74
84
  }
75
85
  const style = loadStyle(a.style);
76
- const opts = { format: a.format ?? "16:9", locale: a.locale ?? "en" };
86
+ // Commands other than check build one format and locale: the last one given.
87
+ const format = a.format?.at(-1);
88
+ const where = { format: format ?? "16:9", locale: a.locale?.at(-1) ?? "en" };
89
+ const optionsFor = await loadOptions(a.options);
90
+ /** Scene options for one scene file at `at`; specs take none. @param {string} file @param {{format: string, locale: string}} at */
91
+ const sceneOpts = async (file, at = where) => {
92
+ if (optionsFor && !isModule(file)) fail(`${cmd}: --options apply to custom scene modules, not to the spec ${file}`);
93
+ return { ...at, options: optionsFor ? await optionsFor(at) : undefined };
94
+ };
77
95
 
78
96
  switch (cmd) {
79
97
  case "formats":
@@ -84,38 +102,17 @@ async function main() {
84
102
  return;
85
103
  case "check": {
86
104
  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
- }
105
+ const bad = await checkFiles(args, { formats: a.format, locales: a.locale, style, options: optionsFor });
111
106
  if (bad) process.exit(1);
112
107
  return;
113
108
  }
114
109
  case "build": {
115
- const loaded = await loadScene(need(args[0], "<scene>"), opts);
116
- const r = checkScene(loaded.scene);
110
+ const file = need(args[0], "<scene>");
111
+ const sopts = await sceneOpts(file);
112
+ const loaded = await loadScene(file, sopts);
113
+ const r = checkScene(loaded.scene, { style });
117
114
  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"] });
115
+ const html = buildHtml(loaded, { style, ...where, options: sopts.options, scrubber: !a["no-scrubber"], heading: !a["no-heading"] });
119
116
  if (/<\/script/i.test(html.slice(html.indexOf("<script>") + 8, html.lastIndexOf("</script>")))) fail("bundled code contains </script>");
120
117
  const out = need(a.out, "--out");
121
118
  mkdirSync(dirname(resolve(out)), { recursive: true });
@@ -125,16 +122,29 @@ async function main() {
125
122
  }
126
123
  case "export": {
127
124
  const file = need(args[0], "<scene>");
128
- const { scene } = await loadScene(file, opts);
129
- const r = checkScene(scene);
125
+ const sopts = await sceneOpts(file);
126
+ const { scene } = await loadScene(file, sopts);
127
+ const r = checkScene(scene, { style });
130
128
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
131
129
  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 });
130
+ // The contact sheet's phone row shows the tall layout, as a phone does.
131
+ /** @type {{ scene?: any, error?: string }} */
132
+ const phone = {};
133
+ if (where.format === "tall") phone.scene = scene;
134
+ else {
135
+ try {
136
+ phone.scene = (await loadScene(file, await sceneOpts(file, { ...where, format: "tall" }))).scene;
137
+ } catch (e) {
138
+ phone.error = e instanceof Error ? e.message : String(e);
139
+ }
140
+ }
141
+ 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, phone, ...sopts });
133
142
  console.log(`wrote ${m.files.length} frames + index.html + manifest.json to ${a.out}`);
134
143
  return;
135
144
  }
136
145
  case "bake": {
137
- const { scene } = await loadScene(need(args[0], "<scene>"), opts);
146
+ const file = need(args[0], "<scene>");
147
+ const { scene } = await loadScene(file, await sceneOpts(file));
138
148
  const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
139
149
  const out = need(a.out, "--out");
140
150
  writeFileSync(out, svg);
@@ -143,7 +153,8 @@ async function main() {
143
153
  return;
144
154
  }
145
155
  case "video": {
146
- const { scene } = await loadScene(need(args[0], "<scene>"), opts);
156
+ const file = need(args[0], "<scene>");
157
+ const { scene } = await loadScene(file, await sceneOpts(file));
147
158
  const out = need(a.out, "--out");
148
159
  const r = await renderVideo(scene, {
149
160
  out,
@@ -161,8 +172,9 @@ async function main() {
161
172
  return;
162
173
  }
163
174
  case "icon": {
164
- const { scene } = await loadScene(need(args[0], "<scene>"), { ...opts, format: a.format ?? "1:1" });
165
- const r = checkScene(scene);
175
+ const file = need(args[0], "<scene>");
176
+ const { scene } = await loadScene(file, await sceneOpts(file, { ...where, format: format ?? "1:1" }));
177
+ const r = checkScene(scene, { style });
166
178
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
167
179
  const png = !a["no-png"];
168
180
  if (png && !(await rasterizer())) fail("icon PNG needs @resvg/resvg-js or Chrome (or pass --no-png)");
@@ -180,7 +192,7 @@ async function main() {
180
192
  const adapter = join(ROOT, "adapters", a.adapter);
181
193
  cpSync(adapter, join(dir, "adapter"), { recursive: true });
182
194
  mkdirSync(join(dir, "lib"), { recursive: true });
183
- cpSync(join(ROOT, "lib", "check.mjs"), join(dir, "lib", "check.mjs"));
195
+ for (const f of ["check.mjs", "gate.mjs", "load.mjs"]) cpSync(join(ROOT, "lib", f), join(dir, "lib", f));
184
196
  writeFileSync(join(dir, "check.mjs"), VENDOR_CHECK);
185
197
  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
198
  console.log(`vendored runtime + ${a.adapter} adapter (motion-kit ${VERSION}) into ${dir}`);
@@ -192,48 +204,40 @@ async function main() {
192
204
  }
193
205
 
194
206
  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";
207
+ // motion-kit gate for vendored copies: the same checks as \`motion-kit check\` (lib/gate.mjs).
208
+ //
209
+ // node check.mjs <scene.json|scene.mjs …> [--format F]… [--locale L]… [--style style.json] [--options O]
210
+ //
211
+ // 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
213
+ // pass the contrast check. --options passes scene options to custom modules:
214
+ // a .json file, inline JSON, or an .mjs module exporting ({ format, locale }) => options.
215
+ // Exits 1 if anything fails; a file that cannot be loaded fails on its own.
216
+ import { parseArgs } from "node:util";
217
+ import { checkFiles } from "./lib/gate.mjs";
218
+ import { loadOptions, loadStyle } from "./lib/load.mjs";
201
219
 
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
- }
220
+ const { values, positionals } = parseArgs({
221
+ allowPositionals: true,
222
+ options: {
223
+ format: { type: "string", multiple: true },
224
+ locale: { type: "string", multiple: true },
225
+ style: { type: "string" },
226
+ options: { type: "string" },
227
+ help: { type: "boolean", short: "h" },
228
+ },
229
+ });
230
+ if (values.help || !positionals.length) {
231
+ console.log("usage: node check.mjs <scene.json|scene.mjs …> [--format F]… [--locale L]… [--style style.json] [--options O]");
232
+ process.exit(values.help ? 0 : 1);
222
233
  }
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"];
234
+ try {
235
+ const bad = await checkFiles(positionals, { formats: values.format, locales: values.locale, style: loadStyle(values.style), options: await loadOptions(values.options) });
236
+ process.exit(bad ? 1 : 0);
237
+ } catch (e) {
238
+ console.error(\`✗ \${e instanceof Error ? e.message : e}\`);
239
+ process.exit(1);
237
240
  }
241
+ `;
238
242
 
239
243
  main().catch((e) => fail(e.stack ?? e.message));