@liqweed/motion-kit 0.9.1 → 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.9.1"
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.9.1",
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
@@ -30,6 +30,7 @@ import { fileURLToPath } from "node:url";
30
30
  import { parseArgs } from "node:util";
31
31
  import { bake, bakeStats } from "../runtime/bake.mjs";
32
32
  import { FORMATS } from "../runtime/scene.mjs";
33
+ import { checkContrast, sharedPairs } from "../runtime/style.mjs";
33
34
  import { SCENE_TYPES } from "../runtime/types/index.mjs";
34
35
  import { checkScene } from "../lib/check.mjs";
35
36
  import { checkFiles } from "../lib/gate.mjs";
@@ -79,6 +80,10 @@ function fail(msg) {
79
80
  console.error(`motion-kit: ${msg}`);
80
81
  process.exit(1);
81
82
  }
83
+ /** Contrast the scene does not draw but the style misses: said, never failed (G12). @param {string[]} warnings */
84
+ function warnAll(warnings) {
85
+ for (const w of warnings) console.error(`motion-kit: warning: contrast: ${w}`);
86
+ }
82
87
  function need(v, what) {
83
88
  if (!v) fail(`${cmd}: ${what} is required`);
84
89
  return v;
@@ -124,6 +129,11 @@ async function main() {
124
129
  const loaded = await loadScene(file, sopts);
125
130
  const r = checkScene(loaded.scene, { style });
126
131
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
132
+ warnAll(r.warnings);
133
+ // The page also paints the player: button text and borders, the selected step,
134
+ // captions, the focus outline, and (unless --no-heading) the heading on the canvas.
135
+ const player = checkContrast(style, sharedPairs(...(a["no-heading"] ? [] : ["ink/bg"]), "ink/surface", "onAccent/accent", "muted/bg", "emphasis/bg", "line/bg", "accent/bg"));
136
+ if (player.length) fail(`the player in the page fails the gate:\n - ${player.join("\n - ")}`);
127
137
  const html = buildHtml(loaded, { style, ...where, options: sopts.options, scrubber: !a["no-scrubber"], heading: !a["no-heading"] });
128
138
  if (/<\/script/i.test(html.slice(html.indexOf("<script>") + 8, html.lastIndexOf("</script>")))) fail("bundled code contains </script>");
129
139
  const out = need(a.out, "--out");
@@ -138,6 +148,7 @@ async function main() {
138
148
  const { scene } = await loadScene(file, sopts);
139
149
  const r = checkScene(scene, { style });
140
150
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
151
+ warnAll(r.warnings);
141
152
  if (a.png && !(await rasterizer())) fail("--png needs @resvg/resvg-js or Chrome");
142
153
  // The contact sheet's phone row shows the tall layout, as a phone does.
143
154
  /** @type {{ scene?: any, error?: string }} */
@@ -159,6 +170,7 @@ async function main() {
159
170
  const { scene } = await loadScene(file, await sceneOpts(file));
160
171
  const gate = checkScene(scene, { style });
161
172
  if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
173
+ warnAll(gate.warnings);
162
174
  const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
163
175
  const out = need(a.out, "--out");
164
176
  writeFileSync(out, svg);
@@ -171,6 +183,7 @@ async function main() {
171
183
  const { scene } = await loadScene(file, await sceneOpts(file));
172
184
  const gate = checkScene(scene, { style });
173
185
  if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
186
+ warnAll(gate.warnings);
174
187
  const out = need(a.out, "--out");
175
188
  const r = await renderVideo(scene, {
176
189
  out,
@@ -192,6 +205,7 @@ async function main() {
192
205
  const { scene } = await loadScene(file, await sceneOpts(file, { ...where, format: format ?? "1:1" }));
193
206
  const r = checkScene(scene, { style });
194
207
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
208
+ warnAll(r.warnings);
195
209
  const png = !a["no-png"];
196
210
  if (png && !(await rasterizer())) fail("icon PNG needs @resvg/resvg-js or Chrome (or pass --no-png)");
197
211
  const root = resolve(need(a.out, "--out"));
@@ -297,7 +311,7 @@ const VENDOR_CHECK = `#!/usr/bin/env node
297
311
  //
298
312
  // Every format unless --format; for a spec every locale its strings carry, for
299
313
  // a custom module its exported locales (default "en"), unless --locale. The style (neutral by default) must
300
- // pass the contrast check. --options passes scene options to custom modules:
314
+ // pass the contrast of the pairs each scene draws (G12). --options passes scene options to custom modules:
301
315
  // a .json file, inline JSON, or an .mjs module exporting ({ format, locale }) => options.
302
316
  // Exits 1 if anything fails; a file that cannot be loaded fails on its own.
303
317
  import { parseArgs } from "node:util";
@@ -38,7 +38,7 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
38
38
  | `steps` | `{at, label, detail?, id?}[]` | MUST | ≥ 1 step; `at` strictly increasing; `at ≤ duration` (+1e-9); every `label` non-empty; an `id`, if present, is a non-empty string unique within the scene [throws] (`validateScene`). The last step is the finished diagram. Page scripts address steps by `id` (§10.2); scene types copy a spec node's, hub's or spoke's `id`. |
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
- | `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]. |
41
+ | `contrastPairs` | `{fg, bg, min, use?}[]` | MAY | The token pairs the scene draws (§6). The gate holds the style to exactly these in both themes, and only warns about the shared pairs (`CONTRAST_PAIRS`) the list leaves out; a scene that declares none is held to every shared pair [gate] G12 (`lib/check.mjs`, `contrastReport`; used by `examples/custom-pulse.scene.mjs`; every registered scene type sets it). Tokens MUST be known and `min` in [1, 21]. |
42
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`). |
43
43
  | `type`, `format`, `locale` | string | MAY | Set by scene types; recorded in the export manifest (`lib/export.mjs:75-77`). |
44
44
 
@@ -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
@@ -312,21 +354,34 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
312
354
  literal (`runtime/scene.mjs:84`, `runtime/style.mjs:86-93`), because slide
313
355
  apps, rasterizers and image viewers ignore CSS variables; an unresolvable
314
356
  token throws.
315
- - **Contrast** (`runtime/style.mjs`, `checkContrast`, WCAG relative
316
- luminance): in both themes, every pair in `CONTRAST_PAIRS`, the token pairs
317
- the scene types and shared parts draw where the pair carries meaning in a
318
- step frame. Text ≥ 4.5:1 — `ink`/`muted` on `bg` and `surface`, `onAccent`
319
- on `accent`; shapes ≥ 3:1 — `line`, `accent`, `emphasis` on `bg`, and
320
- `emphasis` on `accent` (the ring marking the current node sits 3.5 units
321
- from the reached node it surrounds, and tells "here" from "reached" without
322
- hue). `CONTRAST_EXEMPT` lists, with a reason each, the pairs left out:
323
- `line` on `surface` (an outline is told from the canvas outside it),
324
- `accent` on `surface` and `emphasis` on `surface` and `accent` on `line`
325
- (only in motion), `onAccent` on `emphasis` (only the logo; logos are exempt
326
- from WCAG 1.4.11). A scene adds the pairs it draws besides through
327
- `contrastPairs` (§1). `motion-kit check` MUST fail when the selected style
328
- violates any shared pair, once per run, or a scene's own, per scene [gate]
329
- G12 (`lib/gate.mjs`). `neutral` MUST pass (`test/runtime.test.mjs`).
357
+ - **Contrast** (`runtime/style.mjs`, `checkContrast`, `contrastReport`, WCAG
358
+ relative luminance). WCAG judges what a scene draws, not a palette: text
359
+ needs 4.5:1 against what is behind it (1.4.3), the parts of a graphic that
360
+ carry meaning 3:1 against the colours adjacent to them (1.4.11). So the gate
361
+ holds a scene to the token pairs it draws, in both themes, and no others.
362
+ `CONTRAST_PAIRS` is the shared list of what the scene types and shared parts
363
+ draw where the pair carries meaning in a step frame: text ≥ 4.5:1 —
364
+ `ink`/`muted` on `bg` and `surface`, `onAccent` on `accent`; shapes ≥ 3:1 —
365
+ `line`, `accent`, `emphasis` on `bg`, and `emphasis` on `accent` (the ring
366
+ marking the current node sits 3.5 units from the reached node it surrounds,
367
+ and tells "here" from "reached" without hue). Each registered scene type
368
+ records which of them it draws (`contrastPairs` on its scenes,
369
+ `SCENE_TYPE_PAIRS` in `runtime/types/index.mjs`): a `hub-spoke` draws no text
370
+ on the canvas, a `sequence` draws no `ink` on `surface`.
371
+ A custom scene states what it draws in `contrastPairs` (§1; an empty list counts as none; `sharedPairs`
372
+ picks shared ones by name, others are written out). The pairs it declares
373
+ are the gate's problems; the shared pairs it leaves out are only warnings,
374
+ named with their ratio and threshold in both themes. A scene that declares
375
+ nothing is held to every shared pair, so no scene loses a check by saying
376
+ nothing. `CONTRAST_EXEMPT` lists, with a reason each, the pairs no scene
377
+ type draws or draws only in motion: `line` on `surface` (an outline is told
378
+ from the canvas outside it), `accent` on `surface` and `emphasis` on
379
+ `surface` and `accent` on `line` (only in motion), `onAccent` on `emphasis`
380
+ (only the logo; logos are exempt from WCAG 1.4.11). `motion-kit check` MUST
381
+ fail a scene whose style violates a pair it draws [gate] G12
382
+ (`lib/check.mjs`) and MUST report, once per run, every shared pair the style
383
+ misses with the scene types that draw it (`lib/gate.mjs`), without failing
384
+ on it. `neutral` MUST pass every shared pair (`test/runtime.test.mjs`).
330
385
  - motion-kit ships only `neutral` (`styles/neutral.json`); brand styles MUST
331
386
  live in the consumer repo.
332
387
 
@@ -592,8 +647,8 @@ that removes every listener, observer and mark they added.
592
647
  `motion-kit check` and the vendored `check.mjs` both run `checkFiles`
593
648
  (`lib/gate.mjs`): every file × format (all six unless `--format`, repeatable)
594
649
  × locale (`--locale`, repeatable; else every locale a spec's strings carry, and
595
- `en` for a module, §7), with `--options` for modules, plus the style contrast
596
- check. A file that cannot be read, parsed or built fails on its own and the
650
+ `en` for a module, §7), with `--options` for modules, plus the style contrast check of the pairs each scene draws and a once-per-run warning
651
+ for the shared pairs the style misses. A file that cannot be read, parsed or built fails on its own and the
597
652
  remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = unit tests +
598
653
  `check` over `examples/` and `brand/` (`package.json:15-18`).
599
654
 
@@ -610,7 +665,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
610
665
  | G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
611
666
  | G10 | Every word of every step label (escaped, trailing `/` stripped) appears in the final frame's text, unless `stepLabelsInFrame === false`. | `:72-77` | Step buttons and slides refer to things the viewer can see. Word-level, so it does not prove the label is contiguous. |
612
667
  | G11 | Every sampled frame MUST render the same bytes under two stubbed clocks as under the real one: `Date`, `performance.now`, `Temporal.Now` and `Math.random` fixed at 1970 and 0, then at 2100 and ≈ 1, the globals restored afterwards. `frame.toString()` MUST NOT contain `Date.now`, `new Date`, `Math.random`, `performance.now`, `Temporal.Now`. | `lib/check.mjs` (rules 1 and 6) | T1. The stubbed render catches reads in the helpers a frame calls; the source scan, code paths the samples miss. A reference taken before the check runs (`const D = Date` at import) escapes the stub. |
613
- | 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). |
668
+ | G12 | The style passes WCAG contrast in both themes for each pair the scene draws: its `contrastPairs`, which the scene types set to the shared pairs they draw, else every pair in `CONTRAST_PAIRS`. Shared pairs it does not draw are warnings, never failures; the run reports every shared pair the style misses once. | `lib/check.mjs`, `lib/gate.mjs` (`styleWarnings`), `runtime/style.mjs` (`contrastReport`) | Legibility in light and dark, for the pairs actually drawn (WCAG 1.4.3 and 1.4.11 judge rendered content, §6). |
614
669
  | G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `lib/gate.mjs` | Reject, don't invent: a broken picture never renders. |
615
670
  | 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. |
616
671
  | 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. |
@@ -634,6 +689,7 @@ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
634
689
  | 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. |
635
690
  | Vendored parity | CLI and vendored checks MUST call the same `lib/gate.mjs` and `lib/check.mjs`, including contrast, locales and caller options. |
636
691
  | 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. |
692
+ | Drawn pairs only | Recorded 2026-11-21 for [#72](https://github.com/liqweed/motion-kit/issues/72), after [#45](https://github.com/liqweed/motion-kit/issues/45) made every shared pair a failure for every scene. WCAG 1.4.3 and 1.4.11 judge what a scene draws against the colours next to it, so a pair that never meets in a scene is not a requirement for it: the gate fails the pairs a scene draws and warns about the other shared ones. Built-in types record the pairs they draw; a custom scene that declares `contrastPairs` is held to those, one that declares nothing to all shared pairs (no check is lost by saying nothing). `emphasis` on `accent` stays a failure for the types whose ring or dot touches the reached colour (`sequence`, `flowchart`, and the dots of `hub-spoke`, `stack` and the walks), though it rests on WCAG 1.4.1 and the shape already meets it, because the library's own call is to keep it. Thresholds and `neutral` are unchanged; detecting drawn pairs from the rendered SVG is left open. [#65](https://github.com/liqweed/motion-kit/issues/65) (logos) reuses the mechanism. |
637
693
 
638
694
  The controller also exposes `onStep(callback) → unsubscribe`, with an immediate
639
695
  current index and subsequent changed indices (`-1` before the first step).
@@ -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
+ }
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import { easeOut, easeStandard, progress, splitEdge, springTo } from "../runtime/motion.mjs";
10
10
  import { FORMATS, localize } from "../runtime/scene.mjs";
11
- import { tok } from "../runtime/style.mjs";
11
+ import { sharedPairs, tok } from "../runtime/style.mjs";
12
12
  import { cubic, drawOn, el, fade, num, text } from "../runtime/svg.mjs";
13
13
  import { wrapLabel } from "../runtime/wrap.mjs";
14
14
 
@@ -137,9 +137,14 @@ export default function make({ format = "16:9", locale = "en" } = {}) {
137
137
  // Steps here are events, not nodes: their labels live in the player's
138
138
  // step buttons and captions, not in the drawing.
139
139
  stepLabelsInFrame: false,
140
- // Beyond the pairs every scene draws: the progress bar's accent fill on
141
- // its surface track. The gate checks the style against it too.
142
- contrastPairs: [{ fg: "accent", bg: "surface", min: 3, use: "the progress bar's fill on its track" }],
140
+ // The pairs this scene draws, and the only ones the gate holds the style
141
+ // to (the shared pairs it leaves out, text on the canvas for one, are
142
+ // warnings): the shared ones its nodes, links and comet use, and the
143
+ // progress bar's accent fill on its surface track.
144
+ contrastPairs: [
145
+ ...sharedPairs("ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent"),
146
+ { fg: "accent", bg: "surface", min: 3, use: "the progress bar's fill on its track" },
147
+ ],
143
148
  steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
144
149
  frame,
145
150
  };
package/lib/check.mjs CHANGED
@@ -4,13 +4,13 @@
4
4
  * motion-kit · scene gate. Every scene, every format/locale it ships in, must
5
5
  * pass these before anything is exported or mounted.
6
6
  *
7
- * checkScene(scene, { style }) → { ok, problems: string[] }
7
+ * checkScene(scene, { style }) → { ok, problems: string[], warnings: string[] }
8
8
  *
9
9
  * Over files, formats and locales (the CLI and the vendored gate): lib/gate.mjs.
10
10
  */
11
11
  import { labelProblems } from "../runtime/iso.mjs";
12
12
  import { renderSvg, validateScene } from "../runtime/scene.mjs";
13
- import { checkContrast, normalizeStyle } from "../runtime/style.mjs";
13
+ import { contrastReport, normalizeStyle } from "../runtime/style.mjs";
14
14
 
15
15
  const SAMPLES = 120;
16
16
 
@@ -191,16 +191,20 @@ export const SETTLE_AFTER = Object.freeze([0.001, 0.015, 0.03, 0.045]);
191
191
  * Run the scene gate on one built scene.
192
192
  * @param {import("../runtime/scene.mjs").Scene} scene
193
193
  * @param {{ samples?: number, style?: any }} [options]
194
- * style: what the scene's own `contrastPairs` are checked against (neutral
195
- * if absent). The pairs every scene draws (CONTRAST_PAIRS) are a property of
196
- * the style alone, checked once per style by lib/gate.mjs.
197
- * @returns {{ ok: boolean, problems: string[] }}
194
+ * style: what the scene's pairs are checked against (neutral if absent): its
195
+ * own `contrastPairs` if it declares them, else all of CONTRAST_PAIRS. The
196
+ * shared pairs a declaring scene leaves out come back as `warnings`.
197
+ * @returns {{ ok: boolean, problems: string[], warnings: string[] }}
198
198
  */
199
199
  export function checkScene(scene, { samples = SAMPLES, style } = {}) {
200
200
  const problems = [];
201
201
  style = normalizeStyle(style);
202
- try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)] }; }
203
- for (const p of checkContrast(style)) problems.push(`contrast: ${p}`);
202
+ try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)], warnings: [] }; }
203
+ // The style against the pairs this scene draws (G12): all the shared ones
204
+ // unless it declares its own (`scene.contrastPairs`), which then stand in
205
+ // for them; the shared pairs it leaves out are only warnings.
206
+ const { problems: contrastProblems, warnings } = contrastReport(style, scene.contrastPairs);
207
+ for (const p of contrastProblems) problems.push(`contrast: ${p}`);
204
208
  const render = (/** @type {number} */ t) => renderSvg(scene, t, { style });
205
209
  const at = (/** @type {number} */ i) => (scene.duration * i) / samples;
206
210
 
@@ -284,11 +288,7 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
284
288
  }
285
289
  for (const id of fixed) problems.push(`fixed id "${id}": build ids from frame(t, { idPrefix }), e.g. \`\${idPrefix}-${id}\``);
286
290
 
287
- // 8. The token pairs this scene draws beyond the shared ones
288
- // (scene.contrastPairs) meet their contrast in the style, both themes.
289
- if (scene.contrastPairs !== undefined) {
290
- for (const p of checkContrast(style, scene.contrastPairs)) problems.push(`contrast: ${p}`);
291
- }
291
+ // 8. (Contrast, G12: checked first, above, by contrastReport.)
292
292
 
293
293
  // 9. Labels the scene declares (scene.labelBoxes): at the sampled times, each
294
294
  // step and the end, no two overlap, no stem crosses another label and none
@@ -322,5 +322,5 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
322
322
  }
323
323
  }
324
324
 
325
- return { ok: problems.length === 0, problems };
325
+ return { ok: problems.length === 0, problems, warnings };
326
326
  }
package/lib/gate.mjs CHANGED
@@ -6,18 +6,22 @@
6
6
  *
7
7
  * checkFiles(files, { formats, locales, style, options }) → number of failures
8
8
  *
9
- * - The style must pass the contrast check for the pairs every scene draws
10
- * (G12, CONTRAST_PAIRS), once.
11
9
  * - Every file × format (all of FORMATS unless given) × locale passes
12
- * checkScene, which also checks the style against the pairs that scene
13
- * declares it draws besides (`scene.contrastPairs`). Locales: the given ones; else, for a spec, every locale its
14
- * strings carry, and a module’s exported `locales` (default `en`).
10
+ * checkScene, which holds the style to the contrast pairs that scene draws
11
+ * (G12): the pairs its scene type draws, its own `contrastPairs`, or, if it
12
+ * declares none, all of CONTRAST_PAIRS. Locales: the given ones; else, for a
13
+ * spec, every locale its strings carry, and a module’s exported `locales`
14
+ * (default `en`).
15
+ * - The style's other shared pairs are reported once, as warnings, with the
16
+ * scene types they would fail: a style author sees every shared pair's
17
+ * result, and no scene fails on a pair it does not draw.
15
18
  * - A file that cannot be read, parsed or built is a failure for that file
16
19
  * only; the remaining files are still checked.
17
20
  */
18
21
  import { readFileSync } from "node:fs";
19
22
  import { FORMATS } from "../runtime/scene.mjs";
20
- import { checkContrast } from "../runtime/style.mjs";
23
+ import { CONTRAST_PAIRS, checkContrast } from "../runtime/style.mjs";
24
+ import { SCENE_TYPE_PAIRS } from "../runtime/types/index.mjs";
21
25
  import { checkScene } from "./check.mjs";
22
26
  import { isModule, loadScene, moduleLocales } from "./load.mjs";
23
27
 
@@ -45,17 +49,28 @@ export function detectLocales(spec) {
45
49
  return found.size ? [...found] : ["en"];
46
50
  }
47
51
 
52
+ /**
53
+ * Every shared contrast pair the style misses, each with who draws it: the
54
+ * scene types that fail on it, and any custom scene that declares no pairs of
55
+ * its own (it is held to all of them).
56
+ * @param {any} style
57
+ * @returns {string[]}
58
+ */
59
+ export function styleWarnings(style) {
60
+ return CONTRAST_PAIRS.flatMap((pair) => {
61
+ const types = Object.entries(SCENE_TYPE_PAIRS).filter(([, pairs]) => pairs.some((p) => p.fg === pair.fg && p.bg === pair.bg)).map(([t]) => t);
62
+ return checkContrast(style, [pair]).map((problem) => `${problem} (held against: ${[...types, "custom scenes that declare no or empty contrastPairs, or name this pair"].join(", ")}; a warning for any other scene)`);
63
+ });
64
+ }
65
+
48
66
  /**
49
67
  * @param {string[]} files specs (.json) and custom modules (.mjs)
50
- * @param {{ formats?: string[], locales?: string[], style?: any, options?: import("./load.mjs").OptionsSource, log?: (line: string) => void, error?: (line: string) => void }} [o]
68
+ * @param {{ formats?: string[], locales?: string[], style?: any, options?: import("./load.mjs").OptionsSource, log?: (line: string) => void, error?: (line: string) => void, warn?: (line: string) => void }} [o]
51
69
  * @returns {Promise<number>} failures (0 = the gate passes)
52
70
  */
53
- export async function checkFiles(files, { formats, locales, style, options, log = console.log, error = console.error } = {}) {
71
+ export async function checkFiles(files, { formats, locales, style, options, log = console.log, error = console.error, warn = console.warn } = {}) {
54
72
  let bad = 0;
55
- for (const p of checkContrast(style)) {
56
- bad++;
57
- error(`✗ style: ${p}`);
58
- }
73
+ for (const p of styleWarnings(style)) warn(`⚠ style: ${p}`);
59
74
  for (const file of files) {
60
75
  const module = isModule(file);
61
76
  let fileLocales = locales?.length ? locales : ["en"];