@liqweed/motion-kit 0.10.0 → 0.11.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 +3 -1
- package/docs/spec/technique.md +43 -1
- package/examples/connectors.scene.mjs +199 -0
- package/package.json +2 -2
- package/runtime/connectors.mjs +243 -0
- package/runtime/kit.mjs +3 -1
- package/skills/animated-diagram/SKILL.md +3 -2
- package/skills/animated-diagram/references/custom-scenes.md +26 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +19 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "motion-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Deterministic animated diagrams: scenes as pure functions of time for live pages, Slidev, slide frames, baked SVG and video; plus project logos/icons.",
|
|
5
5
|
"author": { "name": "Ophir Radnitz" },
|
|
6
6
|
"repository": "https://github.com/liqweed/motion-kit",
|
package/README.md
CHANGED
|
@@ -58,6 +58,7 @@ runtime/ dependency-free ES modules (browser + Node)
|
|
|
58
58
|
motion.mjs easing (exact cubic-bezier), progress, critically damped spring, retarget, split edges
|
|
59
59
|
svg.mjs escaping, rounding, el/text/fade, polyline + Bézier arc-length, drawOn, several tokens
|
|
60
60
|
iso.mjs isometric kit for custom scenes: camera, solids, depth order, label anchors
|
|
61
|
+
connectors.mjs dashed connectors, diamond junctions and single-pass light pulses for custom scenes
|
|
61
62
|
wrap.mjs label wrapping with hard budgets
|
|
62
63
|
style.mjs tokens, neutral style, contrast checks, token resolution
|
|
63
64
|
scene.mjs scene contract, formats, renderSvg
|
|
@@ -72,7 +73,8 @@ adapters/ slidev (Vue), astro, element (custom element), page (README)
|
|
|
72
73
|
skills/ animated-diagram, motion-render, project-logo (Claude Code / Craft skills)
|
|
73
74
|
examples/ order-flow (sequence), smart-home (hub-spoke), incident (timeline),
|
|
74
75
|
web-stack (stack), custom-pulse (custom module),
|
|
75
|
-
isometric-swivel (custom module: isometric kit, several tokens)
|
|
76
|
+
isometric-swivel (custom module: isometric kit, several tokens),
|
|
77
|
+
connectors (custom module: connectors, diamond junctions, pulses)
|
|
76
78
|
bench/ heavy scene for npm run bench:player (live-player frame cost)
|
|
77
79
|
brand/ logo scene (built with motion-kit); renders go to assets/ + .idea/ (npm run media)
|
|
78
80
|
assets/ generated project icon: icon.svg, icon.png, icon-animated.svg
|
package/docs/spec/technique.md
CHANGED
|
@@ -48,7 +48,7 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
|
|
|
48
48
|
`sceneFromModule` (`runtime/kit.mjs`) with
|
|
49
49
|
`opts = { ...options, format, locale, kit }`. `options` are the caller's
|
|
50
50
|
serializable scene options, passed unchanged; option names `format`,
|
|
51
|
-
`locale` and `kit` throw. `kit` is the flat exports of the `motion`, `svg`, `iso`, `style`, `scene` and `wrap` runtime modules (`KIT`); it has no `createScene`, scene types or player. Both paths
|
|
51
|
+
`locale` and `kit` throw. `kit` is the flat exports of the `motion`, `svg`, `iso`, `style`, `scene`, `connectors` and `wrap` runtime modules (`KIT`); it has no `createScene`, scene types or player. Both paths
|
|
52
52
|
run `validateScene`. The CLI (`--options`), the vendored gate and the Astro
|
|
53
53
|
adapter call `sceneFromModule`, so one module with the same options, format
|
|
54
54
|
and locale gives the same scene everywhere. A `build` page calls the factory
|
|
@@ -270,6 +270,48 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
|
|
|
270
270
|
does when its progress is linear (`tokenPoints` defaults to `easeStandard`;
|
|
271
271
|
pass `ease: linear`).
|
|
272
272
|
|
|
273
|
+
### 4.10 Connectors (`runtime/connectors.mjs`)
|
|
274
|
+
|
|
275
|
+
For custom scenes that tie pieces together; handed to them in `kit`. Pure
|
|
276
|
+
functions; a colour is a token name (G4 applies).
|
|
277
|
+
|
|
278
|
+
- **Path.** `connectorPath(points, {camera?})` is a route through flat points
|
|
279
|
+
(picture pixels) or, with a `camera`, through world points projected by it.
|
|
280
|
+
`at(f)`, `cut(f)` (the picture points up to `f`) and `tip(f)` (the point and
|
|
281
|
+
the direction of travel, in radians) go by distance along the path, in the
|
|
282
|
+
world under a camera, so a pulse on a linear `ease` keeps a constant world
|
|
283
|
+
speed whatever the camera does. It throws for fewer than two points, a
|
|
284
|
+
non-finite coordinate or a path of no length.
|
|
285
|
+
- **Connector.** `drawConnector(path, p, {stroke, width, dash, arrow,
|
|
286
|
+
arrowSize, opacity, id})` draws the path up to fraction `p` (the eased
|
|
287
|
+
progress of a draw-on) as a dashed polyline: nothing for `p ≤ 0`; the dash
|
|
288
|
+
pattern (default `6 5`) starts at the path's start, so dashes stand still as
|
|
289
|
+
the line grows, and `p ≥ 1` is the dashed line it rests as. An open-V
|
|
290
|
+
arrowhead (default on) rides the leading end and fades in over the first
|
|
291
|
+
tenth of `p`.
|
|
292
|
+
- **Junction.** `drawJunction({at, camera?, plane, size, lit, fill, stroke,
|
|
293
|
+
litFill, litStroke, strokeWidth, opacity, id})` draws a diamond, a square
|
|
294
|
+
turned 45°, `size` pixels from centre to corner. `plane: "screen"` stands on
|
|
295
|
+
the picture; `"floor"` lies in the floor plane of an iso view: the same
|
|
296
|
+
diamond flattened by `sin(elevation)`, full in plan view. `lit` (0..1)
|
|
297
|
+
cross-fades the reached layer over the resting one. It throws for a size of
|
|
298
|
+
0 or less and for another plane.
|
|
299
|
+
- **Pulse.** `drawPulse(path, t, run, {color, radius})` is a light that
|
|
300
|
+
travels the connector once. `run` is `{start, duration, lag?, ease?, hold?}`:
|
|
301
|
+
the head takes `duration` s on `ease` (default `easeStandard`) and the tail
|
|
302
|
+
follows `lag` s later (default `PULSE_LAG`, 0.12 s) on the same curve, so the
|
|
303
|
+
light stretches in flight and gathers at the end (split edges, §4.5). The
|
|
304
|
+
head has a glow (three halos of one token, fainter outward) and the tail
|
|
305
|
+
fades toward its trailing end. It grows in over the first tenth of its life
|
|
306
|
+
and, unless held, fades over the last sixth. It draws nothing before `start`
|
|
307
|
+
and, without `hold`, from `pulseEnd(run)` = `start + duration + lag` on; with
|
|
308
|
+
`hold` the head stays lit at the end of the connector. `pulseHead(t, run)` is
|
|
309
|
+
the head's fraction of the path, for lighting a target as the pulse passes.
|
|
310
|
+
- **Canon.** A pulse runs once, in a step's beat, like a token (§4.8): every
|
|
311
|
+
pulse of the beat is over (`pulseEnd`) at least 50 ms before the step's `at`,
|
|
312
|
+
its target has filled, and nothing repeats while a step rests, so the
|
|
313
|
+
settled-frame rule (G6) holds. Several pulses may run in one beat.
|
|
314
|
+
|
|
273
315
|
## 5. Markup
|
|
274
316
|
|
|
275
317
|
- Text and attribute values MUST be escaped (`& < > " '`) via `esc`, `text` or
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Example custom scene: a request fans out through a diamond splitter, then a
|
|
3
|
+
* result rides an isometric feeder line through three junctions.
|
|
4
|
+
*
|
|
5
|
+
* Shows the connector parts (runtime/connectors.mjs): dashed connectors that
|
|
6
|
+
* draw on and rest as dashed lines, with open-V arrowheads; diamond junctions,
|
|
7
|
+
* flat on the picture and lying in the floor plane of an isometric view, that
|
|
8
|
+
* light when a pulse reaches them; and light pulses with a glow and a fading
|
|
9
|
+
* tail. A pulse runs once, inside its step's beat, and is over (`pulseEnd`)
|
|
10
|
+
* before the step's time, so every step frame is settled. Nothing loops: the
|
|
11
|
+
* scene plays once and holds its last frame. Pure: frame(t) depends only on
|
|
12
|
+
* t and constants.
|
|
13
|
+
*/
|
|
14
|
+
import { easeOut, easeStandard, linear, progress } from "../runtime/motion.mjs";
|
|
15
|
+
import { CAMERA_ISOMETRIC, box, drawSolid, fitCamera, labelAnchor, orderSolids, slab } from "../runtime/iso.mjs";
|
|
16
|
+
import { connectorPath, drawConnector, drawJunction, drawPulse, pulseEnd } from "../runtime/connectors.mjs";
|
|
17
|
+
import { FORMATS, localize } from "../runtime/scene.mjs";
|
|
18
|
+
import { tok } from "../runtime/style.mjs";
|
|
19
|
+
import { el, fade, text } from "../runtime/svg.mjs";
|
|
20
|
+
import { wrapLabel } from "../runtime/wrap.mjs";
|
|
21
|
+
|
|
22
|
+
export const locales = ["en", "nl"];
|
|
23
|
+
|
|
24
|
+
const COPY = {
|
|
25
|
+
title: { en: "A request fans out, then rides the feeder", nl: "Een verzoek splitst en volgt de aanvoerlijn" },
|
|
26
|
+
description: {
|
|
27
|
+
en: "A request crosses a diamond splitter and fans out to three services; a result then rides an isometric feeder line through three junctions to the shelf.",
|
|
28
|
+
nl: "Een verzoek passeert een ruitvormige splitser en waaiert uit naar drie diensten; een resultaat volgt daarna een isometrische aanvoerlijn langs drie knooppunten naar het schap.",
|
|
29
|
+
},
|
|
30
|
+
source: { en: "Request", nl: "Verzoek" },
|
|
31
|
+
targets: [
|
|
32
|
+
{ en: "Search", nl: "Zoeken" },
|
|
33
|
+
{ en: "Cache", nl: "Cache" },
|
|
34
|
+
{ en: "Audit", nl: "Logboek" },
|
|
35
|
+
],
|
|
36
|
+
stations: [
|
|
37
|
+
{ en: "Intake", nl: "Intake" },
|
|
38
|
+
{ en: "Shelf", nl: "Schap" },
|
|
39
|
+
],
|
|
40
|
+
steps: [
|
|
41
|
+
{ label: { en: "Request reaches the splitter", nl: "Verzoek bereikt de splitser" }, detail: { en: "One pulse crosses the first connector and lights the diamond.", nl: "Eén puls steekt de eerste verbinding over en laat de ruit oplichten." } },
|
|
42
|
+
{ label: { en: "It fans out", nl: "Het waaiert uit" }, detail: { en: "Three pulses leave the splitter together and light their services.", nl: "Drie pulsen verlaten de splitser tegelijk en laten hun diensten oplichten." } },
|
|
43
|
+
{ label: { en: "The feeder delivers", nl: "De aanvoerlijn levert" }, detail: { en: "A pulse rides the isometric feeder through three junctions to the shelf.", nl: "Een puls volgt de isometrische aanvoerlijn langs drie knooppunten naar het schap." } },
|
|
44
|
+
],
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
// Timeline, in seconds. Every pulse is over, and its target has lit, before the
|
|
48
|
+
// step that follows it; the gate checks the step frames are settled.
|
|
49
|
+
const ENTER = 0.4;
|
|
50
|
+
const DRAW = 0.5;
|
|
51
|
+
const FILL = 0.25;
|
|
52
|
+
const IN = { start: 2, duration: 0.6 };
|
|
53
|
+
const OUT = { start: 3.2, duration: 0.7 };
|
|
54
|
+
const FEED = { start: 4.5, duration: 1.6, ease: linear };
|
|
55
|
+
const STEP_SPLIT = pulseEnd(IN) + FILL + 0.1;
|
|
56
|
+
const STEP_FAN = pulseEnd(OUT) + FILL + 0.1;
|
|
57
|
+
const STEP_FEED = pulseEnd(FEED) + FILL + 0.1;
|
|
58
|
+
const DURATION = STEP_FEED + 0.35;
|
|
59
|
+
|
|
60
|
+
// The feeder, in world units: a floor, two stations and a path with three turns.
|
|
61
|
+
const FLOOR = { w: 10, d: 6.4, h: 0.3 };
|
|
62
|
+
const TOP = FLOOR.h;
|
|
63
|
+
const STATIONS = [
|
|
64
|
+
{ x: -3.6, y: -1.8, w: 1.6, d: 1.6, h: 0.8 },
|
|
65
|
+
{ x: 1.8, y: 1.9, w: 1.6, d: 1.6, h: 0.8 },
|
|
66
|
+
];
|
|
67
|
+
const FEEDER = [
|
|
68
|
+
{ x: -2.6, y: -1.8 },
|
|
69
|
+
{ x: -0.6, y: -1.8 },
|
|
70
|
+
{ x: -0.6, y: -0.4 },
|
|
71
|
+
{ x: 1.8, y: -0.4 },
|
|
72
|
+
{ x: 1.8, y: 0.9 },
|
|
73
|
+
].map((p) => ({ ...p, z: TOP }));
|
|
74
|
+
const TURNS = [1, 2, 3];
|
|
75
|
+
|
|
76
|
+
export default function make({ format = "16:9", locale = "en" } = {}) {
|
|
77
|
+
const f = FORMATS[format];
|
|
78
|
+
if (!f) throw new Error(`unknown format "${format}"`);
|
|
79
|
+
const W = f.width;
|
|
80
|
+
const H = f.height || (format === "tall" ? 640 : 360);
|
|
81
|
+
const fs = 15;
|
|
82
|
+
|
|
83
|
+
// Two panels, one above the other: the flat fan-out, then the isometric feeder.
|
|
84
|
+
const split = Math.round(H * 0.4);
|
|
85
|
+
const flat = { x: 16, y: 12, w: W - 32, h: split - 16 };
|
|
86
|
+
const iso = { x: 16, y: split + 4, w: W - 32, h: H - split - 16 };
|
|
87
|
+
|
|
88
|
+
/* ---- the flat fan-out ---- */
|
|
89
|
+
const along = flat.w / flat.h >= 1.4 ? "x" : "y"; // the direction the flow runs
|
|
90
|
+
const span = along === "x" ? flat.w : flat.h;
|
|
91
|
+
const cross = along === "x" ? flat.h : flat.w;
|
|
92
|
+
const gap = along === "x" ? Math.min(64, (cross - 40) / 2.4) : Math.min(170, (cross - 16) / 3); // between targets, across the flow
|
|
93
|
+
const nodeAcross = along === "x" ? 40 : Math.min(150, gap - 12);
|
|
94
|
+
const nodeAlong = along === "x" ? Math.min(150, span * 0.22) : 40;
|
|
95
|
+
const nodeW = along === "x" ? nodeAlong : nodeAcross;
|
|
96
|
+
const nodeH = along === "x" ? nodeAcross : nodeAlong;
|
|
97
|
+
/** @param {number} a along the flow, from the panel's start @param {number} b across it, from its middle */
|
|
98
|
+
const at = (a, b) => (along === "x" ? { x: flat.x + a, y: flat.y + flat.h / 2 + b } : { x: flat.x + flat.w / 2 + b, y: flat.y + a });
|
|
99
|
+
const ha = nodeAlong / 2;
|
|
100
|
+
const aSource = ha + 6;
|
|
101
|
+
const aSplit = span * 0.42;
|
|
102
|
+
const aTarget = span - ha - 6;
|
|
103
|
+
const spread = [-gap, 0, gap];
|
|
104
|
+
const MARK = 4; // clearance between a connector's end and a node
|
|
105
|
+
|
|
106
|
+
const toSplit = connectorPath([at(aSource + ha + MARK, 0), at(aSplit, 0)]);
|
|
107
|
+
const fan = spread.map((b) => connectorPath(b === 0 ? [at(aSplit, 0), at(aTarget - ha - MARK, 0)] : [at(aSplit, 0), at(aSplit, b), at(aTarget - ha - MARK, b)]));
|
|
108
|
+
const names = [COPY.source, ...COPY.targets].map((s) => wrapLabel(localize(s, locale), Math.floor((nodeW - 16) / (fs * 0.56)), 1));
|
|
109
|
+
const nodes = [at(aSource, 0), ...spread.map((b) => at(aTarget, b))];
|
|
110
|
+
|
|
111
|
+
/* ---- the isometric feeder ---- */
|
|
112
|
+
const extent = [
|
|
113
|
+
...[-1, 1].flatMap((sx) => [-1, 1].map((sy) => ({ x: (sx * FLOOR.w) / 2, y: (sy * FLOOR.d) / 2, z: 0 }))),
|
|
114
|
+
...STATIONS.flatMap((s) => [-1, 1].flatMap((dx) => [-1, 1].map((dy) => ({ x: s.x + (dx * s.w) / 2, y: s.y + (dy * s.d) / 2, z: TOP + s.h })))),
|
|
115
|
+
];
|
|
116
|
+
const fitted = fitCamera(extent, CAMERA_ISOMETRIC, { width: iso.w, height: iso.h, margin: { top: 70, right: 8, bottom: 8, left: 8 } });
|
|
117
|
+
const cam = { ...fitted, pan: { x: fitted.pan.x + iso.x, y: fitted.pan.y + iso.y } };
|
|
118
|
+
const feeder = connectorPath(FEEDER, { camera: cam });
|
|
119
|
+
// A junction lights when the pulse reaches it, at a constant speed (`ease: linear`).
|
|
120
|
+
let travelled = 0;
|
|
121
|
+
const reach = FEEDER.map((p, i) => {
|
|
122
|
+
if (i > 0) travelled += Math.hypot(p.x - FEEDER[i - 1].x, p.y - FEEDER[i - 1].y);
|
|
123
|
+
return travelled;
|
|
124
|
+
}).map((d) => FEED.start + (d / travelled) * FEED.duration);
|
|
125
|
+
const stationNames = COPY.stations.map((s) => wrapLabel(localize(s, locale), 12, 2));
|
|
126
|
+
|
|
127
|
+
/** A flat node: pending, with the reached layer cross-faded over it. */
|
|
128
|
+
function node(/** @type {{ x: number, y: number }} */ c, /** @type {string[]} */ lines, /** @type {number} */ lit) {
|
|
129
|
+
const layer = (/** @type {string} */ fill, /** @type {string} */ stroke, /** @type {string} */ ink) =>
|
|
130
|
+
el(
|
|
131
|
+
"g",
|
|
132
|
+
{},
|
|
133
|
+
el("rect", { x: c.x - nodeW / 2, y: c.y - nodeH / 2, width: nodeW, height: nodeH, rx: 8, fill: tok(fill), stroke: tok(stroke), "stroke-width": 2 }),
|
|
134
|
+
text({ x: c.x, y: c.y, "text-anchor": "middle", "dominant-baseline": "central", "font-size": fs, "font-weight": 600, fill: tok(ink) }, lines),
|
|
135
|
+
);
|
|
136
|
+
return layer("surface", "line", "ink") + fade(lit, {}, layer("accent", "accent", "onAccent"));
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** The feeder's stations at time t: pending, and the reached layer over the last. */
|
|
140
|
+
function stations(/** @type {number} */ t) {
|
|
141
|
+
const enter = progress(t, 0.2, ENTER, easeOut);
|
|
142
|
+
const lit = [0, progress(t, FEED.start + FEED.duration, FILL, easeStandard)];
|
|
143
|
+
const make = STATIONS.map((s, i) => ({ base: box({ x: s.x, y: s.y, w: s.w, d: s.d, h: s.h, z: TOP, fill: "surface", opacity: enter, id: String(i) }), on: box({ x: s.x, y: s.y, w: s.w, d: s.d, h: s.h, z: TOP, fill: "accent", id: String(i) }), lit: lit[i] }));
|
|
144
|
+
return make;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function labels(/** @type {number} */ t) {
|
|
148
|
+
const opacity = progress(t, 0.5, ENTER);
|
|
149
|
+
return STATIONS.map((s, i) => labelAnchor(cam, { id: `station-${i}`, at: { x: s.x, y: s.y, z: TOP + s.h }, lines: stationNames[i], fontSize: fs, lift: 30, opacity }));
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function frame(/** @type {number} */ t) {
|
|
153
|
+
const out = [];
|
|
154
|
+
// The flat fan-out: connectors, then the splitter and its elbows, nodes, and the pulses on top.
|
|
155
|
+
const nodeIn = (/** @type {number} */ i) => progress(t, i * 0.1, ENTER, easeOut);
|
|
156
|
+
const litAt = (/** @type {number} */ from) => progress(t, from, FILL, easeStandard);
|
|
157
|
+
const lit = [0, ...fan.map(() => litAt(OUT.start + OUT.duration))];
|
|
158
|
+
nodes.forEach((c, i) => out.push(fade(nodeIn(i), {}, node(c, names[i], lit[i]))));
|
|
159
|
+
out.push(drawConnector(toSplit, progress(t, 0.35, DRAW, easeStandard)));
|
|
160
|
+
fan.forEach((c, i) => out.push(drawConnector(c, progress(t, 0.7 + i * 0.05, DRAW, easeStandard))));
|
|
161
|
+
spread.forEach((b, i) => {
|
|
162
|
+
if (b !== 0) out.push(drawJunction({ at: at(aSplit, b), size: 5, opacity: progress(t, 0.7 + i * 0.05, ENTER, easeOut) }));
|
|
163
|
+
});
|
|
164
|
+
out.push(drawJunction({ at: at(aSplit, 0), size: 10, lit: litAt(IN.start + IN.duration), opacity: progress(t, 0.3, ENTER, easeOut) }));
|
|
165
|
+
out.push(drawPulse(toSplit, t, IN));
|
|
166
|
+
fan.forEach((c) => out.push(drawPulse(c, t, OUT)));
|
|
167
|
+
|
|
168
|
+
// The isometric feeder: floor, stations far to near, the line, its junctions on the floor, the pulse.
|
|
169
|
+
out.push(drawSolid(slab({ x: 0, y: 0, w: FLOOR.w, d: FLOOR.d, h: FLOOR.h, fill: "bg", opacity: progress(t, 0, ENTER) }), cam));
|
|
170
|
+
const st = stations(t);
|
|
171
|
+
for (const base of orderSolids(st.map((s) => s.base), cam)) {
|
|
172
|
+
const s = st[Number(base.id)];
|
|
173
|
+
out.push(drawSolid(base, cam), s.lit > 0 ? fade(s.lit, {}, drawSolid(s.on, cam)) : "");
|
|
174
|
+
}
|
|
175
|
+
out.push(drawConnector(feeder, progress(t, 0.9, 0.9, easeStandard)));
|
|
176
|
+
for (const i of TURNS) out.push(drawJunction({ at: FEEDER[i], camera: cam, plane: "floor", size: 9, lit: progress(t, reach[i], FILL, easeStandard), opacity: progress(t, 1 + i * 0.1, ENTER, easeOut) }));
|
|
177
|
+
out.push(drawPulse(feeder, t, FEED));
|
|
178
|
+
out.push(...labels(t).map((l) => l.markup));
|
|
179
|
+
return out.join("");
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
return {
|
|
183
|
+
id: `connectors-${format.replace(":", "x")}`,
|
|
184
|
+
width: W,
|
|
185
|
+
height: H,
|
|
186
|
+
duration: DURATION,
|
|
187
|
+
title: localize(COPY.title, locale),
|
|
188
|
+
description: localize(COPY.description, locale),
|
|
189
|
+
// Steps are beats of the story: their labels live in the player's controls, not in the drawing.
|
|
190
|
+
stepLabelsInFrame: false,
|
|
191
|
+
steps: [
|
|
192
|
+
{ at: STEP_SPLIT, ...COPY.steps[0] },
|
|
193
|
+
{ at: STEP_FAN, ...COPY.steps[1] },
|
|
194
|
+
{ at: STEP_FEED, ...COPY.steps[2] },
|
|
195
|
+
].map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
|
|
196
|
+
labelBoxes: (/** @type {number} */ t) => labels(t).map((l) => l.box),
|
|
197
|
+
frame,
|
|
198
|
+
};
|
|
199
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@liqweed/motion-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Deterministic animated diagrams: scenes as pure functions of time, for live pages, slides, baked SVG and video.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"animation",
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
"prepare": "lefthook install || true",
|
|
48
48
|
"test": "node --test test/*.test.mjs",
|
|
49
49
|
"typecheck": "tsc -p .",
|
|
50
|
-
"check": "node cli/motion-kit.mjs check examples/order-flow.json examples/smart-home.json examples/release-pipeline.json examples/agent-loop.json examples/integrations.json examples/incident.json examples/web-stack.json examples/custom-pulse.scene.mjs examples/isometric-swivel.scene.mjs brand/logo.scene.mjs examples/player-states.json examples/checkout.json examples/connection.json examples/pull-request.json",
|
|
50
|
+
"check": "node cli/motion-kit.mjs check examples/order-flow.json examples/smart-home.json examples/release-pipeline.json examples/agent-loop.json examples/integrations.json examples/incident.json examples/web-stack.json examples/custom-pulse.scene.mjs examples/isometric-swivel.scene.mjs examples/connectors.scene.mjs brand/logo.scene.mjs examples/player-states.json examples/checkout.json examples/connection.json examples/pull-request.json",
|
|
51
51
|
"media": "scripts/render-media.sh",
|
|
52
52
|
"media:check": "scripts/render-media.sh --check",
|
|
53
53
|
"site": "npm run -w website build",
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Copyright (c) 2026 Ophir Radnitz
|
|
3
|
+
/**
|
|
4
|
+
* motion-kit · connectors, for custom scenes (`kit`).
|
|
5
|
+
*
|
|
6
|
+
* Parts that tie a diagram's pieces together, as pure functions of time:
|
|
7
|
+
*
|
|
8
|
+
* - a **connector**: a dashed line along a flat polyline or a path through the
|
|
9
|
+
* world (seen through an iso camera), with an optional open-V arrowhead. It
|
|
10
|
+
* draws on from its start, the dash pattern anchored there, and rests as a
|
|
11
|
+
* dashed line (`connectorPath`, `drawConnector`);
|
|
12
|
+
* - a **junction**: a small diamond where connectors turn, split or join, flat
|
|
13
|
+
* on the picture or lying in the floor plane of an iso view, that lights when
|
|
14
|
+
* a pulse reaches it (`drawJunction`);
|
|
15
|
+
* - a **pulse**: a light that travels a connector once, from its start to its
|
|
16
|
+
* end, with a glow and a short fading tail, and is gone (or held at the end)
|
|
17
|
+
* when it arrives (`drawPulse`, `pulseEnd`).
|
|
18
|
+
*
|
|
19
|
+
* Nothing here repeats. A pulse is one run inside a step's beat, as a token is;
|
|
20
|
+
* the scene keeps the steps settled by having every pulse over (`pulseEnd`) at
|
|
21
|
+
* least 50 ms before the step's time. Colours are token names, never literals.
|
|
22
|
+
*
|
|
23
|
+
* Imports stay single-line named imports: lib/bundle.mjs inlines only that form.
|
|
24
|
+
*/
|
|
25
|
+
import { clamp01, easeStandard, progress } from "./motion.mjs";
|
|
26
|
+
import { projector } from "./iso.mjs";
|
|
27
|
+
import { tok } from "./style.mjs";
|
|
28
|
+
import { el, fade, num } from "./svg.mjs";
|
|
29
|
+
|
|
30
|
+
/** @import { Camera } from "./iso.mjs" */
|
|
31
|
+
/** @typedef {{ x: number, y: number, z?: number }} Vertex a flat point (z ignored) or a world point */
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* @typedef {{
|
|
35
|
+
* length: number,
|
|
36
|
+
* at: (f: number) => { x: number, y: number },
|
|
37
|
+
* cut: (f: number) => { x: number, y: number }[],
|
|
38
|
+
* span: (from: number, to: number) => { x: number, y: number }[],
|
|
39
|
+
* tip: (f: number) => { x: number, y: number, angle: number },
|
|
40
|
+
* }} ConnectorPath
|
|
41
|
+
* `length` is the length of the path in its own units (pixels when flat, world
|
|
42
|
+
* units under a camera). `at(f)` is the picture position at fraction `f` of
|
|
43
|
+
* that length, `cut(f)` the picture points of the path up to `f`, `span(from, to)` those
|
|
44
|
+
* between two fractions (every route vertex between them, so a corner stays a
|
|
45
|
+
* corner), and `tip(f)`
|
|
46
|
+
* the position at `f` with the direction of travel there, in radians.
|
|
47
|
+
*/
|
|
48
|
+
|
|
49
|
+
/** @param {number} n */
|
|
50
|
+
const finite = (n) => typeof n === "number" && Number.isFinite(n);
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* A connector's route: through flat `points` (picture pixels), or, with a
|
|
54
|
+
* `camera`, through world points `{ x, y, z }` projected by it. Positions go by
|
|
55
|
+
* distance along the path (in the world under a camera), so a pulse on a linear
|
|
56
|
+
* `ease` keeps a constant speed in the world whatever the camera does.
|
|
57
|
+
* @param {Vertex[]} points
|
|
58
|
+
* @param {{ camera?: Camera }} [opts]
|
|
59
|
+
* @returns {ConnectorPath}
|
|
60
|
+
*/
|
|
61
|
+
export function connectorPath(points, { camera } = {}) {
|
|
62
|
+
if (!Array.isArray(points) || points.length < 2) throw new Error("connectorPath: needs at least two points");
|
|
63
|
+
for (const p of points) if (!p || !finite(p.x) || !finite(p.y) || (p.z !== undefined && !finite(p.z))) throw new Error("connectorPath: points must be finite { x, y, z? }");
|
|
64
|
+
const world = camera ? points.map((p) => ({ x: p.x, y: p.y, z: p.z ?? 0 })) : points.map((p) => ({ x: p.x, y: p.y, z: 0 }));
|
|
65
|
+
const to = camera ? projector(camera) : (/** @type {Vertex} */ p) => ({ x: p.x, y: p.y });
|
|
66
|
+
const starts = [0];
|
|
67
|
+
for (let i = 1; i < world.length; i++) starts.push(starts[i - 1] + Math.hypot(world[i].x - world[i - 1].x, world[i].y - world[i - 1].y, world[i].z - world[i - 1].z));
|
|
68
|
+
const length = starts[starts.length - 1];
|
|
69
|
+
if (!Number.isFinite(length)) throw new Error("connectorPath: the path needs a finite length");
|
|
70
|
+
if (!(length > 0)) throw new Error("connectorPath: the path has no length");
|
|
71
|
+
|
|
72
|
+
/** The segment holding distance `d`, skipping any of zero length, and where in it. */
|
|
73
|
+
const locate = (/** @type {number} */ f) => {
|
|
74
|
+
const d = clamp01(f) * length;
|
|
75
|
+
let i = 1;
|
|
76
|
+
while (i < world.length - 1 && (d > starts[i] || starts[i] === starts[i - 1])) i++;
|
|
77
|
+
const span = starts[i] - starts[i - 1];
|
|
78
|
+
return { i, k: span === 0 ? 0 : Math.min(1, Math.max(0, (d - starts[i - 1]) / span)) };
|
|
79
|
+
};
|
|
80
|
+
const worldAt = (/** @type {number} */ f) => {
|
|
81
|
+
const { i, k } = locate(f);
|
|
82
|
+
const a = world[i - 1];
|
|
83
|
+
const b = world[i];
|
|
84
|
+
return { x: a.x + (b.x - a.x) * k, y: a.y + (b.y - a.y) * k, z: a.z + (b.z - a.z) * k };
|
|
85
|
+
};
|
|
86
|
+
return {
|
|
87
|
+
length,
|
|
88
|
+
at: (f) => to(worldAt(f)),
|
|
89
|
+
cut(f) {
|
|
90
|
+
const { i } = locate(f);
|
|
91
|
+
return [...world.slice(0, i), worldAt(f)].map((p) => {
|
|
92
|
+
const s = to(p);
|
|
93
|
+
return { x: s.x, y: s.y };
|
|
94
|
+
});
|
|
95
|
+
},
|
|
96
|
+
span(from, to0) {
|
|
97
|
+
const a = clamp01(from);
|
|
98
|
+
const b = clamp01(to0);
|
|
99
|
+
const inner = world.filter((_, j) => starts[j] / length > a && starts[j] / length < b);
|
|
100
|
+
return [worldAt(a), ...inner, worldAt(b)].map((p) => {
|
|
101
|
+
const s = to(p);
|
|
102
|
+
return { x: s.x, y: s.y };
|
|
103
|
+
});
|
|
104
|
+
},
|
|
105
|
+
tip(f) {
|
|
106
|
+
const { i } = locate(f);
|
|
107
|
+
const here = to(worldAt(f));
|
|
108
|
+
// The direction of the segment at `f`; a segment that is a point on the picture
|
|
109
|
+
// (straight up in plan view, say) takes the nearest one before it that is not.
|
|
110
|
+
for (let j = i; j >= 1; j--) {
|
|
111
|
+
const a = to(world[j - 1]);
|
|
112
|
+
const b = to(world[j]);
|
|
113
|
+
if (Math.hypot(b.x - a.x, b.y - a.y) > 1e-6) return { x: here.x, y: here.y, angle: Math.atan2(b.y - a.y, b.x - a.x) };
|
|
114
|
+
}
|
|
115
|
+
return { x: here.x, y: here.y, angle: 0 };
|
|
116
|
+
},
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* A connector drawn up to fraction `p` of its path (`p` as the eased progress of
|
|
122
|
+
* a draw-on, 0..1): a dashed polyline in the token `stroke`, whose dash pattern
|
|
123
|
+
* starts at the path's start, so the dashes stand still as the line grows and
|
|
124
|
+
* the finished line is the dashed line it rests as. With `arrow` an open-V
|
|
125
|
+
* arrowhead rides the leading end, fading in over the first tenth of the
|
|
126
|
+
* draw-on. Nothing for `p` ≤ 0.
|
|
127
|
+
* @param {ConnectorPath} path
|
|
128
|
+
* @param {number} p
|
|
129
|
+
* @param {{ stroke?: string, width?: number, dash?: [number, number], arrow?: boolean, arrowSize?: number, opacity?: number, id?: string }} [o]
|
|
130
|
+
* @returns {string}
|
|
131
|
+
*/
|
|
132
|
+
export function drawConnector(path, p, { stroke = "line", width = 1.5, dash = [6, 5], arrow = true, arrowSize = 9, opacity = 1, id } = {}) {
|
|
133
|
+
if (p <= 0) return "";
|
|
134
|
+
const color = tok(stroke);
|
|
135
|
+
const pts = path.cut(p);
|
|
136
|
+
const d = pts.map((q, i) => `${i === 0 ? "M" : "L"}${num(q.x)} ${num(q.y)}`).join(" ");
|
|
137
|
+
const line = el("path", { d, fill: "none", stroke: color, "stroke-width": width, "stroke-dasharray": `${num(dash[0])} ${num(dash[1])}`, "stroke-linejoin": "round" });
|
|
138
|
+
let head = "";
|
|
139
|
+
if (arrow) {
|
|
140
|
+
const { x, y, angle } = path.tip(p);
|
|
141
|
+
const spread = (28 * Math.PI) / 180;
|
|
142
|
+
const wing = (/** @type {number} */ s) => `${num(x - arrowSize * Math.cos(angle + s))} ${num(y - arrowSize * Math.sin(angle + s))}`;
|
|
143
|
+
head = fade(clamp01(p / 0.1), {}, el("path", { d: `M${wing(spread)} L${num(x)} ${num(y)} L${wing(-spread)}`, fill: "none", stroke: color, "stroke-width": width, "stroke-linecap": "round", "stroke-linejoin": "round" }));
|
|
144
|
+
}
|
|
145
|
+
return fade(opacity, id ? { "data-connector": id } : {}, line, head);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* A diamond junction, centred where connectors turn, split or join: a small
|
|
150
|
+
* square turned 45°, `size` pixels from its centre to a corner. `plane:
|
|
151
|
+
* "screen"` (default) stands on the picture; `"floor"` lies in the floor plane
|
|
152
|
+
* of an iso view, which is the same diamond flattened by `sin(elevation)`, so
|
|
153
|
+
* it is a full diamond in plan view and a flat one in isometric. `lit` (0..1)
|
|
154
|
+
* cross-fades a second layer (`litFill`, `litStroke`) over the resting one, for
|
|
155
|
+
* the moment a pulse arrives.
|
|
156
|
+
* @param {{ at: Vertex, camera?: Camera, plane?: "screen" | "floor", size?: number, lit?: number, fill?: string, stroke?: string, litFill?: string, litStroke?: string, strokeWidth?: number, opacity?: number, id?: string }} o
|
|
157
|
+
* `at` is a flat point, or a world point when `camera` is given.
|
|
158
|
+
* @returns {string}
|
|
159
|
+
*/
|
|
160
|
+
export function drawJunction({ at, camera, plane = "screen", size = 7, lit = 0, fill = "surface", stroke = "line", litFill = "accent", litStroke = "accent", strokeWidth = 1.5, opacity = 1, id }) {
|
|
161
|
+
if (!finite(size) || size <= 0) throw new Error(`drawJunction: size must be a positive number, got ${size}`);
|
|
162
|
+
if (plane !== "screen" && plane !== "floor") throw new Error(`drawJunction: plane must be "screen" or "floor", got "${plane}"`);
|
|
163
|
+
const c = camera ? projector(camera)({ x: at.x, y: at.y, z: at.z ?? 0 }) : at;
|
|
164
|
+
const ry = plane === "floor" && camera ? size * Math.sin((camera.elevation * Math.PI) / 180) : size;
|
|
165
|
+
const d = `M${num(c.x)} ${num(c.y - ry)} L${num(c.x + size)} ${num(c.y)} L${num(c.x)} ${num(c.y + ry)} L${num(c.x - size)} ${num(c.y)} Z`;
|
|
166
|
+
const layer = (/** @type {string} */ f, /** @type {string} */ s) => el("path", { d, fill: tok(f), stroke: tok(s), "stroke-width": strokeWidth, "stroke-linejoin": "round" });
|
|
167
|
+
return fade(opacity, id ? { "data-junction": id } : {}, layer(fill, stroke), fade(lit, {}, layer(litFill, litStroke)));
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** Seconds the pulse's tail trails its head by, unless a run sets `lag`. */
|
|
171
|
+
export const PULSE_LAG = 0.12;
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* One pulse's journey: it starts at `start` s, its head takes `duration` s along
|
|
175
|
+
* the connector on `ease` (default `easeStandard`), and its tail follows `lag` s
|
|
176
|
+
* later on the same curve (split edges), so the light stretches in flight and
|
|
177
|
+
* gathers at the end. The pulse grows in over the first tenth of its life and,
|
|
178
|
+
* unless it is held, fades over the last sixth; with `hold` the head stays lit
|
|
179
|
+
* at the end of the connector once the tail has gathered.
|
|
180
|
+
* @typedef {{ start: number, duration: number, lag?: number, ease?: (p: number) => number, hold?: boolean }} PulseRun
|
|
181
|
+
*/
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* The time a pulse is over (or, held, at rest): `start + duration + lag`. A
|
|
185
|
+
* scene's step comes at least 50 ms after this for every pulse of its beat.
|
|
186
|
+
* @param {PulseRun} run
|
|
187
|
+
* @returns {number}
|
|
188
|
+
*/
|
|
189
|
+
export function pulseEnd(run) {
|
|
190
|
+
return run.start + run.duration + (run.lag ?? PULSE_LAG);
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Where a pulse's head is on its connector, as a fraction 0..1 of the path, at
|
|
195
|
+
* time `t` (0 before it starts, 1 once it has arrived), for a scene that lights
|
|
196
|
+
* a target as the pulse passes it.
|
|
197
|
+
* @param {number} t
|
|
198
|
+
* @param {PulseRun} run
|
|
199
|
+
* @returns {number}
|
|
200
|
+
*/
|
|
201
|
+
export function pulseHead(t, run) {
|
|
202
|
+
return progress(t, run.start, run.duration, run.ease ?? easeStandard);
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
const TAIL_SLICES = 6;
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* A pulse at time `t`: a bright head with a soft glow (three halos in the same
|
|
209
|
+
* token, fainter outward) and a tail of short slices that fade toward the
|
|
210
|
+
* trailing end. Empty before the run starts and, unless it is held, after
|
|
211
|
+
* `pulseEnd(run)`.
|
|
212
|
+
* @param {ConnectorPath} path
|
|
213
|
+
* @param {number} t
|
|
214
|
+
* @param {PulseRun} run
|
|
215
|
+
* @param {{ color?: string, radius?: number }} [o] `color` is a token (default `emphasis`), `radius` the head's, in pixels
|
|
216
|
+
* @returns {string}
|
|
217
|
+
*/
|
|
218
|
+
export function drawPulse(path, t, run, { color = "emphasis", radius = 4 } = {}) {
|
|
219
|
+
const lag = run.lag ?? PULSE_LAG;
|
|
220
|
+
const ease = run.ease ?? easeStandard;
|
|
221
|
+
const lead = progress(t, run.start, run.duration, ease);
|
|
222
|
+
if (lead <= 0) return "";
|
|
223
|
+
if (t >= pulseEnd(run) && !run.hold) return "";
|
|
224
|
+
const total = run.duration + lag;
|
|
225
|
+
const life = total > 0 ? (t - run.start) / total : 1; // an instantaneous run is already at its end
|
|
226
|
+
const trail = progress(t, run.start + lag, run.duration, ease);
|
|
227
|
+
const env = clamp01(Math.min(life / 0.1, run.hold ? 1 : (1 - life) / (1 / 6)));
|
|
228
|
+
if (env < 0.001) return "";
|
|
229
|
+
const fill = tok(color);
|
|
230
|
+
const out = [];
|
|
231
|
+
if (lead - trail > 1e-6) {
|
|
232
|
+
for (let i = 0; i < TAIL_SLICES; i++) {
|
|
233
|
+
// Each slice follows the route, so it turns at a corner between its ends.
|
|
234
|
+
const pts = path.span(trail + ((lead - trail) * i) / TAIL_SLICES, trail + ((lead - trail) * (i + 1)) / TAIL_SLICES);
|
|
235
|
+
const k = (i + 1) / TAIL_SLICES;
|
|
236
|
+
out.push(el("path", { d: pts.map((q, j) => `${j === 0 ? "M" : "L"}${num(q.x)} ${num(q.y)}`).join(" "), fill: "none", stroke: fill, "stroke-width": radius * 2 * (0.3 + 0.7 * k) * env, "stroke-linecap": "round", "stroke-linejoin": "round", opacity: 0.5 * k * env }));
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
const head = path.at(lead);
|
|
240
|
+
for (const [grow, alpha] of [[3.2, 0.1], [2.2, 0.16], [1.5, 0.26]]) out.push(el("circle", { cx: head.x, cy: head.y, r: radius * grow * env, fill, opacity: alpha * env }));
|
|
241
|
+
out.push(el("circle", { cx: head.x, cy: head.y, r: radius * env, fill }));
|
|
242
|
+
return out.join("");
|
|
243
|
+
}
|
package/runtime/kit.mjs
CHANGED
|
@@ -26,11 +26,12 @@ import { FORMATS, localize, renderSvg, safeId, stepIndex, stepIndexAt, stepTimes
|
|
|
26
26
|
import { CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, contrastReport, cssVars, normalizeStyle, resolveTokens, sharedPairs, tok } from "./style.mjs";
|
|
27
27
|
import { CAMERA_ISOMETRIC, CAMERA_PLAN, ISO_ELEVATION, box, camera, drawSolid, drawSolids, fitCamera, labelAnchor, labelProblems, lerpCamera, orderSolids, path3, prism, project, projector, regularPolygon, slab } from "./iso.mjs";
|
|
28
28
|
import { attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, tokenPoints, tokensAlong, translate, trimSegment } from "./svg.mjs";
|
|
29
|
+
import { PULSE_LAG, connectorPath, drawConnector, drawJunction, drawPulse, pulseEnd, pulseHead } from "./connectors.mjs";
|
|
29
30
|
import { estimateWidth, wrapLabel } from "./wrap.mjs";
|
|
30
31
|
|
|
31
32
|
/**
|
|
32
33
|
* The runtime, flat, handed to custom scene modules as `opts.kit`: the exports
|
|
33
|
-
* of motion, scene, style, svg, iso and wrap (not the scene types or the player).
|
|
34
|
+
* of motion, scene, style, svg, iso, connectors and wrap (not the scene types or the player).
|
|
34
35
|
* Named imports, because lib/bundle.mjs inlines only that form; a new export
|
|
35
36
|
* in one of those modules is added here (test/runtime.test.mjs checks).
|
|
36
37
|
*/
|
|
@@ -40,6 +41,7 @@ export const KIT = Object.freeze({
|
|
|
40
41
|
...{ CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, contrastReport, cssVars, normalizeStyle, resolveTokens, sharedPairs, tok },
|
|
41
42
|
...{ attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, tokenPoints, tokensAlong, translate, trimSegment },
|
|
42
43
|
...{ CAMERA_ISOMETRIC, CAMERA_PLAN, ISO_ELEVATION, box, camera, drawSolid, drawSolids, fitCamera, labelAnchor, labelProblems, lerpCamera, orderSolids, path3, prism, project, projector, regularPolygon, slab },
|
|
44
|
+
...{ PULSE_LAG, connectorPath, drawConnector, drawJunction, drawPulse, pulseEnd, pulseHead },
|
|
43
45
|
...{ estimateWidth, wrapLabel },
|
|
44
46
|
});
|
|
45
47
|
|
|
@@ -58,7 +58,8 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
|
|
|
58
58
|
flowchart? `motion-kit import flow.mmd --out flow.json` writes the spec
|
|
59
59
|
(layout computed once). Only write a custom scene module when no type fits
|
|
60
60
|
(`references/custom-scenes.md`): that file also covers an isometric view
|
|
61
|
-
(camera, solids, depth order, label anchors)
|
|
61
|
+
(camera, solids, depth order, label anchors), several tokens moving at once and
|
|
62
|
+
dashed connectors with diamond junctions and light pulses.
|
|
62
63
|
4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
|
|
63
64
|
shipped: deterministic, settled steps, rounded numbers, token-only colours,
|
|
64
65
|
escaped labels, labels fit, holds the final frame.
|
|
@@ -113,7 +114,7 @@ headers when redistributing the vendored runtime and adapters.
|
|
|
113
114
|
| `references/targets.md` | Where it will be shown and what each target allows |
|
|
114
115
|
| `references/styles.md` | Neutral default, style files, brand presets, contrast |
|
|
115
116
|
| `references/qc.md` | Review stages, checklist, review-report template |
|
|
116
|
-
| `references/custom-scenes.md` | Writing a one-off scene module, including isometric views
|
|
117
|
+
| `references/custom-scenes.md` | Writing a one-off scene module, including isometric views, several tokens at once, and connectors with pulses |
|
|
117
118
|
| `references/ecosystem.md` | When GSAP, HyperFrames, Remotion, Motion Canvas, Manim, Mermaid or ELK are the better tool |
|
|
118
119
|
|
|
119
120
|
For rendering, slide packaging and video, see the **motion-render** skill.
|
|
@@ -158,6 +158,32 @@ arrived, and the arrivals have filled, before the step's time (the settled-step
|
|
|
158
158
|
rule in the gate applies as ever), and a token that stops mid-path is not a
|
|
159
159
|
resting state. A token never loops back to the start.
|
|
160
160
|
|
|
161
|
+
## Connectors, junctions and pulses
|
|
162
|
+
|
|
163
|
+
`kit` also ties pieces together (`runtime/connectors.mjs`). Template:
|
|
164
|
+
`examples/connectors.scene.mjs` (a request fans out through a diamond splitter;
|
|
165
|
+
a result rides an isometric feeder line through three junctions).
|
|
166
|
+
|
|
167
|
+
| Need | Use |
|
|
168
|
+
|---|---|
|
|
169
|
+
| A route | `connectorPath(points, { camera? })`: flat `{ x, y }` points in pixels, or world `{ x, y, z }` points projected by `camera` (build it once if the camera rests, each frame if it moves). Positions go by distance, in the world under a camera |
|
|
170
|
+
| A dashed connector | `drawConnector(path, p, { stroke, width, dash, arrow, opacity })`: draws the route up to fraction `p`, a dashed line whose dashes stay put as it grows. Draw it on with `progress(t, start, 0.5, easeStandard)`; at `p = 1` it is the resting dashed line. An open-V arrowhead rides the leading end (`arrow: false` for none) |
|
|
171
|
+
| A diamond junction | `drawJunction({ at, camera?, plane, size, lit })` where connectors turn, split or join. `plane: "screen"` (default) stands on the picture, `"floor"` lies in an iso view's floor plane (give it the world point and the `camera`). `lit` (0..1) cross-fades the reached layer in, as a node's two layers do |
|
|
172
|
+
| A light pulse | `drawPulse(path, t, { start, duration, lag?, ease?, hold? }, { color, radius })`: a head with a soft glow and a fading tail, from the connector's start to its end, once. `color` is a token (default `emphasis`). Gone at `pulseEnd(run)`, or held at the end with `hold` |
|
|
173
|
+
|
|
174
|
+
**One pulse per step, inside the beat.** A pulse is a token with a glow: it runs
|
|
175
|
+
once, in its step's beat, and is over before the step. Take `pulseEnd(run)`
|
|
176
|
+
(`start + duration + lag`), add the time its target takes to light (200–300 ms),
|
|
177
|
+
and put the step's `at` at least 50 ms after that; the settled-frame rule in the
|
|
178
|
+
gate then holds. Several pulses may run in one beat: one per connector, starting
|
|
179
|
+
together to fan out from a junction (the twin pulses of an explainer), or one
|
|
180
|
+
after another, each starting when the last has arrived. Light a junction or a
|
|
181
|
+
target when the pulse reaches it: `lit: progress(t, arriveAt, 0.25, easeStandard)`,
|
|
182
|
+
where `arriveAt` is `run.start + run.duration` (with `ease: linear`, a junction
|
|
183
|
+
at a fraction `f` of the path is reached at `run.start + f * run.duration`).
|
|
184
|
+
A pulse never repeats while a step rests: a connector that pulses on a loop is
|
|
185
|
+
ambient motion, which the canon rules out.
|
|
186
|
+
|
|
161
187
|
Canon: no loops, no ambient motion, no continuous scrubbing, 12 s hard limit
|
|
162
188
|
(8 s target). An isometric scene plays once and holds its last frame, like any
|
|
163
189
|
other, and under reduced motion the player shows that frame. A constantly
|
|
@@ -77,6 +77,25 @@ Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
|
|
|
77
77
|
A shadow on the floor under each token (an ellipse of `ink` at ≈ 18 %,
|
|
78
78
|
squashed by `sin(elevation)`) shows where it is in the world.
|
|
79
79
|
|
|
80
|
+
## Connectors and pulses (derived)
|
|
81
|
+
|
|
82
|
+
- **Connector:** draws on from its start in 0.4–0.6 s on `easeStandard`, the
|
|
83
|
+
dashes fixed to the path so they do not crawl, and rests as a dashed line. The
|
|
84
|
+
open-V arrowhead rides the leading end.
|
|
85
|
+
- **Pulse:** one run per connector per step, 0.5–0.8 s on a flat connector, with
|
|
86
|
+
the tail lagging the head by 80–150 ms (split edges). On a long isometric
|
|
87
|
+
feeder use `linear`, 1.2–2 s, so the speed is constant and each junction
|
|
88
|
+
lights as it passes. It grows in over the first tenth of its life and fades
|
|
89
|
+
over the last sixth, so it never pops.
|
|
90
|
+
- **Timing rule:** the pulse is over (`pulseEnd`), and its target has lit
|
|
91
|
+
(200–300 ms), ≥ 50 ms before the step. Several pulses may share a beat: all
|
|
92
|
+
at once to fan out from a junction (twin pulses outward), or in sequence, each
|
|
93
|
+
starting as the last arrives.
|
|
94
|
+
- **Never** a pulse that repeats or runs while a step rests; that is looping
|
|
95
|
+
ambient motion (canon above). Loops are forbidden by contract and need review;
|
|
96
|
+
the gate's settled-frame rule only catches motion around the sampled step
|
|
97
|
+
boundaries, so it will not see every repeat.
|
|
98
|
+
|
|
80
99
|
## Container and text timing
|
|
81
100
|
|
|
82
101
|
- The container (box, card) starts moving immediately; new text appears only
|