@liqweed/motion-kit 0.0.0-stage → 0.2.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 +13 -0
- package/.claude-plugin/plugin.json +9 -0
- package/LICENSE +21 -0
- package/README.md +119 -2
- package/adapters/astro/AnimatedDiagram.astro +55 -0
- package/adapters/page/README.md +22 -0
- package/adapters/slidev/AnimatedDiagram.vue +137 -0
- package/brand/logo.scene.mjs +115 -0
- package/cli/motion-kit.mjs +239 -0
- package/docs/spec/technique.md +447 -0
- package/examples/agent-loop.json +18 -0
- package/examples/custom-pulse.scene.mjs +141 -0
- package/examples/integrations.json +20 -0
- package/examples/order-flow.json +17 -0
- package/examples/release-pipeline.json +17 -0
- package/examples/smart-home.json +17 -0
- package/lib/build.mjs +62 -0
- package/lib/bundle.mjs +68 -0
- package/lib/check.mjs +86 -0
- package/lib/export.mjs +113 -0
- package/lib/icon.mjs +41 -0
- package/lib/load.mjs +53 -0
- package/lib/raster.mjs +69 -0
- package/lib/video.mjs +77 -0
- package/package.json +69 -5
- package/runtime/bake.mjs +61 -0
- package/runtime/motion.mjs +154 -0
- package/runtime/parts.mjs +123 -0
- package/runtime/player.mjs +207 -0
- package/runtime/scene.mjs +101 -0
- package/runtime/style.mjs +142 -0
- package/runtime/svg.mjs +165 -0
- package/runtime/types/hub-spoke.mjs +215 -0
- package/runtime/types/index.mjs +25 -0
- package/runtime/types/sequence.mjs +201 -0
- package/runtime/wrap.mjs +44 -0
- package/skills/animated-diagram/SKILL.md +90 -0
- package/skills/animated-diagram/references/custom-scenes.md +56 -0
- package/skills/animated-diagram/references/ecosystem.md +28 -0
- package/skills/animated-diagram/references/interactivity.md +38 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +70 -0
- package/skills/animated-diagram/references/qc.md +41 -0
- package/skills/animated-diagram/references/scene-types.md +59 -0
- package/skills/animated-diagram/references/styles.md +55 -0
- package/skills/animated-diagram/references/targets.md +27 -0
- package/skills/animated-diagram/references/technique.md +148 -0
- package/skills/motion-render/SKILL.md +68 -0
- package/skills/motion-render/references/formats.md +18 -0
- package/skills/motion-render/references/slides.md +18 -0
- package/skills/motion-render/references/video.md +61 -0
- package/skills/project-logo/SKILL.md +72 -0
- package/skills/project-logo/references/design.md +22 -0
- package/skills/project-logo/references/discovery.md +15 -0
- package/skills/project-logo/references/external-prompt.md +23 -0
- package/styles/neutral.json +26 -0
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"type": "sequence",
|
|
3
|
+
"id": "order-flow",
|
|
4
|
+
"title": { "en": "How an order reaches the customer", "nl": "Hoe een bestelling bij de klant komt" },
|
|
5
|
+
"description": {
|
|
6
|
+
"en": "Six stages in order: order, payment, pick and pack, ship, deliver and follow up.",
|
|
7
|
+
"nl": "Zes stappen op volgorde: bestelling, betaling, verzamelen en inpakken, verzenden, bezorgen en opvolgen."
|
|
8
|
+
},
|
|
9
|
+
"nodes": [
|
|
10
|
+
{ "label": { "en": "Order", "nl": "Bestelling" }, "detail": { "en": "The customer places an order.", "nl": "De klant plaatst een bestelling." } },
|
|
11
|
+
{ "label": { "en": "Payment", "nl": "Betaling" }, "detail": { "en": "Payment is confirmed.", "nl": "De betaling wordt bevestigd." } },
|
|
12
|
+
{ "label": { "en": "Pick / Pack", "nl": "Verzamelen / Inpakken" }, "detail": { "en": "Items are collected and packed.", "nl": "Artikelen worden verzameld en ingepakt." } },
|
|
13
|
+
{ "label": { "en": "Ship", "nl": "Verzenden" }, "detail": { "en": "The parcel leaves the warehouse.", "nl": "Het pakket verlaat het magazijn." } },
|
|
14
|
+
{ "label": { "en": "Deliver", "nl": "Bezorgen" }, "detail": { "en": "The carrier delivers the parcel.", "nl": "De vervoerder bezorgt het pakket." } },
|
|
15
|
+
{ "label": { "en": "Follow up", "nl": "Opvolgen" }, "detail": { "en": "The customer is asked for feedback.", "nl": "De klant wordt om feedback gevraagd." } }
|
|
16
|
+
]
|
|
17
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"type": "sequence",
|
|
3
|
+
"id": "release-pipeline",
|
|
4
|
+
"title": { "en": "From commit to published media", "nl": "Van commit tot gepubliceerde media" },
|
|
5
|
+
"description": {
|
|
6
|
+
"en": "Five stages: commit, test, gate, bake and publish. Unchanged inputs give byte-identical files.",
|
|
7
|
+
"nl": "Vijf stappen: commit, test, gate, bakken en publiceren. Ongewijzigde invoer geeft identieke bestanden."
|
|
8
|
+
},
|
|
9
|
+
"nodes": [
|
|
10
|
+
{ "label": { "en": "Commit", "nl": "Commit" }, "detail": { "en": "Someone changes a spec, a label or a custom scene.", "nl": "Iemand wijzigt een spec, een label of een eigen scène." } },
|
|
11
|
+
{ "label": { "en": "Test", "nl": "Test" }, "detail": { "en": "Unit tests run first, including browser-versus-Node byte equality.", "nl": "Eerst draaien de unittests, ook de bytevergelijking tussen browser en Node." } },
|
|
12
|
+
{ "label": { "en": "Gate", "nl": "Poort" }, "detail": { "en": "Every example is built in every format and locale and sampled 121 times.", "nl": "Elk voorbeeld wordt in elk formaat en elke taal gebouwd en 121 keer bemonsterd." } },
|
|
13
|
+
{ "label": { "en": "Bake", "nl": "Bakken" }, "detail": { "en": "README animations and the logo are regenerated, never edited by hand.", "nl": "README-animaties en het logo worden opnieuw gegenereerd, nooit met de hand bewerkt." } },
|
|
14
|
+
{ "label": { "en": "Publish", "nl": "Publiceren" }, "detail": { "en": "A diff in the media folder means something really changed.", "nl": "Een verschil in de mediamap betekent dat er echt iets veranderd is." } }
|
|
15
|
+
],
|
|
16
|
+
"glyphs": "numbers"
|
|
17
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"type": "hub-spoke",
|
|
3
|
+
"id": "smart-home",
|
|
4
|
+
"title": { "en": "One hub for every device in the house", "nl": "Eén hub voor elk apparaat in huis" },
|
|
5
|
+
"description": {
|
|
6
|
+
"en": "A central hub talks to five kinds of devices, one link at a time.",
|
|
7
|
+
"nl": "Een centrale hub praat met vijf soorten apparaten, één koppeling tegelijk."
|
|
8
|
+
},
|
|
9
|
+
"hub": { "label": { "en": "Home hub", "nl": "Thuishub" }, "detail": { "en": "Automations run here, locally.", "nl": "Automatiseringen draaien hier, lokaal." } },
|
|
10
|
+
"spokes": [
|
|
11
|
+
{ "label": { "en": "Lights", "nl": "Verlichting" }, "detail": { "en": "Scenes follow the time of day.", "nl": "Scènes volgen het tijdstip." } },
|
|
12
|
+
{ "label": { "en": "Door locks", "nl": "Deursloten" }, "detail": { "en": "Locks report state and battery.", "nl": "Sloten melden status en batterij." } },
|
|
13
|
+
{ "label": { "en": "Heating", "nl": "Verwarming" }, "detail": { "en": "Rooms heat when someone is home.", "nl": "Kamers warmen op als er iemand thuis is." } },
|
|
14
|
+
{ "label": { "en": "Smoke alarms", "nl": "Rookmelders" }, "detail": { "en": "An alarm reaches every phone.", "nl": "Een alarm bereikt elke telefoon." } },
|
|
15
|
+
{ "label": { "en": "Phones", "nl": "Telefoons" }, "detail": { "en": "Presence comes from the phones.", "nl": "Aanwezigheid komt van de telefoons." } }
|
|
16
|
+
]
|
|
17
|
+
}
|
package/lib/build.mjs
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* motion-kit · build a self-contained interactive HTML file.
|
|
3
|
+
*
|
|
4
|
+
* One document, runtime inlined, no network requests: safe for Craft Pages
|
|
5
|
+
* (connect-src 'none'), file:// and any static host. The final frame is
|
|
6
|
+
* pre-rendered into the markup, so it reads correctly before (or without) JS.
|
|
7
|
+
*/
|
|
8
|
+
import { fileURLToPath } from "node:url";
|
|
9
|
+
import { bundle } from "./bundle.mjs";
|
|
10
|
+
import { escapeHtml } from "./export.mjs";
|
|
11
|
+
import { renderSvg } from "../runtime/scene.mjs";
|
|
12
|
+
import { cssVars } from "../runtime/style.mjs";
|
|
13
|
+
|
|
14
|
+
const RUNTIME = fileURLToPath(new URL("../runtime/", import.meta.url));
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* @param {import("./load.mjs").LoadedScene} loaded
|
|
18
|
+
* @param {{style:import("../runtime/style.mjs").Style, format:string, locale:string, scrubber?:boolean, heading?:boolean, theme?:string, labels?:Record<string,string>}} o
|
|
19
|
+
*/
|
|
20
|
+
export function buildHtml(loaded, o) {
|
|
21
|
+
const entries = [`${RUNTIME}types/index.mjs`, `${RUNTIME}scene.mjs`, `${RUNTIME}player.mjs`];
|
|
22
|
+
if (loaded.kind === "module") entries.push(loaded.file);
|
|
23
|
+
const code = bundle(entries);
|
|
24
|
+
const { scene } = loaded;
|
|
25
|
+
const fallback = renderSvg(scene, scene.duration, { style: o.style, live: true, idPrefix: "mk-fallback" });
|
|
26
|
+
const make =
|
|
27
|
+
loaded.kind === "spec"
|
|
28
|
+
? `MotionKit.createScene(${JSON.stringify(loaded.spec)}, ${JSON.stringify({ format: o.format, locale: o.locale })})`
|
|
29
|
+
: `MotionKit.default(${JSON.stringify({ format: o.format, locale: o.locale })})`;
|
|
30
|
+
const options = { style: o.style, scrubber: o.scrubber !== false, theme: o.theme, labels: o.labels };
|
|
31
|
+
const lang = scene.locale ?? o.locale ?? "en";
|
|
32
|
+
return `<!doctype html>
|
|
33
|
+
<html lang="${escapeHtml(lang)}">
|
|
34
|
+
<head>
|
|
35
|
+
<meta charset="utf-8">
|
|
36
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
37
|
+
<title>${escapeHtml(scene.title)}</title>
|
|
38
|
+
<style>
|
|
39
|
+
:root{${cssVars(o.style, "light")}}
|
|
40
|
+
@media (prefers-color-scheme: dark){:root{${cssVars(o.style, "dark")}}}
|
|
41
|
+
body{margin:0;padding:24px;background:var(--mk-bg);color:var(--mk-ink);font-family:${o.style.font}}
|
|
42
|
+
main{max-width:${Math.max(scene.width, 360)}px;margin:0 auto}
|
|
43
|
+
h1{font-size:20px;line-height:1.3;margin:0 0 4px}
|
|
44
|
+
.lede{margin:0 0 16px;color:var(--mk-muted);font-size:15px;line-height:1.45}
|
|
45
|
+
</style>
|
|
46
|
+
</head>
|
|
47
|
+
<body>
|
|
48
|
+
<main>
|
|
49
|
+
${o.heading === false ? "" : `<h1>${escapeHtml(scene.title)}</h1>\n<p class="lede">${escapeHtml(scene.description)}</p>`}
|
|
50
|
+
<div id="mk">${fallback}</div>
|
|
51
|
+
</main>
|
|
52
|
+
<script>
|
|
53
|
+
${code}
|
|
54
|
+
(function () {
|
|
55
|
+
var scene = ${make};
|
|
56
|
+
MotionKit.mountPlayer(document.getElementById("mk"), scene, ${JSON.stringify(options)});
|
|
57
|
+
})();
|
|
58
|
+
</script>
|
|
59
|
+
</body>
|
|
60
|
+
</html>
|
|
61
|
+
`;
|
|
62
|
+
}
|
package/lib/bundle.mjs
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* motion-kit · tiny module inliner (Node side).
|
|
3
|
+
*
|
|
4
|
+
* Turns runtime ES modules (plus an optional custom scene module) into one
|
|
5
|
+
* classic <script> body with no imports, so the output works where only inline
|
|
6
|
+
* scripts are allowed (Craft Pages: connect-src 'none'; plain file:// HTML).
|
|
7
|
+
*
|
|
8
|
+
* Supported subset (enforced, throws otherwise): single-line
|
|
9
|
+
* import { a, b as c } from "./relative.mjs";
|
|
10
|
+
* and top-level `export function|const|let|class NAME`, `export { a, b }`,
|
|
11
|
+
* `export default <expr|function>`. Each module gets its own scope.
|
|
12
|
+
*/
|
|
13
|
+
import { readFileSync } from "node:fs";
|
|
14
|
+
import { dirname, resolve } from "node:path";
|
|
15
|
+
|
|
16
|
+
const IMPORT_RE = /^import\s*\{([^}]*)\}\s*from\s*["'](\.{1,2}\/[^"']+)["'];?\s*$/;
|
|
17
|
+
|
|
18
|
+
export function bundle(entries, { globalName = "MotionKit" } = {}) {
|
|
19
|
+
const order = [];
|
|
20
|
+
const seen = new Map();
|
|
21
|
+
function visit(file) {
|
|
22
|
+
const abs = resolve(file);
|
|
23
|
+
if (seen.has(abs)) return seen.get(abs);
|
|
24
|
+
const id = `__m${seen.size}`;
|
|
25
|
+
seen.set(abs, id);
|
|
26
|
+
const src = readFileSync(abs, "utf8");
|
|
27
|
+
const lines = src.split("\n");
|
|
28
|
+
const body = [];
|
|
29
|
+
const exported = [];
|
|
30
|
+
for (const line of lines) {
|
|
31
|
+
if (/^\s*import\s/.test(line)) {
|
|
32
|
+
const m = line.match(IMPORT_RE);
|
|
33
|
+
if (!m) throw new Error(`${abs}: unsupported import form: ${line.trim()}`);
|
|
34
|
+
const dep = visit(resolve(dirname(abs), m[2]));
|
|
35
|
+
const names = m[1]
|
|
36
|
+
.split(",")
|
|
37
|
+
.map((s) => s.trim())
|
|
38
|
+
.filter(Boolean)
|
|
39
|
+
.map((s) => s.replace(/\s+as\s+/, ": "));
|
|
40
|
+
body.push(`const { ${names.join(", ")} } = ${dep};`);
|
|
41
|
+
continue;
|
|
42
|
+
}
|
|
43
|
+
let m = line.match(/^export\s+(async\s+function|function\*?|const|let|class)\s+([A-Za-z_$][\w$]*)/);
|
|
44
|
+
if (m) {
|
|
45
|
+
exported.push(m[2]);
|
|
46
|
+
body.push(line.replace(/^export\s+/, ""));
|
|
47
|
+
continue;
|
|
48
|
+
}
|
|
49
|
+
m = line.match(/^export\s*\{([^}]*)\};?\s*$/);
|
|
50
|
+
if (m) {
|
|
51
|
+
exported.push(...m[1].split(",").map((s) => s.trim()).filter(Boolean));
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
if (/^export\s+default\s+/.test(line)) {
|
|
55
|
+
body.push(line.replace(/^export\s+default\s+/, "const __default = "));
|
|
56
|
+
exported.push("default: __default");
|
|
57
|
+
continue;
|
|
58
|
+
}
|
|
59
|
+
if (/^\s*export\s/.test(line)) throw new Error(`${abs}: unsupported export form: ${line.trim()}`);
|
|
60
|
+
body.push(line);
|
|
61
|
+
}
|
|
62
|
+
order.push(`const ${id} = (() => {\n${body.join("\n")}\nreturn { ${exported.join(", ")} };\n})();`);
|
|
63
|
+
return id;
|
|
64
|
+
}
|
|
65
|
+
const ids = entries.map((e) => visit(e));
|
|
66
|
+
const merged = ids.map((id) => `...${id}`).join(", ");
|
|
67
|
+
return `(() => {\n"use strict";\n${order.join("\n")}\nglobalThis.${globalName} = Object.freeze({ ${merged} });\n})();\n`;
|
|
68
|
+
}
|
package/lib/check.mjs
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Copyright (c) 2026 Ophir Radnitz
|
|
3
|
+
/**
|
|
4
|
+
* motion-kit · scene gate. Every scene, every format/locale it ships in, must
|
|
5
|
+
* pass these before anything is exported or mounted.
|
|
6
|
+
*
|
|
7
|
+
* checkScene(scene) → { ok, problems: string[] }
|
|
8
|
+
*/
|
|
9
|
+
import { renderSvg } from "../runtime/scene.mjs";
|
|
10
|
+
|
|
11
|
+
const SAMPLES = 120;
|
|
12
|
+
|
|
13
|
+
/** Minimal well-formedness check: balanced tags, no raw "<" in text, entities ok. */
|
|
14
|
+
export function wellFormed(svg) {
|
|
15
|
+
const stack = [];
|
|
16
|
+
const re = /<(\/?)([a-zA-Z][\w:-]*)((?:\s+[\w:-]+="[^"]*")*)\s*(\/?)>|<|&(?!(?:amp|lt|gt|quot|#39|#\d+);)/g;
|
|
17
|
+
let m;
|
|
18
|
+
let last = 0;
|
|
19
|
+
while ((m = re.exec(svg))) {
|
|
20
|
+
if (m[0] === "<") return `stray "<" at ${m.index}`;
|
|
21
|
+
if (m[0].startsWith("&")) return `bare "&" at ${m.index}`;
|
|
22
|
+
last = re.lastIndex;
|
|
23
|
+
const [, close, tag, , self] = m;
|
|
24
|
+
if (self) continue;
|
|
25
|
+
if (close) {
|
|
26
|
+
const open = stack.pop();
|
|
27
|
+
if (open !== tag) return `</${tag}> closes <${open}>`;
|
|
28
|
+
} else stack.push(tag);
|
|
29
|
+
}
|
|
30
|
+
if (stack.length) return `unclosed <${stack[stack.length - 1]}>`;
|
|
31
|
+
if (last === 0) return "no markup";
|
|
32
|
+
return null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export function checkScene(scene, { samples = SAMPLES } = {}) {
|
|
36
|
+
const problems = [];
|
|
37
|
+
const render = (t) => renderSvg(scene, t);
|
|
38
|
+
const at = (i) => (scene.duration * i) / samples;
|
|
39
|
+
|
|
40
|
+
// 1. Deterministic + well-formed + rounded + token-only, across the timeline.
|
|
41
|
+
for (let i = 0; i <= samples; i++) {
|
|
42
|
+
const t = at(i);
|
|
43
|
+
const a = render(t);
|
|
44
|
+
if (a !== render(t)) problems.push(`not deterministic at t=${t.toFixed(3)}`);
|
|
45
|
+
const wf = wellFormed(a);
|
|
46
|
+
if (wf) problems.push(`malformed at t=${t.toFixed(3)}: ${wf}`);
|
|
47
|
+
const long = a.match(/-?\d+\.\d{5,}/);
|
|
48
|
+
if (long) problems.push(`unrounded number ${long[0]} at t=${t.toFixed(3)} (use num())`);
|
|
49
|
+
const frame = scene.frame(Math.min(t, scene.duration));
|
|
50
|
+
const lit = frame.match(/#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(/);
|
|
51
|
+
if (lit) problems.push(`colour literal "${lit[0]}" at t=${t.toFixed(3)} (use tok())`);
|
|
52
|
+
if (/NaN|undefined|Infinity/.test(frame)) problems.push(`NaN/undefined/Infinity in frame at t=${t.toFixed(3)}`);
|
|
53
|
+
if (problems.length > 12) break;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// 2. Settled steps: nothing moves at a step's time.
|
|
57
|
+
for (const s of scene.steps) {
|
|
58
|
+
const before = render(Math.max(0, s.at - 0.001));
|
|
59
|
+
if (before !== render(s.at)) problems.push(`step "${s.label}" at ${s.at.toFixed(3)}s is not settled (something is still moving)`);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// 3. Builds up and finishes.
|
|
63
|
+
const first = render(0);
|
|
64
|
+
const lastFrame = render(scene.duration);
|
|
65
|
+
if (first === lastFrame) problems.push("first and last frame are identical: nothing animates");
|
|
66
|
+
if (scene.steps[scene.steps.length - 1].at > scene.duration) problems.push("last step is after duration");
|
|
67
|
+
if (render(scene.duration + 5) !== lastFrame) problems.push("frames after the end differ from the final frame (must hold)");
|
|
68
|
+
|
|
69
|
+
// 4. Budget: whole scene under ~10 s (design guidance: ≤ 8 s for explainers).
|
|
70
|
+
if (scene.duration > 12) problems.push(`duration ${scene.duration.toFixed(1)}s is long for an explainer (≤ 8–10 s)`);
|
|
71
|
+
|
|
72
|
+
// 5. Every step label is visible in the final frame (escaped form), unless
|
|
73
|
+
// the scene declares narrative steps (stepLabelsInFrame: false).
|
|
74
|
+
const escd = (s) => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """).replace(/'/g, "'");
|
|
75
|
+
const plain = lastFrame.replace(/<\/tspan><tspan[^>]*>/g, " ").replace(/<[^>]+>/g, "\u0000");
|
|
76
|
+
for (const s of scene.stepLabelsInFrame === false ? [] : scene.steps) {
|
|
77
|
+
const words = escd(s.label).split(/\s+/);
|
|
78
|
+
if (!words.every((w) => plain.includes(w.replace(/\/$/, "")))) problems.push(`step label "${s.label}" not found in the final frame`);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// 6. No forbidden sources of time/randomness in the frame function.
|
|
82
|
+
const src = scene.frame.toString();
|
|
83
|
+
if (/Date\.now|new Date|Math\.random|performance\.now/.test(src)) problems.push("frame() reads the clock or randomness");
|
|
84
|
+
|
|
85
|
+
return { ok: problems.length === 0, problems };
|
|
86
|
+
}
|
package/lib/export.mjs
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* motion-kit · export step frames for slides and review.
|
|
3
|
+
*
|
|
4
|
+
* Writes, into `out`:
|
|
5
|
+
* NN-<step>.svg standalone, tokens resolved (PowerPoint/Keynote take SVG)
|
|
6
|
+
* NN-<step>.png with --png (Google Slides, Marp/Slidev, travelling decks)
|
|
7
|
+
* qc/… with --qc: frames 0.2 s before and after every step
|
|
8
|
+
* index.html contact sheet (steps, QC row, phone-size row)
|
|
9
|
+
* manifest.json reproducible: no timestamps; input hash + settings
|
|
10
|
+
*/
|
|
11
|
+
import { createHash } from "node:crypto";
|
|
12
|
+
import { execFileSync } from "node:child_process";
|
|
13
|
+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
14
|
+
import { join } from "node:path";
|
|
15
|
+
import { renderSvg } from "../runtime/scene.mjs";
|
|
16
|
+
import { svgToPng } from "./raster.mjs";
|
|
17
|
+
|
|
18
|
+
export function slug(s) {
|
|
19
|
+
return String(s)
|
|
20
|
+
.normalize("NFKD")
|
|
21
|
+
.replace(/[̀-ͯ]/g, "")
|
|
22
|
+
.toLowerCase()
|
|
23
|
+
.replace(/[^a-z0-9]+/g, "-")
|
|
24
|
+
.replace(/^-|-$/g, "")
|
|
25
|
+
.slice(0, 40);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function gitCommit(cwd) {
|
|
29
|
+
try {
|
|
30
|
+
return execFileSync("git", ["rev-parse", "--short", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
|
|
31
|
+
} catch {
|
|
32
|
+
return null;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* @param {any} scene
|
|
38
|
+
* @param {{out: string, style?: import("../runtime/style.mjs").Style, theme?: string, png?: boolean, scale?: number, qc?: boolean, background?: boolean, sourceFile?: string, version?: string}} options
|
|
39
|
+
*/
|
|
40
|
+
export async function exportSteps(scene, { out, style, theme = "light", png = false, scale = 2, qc = false, background = false, sourceFile, version }) {
|
|
41
|
+
mkdirSync(out, { recursive: true });
|
|
42
|
+
const opts = { standalone: true, style, theme, background };
|
|
43
|
+
const files = [];
|
|
44
|
+
const write = async (name, t, kind, label) => {
|
|
45
|
+
const svg = renderSvg(scene, t, opts);
|
|
46
|
+
writeFileSync(join(out, `${name}.svg`), svg);
|
|
47
|
+
const entry = { kind, t: Math.round(t * 1000) / 1000, label, svg: `${name}.svg` };
|
|
48
|
+
if (png) {
|
|
49
|
+
writeFileSync(join(out, `${name}.png`), await svgToPng(svg, { scale }));
|
|
50
|
+
entry.png = `${name}.png`;
|
|
51
|
+
}
|
|
52
|
+
files.push(entry);
|
|
53
|
+
};
|
|
54
|
+
for (const [i, s] of scene.steps.entries()) {
|
|
55
|
+
const n = String(i + 1).padStart(2, "0");
|
|
56
|
+
await write(`${n}-${slug(s.label)}`, s.at, "step", s.label);
|
|
57
|
+
}
|
|
58
|
+
if (qc) {
|
|
59
|
+
mkdirSync(join(out, "qc"), { recursive: true });
|
|
60
|
+
for (const [i, s] of scene.steps.entries()) {
|
|
61
|
+
const n = String(i + 1).padStart(2, "0");
|
|
62
|
+
await write(`qc/${n}-before`, Math.max(0, s.at - 0.2), "before", s.label);
|
|
63
|
+
if (i < scene.steps.length - 1) await write(`qc/${n}-after`, s.at + 0.2, "after", s.label);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
const inputHash = createHash("sha256")
|
|
67
|
+
.update(sourceFile ? readFileSync(sourceFile) : scene.frame.toString())
|
|
68
|
+
.update(JSON.stringify(style ?? "neutral"))
|
|
69
|
+
.digest("hex")
|
|
70
|
+
.slice(0, 16);
|
|
71
|
+
const manifest = {
|
|
72
|
+
tool: "motion-kit",
|
|
73
|
+
version,
|
|
74
|
+
scene: scene.id,
|
|
75
|
+
type: scene.type ?? "custom",
|
|
76
|
+
format: scene.format ?? null,
|
|
77
|
+
locale: scene.locale ?? null,
|
|
78
|
+
width: scene.width,
|
|
79
|
+
height: scene.height,
|
|
80
|
+
duration: Math.round(scene.duration * 1000) / 1000,
|
|
81
|
+
style: style?.name ?? "neutral",
|
|
82
|
+
theme,
|
|
83
|
+
inputHash,
|
|
84
|
+
sourceCommit: sourceFile ? gitCommit(join(sourceFile, "..")) : null,
|
|
85
|
+
render: { png, scale: png ? scale : null, background, qc },
|
|
86
|
+
files,
|
|
87
|
+
};
|
|
88
|
+
writeFileSync(join(out, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
|
|
89
|
+
writeFileSync(join(out, "index.html"), contactSheet(scene, files, theme, style));
|
|
90
|
+
return manifest;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function contactSheet(scene, files, theme, style) {
|
|
94
|
+
const bg = style?.[theme]?.bg ?? (theme === "dark" ? "#0f1115" : "#ffffff");
|
|
95
|
+
const card = (f) =>
|
|
96
|
+
`<figure><img src="${f.svg}" alt=""><figcaption>${f.kind} · ${f.t}s · ${escapeHtml(f.label)}</figcaption></figure>`;
|
|
97
|
+
const steps = files.filter((f) => f.kind === "step");
|
|
98
|
+
const qcs = files.filter((f) => f.kind !== "step");
|
|
99
|
+
return `<!doctype html><meta charset="utf-8"><title>${escapeHtml(scene.title)} · contact sheet</title>
|
|
100
|
+
<style>body{font:14px system-ui;margin:24px;background:#e5e7eb}h2{margin:24px 0 8px}
|
|
101
|
+
.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(320px,1fr));gap:12px}
|
|
102
|
+
figure{margin:0;background:${bg};padding:8px;border-radius:8px}img{width:100%;display:block}
|
|
103
|
+
figcaption{font-size:12px;color:#6b7280;margin-top:4px}.phone figure{width:360px}</style>
|
|
104
|
+
<h1>${escapeHtml(scene.title)}</h1><p>${escapeHtml(scene.id)} · ${scene.width}×${scene.height} · ${scene.duration.toFixed(2)} s · ${theme}</p>
|
|
105
|
+
<h2>Steps (what a slide shows)</h2><div class="grid">${steps.map(card).join("")}</div>
|
|
106
|
+
${qcs.length ? `<h2>QC: 0.2 s before / after each step</h2><div class="grid">${qcs.map(card).join("")}</div>` : ""}
|
|
107
|
+
<h2>Phone size (360 px wide)</h2><div class="grid phone">${steps.slice(-1).map(card).join("")}</div>
|
|
108
|
+
<h2>Review</h2><ol><li>Does the step sequence tell the story without narration?</li><li>Any overlapping text, half-drawn lines or stray dots?</li><li>Readable at phone size?</li><li>Only approved copy and claims? No invented numbers?</li><li>Human approval: ____________ (name, date)</li></ol>`;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export function escapeHtml(s) {
|
|
112
|
+
return String(s).replace(/[&<>"]/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """ })[c]);
|
|
113
|
+
}
|
package/lib/icon.mjs
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* motion-kit · write a project icon set from a square scene's final frame.
|
|
3
|
+
*
|
|
4
|
+
* Writes, under `root` (a repository root):
|
|
5
|
+
* assets/icon.svg static mark, light theme (README, docs, favicon source)
|
|
6
|
+
* assets/icon.png `size`×`size` PNG; Conductor picks up assets/icon.png
|
|
7
|
+
* assets/icon-animated.svg zero-JS animated SVG that plays once and holds
|
|
8
|
+
* .idea/icon.svg JetBrains IDEs' project icon (Welcome screen, project switcher)
|
|
9
|
+
* .idea/icon_dark.svg the same in the dark theme
|
|
10
|
+
*
|
|
11
|
+
* Paths other tools look in are listed in skills/project-logo/references/discovery.md.
|
|
12
|
+
*/
|
|
13
|
+
import { mkdirSync, writeFileSync } from "node:fs";
|
|
14
|
+
import { dirname, join } from "node:path";
|
|
15
|
+
import { bake } from "../runtime/bake.mjs";
|
|
16
|
+
import { renderSvg } from "../runtime/scene.mjs";
|
|
17
|
+
import { svgToPng } from "./raster.mjs";
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* @param {any} scene a square scene (width === height)
|
|
21
|
+
* @param {{root: string, style?: object, size?: number, png?: boolean}} options
|
|
22
|
+
* @returns {Promise<string[]>} files written, relative to root
|
|
23
|
+
*/
|
|
24
|
+
export async function writeIconSet(scene, { root, style, size = 512, png = true }) {
|
|
25
|
+
if (scene.width !== scene.height) throw new Error(`icon: scene must be square, got ${scene.width}×${scene.height} (use --format 1:1)`);
|
|
26
|
+
const final = (theme, scale = 1) => renderSvg(scene, scene.duration, { standalone: true, style, theme, scale });
|
|
27
|
+
/** @type {[string, string | Buffer][]} */
|
|
28
|
+
const files = [
|
|
29
|
+
["assets/icon.svg", final("light")],
|
|
30
|
+
["assets/icon-animated.svg", bake(scene, { style, theme: "light" })],
|
|
31
|
+
[".idea/icon.svg", final("light")],
|
|
32
|
+
[".idea/icon_dark.svg", final("dark")],
|
|
33
|
+
];
|
|
34
|
+
if (png) files.splice(1, 0, ["assets/icon.png", await svgToPng(final("light", size / scene.width))]);
|
|
35
|
+
for (const [rel, body] of files) {
|
|
36
|
+
const abs = join(root, rel);
|
|
37
|
+
mkdirSync(dirname(abs), { recursive: true });
|
|
38
|
+
writeFileSync(abs, body);
|
|
39
|
+
}
|
|
40
|
+
return files.map(([rel]) => rel);
|
|
41
|
+
}
|
package/lib/load.mjs
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* motion-kit · load a scene from a spec (.json) or a custom module (.mjs).
|
|
3
|
+
*
|
|
4
|
+
* Custom modules: `export default (opts) => scene` with
|
|
5
|
+
* opts = { format, locale, kit }. `kit` is the whole runtime in one flat
|
|
6
|
+
* namespace (motion, svg, style, scene, wrap), so a scene that lives in
|
|
7
|
+
* another repository (a project logo) needs no imports at all:
|
|
8
|
+
*
|
|
9
|
+
* export default ({ kit }) => { const { tok, el, num } = kit; … }
|
|
10
|
+
*
|
|
11
|
+
* Scenes inside this repo (or a vendored copy) may import the runtime with
|
|
12
|
+
* relative paths instead; `motion-kit build` (browser bundle) requires that.
|
|
13
|
+
*/
|
|
14
|
+
import { readFileSync } from "node:fs";
|
|
15
|
+
import { resolve } from "node:path";
|
|
16
|
+
import { pathToFileURL } from "node:url";
|
|
17
|
+
import { validateScene } from "../runtime/scene.mjs";
|
|
18
|
+
import { normalizeStyle } from "../runtime/style.mjs";
|
|
19
|
+
import { createScene } from "../runtime/types/index.mjs";
|
|
20
|
+
import * as motion from "../runtime/motion.mjs";
|
|
21
|
+
import * as scene from "../runtime/scene.mjs";
|
|
22
|
+
import * as style from "../runtime/style.mjs";
|
|
23
|
+
import * as svg from "../runtime/svg.mjs";
|
|
24
|
+
import * as wrap from "../runtime/wrap.mjs";
|
|
25
|
+
|
|
26
|
+
/** The runtime, flat, handed to custom scene modules as `opts.kit`. */
|
|
27
|
+
export const KIT = Object.freeze({ ...motion, ...svg, ...style, ...scene, ...wrap });
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* @typedef {{scene: any, spec?: any, kind: "spec" | "module", file: string}} LoadedScene
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* @param {string} file path to a .json spec or an .mjs module
|
|
35
|
+
* @param {{format?: string, locale?: string}} [opts]
|
|
36
|
+
* @returns {Promise<LoadedScene>}
|
|
37
|
+
*/
|
|
38
|
+
export async function loadScene(file, opts = {}) {
|
|
39
|
+
const abs = resolve(file);
|
|
40
|
+
if (abs.endsWith(".json")) {
|
|
41
|
+
const spec = JSON.parse(readFileSync(abs, "utf8"));
|
|
42
|
+
return { scene: createScene(spec, opts), spec, kind: "spec", file: abs };
|
|
43
|
+
}
|
|
44
|
+
const mod = await import(pathToFileURL(abs).href);
|
|
45
|
+
const make = mod.default;
|
|
46
|
+
if (typeof make !== "function") throw new Error(`${file}: default export must be (opts) => scene`);
|
|
47
|
+
return { scene: validateScene(make({ ...opts, kit: KIT })), kind: "module", file: abs };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function loadStyle(arg) {
|
|
51
|
+
if (!arg || arg === "neutral") return normalizeStyle("neutral");
|
|
52
|
+
return normalizeStyle(JSON.parse(readFileSync(resolve(arg), "utf8")));
|
|
53
|
+
}
|
package/lib/raster.mjs
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* motion-kit · rasterize standalone SVG to PNG.
|
|
3
|
+
*
|
|
4
|
+
* Prefers @resvg/resvg-js (in-process, deterministic, no browser). Falls back
|
|
5
|
+
* to headless Chrome when resvg is not installed.
|
|
6
|
+
*/
|
|
7
|
+
import { execFileSync } from "node:child_process";
|
|
8
|
+
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
9
|
+
import { tmpdir } from "node:os";
|
|
10
|
+
import { join } from "node:path";
|
|
11
|
+
|
|
12
|
+
let resvg;
|
|
13
|
+
async function getResvg() {
|
|
14
|
+
if (resvg !== undefined) return resvg;
|
|
15
|
+
try {
|
|
16
|
+
resvg = (await import("@resvg/resvg-js")).Resvg;
|
|
17
|
+
} catch {
|
|
18
|
+
resvg = null;
|
|
19
|
+
}
|
|
20
|
+
return resvg;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const CHROME = [
|
|
24
|
+
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
|
|
25
|
+
"/usr/bin/google-chrome",
|
|
26
|
+
"/usr/bin/chromium",
|
|
27
|
+
"/usr/bin/chromium-browser",
|
|
28
|
+
];
|
|
29
|
+
|
|
30
|
+
export async function rasterizer() {
|
|
31
|
+
return (await getResvg()) ? "resvg" : CHROME.find((p) => existsSync(p)) ? "chrome" : null;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* @param {string} svg standalone SVG (tokens resolved, width/height set)
|
|
36
|
+
* @param {{scale?:number, font?:string}} o
|
|
37
|
+
* @returns {Promise<Buffer>}
|
|
38
|
+
*/
|
|
39
|
+
export async function svgToPng(svg, { scale = 1, font = "Helvetica" } = {}) {
|
|
40
|
+
const R = await getResvg();
|
|
41
|
+
if (R) {
|
|
42
|
+
const r = new R(svg, {
|
|
43
|
+
fitTo: { mode: "zoom", value: scale },
|
|
44
|
+
font: { loadSystemFonts: true, defaultFontFamily: font, sansSerifFamily: font },
|
|
45
|
+
shapeRendering: 2,
|
|
46
|
+
textRendering: 1,
|
|
47
|
+
});
|
|
48
|
+
return r.render().asPng();
|
|
49
|
+
}
|
|
50
|
+
const chrome = CHROME.find((p) => existsSync(p));
|
|
51
|
+
if (!chrome) throw new Error("no rasterizer: npm install @resvg/resvg-js, or install Chrome");
|
|
52
|
+
const size = (attr) => {
|
|
53
|
+
const m = svg.match(new RegExp(`${attr}="([\\d.]+)"`));
|
|
54
|
+
if (!m) throw new Error(`svg has no ${attr}: rasterize standalone output`);
|
|
55
|
+
return Number(m[1]);
|
|
56
|
+
};
|
|
57
|
+
const w = size("width");
|
|
58
|
+
const h = size("height");
|
|
59
|
+
const dir = mkdtempSync(join(tmpdir(), "mk-"));
|
|
60
|
+
try {
|
|
61
|
+
const src = join(dir, "f.svg");
|
|
62
|
+
const out = join(dir, "f.png");
|
|
63
|
+
writeFileSync(src, svg);
|
|
64
|
+
execFileSync(chrome, ["--headless", "--hide-scrollbars", "--default-background-color=00000000", `--force-device-scale-factor=${scale}`, `--window-size=${Math.ceil(w)},${Math.ceil(h)}`, `--screenshot=${out}`, `file://${src}`], { stdio: "ignore" });
|
|
65
|
+
return readFileSync(out);
|
|
66
|
+
} finally {
|
|
67
|
+
rmSync(dir, { recursive: true, force: true });
|
|
68
|
+
}
|
|
69
|
+
}
|
package/lib/video.mjs
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* motion-kit · render a scene to MP4 / GIF / WebM.
|
|
3
|
+
*
|
|
4
|
+
* frame f → t = f / fps → standalone SVG (opaque bg) → PNG (resvg) → ffmpeg stdin
|
|
5
|
+
*
|
|
6
|
+
* Frames stream through a pipe: nothing is written per frame. The final frame
|
|
7
|
+
* is held for `hold` seconds so the end state can be read. Output is
|
|
8
|
+
* deterministic for the same inputs (same frames, same encoder settings).
|
|
9
|
+
*/
|
|
10
|
+
import { spawn, spawnSync } from "node:child_process";
|
|
11
|
+
import { renderSvg } from "../runtime/scene.mjs";
|
|
12
|
+
import { svgToPng } from "./raster.mjs";
|
|
13
|
+
|
|
14
|
+
export function hasFfmpeg() {
|
|
15
|
+
return spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function codecArgs(out, fps) {
|
|
19
|
+
if (out.endsWith(".gif")) {
|
|
20
|
+
return ["-filter_complex", `fps=${Math.min(fps, 20)},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=4`, "-loop", "-1"];
|
|
21
|
+
}
|
|
22
|
+
if (out.endsWith(".webm")) return ["-c:v", "libvpx-vp9", "-b:v", "0", "-crf", "32", "-pix_fmt", "yuv420p"];
|
|
23
|
+
return ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-pix_fmt", "yuv420p", "-movflags", "+faststart", "-vf", "pad=ceil(iw/2)*2:ceil(ih/2)*2"];
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @param {any} scene
|
|
28
|
+
* @param {{out:string, fps?:number, scale?:number, hold?:number, lead?:number, style?:import("../runtime/style.mjs").Style, theme?:string, onProgress?:(f:number,n:number)=>void}} o
|
|
29
|
+
*/
|
|
30
|
+
export async function renderVideo(scene, o) {
|
|
31
|
+
if (!hasFfmpeg()) throw new Error("ffmpeg not found (brew install ffmpeg / apt install ffmpeg)");
|
|
32
|
+
const fps = o.fps ?? 30;
|
|
33
|
+
const scale = o.scale ?? 2;
|
|
34
|
+
const hold = o.hold ?? 1.5;
|
|
35
|
+
const lead = o.lead ?? 0.25;
|
|
36
|
+
const total = Math.round((lead + scene.duration + hold) * fps);
|
|
37
|
+
const ff = spawn("ffmpeg", ["-y", "-loglevel", "error", "-f", "image2pipe", "-framerate", String(fps), "-c:v", "png", "-i", "-", ...codecArgs(o.out, fps), o.out], { stdio: ["pipe", "inherit", "inherit"] });
|
|
38
|
+
const done = /** @type {Promise<void>} */ (new Promise((res, rej) => {
|
|
39
|
+
ff.on("error", rej);
|
|
40
|
+
ff.on("close", (code) => (code === 0 ? res() : rej(new Error(`ffmpeg exited with ${code}`))));
|
|
41
|
+
}));
|
|
42
|
+
/** @type {number | null} */
|
|
43
|
+
let lastT = null;
|
|
44
|
+
/** @type {Buffer | null} */
|
|
45
|
+
let lastPng = null;
|
|
46
|
+
for (let f = 0; f < total; f++) {
|
|
47
|
+
const t = Math.min(Math.max(f / fps - lead, 0), scene.duration);
|
|
48
|
+
if (t !== lastT) {
|
|
49
|
+
const svg = renderSvg(scene, t, { standalone: true, background: true, style: o.style, theme: o.theme ?? "light" });
|
|
50
|
+
lastPng = await svgToPng(svg, { scale });
|
|
51
|
+
lastT = t;
|
|
52
|
+
}
|
|
53
|
+
if (!ff.stdin.write(lastPng)) await new Promise((r) => ff.stdin.once("drain", r));
|
|
54
|
+
o.onProgress?.(f + 1, total);
|
|
55
|
+
}
|
|
56
|
+
ff.stdin.end();
|
|
57
|
+
await done;
|
|
58
|
+
return { frames: total, fps, seconds: total / fps, out: o.out };
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Contact sheet of a rendered video: one thumbnail per second, 5 columns. */
|
|
62
|
+
export function videoContactSheet(video, out) {
|
|
63
|
+
const n = Math.max(1, Math.ceil(probe(video).duration));
|
|
64
|
+
const cols = Math.min(5, n);
|
|
65
|
+
const rows = Math.ceil(n / cols);
|
|
66
|
+
const r = spawnSync("ffmpeg", ["-y", "-loglevel", "error", "-i", video, "-vf", `fps=1,scale=270:-1,tile=${cols}x${rows}:padding=6:color=0x9ca3af`, "-frames:v", "1", out]);
|
|
67
|
+
if (r.status !== 0) throw new Error(`ffmpeg contact sheet failed: ${r.stderr}`);
|
|
68
|
+
return out;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Duration and size of a media file via ffprobe. */
|
|
72
|
+
export function probe(file) {
|
|
73
|
+
const r = spawnSync("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height,r_frame_rate:format=duration", "-of", "json", file], { encoding: "utf8" });
|
|
74
|
+
if (r.status !== 0) throw new Error(r.stderr);
|
|
75
|
+
const j = JSON.parse(r.stdout);
|
|
76
|
+
return { width: j.streams[0].width, height: j.streams[0].height, fps: j.streams[0].r_frame_rate, duration: Number(j.format.duration) };
|
|
77
|
+
}
|