@liqweed/motion-kit 0.7.0 → 0.9.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.7.0"
10
+ "version": "0.9.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.7.0",
3
+ "version": "0.9.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
@@ -56,7 +56,8 @@ dependency) or Chrome; video: `ffmpeg`.
56
56
  ```
57
57
  runtime/ dependency-free ES modules (browser + Node)
58
58
  motion.mjs easing (exact cubic-bezier), progress, critically damped spring, retarget, split edges
59
- svg.mjs escaping, rounding, el/text/fade, polyline + Bézier arc-length, drawOn
59
+ svg.mjs escaping, rounding, el/text/fade, polyline + Bézier arc-length, drawOn, several tokens
60
+ iso.mjs isometric kit for custom scenes: camera, solids, depth order, label anchors
60
61
  wrap.mjs label wrapping with hard budgets
61
62
  style.mjs tokens, neutral style, contrast checks, token resolution
62
63
  scene.mjs scene contract, formats, renderSvg
@@ -70,7 +71,8 @@ lib/ Node-side: check (gate), export, build (HTML inliner), raster, v
70
71
  adapters/ slidev (Vue), astro, element (custom element), page (README)
71
72
  skills/ animated-diagram, motion-render, project-logo (Claude Code / Craft skills)
72
73
  examples/ order-flow (sequence), smart-home (hub-spoke), incident (timeline),
73
- web-stack (stack), custom-pulse (custom module)
74
+ web-stack (stack), custom-pulse (custom module),
75
+ isometric-swivel (custom module: isometric kit, several tokens)
74
76
  bench/ heavy scene for npm run bench:player (live-player frame cost)
75
77
  brand/ logo scene (built with motion-kit); renders go to assets/ + .idea/ (npm run media)
76
78
  assets/ generated project icon: icon.svg, icon.png, icon-animated.svg
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: motion-kit technique — normative specification
3
3
  status: draft
4
- last_updated: 2026-11-18
4
+ last_updated: 2026-11-19
5
5
  ---
6
6
 
7
7
  # motion-kit technique — normative specification
@@ -39,6 +39,7 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
39
39
  | `frame(t, ctx)` | `(number, {idPrefix}) → string` | MUST | Inner SVG markup at `t` (§2). `ctx.idPrefix` is unique to the rendered instance; every id the frame defines (clip paths, gradients, masks, markers, filters) MUST start with it, as `${idPrefix}-name` [gate] G14. A frame that defines no ids MAY ignore `ctx`. |
40
40
  | `stepLabelsInFrame` | boolean | MAY | `false` declares narrative steps whose labels are not drawn; exempts the scene from gate rule G10 (`lib/check.mjs:74`; used by `examples/custom-pulse.scene.mjs:137`, `brand/logo.scene.mjs:108`). |
41
41
  | `contrastPairs` | `{fg, bg, min, use?}[]` | MAY | Token pairs the scene draws beyond `CONTRAST_PAIRS` (§6); the gate checks the style against them in both themes [gate] G12 (`lib/check.mjs`, rule 8; used by `examples/custom-pulse.scene.mjs`). Tokens MUST be known and `min` in [1, 21]. |
42
+ | `labelBoxes(t)` | `(number) → LabelBox[]` | MAY | The box of every label `frame(t)` draws, in the scene's own coordinates (`{id, x, y, width, height, stem?, opacity?}`; `labelAnchor` returns one, §4.9). Must be a function [throws]. The gate fails a scene whose labels overlap, whose stems cross a label or that leave the picture [gate] G15 (`lib/check.mjs`, rule 9; each box MUST be `{id, x, y, width, height}` with finite numbers [gate]; used by `examples/isometric-swivel.scene.mjs`). |
42
43
  | `type`, `format`, `locale` | string | MAY | Set by scene types; recorded in the export manifest (`lib/export.mjs:75-77`). |
43
44
 
44
45
  - A scene MUST be produced by either a registered scene type —
@@ -47,7 +48,7 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
47
48
  `sceneFromModule` (`runtime/kit.mjs`) with
48
49
  `opts = { ...options, format, locale, kit }`. `options` are the caller's
49
50
  serializable scene options, passed unchanged; option names `format`,
50
- `locale` and `kit` throw. `kit` is the flat exports of the `motion`, `svg`, `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` and `wrap` runtime modules (`KIT`); it has no `createScene`, scene types or player. Both paths
51
52
  run `validateScene`. The CLI (`--options`), the vendored gate and the Astro
52
53
  adapter call `sceneFromModule`, so one module with the same options, format
53
54
  and locale gives the same scene everywhere. A `build` page calls the factory
@@ -204,6 +205,70 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
204
205
  opacities `1 − p` and `p` instead of interpolating colours, which would need
205
206
  literals (`runtime/parts.mjs:1-8,68,94,109`).
206
207
 
208
+ ### 4.8 Several tokens (`runtime/svg.mjs`)
209
+
210
+ - `tokenPoints(path, t, runs)` → `{index, progress, point, run}[]` for each
211
+ token in flight at `t`; `tokensAlong(path, t, runs, draw)` concatenates
212
+ `draw(point, {index, progress, run})` for them. `path` is anything with
213
+ `at(fraction) → point` (`polyline`, `cubic`, `path3`); `runs` is
214
+ `{start, duration, ease?, path?, hold?}[]`, one per token, each on its own
215
+ `path` if it has one and on `easeStandard` by default.
216
+ - A token is in flight while its eased progress is above 0 and below 1; with
217
+ `hold` it stays at the end of its path once it has arrived. Both are pure
218
+ functions of `t`: no token carries state from an earlier frame.
219
+ - Any number of tokens MAY move at the same time. The canon does not change:
220
+ they MUST move only between settled steps, so every token has arrived (or is
221
+ held still) at each step's `at` and the gate's settled-frame rule (G6)
222
+ holds. A token MUST NOT loop or restart: a scene plays once (§2).
223
+
224
+ ### 4.9 Isometric kit (`runtime/iso.mjs`)
225
+
226
+ For custom scenes that draw a 3D view; handed to them in `kit`. Pure
227
+ functions; a colour is a token name, resolved with `tok()` (G4 applies).
228
+
229
+ - **Camera.** `camera({azimuth, elevation, zoom, pan})` (degrees, pixels per
230
+ world unit, and the screen position of the world origin; defaults: 45°,
231
+ `ISO_ELEVATION` = atan(1/√2) ≈ 35.264°, 1, the screen origin). `elevation`
232
+ MUST be in [0, 90], `zoom` > 0 [throws]. World: x east, y north, z up.
233
+ The projection is orthographic:
234
+ `x' = pan.x + zoom·u`, `y' = pan.y − zoom·(v·sin el + z·cos el)`,
235
+ `depth = −v·cos el + z·sin el`, with `u = x·cos az + y·sin az` and
236
+ `v = −x·sin az + y·cos az`. At 90° elevation the result does not depend on
237
+ `z`: the plan view, which has north up at azimuth 0 (sine and cosine are exact
238
+ at multiples of 90°); at the default 45° azimuth north points up and right.
239
+ `projector(cam)` / `project(cam, p)` give `{x, y, depth}`; larger `depth` is
240
+ nearer the viewer.
241
+ - **Swivel.** `lerpCamera(a, b, p)` interpolates every field linearly (`a` at
242
+ `p ≤ 0`, `b` at `p ≥ 1`); `fitCamera(points, cam, {width, height, margin})`
243
+ returns `cam` with the pan and zoom that centre and fit the points in what
244
+ the margins leave. A swivel is a move between two settled steps (§8).
245
+ - **Solids.** `prism({points, h, z, fill, sides, shade, stroke, strokeWidth,
246
+ opacity, id})` extrudes a convex footprint (any winding; stored
247
+ counter-clockwise) from base height `z` by `h` ≥ 0; `box` (centred on x, y)
248
+ and `slab` (default `h` 0.25) are rectangular prisms; `regularPolygon` makes
249
+ a footprint. A non-convex, degenerate or too-small footprint, an unknown
250
+ token or a negative height throws. `fill` is the token of the top face,
251
+ `sides` of the side faces (default `fill`); `shade` (default `ink`, `null`
252
+ for none) is layered over each side at an opacity from 0.10 to 0.26 by how
253
+ far the face turns from screen left. Faces are `<path>`s outlined with
254
+ `stroke`; only faces that face the camera are drawn (the top when elevation
255
+ > 0, a side when its outward normal faces the camera and elevation < 90°).
256
+ - **Depth order.** `orderSolids(solids, cam)` returns the solids far to near.
257
+ Two solids whose projections overlap are ordered by the axes that separate
258
+ them (a footprint edge, or height when seen from above); where the axes
259
+ disagree, or none separates them, they are not ordered. The result is a
260
+ topological sort, ties and cycles broken by the nearer centre, then by input
261
+ order: the same solids always give the same order. `drawSolids` draws in it.
262
+ - **Labels.** `labelAnchor(cam, {id, at, lines, fontSize, lift, side,
263
+ opacity})` draws a dot on the projected point, a vertical stem `lift` pixels
264
+ up and a label box above it (or beside its top), and returns the markup and
265
+ the `LabelBox`. `labelProblems(boxes, {width, height, gap = 4})` lists the
266
+ collisions G15 reports. Labels follow §7 (wrapped, localized, ≥ 14 px).
267
+ - **Paths.** `path3(points)` is a polyline through world points with its
268
+ length in world units, so a token keeps a constant speed whatever the camera
269
+ does when its progress is linear (`tokenPoints` defaults to `easeStandard`;
270
+ pass `ease: linear`).
271
+
207
272
  ## 5. Markup
208
273
 
209
274
  - Text and attribute values MUST be escaped (`& < > " '`) via `esc`, `text` or
@@ -235,7 +300,7 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
235
300
  `accent`, `onAccent`, `emphasis`. Roles: see
236
301
  [`styles.md`](../../skills/animated-diagram/references/styles.md). Exactly one
237
302
  element at a time SHOULD carry `emphasis`.
238
- - A style is data: `{name, font, radius, stroke, light: {token: #rrggbb}, dark: {…}}`.
303
+ - A style is data: `{name, font, radius, stroke, motion, light: {token: #rrggbb}, dark: {…}}`.
239
304
  `normalizeStyle` fills missing fields from `NEUTRAL`
240
305
  (`runtime/style.mjs:25-50,58-77`) and MUST throw on an unknown token or a
241
306
  non-`#rrggbb` value (`runtime/style.mjs:70-73`). If `dark` is absent, dark
@@ -282,6 +347,9 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
282
347
  or empty translation throws; null/undefined optional copy returns "".
283
348
  - Labels are labels; sentences go in `detail`. Font size MUST NOT go below
284
349
  14 px at 1× (§3).
350
+ - A scene that places labels in a projected or moving view (§4.9) SHOULD
351
+ declare their boxes in `labelBoxes` (§1); the gate then fails overlapping
352
+ labels in every format and locale (G15).
285
353
  - Every shipped locale × format MUST pass the gate. `check` derives locales
286
354
  from a `.json` spec's localized objects (keys `xx` or `xx-YY`)
287
355
  (`lib/gate.mjs`). Modules export a non-empty unique `locales` array (default
@@ -543,6 +611,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
543
611
  | G12 | Style passes WCAG contrast in both themes for every pair in `CONTRAST_PAIRS` (once per run) and for each scene's `contrastPairs` (per scene). | `lib/gate.mjs`, `lib/check.mjs` (rule 8), `runtime/style.mjs` (`checkContrast`) | Legibility in light and dark, for the pairs actually drawn (§6). |
544
612
  | G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `lib/gate.mjs` | Reject, don't invent: a broken picture never renders. |
545
613
  | G14 | Rendered with two different `idPrefix` values, sampled frames share no `id`. | `lib/check.mjs` (rule 7) | Two instances on one page (wide and tall, or one diagram twice) must not share ids: `url(#x)` resolves to the first element with that id, and WCAG 2.1 SC 4.1.1 forbids duplicates. |
614
+ | G15 | If the scene defines `labelBoxes`, at each sampled time and each step time: no two boxes with `opacity` > 0 are closer than 4 px, no stem crosses another box and every box lies inside the picture (`0, 0, width, height`). `labelBoxes` MUST return an array and not throw. Each problem is reported once, at its first time. | `lib/check.mjs` (rule 9), `runtime/iso.mjs` (`labelProblems`) | Labels placed in a projected view move with the camera; nothing else checks them against one another. Opacity 0 is not drawn, so a scene hides labels while the camera moves. |
546
615
 
547
616
  The gate checks structure, not looks. Visual review (before/after frames,
548
617
  phone size, real-time playback, dark mode) is required by
@@ -560,6 +629,7 @@ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
560
629
  | Module locales | Modules MAY export `locales`; all declared locales MUST be checked by default. Undeclared modules retain `en` for compatibility. Explicit `--locale` overrides. |
561
630
  | Translations | A localized object MUST supply the exact requested locale. Plain strings are shared. Silent cross-language fallback is forbidden. |
562
631
  | Shape styles | Built-in scenes MUST use radius 0–24 (default 10) for rectangular node corners and stroke 1–4 (default 2) as their base width. Accent lines are 1.5×; timeline stems 0.75×. Circles, region borders and pills retain their shapes. Custom scenes MAY read normalized `style` from the frame context. |
632
+ | Motion tokens | A style MAY set `motion.enter` (entrances) and `motion.move` (movement between visible states) as four numbers, a CSS `cubic-bezier(x1, y1, x2, y2)`, each from 0 to 1: no curve overshoots. Defaults: `(0, 0, .2, 1)` and `(.4, 0, .2, 1)`. Built-in scene types read them through `easings(style.motion)`; durations, delays and step times stay fixed, so a curve changes how a move travels and never when a step settles. A curve that is still moving near its end (a linear one) would leave a step frame unsettled, so `easings` finishes it in the first 95 % of each move and holds it at 1 for the last 5 %; a curve that ends flat (both defaults) is the exact CSS curve. Custom scenes MAY do the same. |
563
633
  | Vendored parity | CLI and vendored checks MUST call the same `lib/gate.mjs` and `lib/check.mjs`, including contrast, locales and caller options. |
564
634
  | Neutral contrast | Keep emphasis-on-accent at 3:1, the darker light accent and lighter dark emphasis. The site chrome follows the corresponding neutral tokens. |
565
635
 
@@ -0,0 +1,171 @@
1
+ /**
2
+ * Example custom scene: a plan view that swivels into isometric, then three
3
+ * work items travel a line of four stations at once.
4
+ *
5
+ * Shows the isometric kit (runtime/iso.mjs): a camera interpolated between the
6
+ * plan view and true isometric, fitted to the picture each frame (pan and
7
+ * zoom); solids (a slab, boxes and a hexagonal prism) coloured by tokens and
8
+ * depth ordered; label anchors with stems, whose boxes the gate checks; and
9
+ * several tokens on one path (`tokensAlong`), all inside a settled step.
10
+ * Nothing loops: the scene plays once and holds its last frame, and the
11
+ * swivel is one move between two settled steps. Pure: frame(t) depends only
12
+ * on t and constants.
13
+ */
14
+ import { easeOut, easeStandard, linear, progress } from "../runtime/motion.mjs";
15
+ import { CAMERA_ISOMETRIC, CAMERA_PLAN, box, drawSolid, fitCamera, labelAnchor, lerpCamera, orderSolids, path3, prism, project, regularPolygon, slab } from "../runtime/iso.mjs";
16
+ import { FORMATS, localize } from "../runtime/scene.mjs";
17
+ import { tok } from "../runtime/style.mjs";
18
+ import { el, fade, num, tokensAlong } from "../runtime/svg.mjs";
19
+ import { wrapLabel } from "../runtime/wrap.mjs";
20
+
21
+ export const locales = ["en", "nl"];
22
+
23
+ const COPY = {
24
+ title: { en: "A floor plan that turns isometric", nl: "Een plattegrond die isometrisch draait" },
25
+ description: {
26
+ en: "Four stations stand on one floor, seen from above. The view swivels to isometric, and three work items travel the line at once.",
27
+ nl: "Vier stations staan op één vloer, van boven gezien. Het beeld draait naar isometrisch en drie werkitems reizen tegelijk langs de lijn.",
28
+ },
29
+ stations: [
30
+ { en: "Intake", nl: "Intake" },
31
+ { en: "Review", nl: "Controle" },
32
+ { en: "Build", nl: "Bouw" },
33
+ { en: "Deliver", nl: "Levering" },
34
+ ],
35
+ steps: [
36
+ { label: { en: "Seen from above", nl: "Van boven gezien" }, detail: { en: "Four stations on one floor, in plan.", nl: "Vier stations op één vloer, in plattegrond." } },
37
+ { label: { en: "Turned isometric", nl: "Isometrisch gedraaid" }, detail: { en: "The same floor, now with height.", nl: "Dezelfde vloer, nu met hoogte." } },
38
+ { label: { en: "Three items arrive", nl: "Drie items aangekomen" }, detail: { en: "Three work items travelled the line together.", nl: "Drie werkitems reisden samen langs de lijn." } },
39
+ ],
40
+ };
41
+
42
+ // World, in units: a 14 × 7 floor and four stations along a diagonal.
43
+ const FLOOR = { w: 14, d: 7, h: 0.3 };
44
+ const STATIONS = [
45
+ { x: -4.5, y: -2, h: 0.8, hex: false },
46
+ { x: -1.5, y: -0.7, h: 1.6, hex: false },
47
+ { x: 1.5, y: 0.7, h: 1.2, hex: true },
48
+ { x: 4.5, y: 2, h: 0.8, hex: false },
49
+ ];
50
+ const CARRY = 2.5; // the height tokens travel at, above every station
51
+ const TOP = FLOOR.h;
52
+
53
+ // Timeline, in seconds. Every beat ends before the next one starts, so each
54
+ // step frame is settled (the gate checks it).
55
+ const ENTER = 0.4;
56
+ const STAGGER = 0.1;
57
+ const LABELS_IN = 0.9;
58
+ const LABEL_FADE = 0.4;
59
+ const STEP_PLAN = 1.6;
60
+ const LABELS_OUT = 1.9;
61
+ const SWIVEL_AT = 2.25;
62
+ const SWIVEL = 1.4;
63
+ const LABELS_BACK = 3.7;
64
+ const STEP_ISO = 4.3;
65
+ const GO = 4.4;
66
+ const GAP = 0.3;
67
+ const TRIP = 1.6;
68
+ const FILL = 0.3;
69
+ const RUNS = [0, 1, 2].map((i) => ({ start: GO + i * GAP, duration: TRIP, ease: linear }));
70
+
71
+ export default function make({ format = "16:9", locale = "en" } = {}) {
72
+ const f = FORMATS[format];
73
+ if (!f) throw new Error(`unknown format "${format}"`);
74
+ const W = f.width;
75
+ const H = f.height || (format === "tall" ? 520 : 400);
76
+ const names = COPY.stations.map((s) => wrapLabel(localize(s, locale), 12, 2));
77
+ const fs = 14;
78
+
79
+ // The fit's room: the labels stand above the stations, so the top margin is theirs.
80
+ // Neighbouring labels stand at two heights, further apart in a narrow picture, where they are closer.
81
+ const lifts = W < 600 ? [36, 112, 36, 112] : [36, 80, 36, 80];
82
+ const margin = { top: Math.max(...lifts) + 36, right: 20, bottom: 20, left: 20 };
83
+ // What the camera must keep in view: the floor, every station at full height, and the tokens' route.
84
+ const extent = [
85
+ ...[-1, 1].flatMap((sx) => [-1, 1].map((sy) => ({ x: (sx * FLOOR.w) / 2, y: (sy * FLOOR.d) / 2, z: 0 }))),
86
+ ...STATIONS.flatMap((s) => [-1, 1].flatMap((dx) => [-1, 1].map((dy) => ({ x: s.x + dx * 1.25, y: s.y + dy * 1.25, z: TOP + s.h })))),
87
+ ...STATIONS.map((s) => ({ x: s.x, y: s.y, z: CARRY })),
88
+ ];
89
+ const swivel = (/** @type {number} */ t) => progress(t, SWIVEL_AT, SWIVEL, easeStandard);
90
+ const cameraAt = (/** @type {number} */ t) => fitCamera(extent, lerpCamera(CAMERA_PLAN, CAMERA_ISOMETRIC, swivel(t)), { width: W, height: H, margin });
91
+
92
+ const route = path3(STATIONS.map((s) => ({ x: s.x, y: s.y, z: CARRY })));
93
+ // Station i is reached when the first token passes it: its share of the route, at constant speed.
94
+ let along = 0;
95
+ const reached = STATIONS.map((s, i) => {
96
+ if (i > 0) along += Math.hypot(s.x - STATIONS[i - 1].x, s.y - STATIONS[i - 1].y);
97
+ return RUNS[0].start + (along / route.length) * TRIP;
98
+ });
99
+ // The last token lands, and the last station has filled, before the last step.
100
+ const landed = Math.max(RUNS[RUNS.length - 1].start + TRIP, reached[reached.length - 1] + FILL);
101
+ const steps = [
102
+ { at: STEP_PLAN, ...COPY.steps[0] },
103
+ { at: STEP_ISO, ...COPY.steps[1] },
104
+ { at: landed + 0.15, ...COPY.steps[2] },
105
+ ];
106
+ const duration = steps[2].at + 0.35;
107
+
108
+ /** The solids at time t: the floor, then the stations (entering, rising with the swivel, filling). */
109
+ function scene(/** @type {number} */ t) {
110
+ const rise = progress(t, SWIVEL_AT + 0.1, SWIVEL, easeOut);
111
+ const floor = slab({ x: 0, y: 0, w: FLOOR.w, d: FLOOR.d, h: FLOOR.h, fill: "bg", opacity: progress(t, 0, ENTER) });
112
+ const stations = STATIONS.map((s, i) => {
113
+ const shape = { id: String(i), z: TOP, h: Math.max(0.02, s.h * rise), opacity: progress(t, STAGGER + i * STAGGER, ENTER) };
114
+ const make = (/** @type {string} */ fill) => (s.hex ? prism({ points: regularPolygon(s.x, s.y, 1.25, 6, 0), fill, ...shape }) : box({ x: s.x, y: s.y, w: 2, d: 2, fill, ...shape }));
115
+ const on = progress(t, reached[i], FILL, easeStandard);
116
+ return { base: make("surface"), on: on > 0 ? make("accent") : null, fill: on };
117
+ });
118
+ return { floor, stations };
119
+ }
120
+
121
+ /** The labels at time t, with their boxes: they stand while the camera rests. */
122
+ function labels(/** @type {number} */ t) {
123
+ const opacity = Math.max(progress(t, LABELS_IN, LABEL_FADE) * (1 - progress(t, LABELS_OUT, 0.25)), progress(t, LABELS_BACK, LABEL_FADE));
124
+ const cam = cameraAt(t);
125
+ const rise = progress(t, SWIVEL_AT + 0.1, SWIVEL, easeOut);
126
+ return STATIONS.map((s, i) => labelAnchor(cam, { id: `station-${i}`, at: { x: s.x, y: s.y, z: TOP + Math.max(0.02, s.h * rise) }, lines: names[i], fontSize: fs, lift: lifts[i], opacity }));
127
+ }
128
+
129
+ function frame(/** @type {number} */ t) {
130
+ const cam = cameraAt(t);
131
+ const { floor, stations } = scene(t);
132
+ const squash = Math.sin((cam.elevation * Math.PI) / 180); // a circle on the floor, seen at this elevation
133
+ // A token's size grows in over the first 8 % of its trip and shrinks out over the last 8 %.
134
+ const size = (/** @type {number} */ k) => Math.min(1, k / 0.08, (1 - k) / 0.08);
135
+ const out = [drawSolid(floor, cam)];
136
+ // A shadow under each token, on the floor, so its place in the world reads. Under the stations, which hide it.
137
+ out.push(
138
+ tokensAlong(route, t, RUNS, (p, { progress: k }) => {
139
+ const g = project(cam, { x: p.x, y: p.y, z: TOP });
140
+ return el("ellipse", { cx: g.x, cy: g.y, rx: 10 * size(k), ry: 10 * size(k) * squash, fill: tok("ink"), opacity: 0.18 });
141
+ }),
142
+ );
143
+ // Stations far to near, each with its reached layer fading in over the pending one.
144
+ for (const base of orderSolids(stations.map((s) => s.base), cam)) {
145
+ const s = stations[Number(base.id)];
146
+ out.push(drawSolid(base, cam), s.on ? fade(s.fill, {}, drawSolid(s.on, cam)) : "");
147
+ }
148
+ out.push(
149
+ tokensAlong(route, t, RUNS, (p, { progress: k }) => {
150
+ const a = project(cam, p);
151
+ return el("circle", { cx: a.x, cy: a.y, r: 7 * size(k), fill: tok("emphasis"), stroke: tok("bg"), "stroke-width": 1.5 });
152
+ }),
153
+ );
154
+ out.push(...labels(t).map((l) => l.markup));
155
+ return out.join("");
156
+ }
157
+
158
+ return {
159
+ id: `isometric-swivel-${format.replace(":", "x")}`,
160
+ width: W,
161
+ height: H,
162
+ duration,
163
+ title: localize(COPY.title, locale),
164
+ description: localize(COPY.description, locale),
165
+ // Steps are beats of the story: their labels live in the player's controls, not in the drawing.
166
+ stepLabelsInFrame: false,
167
+ steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
168
+ labelBoxes: (/** @type {number} */ t) => labels(t).map((l) => l.box),
169
+ frame,
170
+ };
171
+ }
package/lib/check.mjs CHANGED
@@ -8,6 +8,7 @@
8
8
  *
9
9
  * Over files, formats and locales (the CLI and the vendored gate): lib/gate.mjs.
10
10
  */
11
+ import { labelProblems } from "../runtime/iso.mjs";
11
12
  import { renderSvg, validateScene } from "../runtime/scene.mjs";
12
13
  import { checkContrast, normalizeStyle } from "../runtime/style.mjs";
13
14
 
@@ -289,5 +290,37 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
289
290
  for (const p of checkContrast(style, scene.contrastPairs)) problems.push(`contrast: ${p}`);
290
291
  }
291
292
 
293
+ // 9. Labels the scene declares (scene.labelBoxes): at the sampled times, each
294
+ // step and the end, no two overlap, no stem crosses another label and none
295
+ // leaves the picture. Each problem is reported once, at its first time.
296
+ if (scene.labelBoxes) {
297
+ const seen = new Set();
298
+ const times = [...Array.from({ length: samples + 1 }, (_, i) => at(i)), ...scene.steps.map((s) => s.at)].sort((a, b) => a - b);
299
+ for (const t of times) {
300
+ let boxes;
301
+ try {
302
+ boxes = scene.labelBoxes(Math.min(t, scene.duration));
303
+ } catch (e) {
304
+ problems.push(`labelBoxes() threw at t=${t.toFixed(3)}: ${e instanceof Error ? e.message : String(e)}`);
305
+ break;
306
+ }
307
+ if (!Array.isArray(boxes)) {
308
+ problems.push("labelBoxes() must return an array of label boxes");
309
+ break;
310
+ }
311
+ const bad = boxes.findIndex((b) => !b || typeof b !== "object" || typeof b.id !== "string" || !["x", "y", "width", "height"].every((k) => Number.isFinite(b[k])) || (b.opacity !== undefined && !Number.isFinite(b.opacity)) || (b.stem !== undefined && (!b.stem || typeof b.stem !== "object" || !["x1", "y1", "x2", "y2"].every((k) => Number.isFinite(b.stem[k])))));
312
+ if (bad >= 0) {
313
+ problems.push(`labelBoxes() entry ${bad} must be { id, x, y, width, height } with finite numbers (and a stem, when given, { x1, y1, x2, y2 }), at t=${t.toFixed(3)}`);
314
+ break;
315
+ }
316
+ for (const p of labelProblems(boxes, { width: scene.width, height: scene.height })) {
317
+ if (seen.has(p)) continue;
318
+ seen.add(p);
319
+ problems.push(`${p} at t=${t.toFixed(3)}`);
320
+ }
321
+ if (problems.length > 12) break;
322
+ }
323
+ }
324
+
292
325
  return { ok: problems.length === 0, problems };
293
326
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@liqweed/motion-kit",
3
- "version": "0.7.0",
3
+ "version": "0.9.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 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 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",
@@ -57,7 +57,8 @@
57
57
  "bench:player": "node scripts/bench-player.mjs",
58
58
  "snapshots:update": "node scripts/update-snapshots.mjs",
59
59
  "gate:core": "npm run -s typecheck && npm run -s versions && npm test && npm run -s check && npm run -s media:check",
60
- "gate": "npm run -s gate:core && npm run -s site"
60
+ "gate": "npm run -s gate:core && npm run -s site",
61
+ "skills:design": "DISABLE_TELEMETRY=1 npx -y skills@1.9.0 experimental_install --frozen-lockfile -a claude-code -a codex"
61
62
  },
62
63
  "optionalDependencies": {
63
64
  "@resvg/resvg-js": "^2.6.2"