@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.
@@ -7,7 +7,7 @@
7
7
  "name": "motion-kit",
8
8
  "source": "./",
9
9
  "description": "animated-diagram, motion-render and project-logo skills and the motion-kit runtime/CLI",
10
- "version": "0.10.0"
10
+ "version": "0.11.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.10.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
@@ -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.10.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) and several tokens moving at once.
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 and several tokens at once |
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