@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +63 -10
- package/adapters/astro/AnimatedDiagram.astro +150 -24
- package/adapters/element/README.md +6 -1
- package/adapters/element/motion-diagram.mjs +4 -3
- package/adapters/page/README.md +8 -2
- package/adapters/slidev/AnimatedDiagram.vue +24 -0
- package/cli/motion-kit.mjs +85 -81
- package/docs/spec/technique.md +166 -63
- package/examples/custom-pulse.scene.mjs +3 -0
- package/examples/incident.json +18 -0
- package/examples/web-stack.json +17 -0
- package/lib/build.mjs +26 -12
- package/lib/bundle.mjs +9 -2
- package/lib/check.mjs +219 -15
- package/lib/export.mjs +135 -16
- package/lib/gate.mjs +90 -0
- package/lib/load.mjs +49 -19
- package/package.json +6 -3
- package/runtime/bake.mjs +18 -4
- package/runtime/kit.mjs +59 -0
- package/runtime/links.mjs +314 -0
- package/runtime/page.mjs +52 -0
- package/runtime/parts.mjs +15 -0
- package/runtime/patch.mjs +297 -0
- package/runtime/player.mjs +334 -130
- package/runtime/scene.mjs +82 -5
- package/runtime/style.mjs +64 -16
- package/runtime/types/hub-spoke.mjs +7 -7
- package/runtime/types/index.mjs +4 -0
- package/runtime/types/sequence.mjs +5 -5
- package/runtime/types/stack.mjs +227 -0
- package/runtime/types/timeline.mjs +405 -0
- package/skills/animated-diagram/SKILL.md +30 -7
- package/skills/animated-diagram/references/custom-scenes.md +64 -9
- package/skills/animated-diagram/references/interactivity.md +150 -15
- package/skills/animated-diagram/references/qc.md +5 -2
- package/skills/animated-diagram/references/scene-types.md +45 -2
- package/skills/animated-diagram/references/styles.md +45 -5
- package/skills/animated-diagram/references/targets.md +7 -5
- package/skills/animated-diagram/references/technique.md +14 -4
- package/skills/motion-render/SKILL.md +31 -8
- package/skills/motion-render/references/formats.md +8 -8
- package/skills/project-logo/SKILL.md +15 -4
- package/styles/neutral.json +2 -2
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Copyright (c) 2026 Ophir Radnitz
|
|
3
|
+
/**
|
|
4
|
+
* motion-kit · update rendered SVG in place (browser; the parser runs anywhere).
|
|
5
|
+
*
|
|
6
|
+
* patchMarkup(parent, markup) → true when updated in place, false when it fell back to innerHTML
|
|
7
|
+
*
|
|
8
|
+
* The live player draws each frame by handing the frame's markup to
|
|
9
|
+
* patchMarkup instead of assigning innerHTML. Nodes that persist between
|
|
10
|
+
* frames are kept; only changed attributes and text are written; nodes are
|
|
11
|
+
* added or removed only where the markup's structure changes. The browser
|
|
12
|
+
* then restyles and lays out what changed, and hover and other node state
|
|
13
|
+
* survive.
|
|
14
|
+
*
|
|
15
|
+
* Children are matched by position: a child whose tag differs from the one
|
|
16
|
+
* drawn before is replaced with its subtree, and a child whose markup is
|
|
17
|
+
* byte-identical to the one drawn before is not visited at all.
|
|
18
|
+
*
|
|
19
|
+
* The parser takes the markup scenes emit (one or more `<svg>` elements;
|
|
20
|
+
* double-quoted attributes; text with the entities `esc()` writes and numeric
|
|
21
|
+
* ones) and builds the nodes the HTML parser would build from the same string:
|
|
22
|
+
* names lowercased then SVG-cased, `xlink:`/`xml:`/`xmlns` attributes in their
|
|
23
|
+
* namespaces. Anything else (comments, CDATA, single-quoted or bare
|
|
24
|
+
* attributes, named entities beyond the XML five, elements inside `<title>`,
|
|
25
|
+
* `<desc>` or `<foreignObject>`, HTML elements that leave SVG) is left to the
|
|
26
|
+
* HTML parser: patchMarkup then assigns innerHTML for that call.
|
|
27
|
+
*
|
|
28
|
+
* The patch owns the parent's content: change it only through patchMarkup. If
|
|
29
|
+
* the parent's children were replaced by other code, the next call rebuilds.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
const SVG_NS = "http://www.w3.org/2000/svg";
|
|
33
|
+
const XLINK_NS = "http://www.w3.org/1999/xlink";
|
|
34
|
+
const XML_NS = "http://www.w3.org/XML/1998/namespace";
|
|
35
|
+
const XMLNS_NS = "http://www.w3.org/2000/xmlns/";
|
|
36
|
+
|
|
37
|
+
/** @param {string} names @returns {Map<string, string>} lowercased → SVG-cased */
|
|
38
|
+
const caseMap = (names) => new Map(names.split(" ").map((n) => [n.toLowerCase(), n]));
|
|
39
|
+
|
|
40
|
+
// The HTML parser's "adjust SVG tag names" and "adjust SVG attributes" tables.
|
|
41
|
+
const SVG_TAGS = caseMap(
|
|
42
|
+
"altGlyph altGlyphDef altGlyphItem animateColor animateMotion animateTransform clipPath feBlend feColorMatrix feComponentTransfer " +
|
|
43
|
+
"feComposite feConvolveMatrix feDiffuseLighting feDisplacementMap feDistantLight feDropShadow feFlood feFuncA feFuncB feFuncG feFuncR " +
|
|
44
|
+
"feGaussianBlur feImage feMerge feMergeNode feMorphology feOffset fePointLight feSpecularLighting feSpotLight feTile feTurbulence " +
|
|
45
|
+
"foreignObject glyphRef linearGradient radialGradient textPath",
|
|
46
|
+
);
|
|
47
|
+
const SVG_ATTRS = caseMap(
|
|
48
|
+
"attributeName attributeType baseFrequency baseProfile calcMode clipPathUnits diffuseConstant edgeMode filterUnits glyphRef " +
|
|
49
|
+
"gradientTransform gradientUnits kernelMatrix kernelUnitLength keyPoints keySplines keyTimes lengthAdjust limitingConeAngle " +
|
|
50
|
+
"markerHeight markerUnits markerWidth maskContentUnits maskUnits numOctaves pathLength patternContentUnits patternTransform " +
|
|
51
|
+
"patternUnits pointsAtX pointsAtY pointsAtZ preserveAlpha preserveAspectRatio primitiveUnits refX refY repeatCount repeatDur " +
|
|
52
|
+
"requiredExtensions requiredFeatures specularConstant specularExponent spreadMethod startOffset stdDeviation stitchTiles " +
|
|
53
|
+
"surfaceScale systemLanguage tableValues targetX targetY textLength viewBox viewTarget xChannelSelector yChannelSelector zoomAndPan",
|
|
54
|
+
);
|
|
55
|
+
/** The HTML parser's "adjust foreign attributes": name → [namespace, local name]. @type {Map<string, [string, string]>} */
|
|
56
|
+
const FOREIGN_ATTRS = new Map([
|
|
57
|
+
...["actuate", "arcrole", "href", "role", "show", "title", "type"].map((n) => /** @type {[string, [string, string]]} */ ([`xlink:${n}`, [XLINK_NS, n]])),
|
|
58
|
+
["xml:lang", [XML_NS, "lang"]],
|
|
59
|
+
["xml:space", [XML_NS, "space"]],
|
|
60
|
+
["xmlns", [XMLNS_NS, "xmlns"]],
|
|
61
|
+
["xmlns:xlink", [XMLNS_NS, "xlink"]],
|
|
62
|
+
]);
|
|
63
|
+
// Start tags that take the HTML parser out of SVG, and the SVG elements whose
|
|
64
|
+
// child elements it parses as HTML.
|
|
65
|
+
const LEAVES_SVG = new Set(
|
|
66
|
+
"b big blockquote body br center code dd div dl dt em embed font h1 h2 h3 h4 h5 h6 head hr i img li listing math menu meta nobr ol p pre ruby s small span strike strong sub sup table tt u ul var".split(" "),
|
|
67
|
+
);
|
|
68
|
+
const HTML_INSIDE = new Set(["title", "desc", "foreignObject"]);
|
|
69
|
+
|
|
70
|
+
// Whitespace is the HTML parser's: tab, line feed, form feed, space.
|
|
71
|
+
const TAG = /<(\/?)([A-Za-z][^\t\n\f />]*)((?:[\t\n\f ]+[^\t\n\f "'<>/=]+="[^"]*")*)[\t\n\f ]*(\/?)>/y;
|
|
72
|
+
const ATTR = /([^\t\n\f "'<>/=]+)="([^"]*)"/g;
|
|
73
|
+
const ENTITY = /&(?:#(\d{1,7})|#[xX]([0-9a-fA-F]{1,6})|(amp|lt|gt|quot|apos));|&/g;
|
|
74
|
+
const NAMED = /** @type {Record<string, string>} */ ({ amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" });
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* One parsed node. Elements have a tag, attributes as a flat
|
|
78
|
+
* `[name, value, …]` list and children; text nodes have the tag `#text` and
|
|
79
|
+
* their decoded `text`. `src` is the node's own markup; `dom` the live node
|
|
80
|
+
* once drawn.
|
|
81
|
+
* @typedef {{ tag: string, attrs: string[], kids: MarkupNode[], src: string, text: string, dom: Node | null }} MarkupNode
|
|
82
|
+
*/
|
|
83
|
+
|
|
84
|
+
// Shared empty lists: a node's attributes when it has none, and a text node's
|
|
85
|
+
// children (never patched).
|
|
86
|
+
/** @type {string[]} */
|
|
87
|
+
const NO_ATTRS = [];
|
|
88
|
+
/** @type {MarkupNode[]} */
|
|
89
|
+
const NO_KIDS = [];
|
|
90
|
+
|
|
91
|
+
/** Decode entities as the HTML parser does; null for an `&` it might read differently. @param {string} s */
|
|
92
|
+
function decode(s) {
|
|
93
|
+
if (!s.includes("&")) return s;
|
|
94
|
+
let ok = true;
|
|
95
|
+
const out = s.replace(ENTITY, (m, dec, hex, name) => {
|
|
96
|
+
if (name) return NAMED[name];
|
|
97
|
+
const cp = dec ? Number(dec) : hex ? parseInt(hex, 16) : -1;
|
|
98
|
+
// Code points the HTML parser remaps or rejects are left to it.
|
|
99
|
+
if (cp < 0x20 ? cp !== 9 && cp !== 10 : (cp >= 0x7f && cp <= 0x9f) || (cp >= 0xd800 && cp <= 0xdfff) || cp > 0x10ffff) ok = false;
|
|
100
|
+
return ok ? String.fromCodePoint(cp) : m;
|
|
101
|
+
});
|
|
102
|
+
return ok ? out : null;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** @param {string} s */
|
|
106
|
+
function parseAttrs(s) {
|
|
107
|
+
/** @type {string[]} */
|
|
108
|
+
const attrs = [];
|
|
109
|
+
for (const m of s.matchAll(ATTR)) {
|
|
110
|
+
const lower = m[1].toLowerCase();
|
|
111
|
+
const name = SVG_ATTRS.get(lower) ?? lower;
|
|
112
|
+
const value = decode(m[2]);
|
|
113
|
+
if (value === null) return null;
|
|
114
|
+
// The HTML parser keeps the first of a repeated attribute.
|
|
115
|
+
if (find(attrs, name) < 0) attrs.push(name, value);
|
|
116
|
+
}
|
|
117
|
+
return attrs;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Parse markup into nodes, or return null when it is outside the subset this
|
|
122
|
+
* module reproduces exactly (see the module comment). Exported for tests.
|
|
123
|
+
* @param {string} markup
|
|
124
|
+
* @returns {MarkupNode[] | null}
|
|
125
|
+
*/
|
|
126
|
+
export function parseMarkup(markup) {
|
|
127
|
+
if (/[\r\0]/.test(markup)) return null;
|
|
128
|
+
/** @type {MarkupNode[]} */
|
|
129
|
+
const root = [];
|
|
130
|
+
/** @type {MarkupNode[]} */
|
|
131
|
+
const open = [];
|
|
132
|
+
/** @type {number[]} */
|
|
133
|
+
const starts = [];
|
|
134
|
+
let kids = root;
|
|
135
|
+
let pos = 0;
|
|
136
|
+
while (pos < markup.length) {
|
|
137
|
+
if (markup.charCodeAt(pos) !== 60 /* < */) {
|
|
138
|
+
let end = markup.indexOf("<", pos);
|
|
139
|
+
if (end < 0) end = markup.length;
|
|
140
|
+
const src = markup.slice(pos, end);
|
|
141
|
+
const text = decode(src);
|
|
142
|
+
if (text === null) return null;
|
|
143
|
+
kids.push({ tag: "#text", attrs: NO_ATTRS, kids: NO_KIDS, src, text, dom: null });
|
|
144
|
+
pos = end;
|
|
145
|
+
continue;
|
|
146
|
+
}
|
|
147
|
+
TAG.lastIndex = pos;
|
|
148
|
+
const m = TAG.exec(markup);
|
|
149
|
+
if (!m) return null;
|
|
150
|
+
const lower = m[2].toLowerCase();
|
|
151
|
+
const tag = SVG_TAGS.get(lower) ?? lower;
|
|
152
|
+
if (m[1]) {
|
|
153
|
+
if (m[3] || m[4]) return null;
|
|
154
|
+
const el = open.pop();
|
|
155
|
+
if (!el || el.tag !== tag) return null;
|
|
156
|
+
el.src = markup.slice(/** @type {number} */ (starts.pop()), TAG.lastIndex);
|
|
157
|
+
kids = open.length ? open[open.length - 1].kids : root;
|
|
158
|
+
} else {
|
|
159
|
+
const parent = open[open.length - 1];
|
|
160
|
+
if (parent ? HTML_INSIDE.has(parent.tag) || LEAVES_SVG.has(tag) : tag !== "svg") return null;
|
|
161
|
+
const attrs = m[3] ? parseAttrs(m[3]) : NO_ATTRS;
|
|
162
|
+
if (!attrs) return null;
|
|
163
|
+
/** @type {MarkupNode} */
|
|
164
|
+
const el = { tag, attrs, kids: [], src: m[0], text: "", dom: null };
|
|
165
|
+
kids.push(el);
|
|
166
|
+
if (!m[4]) {
|
|
167
|
+
open.push(el);
|
|
168
|
+
starts.push(pos);
|
|
169
|
+
kids = el.kids;
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
pos = TAG.lastIndex;
|
|
173
|
+
}
|
|
174
|
+
return open.length ? null : root;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** @param {Element} el @param {string} name @param {string} value */
|
|
178
|
+
function setAttr(el, name, value) {
|
|
179
|
+
const f = FOREIGN_ATTRS.get(name);
|
|
180
|
+
if (f) el.setAttributeNS(f[0], name, value);
|
|
181
|
+
else el.setAttribute(name, value);
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** @param {Element} el @param {string} name */
|
|
185
|
+
function removeAttr(el, name) {
|
|
186
|
+
const f = FOREIGN_ATTRS.get(name);
|
|
187
|
+
if (f) el.removeAttributeNS(f[0], f[1]);
|
|
188
|
+
else el.removeAttribute(name);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** Write the attributes that changed. @param {Element} el @param {string[]} from @param {string[]} to */
|
|
192
|
+
function patchAttrs(el, from, to) {
|
|
193
|
+
let same = from.length === to.length;
|
|
194
|
+
for (let i = 0; same && i < to.length; i += 2) same = from[i] === to[i];
|
|
195
|
+
if (same) {
|
|
196
|
+
// Same names in the same order: the usual case for an animated element.
|
|
197
|
+
for (let i = 1; i < to.length; i += 2) if (from[i] !== to[i]) setAttr(el, to[i - 1], to[i]);
|
|
198
|
+
return;
|
|
199
|
+
}
|
|
200
|
+
for (let i = 0; i < from.length; i += 2) if (find(to, from[i]) < 0) removeAttr(el, from[i]);
|
|
201
|
+
for (let i = 0; i < to.length; i += 2) {
|
|
202
|
+
const j = find(from, to[i]);
|
|
203
|
+
if (j < 0 || from[j + 1] !== to[i + 1]) setAttr(el, to[i], to[i + 1]);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** Index of an attribute's name in a flat `[name, value, …]` list, or -1. @param {string[]} attrs @param {string} name */
|
|
208
|
+
function find(attrs, name) {
|
|
209
|
+
for (let i = 0; i < attrs.length; i += 2) if (attrs[i] === name) return i;
|
|
210
|
+
return -1;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** Build a node's subtree, detached. @param {Document} doc @param {MarkupNode} node @returns {Node} */
|
|
214
|
+
function create(doc, node) {
|
|
215
|
+
if (node.tag === "#text") return (node.dom = doc.createTextNode(node.text));
|
|
216
|
+
const el = doc.createElementNS(SVG_NS, node.tag);
|
|
217
|
+
for (let i = 0; i < node.attrs.length; i += 2) setAttr(el, node.attrs[i], node.attrs[i + 1]);
|
|
218
|
+
for (const kid of node.kids) el.appendChild(create(doc, kid));
|
|
219
|
+
return (node.dom = el);
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Make `parent`'s children, drawn from `from`, match `to`. Children of `to`
|
|
224
|
+
* whose markup did not change are replaced by their `from` node, which keeps
|
|
225
|
+
* its live node and its children.
|
|
226
|
+
* @param {Document} doc @param {Node} parent @param {MarkupNode[]} from @param {MarkupNode[]} to
|
|
227
|
+
*/
|
|
228
|
+
function patchKids(doc, parent, from, to) {
|
|
229
|
+
for (let i = 0; i < to.length; i++) {
|
|
230
|
+
const next = to[i];
|
|
231
|
+
const prev = from[i];
|
|
232
|
+
if (!prev) {
|
|
233
|
+
parent.appendChild(create(doc, next));
|
|
234
|
+
} else if (prev.src === next.src) {
|
|
235
|
+
to[i] = prev;
|
|
236
|
+
} else if (prev.tag !== next.tag) {
|
|
237
|
+
parent.replaceChild(create(doc, next), /** @type {Node} */ (prev.dom));
|
|
238
|
+
} else if (next.tag === "#text") {
|
|
239
|
+
next.dom = prev.dom;
|
|
240
|
+
if (prev.text !== next.text) /** @type {Text} */ (next.dom).data = next.text;
|
|
241
|
+
} else {
|
|
242
|
+
const el = /** @type {Element} */ (prev.dom);
|
|
243
|
+
next.dom = el;
|
|
244
|
+
patchAttrs(el, prev.attrs, next.attrs);
|
|
245
|
+
patchKids(doc, el, prev.kids, next.kids);
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
for (let i = from.length - 1; i >= to.length; i--) parent.removeChild(/** @type {Node} */ (from[i].dom));
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/** What each parent shows: its nodes and the markup they came from. @type {WeakMap<Node, { kids: MarkupNode[], markup: string }>} */
|
|
252
|
+
const drawn = new WeakMap();
|
|
253
|
+
|
|
254
|
+
/** Whether the parent still holds exactly the nodes drawn last time. @param {Node} parent @param {MarkupNode[]} kids */
|
|
255
|
+
function intact(parent, kids) {
|
|
256
|
+
const nodes = parent.childNodes;
|
|
257
|
+
if (nodes.length !== kids.length) return false;
|
|
258
|
+
for (let i = 0; i < kids.length; i++) if (nodes[i] !== kids[i].dom) return false;
|
|
259
|
+
return true;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Show `markup` in `parent`, updating the nodes already there instead of
|
|
264
|
+
* replacing them. The result is the DOM `parent.innerHTML = markup` would
|
|
265
|
+
* build. Falls back to that assignment when the markup is outside the subset
|
|
266
|
+
* described in the module comment.
|
|
267
|
+
* @param {Element} parent an HTML element whose content only patchMarkup changes
|
|
268
|
+
* @param {string} markup one frame's SVG markup (renderSvg output)
|
|
269
|
+
* @returns {boolean} true when the DOM was updated in place, false when innerHTML was assigned
|
|
270
|
+
*/
|
|
271
|
+
export function patchMarkup(parent, markup) {
|
|
272
|
+
const last = drawn.get(parent);
|
|
273
|
+
const kept = last !== undefined && intact(parent, last.kids);
|
|
274
|
+
if (kept && last.markup === markup) return true;
|
|
275
|
+
const kids = parseMarkup(markup);
|
|
276
|
+
if (kids) {
|
|
277
|
+
const doc = /** @type {Document} */ (parent.ownerDocument);
|
|
278
|
+
try {
|
|
279
|
+
if (kept) patchKids(doc, parent, last.kids, kids);
|
|
280
|
+
else {
|
|
281
|
+
parent.textContent = "";
|
|
282
|
+
for (const kid of kids) parent.appendChild(create(doc, kid));
|
|
283
|
+
}
|
|
284
|
+
drawn.set(parent, { kids, markup });
|
|
285
|
+
return true;
|
|
286
|
+
} catch (e) {
|
|
287
|
+
// A name the DOM refuses (createElementNS, setAttribute) but the HTML
|
|
288
|
+
// parser accepts: let it decide. Anything else is a bug; surface it.
|
|
289
|
+
// A DOMException, possibly from another realm (an iframe's document).
|
|
290
|
+
const name = typeof e === "object" && e !== null && "name" in e ? e.name : "";
|
|
291
|
+
if (name !== "InvalidCharacterError" && name !== "NamespaceError") throw e;
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
drawn.delete(parent);
|
|
295
|
+
parent.innerHTML = markup;
|
|
296
|
+
return false;
|
|
297
|
+
}
|