@liqweed/motion-kit 0.12.0 → 0.14.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.12.0"
10
+ "version": "0.14.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.12.0",
3
+ "version": "0.14.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
@@ -28,6 +28,11 @@ README and follow your GitHub theme. Regenerate with `npm run media`.
28
28
  <img src="docs/media/smart-home-light.svg" alt="smart-home: a hub-and-spoke scene" width="720">
29
29
  </picture>
30
30
 
31
+ <picture>
32
+ <source media="(prefers-color-scheme: dark)" srcset="docs/media/bars-dark.svg">
33
+ <img src="docs/media/bars-light.svg" alt="bars: a three-row benchmark chart comparing cached 0.8 s, incremental 2.4 s, and clean 6.5 s builds" width="720">
34
+ </picture>
35
+
31
36
  The interactive player (scrubber, steps, captions) needs scripts, which
32
37
  GitHub does not run: `node cli/motion-kit.mjs build examples/order-flow.json -o out/order.html`
33
38
  and open the file.
@@ -56,9 +61,10 @@ dependency) or Chrome; video: `ffmpeg`.
56
61
  ```
57
62
  runtime/ dependency-free ES modules (browser + Node)
58
63
  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, several tokens
64
+ svg.mjs escaping, rounding, el/text/fade, polyline + Bézier arc-length, drawOn, several tokens, blur reveal, highlighter sweep
60
65
  iso.mjs isometric kit for custom scenes: camera, solids (rounded too), depth order, grid backdrop, content on faces, label anchors and pills
61
66
  connectors.mjs dashed connectors, diamond junctions and single-pass light pulses for custom scenes
67
+ bars.mjs hatched tracks, rounded bars on the style's curve and rolling values for custom scenes
62
68
  wrap.mjs label wrapping with hard budgets
63
69
  style.mjs tokens, neutral style, contrast checks, token resolution
64
70
  scene.mjs scene contract, formats, renderSvg
@@ -74,8 +80,10 @@ skills/ animated-diagram, motion-render, project-logo (Claude Code / Cra
74
80
  examples/ order-flow (sequence), smart-home (hub-spoke), incident (timeline),
75
81
  web-stack (stack), custom-pulse (custom module),
76
82
  isometric-swivel (custom module: isometric kit, several tokens),
77
- isometric-platform (custom module: rounded slabs, grid backdrop, mark on a top face, pill tags)
78
- connectors (custom module: connectors, diamond junctions, pulses)
83
+ isometric-platform (custom module: rounded slabs, grid backdrop, mark on a top face, pill tags),
84
+ connectors (custom module: connectors, diamond junctions, pulses),
85
+ text-reveal (custom module: blur-and-fade reveal, highlighter sweep),
86
+ bars (custom module: hatched tracks, bars, rolling values)
79
87
  bench/ heavy scene for npm run bench:player (live-player frame cost)
80
88
  brand/ logo scene (built with motion-kit); renders go to assets/ + .idea/ (npm run media)
81
89
  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-19
4
+ last_updated: 2026-11-21
5
5
  ---
6
6
 
7
7
  # motion-kit technique — normative specification
@@ -39,7 +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 | 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
- | `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` and `labelPill` return 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
+ | `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(...)` and `labelPill(...)` return `{markup, box}`; return its `.box`, not the whole result, §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 `id` a string and the rest finite numbers, `width` and `height` not negative, `opacity`, when given, finite, and `stem`, when given, `{x1, y1, x2, y2}` with four 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
 
45
45
  - A scene MUST be produced by either a registered scene type —
@@ -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`, `connectors` 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`, `bars` 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
@@ -68,9 +68,9 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
68
68
  |---|---|---|---|
69
69
  | T1 | `frame(t)` MUST depend only on `t` and the scene's constants: no `Date`, `Math.random`, `performance.now`, no state carried between calls, no module-level mutable state. | [gate] G1 re-renders each `t`; G11 renders under stubbed clocks and scans the source (`lib/check.mjs`) | Random access: a player can jump, an exporter can write exactly one frame, video samples `t = f/fps` (`runtime/scene.mjs:14-17`). |
70
70
  | T2 | Same `t` (and same style/options) MUST give byte-identical output. | [gate] G1 | Tests, diffs, caching and committed media all depend on it. |
71
- | T3 | Callers MUST clamp `t` to `[0, duration]`; `renderSvg` does (`runtime/scene.mjs:70`). `frame` MAY assume a clamped `t`. | — | Defines "before start" and "hold". |
72
- | T4 | Every number interpolated into markup MUST be rounded: `num(n, 2)` by default, 3 digits for `opacity`, 4 for scale factors (`runtime/svg.mjs:17-22,29,64`). `num` MUST throw on non-finite input and never emit `-0`. | [gate] G3; non-finite → G5 | 17-digit floats made "settled" frames differ by 1 ms (`skills/animated-diagram/references/technique.md:128-129`). |
73
- | T5 | Visibility MUST be decided on rounded values: an element whose opacity rounds to 0 is omitted; an opacity that rounds to 1 is not written (`runtime/svg.mjs:28,39,68-72`). | by construction (`el`, `fade`) | Identical-looking frames must be identical bytes (opacity 0.9999 vs omitted). |
71
+ | T3 | Callers MUST clamp `t` to `[0, duration]`; `renderSvg` does (`renderSvg` in `runtime/scene.mjs`). `frame` MAY assume a clamped `t`, except that it MUST hold: the gate also calls it with a raw `t` past `duration` and requires the final frame. | — | Defines "before start" and "hold". |
72
+ | T4 | Every number interpolated into markup MUST be rounded: `num(n, 2)` by default, 3 digits for `opacity`, 4 for scale factors (`num`, `el`, `fade` in `runtime/svg.mjs`). `num` MUST throw on non-finite input and never emit `-0`. | [gate] G3; non-finite → G5 | 17-digit floats made "settled" frames differ by 1 ms (`skills/animated-diagram/references/technique.md`, "Lessons learned"). |
73
+ | T5 | Visibility MUST be decided on rounded values: an element whose opacity rounds to 0 is omitted; an opacity that rounds to 1 is not written (`el`, `fade` in `runtime/svg.mjs`). | by construction (`el`, `fade`) | Identical-looking frames must be identical bytes (opacity 0.9999 vs omitted). |
74
74
  | T6 | Scenes MUST NOT use CSS transitions/animations or timers; the renderer owns the clock (`runtime/player.mjs:15`). | — | Exported frames would not match what plays. |
75
75
  | T7 | Variation, if any, MUST derive from constants and `t` (seeded), never from runtime randomness. | [gate] G1, G11 | Same as T2. |
76
76
 
@@ -194,13 +194,13 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
194
194
  ### 4.7 Geometry: arc length and draw-on (`runtime/svg.mjs`)
195
195
 
196
196
  - `polyline(points)` → `{length, d, at(f)}`; `at` returns the point at fraction
197
- `f` of total arc length (`runtime/svg.mjs:92-113`).
197
+ `f` of total arc length (`polyline` in `runtime/svg.mjs`).
198
198
  - `cubic(p0…p3, samples = 64)` → `{length, d, at(f)}` with a 64-sample
199
199
  arc-length lookup table and binary search, so a marker moves at constant
200
- speed without a DOM in Node and browsers (`runtime/svg.mjs:119-152`).
200
+ speed (approximately, within a lookup interval) without a DOM in Node and browsers (`cubic` in `runtime/svg.mjs`).
201
201
  - `drawOn(length, p)`: `null` for `p ≤ 0`, `{}` for `p ≥ 1`, else
202
202
  `stroke-dasharray: L L; stroke-dashoffset: L·(1 − p)`
203
- (`runtime/svg.mjs:159-163`). Callers MUST skip the element when it returns
203
+ (`drawOn` in `runtime/svg.mjs`). Callers MUST skip the element when it returns
204
204
  `null`: a zero-length dash with round caps paints a dot.
205
205
  - Two-state elements (pending → active) MUST cross-fade two layers with
206
206
  opacities `1 − p` and `p` instead of interpolating colours, which would need
@@ -247,7 +247,7 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
247
247
  opacity, id})` extrudes a convex footprint (any winding; stored
248
248
  counter-clockwise) from base height `z` by `h` ≥ 0; `box` (centred on x, y)
249
249
  and `slab` (default `h` 0.25) are rectangular prisms; `regularPolygon` makes
250
- a footprint. A non-convex, degenerate or too-small footprint, an unknown
250
+ a footprint. A non-convex, degenerate or too-small footprint, one with a repeated vertex (adjacent or not, so a footprint that winds round twice), an unknown
251
251
  token or a negative height throws. `fill` is the token of the top face,
252
252
  `sides` of the side faces (default `fill`); `shade` (default `ink`, `null`
253
253
  for none) is layered over each side at an opacity from 0.10 to 0.26 by how
@@ -305,8 +305,9 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
305
305
  - **Labels.** `labelAnchor(cam, {id, at, lines, fontSize, lift, side,
306
306
  opacity})` draws a dot on the projected point, a vertical stem `lift` pixels
307
307
  up and a label box above it (or beside its top), and returns the markup and
308
- the `LabelBox`. `labelProblems(boxes, {width, height, gap = 4})` lists the
309
- collisions G15 reports. Labels follow §7 (wrapped, localized, ≥ 14 px).
308
+ the `LabelBox`, rounded to two decimals as the SVG attributes are, so the gate
309
+ and the picture agree on those coordinates (`labelPill` rounds its box the same way). `labelProblems(boxes, {width, height, gap = 4, limit})`
310
+ lists the collisions G15 reports, and stops at `limit` (a whole number from 0 or Infinity, else `RangeError`; default all; 0 returns none; only distinct sentences count). Labels follow §7 (wrapped, localized, ≥ 14 px).
310
311
  `labelPill({id, x, y, lines, fontSize, fill, stroke, ink, opacity})` is a
311
312
  stemless tag: a rounded box of text centred on the screen point (`x`, `y`),
312
313
  its colours tokens (`surface`, `line`, `ink` by default). It returns the
@@ -358,11 +359,128 @@ functions; a colour is a token name (G4 applies).
358
359
  its target has filled, and nothing repeats while a step rests, so the
359
360
  settled-frame rule (G6) holds. Several pulses may run in one beat.
360
361
 
362
+ ### 4.11 Text reveal and highlighter sweep (`runtime/svg.mjs`)
363
+
364
+ - `blurReveal(enter, {id, rise = 6, blur = 4}, ...children)` draws `children`
365
+ with an opacity that rises to one and a rise and a blur that go to zero as
366
+ `enter` (an eased progress, §4.2) goes from 0 to 1: one `<g transform opacity filter>` and,
367
+ while the blur is 0.005 or more, a `<defs>` holding one `<filter>` with one
368
+ `<feGaussianBlur>`. It returns `""` for `enter ≤ 0` and wherever the opacity rounds to zero.
369
+ - **Settled means bare.** Once `enter` reaches 1, as `fade` rounds it (0.9995
370
+ and above), `blurReveal` MUST return the children unchanged: no group, no
371
+ filter, no `<defs>`, so a settled frame is byte-identical to the same markup
372
+ drawn without the reveal, and every step frame, the final frame, a baked
373
+ last slice and a reduced-motion frame carry no filter. Between 0 and 1 the
374
+ `transform` and the `filter` are left off once they round to nothing
375
+ (a rise or a blur under 0.005 units), so a frame never carries
376
+ a `stdDeviation="0"`, which renderers read differently.
377
+ - **Ids.** `id` names the filter and MUST be built from `frame`'s `idPrefix`
378
+ (`${idPrefix}-reveal-1`), one per revealed element, so the sampled G14 check for ids shared across instances holds and a baked
379
+ SVG, which renders each slice with its own prefix, never repeats one
380
+ [throws unless `id` is a CSS-safe token]. `rise` is 0 to 24 and `blur` 0 to 12
381
+ [throws].
382
+ - **Renderers.** The filter is `feGaussianBlur` in sRGB over a region of
383
+ `x −25 %`, `y −100 %`, `width 150 %`, `height 300 %` of the element's box,
384
+ which holds the blur only while, on each side, the padding (25 % of the width sideways, 100 % of the height above and below) less any overhang of stroke or markers past the box leaves at least 3 × `blur` of clearance. For an element too narrow or shallow for that (a zero-height rule included), a `blur` above the default, or a stroke or markers that eat the padding (a thick stroke on a small shape, at any size), `box: {x, y, width, height}` (the
385
+ element's own painted box: all four fields finite, `width` and `height` positive, `x` and `y` free [throws], covering the painted stroke) makes the region that box
386
+ plus 3 × `blur` on every side (`filterUnits="userSpaceOnUse"`). The tests compare the SVG markup, baked slices and the patched DOM, and a resvg fixture of one mid-reveal frame; other renderers are not compared. The live player (its
387
+ in-place patch updates `stdDeviation` and the group's attributes, and drops
388
+ the group when the reveal ends), `renderSvg` and `bake` use the same helper and filter parameters; their SVG bytes differ (`bake` renames filter ids per slice and wraps frames in groups; `renderSvg` resolves token references only in standalone mode), so do not compare or reuse them interchangeably. PNG export and video rasterize with resvg or Chrome, and raster appearance can vary with renderer, fonts and scale (`test/reveal.test.mjs`,
389
+ `test/player.test.mjs`). A consumer that ignores SVG filters (some slide
390
+ applications) shows the fade and the rise without the blur, and only in a
391
+ frame taken mid-reveal: step frames carry no filter.
392
+ - **Timing.** The reveal is one entrance, 300 to 600 ms (§4.2), on the style's
393
+ entrance curve (`easings(style.motion).easeOut`), finished 50 ms or more
394
+ before the step it belongs to. That is the scene's obligation: G6 only checks that frames around a step are stable, so a scene that holds `enter` at, say, 0.5 through a step or the end keeps a filter in those frames and passes. The no-filter guarantee holds only for a reveal completed in time. It happens once per element and holds.
395
+ The blur is a paint cost no other motion helper has; the plain fade
396
+ (`fade`) stays the default for a label whose arrival does not need to be
397
+ watched
398
+ ([`motion-vocabulary.md`](../../skills/animated-diagram/references/motion-vocabulary.md)).
399
+ - `highlightSweep(p, {x, y, width, height, token = "emphasis", opacity = 0.3,
400
+ radius = 4})` draws a rounded `<rect>` filled with a token at `opacity`,
401
+ from `x` to `x + width · p` (`p` eased, 0 to 1); `""` for a swept width under 0.01 (`p ≤ 0` included), which returns before the `token` is read, so an unknown token throws only once the swept width reaches 0.01; an `opacity` that rounds to zero also yields `""`, but only after the `token` has been checked; at 1 the
402
+ rectangle is the same on every frame. It is drawn before the text it marks,
403
+ and `opacity` starts low (0.2 to 0.4): at the default 0.3 the neutral
404
+ style's ink reads on the tinted canvas at 4.5:1 or more in both themes
405
+ (`test/reveal.test.mjs`). The gate checks text against the canvas, not
406
+ against the band, so a custom style must check its ink against the
407
+ composited tint itself. `width` is the scene's to set; `estimateWidth` is a
408
+ rough heuristic (characters × size × 0.56), not a bound, so pass a
409
+ conservative width where the band must cover the whole line [throws on a
410
+ non-finite or non-positive size, an unknown token, or an `opacity` that is
411
+ not a finite number in (0, 1]].
412
+ - Both helpers are pure functions of their arguments. `examples/text-reveal.scene.mjs`
413
+ reveals three labels in reading order, then a quoted line with one band per
414
+ wrapped line swept first line to last.
415
+
416
+ ### 4.12 Bars with values (`runtime/bars.mjs`)
417
+
418
+ For custom scenes that chart a few values; handed to them in `kit`. Pure
419
+ functions; a colour is a token name (G4 applies).
420
+
421
+ - **Hatch.** `hatchPattern({idPrefix, name, stroke, spacing, width})` returns
422
+ `{id, fill, markup}`: a `<pattern>` of lines at 45°, rising to the right,
423
+ `spacing` px apart (default 7) and `width` px wide (default 1.5), in the token
424
+ `stroke` (default `line`). Its id is `${safeId(idPrefix)}-hatch-${name}` (`name` defaults to
425
+ `hatch`), so its hatch namespace cannot collide with clip paths generated by `drawBar`; a scene that draws several hatchings gives each
426
+ its own `name`, of letters, digits and `_` only. Prefixes must be unique after `safeId` normalizes them. `name` also cannot be `title` or `desc`,
427
+ which `renderSvg` reserves. `markup` is a `<defs>` the frame emits once, before the tracks,
428
+ on every frame; `fill` is `url(#id)`. The pattern is in the user space of the element that references it (picture
429
+ units for tracks drawn at the top level, which scale with the SVG), so
430
+ tracks that share it show one continuous hatch, and in the player, in `bake`
431
+ and in a PNG or video export it draws the same. It makes the `idPrefix` a safe id token as `renderSvg` does; it throws for an
432
+ empty `idPrefix`, a `name` that is not a safe id token or is reserved, a `spacing` of 0 or less, and a `width` of
433
+ 0 or less or not below the spacing after SVG number rounding. A hatch must come from `hatchPattern`; a frozen hatch from another vendored runtime copy works too, if its `fill` is an own data property `url(#id)` (a getter or an inherited `fill` is refused).
434
+ - **Track.** `drawTrack({x, y, width, height, hatch, fill, radius, opacity, id})`
435
+ is an empty bar: a rounded rect filled with the token `fill` (default
436
+ `surface`, `null` for none) and the `hatch` over it. It needs one of the two.
437
+ `radius` defaults to half the height and is never more than half a side. It
438
+ throws for a size of 0 or less (including after SVG number rounding) and for a hatch that is not frozen or whose `fill` is not `url(#id)`. It emits only the hatch's `fill`; putting its `markup` in the frame is the scene's job, and a hatch whose `<defs>` is missing paints nothing.
439
+ - **Bar.** `drawBar({x, y, width, height, p, fill, radius, trackRadius, opacity, idPrefix, id, trackWidth})` draws a
440
+ bar from `x` that is `width * p` long (`width` is its length when done, a share
441
+ of the track's, `p` the eased
442
+ progress 0..1 of its growth), rounded at both ends all the way, so it grows as
443
+ a pill. Nothing for `p ≤ 0`; `p ≥ 1` is the bar it rests as. `fill` is a token
444
+ (default `accent`). Give `trackWidth`, the frame's `idPrefix`, and a local safe
445
+ `id` (letters, digits and `_`, except `title` and `desc`) to clip a short bar to its rounded track; clip IDs use a separate `-clip-` namespace. Use
446
+ `trackRadius` whenever the track sets a `radius` explicitly (the clip otherwise defaults to half the track height, whatever the bar's own `radius`).
447
+ - **Growth.** `barProgress(t, {start, duration}, style)` is the bar's `p`: 0
448
+ before `start` and exactly 1 from `barEnd(run)` = `start + duration` on, on the
449
+ style's movement curve (`style.motion.move`, through `easings`, so it settles
450
+ whatever curve the style names), the default curve for no style. `style` is the
451
+ one `frame(t, {idPrefix, style})` receives. A run has a finite `start` and a
452
+ finite, positive `duration` and a finite end strictly after its start; invalid
453
+ runs throw rather than producing an invalid end time.
454
+ - **Value.** `rollingValue(from, to, p)` is `from` at `p ≤ 0`, `to` itself, not a
455
+ sum that rounds to it, at `p ≥ 1`, and between them a straight line in `p`, so
456
+ the raw number and the bar, which `p` has already eased, arrive together (a
457
+ `format` that rounds may show its final digits before the bar settles).
458
+ `drawValue({x, y, to, from, p, format, fontSize, anchor, fill, weight, family,
459
+ opacity, id})` draws `format(rollingValue(from, to, p))` as text (default
460
+ `from` 0, `format` rounding to a whole number, `anchor` `start`, `fill` the
461
+ token `ink`, `dominant-baseline` central on `y`). `format` is the caller's and
462
+ carries the units, decimals and locale; it must return a string, which is
463
+ escaped. It throws for a `format` that is not a function or returns another
464
+ type, and for a non-finite number. Until the monospace face of the style
465
+ lands, a scene sets its own `family` to keep the digits from jittering.
466
+ - **Canon.** A bar grows once, in a step's beat, and rests (§4.8): every bar of
467
+ the beat has settled (`barEnd`) at least 50 ms before the step's `at`, and from
468
+ then its value is exactly `format(to)`, so the step frame is the settled
469
+ frame (G6). G6 compares the whole frame up to 45 ms after `at`, so the track's
470
+ own entrance also finishes 50 ms or more before `at`, and the next motion
471
+ starts no earlier than 50 ms after it. Nothing repeats. A value that updates live beside footage is not
472
+ this part. A scene that draws the bar's accent on the track's colour declares
473
+ the pairs in `contrastPairs` (G12), for example `accent` on `surface` at 3 and
474
+ `line` on `surface` at 2.5 for decorative hatch texture. Informative hatching
475
+ is a shape and needs 3:1; the opaque bar itself is adjacent to `surface`, not
476
+ to the hatch beneath it.
477
+
478
+
361
479
  ## 5. Markup
362
480
 
363
481
  - Text and attribute values MUST be escaped (`& < > " '`) via `esc`, `text` or
364
- `el`/`attrString` (`runtime/svg.mjs:10-14,24-33,45-57`). Labels MUST NOT be able
365
- to inject markup (`test/runtime.test.mjs:118-124`).
482
+ `el`/`attrString` (`esc`, `text`, `el` in `runtime/svg.mjs`). Labels MUST NOT be able
483
+ to inject markup (the "escapes label text" test in `test/runtime.test.mjs`).
366
484
  - `el(tag, attrs, …children)` treats children as trusted markup; untrusted
367
485
  strings MUST go through `text()`/`esc()`.
368
486
  - Output MUST be well-formed: balanced tags, no stray `<`, no bare `&` [gate] G2.
@@ -689,14 +807,15 @@ that removes every listener, observer and mark they added.
689
807
  ## 11. The gate
690
808
 
691
809
  `checkScene(scene)` (`lib/check.mjs`) samples 121 evenly spaced times
692
- (`SAMPLES = 120`) and stops collecting after 13 problems.
810
+ (`SAMPLES = 120`). The per-sample rules test for 13 problems between samples, so one sample can add a few more; the fixed-id check and the label gate (rule 9) hold to what is left of 13, but the settled-step check appends one problem per moving step whatever the count, so the total can exceed 13.
693
811
  `motion-kit check` and the vendored `check.mjs` both run `checkFiles`
694
812
  (`lib/gate.mjs`): every file × format (all six unless `--format`, repeatable)
695
813
  × locale (`--locale`, repeatable; else every locale a spec's strings carry, and
696
814
  `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
697
815
  for the shared pairs the style misses. A file that cannot be read, parsed or built fails on its own and the
698
- remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = unit tests +
699
- `check` over `examples/` and `brand/` (`package.json:15-18`).
816
+ remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = `gate:core`
817
+ (typecheck, version sync, unit tests, `check` over `examples/` and `brand/`,
818
+ media freshness) plus the site build (`package.json` scripts `gate:core`, `gate`).
700
819
 
701
820
  | ID | Rule | Code | Rationale |
702
821
  |---|---|---|---|
@@ -707,7 +826,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
707
826
  | G5 | No `NaN`, `undefined`, `Infinity` in `frame()` output. | `:50` | Silent geometry bugs. |
708
827
  | G6 | For every step, `render(at)` equals `render(at − 1 ms)` and `render(at + δ)` for δ = 1, 15, 30, 45 ms (before the next step). | `lib/check.mjs` (rule 2, `SETTLE_AFTER`) | Settled step frames (§8); the 45 ms look-ahead sees slow motion that rounding hides over 1 ms. |
709
828
  | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
710
- | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
829
+ | G8 | `frame(duration + 5) === frame(duration)`, called raw, unclamped. | `checkScene` in `lib/check.mjs` | Holds the final frame. |
711
830
  | G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
712
831
  | 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. |
713
832
  | 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. |
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Example custom scene: three rows of a small benchmark, revealed top to bottom,
3
+ * one step each.
4
+ *
5
+ * Shows the bar parts (runtime/bars.mjs): an empty track filled with diagonal
6
+ * hatching, a rounded bar that grows over it on the style's movement curve, and
7
+ * a number beside it that rolls up with the bar and shows exactly its end value
8
+ * once the bar has settled. The hatch's id is built from the frame's `idPrefix`,
9
+ * so two instances on a page never share one. Each bar grows once, inside its
10
+ * step's beat, and is settled (`barEnd`) before the step's time, so every step
11
+ * frame is settled. Nothing loops: the scene plays once and holds its last frame.
12
+ * Pure: frame(t) depends only on t and constants.
13
+ */
14
+ import { barEnd, barProgress, drawBar, drawTrack, drawValue, hatchPattern } from "../runtime/bars.mjs";
15
+ import { easings, progress } from "../runtime/motion.mjs";
16
+ import { FORMATS, localize } from "../runtime/scene.mjs";
17
+ import { sharedPairs, tok } from "../runtime/style.mjs";
18
+ import { fade, text } 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: "Build time, three ways", nl: "Bouwtijd, op drie manieren" },
25
+ description: {
26
+ en: "Three bars over hatched tracks show how long a build takes: cached, incremental and clean. Each bar grows while its time counts up.",
27
+ nl: "Drie balken over gearceerde banen tonen hoe lang een build duurt: uit cache, incrementeel en schoon. Elke balk groeit terwijl de tijd oploopt.",
28
+ },
29
+ unit: { en: "s", nl: "s" },
30
+ rows: [
31
+ { label: { en: "Cached", nl: "Uit cache" }, value: 0.8, detail: { en: "Nothing changed, so the build is read back.", nl: "Er is niets veranderd, dus de build wordt teruggelezen." } },
32
+ { label: { en: "Incremental", nl: "Incrementeel" }, value: 2.4, detail: { en: "Only what changed is built again.", nl: "Alleen wat veranderd is wordt opnieuw gebouwd." } },
33
+ { label: { en: "Clean", nl: "Schoon" }, value: 6.5, detail: { en: "Everything is built from scratch.", nl: "Alles wordt vanaf nul gebouwd." } },
34
+ ],
35
+ };
36
+
37
+ // Timeline, in seconds. Row i starts at START + i·PERIOD: its track fades in,
38
+ // then its bar grows while the value rolls, and the step comes 100 ms after the
39
+ // bar has settled. The next row starts well after that.
40
+ const START = 0.2;
41
+ const PERIOD = 1.4;
42
+ const ENTER = 0.4;
43
+ const GROW = { delay: 0.25, duration: 0.7 };
44
+ const SETTLE = 0.1;
45
+ const SCALE = 8; // the track's full length is this many seconds
46
+ const MONO = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
47
+
48
+ /** @param {number} i */
49
+ const rowStart = (i) => START + i * PERIOD;
50
+ /** @param {number} i */
51
+ const growRun = (i) => ({ start: rowStart(i) + GROW.delay, duration: GROW.duration });
52
+
53
+ export default function make({ format = "16:9", locale = "en" } = {}) {
54
+ const f = FORMATS[format];
55
+ if (!f) throw new Error(`unknown format "${format}"`);
56
+ const W = f.width;
57
+ const fs = 17;
58
+ const barH = 26;
59
+ const gap = 8; // between a row's label and its track
60
+ const rowGap = 26;
61
+ const pad = 32;
62
+ const valueW = 92;
63
+ const rowH = fs * 1.25 + gap + barH;
64
+ const total = COPY.rows.length * rowH + (COPY.rows.length - 1) * rowGap;
65
+ const H = f.height || Math.round(total + 2 * pad);
66
+ const top = (H - total) / 2;
67
+ const trackX = pad;
68
+ const trackW = W - 2 * pad - valueW - 12;
69
+ const valueX = W - pad;
70
+ const number = new Intl.NumberFormat(locale, { minimumFractionDigits: 1, maximumFractionDigits: 1 });
71
+ const format1 = (/** @type {number} */ v) => `${number.format(v)} ${localize(COPY.unit, locale)}`;
72
+ const labels = COPY.rows.map((r) => wrapLabel(localize(r.label, locale), Math.floor((W - 2 * pad) / (fs * 0.56)), 1));
73
+
74
+ /** @param {number} t @param {{ idPrefix: string, style?: any }} ctx */
75
+ function frame(t, { idPrefix, style }) {
76
+ const hatch = hatchPattern({ idPrefix, stroke: "line" });
77
+ const { easeOut } = easings(style?.motion);
78
+ const out = [hatch.markup];
79
+ COPY.rows.forEach((row, i) => {
80
+ const enter = progress(t, rowStart(i), ENTER, easeOut);
81
+ if (enter <= 0) return;
82
+ const y = top + i * (rowH + rowGap);
83
+ const ty = y + fs * 1.25 + gap;
84
+ const p = barProgress(t, growRun(i), style);
85
+ out.push(
86
+ fade(enter, {}, text({ x: pad, y: y + (fs * 1.25) / 2, "dominant-baseline": "central", "font-size": fs, "font-weight": 600, fill: tok("ink") }, labels[i])),
87
+ drawTrack({ x: trackX, y: ty, width: trackW, height: barH, hatch, opacity: enter, id: `row-${i}` }),
88
+ drawBar({ x: trackX, y: ty, width: trackW * (row.value / SCALE), trackWidth: trackW, height: barH, p, idPrefix, id: `row_${i}` }),
89
+ drawValue({ x: valueX, y: ty + barH / 2, to: row.value, p, format: format1, fontSize: 20, anchor: "end", family: MONO, opacity: enter, id: `row-${i}` }),
90
+ );
91
+ });
92
+ return out.join("");
93
+ }
94
+
95
+ const steps = COPY.rows.map((row, i) => ({
96
+ at: barEnd(growRun(i)) + SETTLE,
97
+ label: localize(row.label, locale),
98
+ detail: `${localize(row.detail, locale)} ${format1(row.value)}`,
99
+ }));
100
+
101
+ return {
102
+ id: `bars-${format.replace(":", "x")}`,
103
+ width: W,
104
+ height: H,
105
+ duration: steps[steps.length - 1].at + 0.4,
106
+ title: localize(COPY.title, locale),
107
+ description: localize(COPY.description, locale),
108
+ // The pairs this scene draws: the labels and values on the canvas, and the
109
+ // bar's accent fill on its track.
110
+ contrastPairs: [...sharedPairs("ink/bg"), { fg: "accent", bg: "surface", min: 3, use: "the bar's fill on its track" }, { fg: "line", bg: "surface", min: 2.5, use: "the hatching on the track: texture that marks the empty track, not data" }],
111
+ steps,
112
+ frame,
113
+ };
114
+ }
@@ -0,0 +1,152 @@
1
+ /**
2
+ * Example custom scene: text that sharpens into place, and a highlighter.
3
+ *
4
+ * Shows the text helpers of `kit` (runtime/svg.mjs): `blurReveal`, which
5
+ * fades a line in while it rises a few units and a blur goes to zero, and
6
+ * `highlightSweep`, a token-coloured band that grows behind a line. Three
7
+ * labels reveal in reading order, then a quoted line reveals and is marked,
8
+ * one band per wrapped line, swept from the first line to the last. Each
9
+ * reveal is one beat on the style's entrance curve and ends before its step,
10
+ * so a step frame carries no filter at all. Nothing loops. Pure: frame(t)
11
+ * depends only on t and constants.
12
+ */
13
+ import { easings, progress } from "../runtime/motion.mjs";
14
+ import { FORMATS, localize } from "../runtime/scene.mjs";
15
+ import { tok } from "../runtime/style.mjs";
16
+ import { blurReveal, el, highlightSweep, text } from "../runtime/svg.mjs";
17
+ import { estimateWidth, wrapLabel } from "../runtime/wrap.mjs";
18
+
19
+ export const locales = ["en", "nl"];
20
+
21
+ const COPY = {
22
+ title: { en: "Release notes, line by line", nl: "Releasenotes, regel voor regel" },
23
+ description: {
24
+ en: "Three labels sharpen into place one after another, then a quoted line appears and a highlighter sweeps behind it.",
25
+ nl: "Drie labels worden één voor één scherp, daarna verschijnt een geciteerde regel en veegt een markeerstift erachter.",
26
+ },
27
+ heading: { en: "What's new", nl: "Wat is nieuw" },
28
+ labels: [
29
+ { en: "Faster startup", nl: "Snellere start" },
30
+ { en: "Smaller bundles", nl: "Kleinere bundels" },
31
+ { en: "Clearer errors", nl: "Duidelijkere fouten" },
32
+ ],
33
+ quote: {
34
+ en: "Each change lands once, then it holds.",
35
+ nl: "Elke wijziging landt één keer en blijft dan staan.",
36
+ },
37
+ steps: [
38
+ { label: { en: "Labels revealed", nl: "Labels onthuld" }, detail: { en: "Three labels sharpen into place, one after another.", nl: "Drie labels worden één voor één scherp." } },
39
+ { label: { en: "Quote highlighted", nl: "Citaat gemarkeerd" }, detail: { en: "A band sweeps behind the quoted line.", nl: "Een band veegt achter de geciteerde regel." } },
40
+ ],
41
+ };
42
+
43
+ const ENTER = 0.4; // one reveal (the entrance budget is 0.3–0.6 s)
44
+ const GAP = 0.12; // siblings, in reading order (80–150 ms)
45
+ const PAUSE = 0.05; // between a beat and its step
46
+ const QUOTE_AT = 1.3;
47
+ const SWEEP_AT = QUOTE_AT + 0.2;
48
+ const SWEEP = 0.6;
49
+
50
+ export default function make({ format = "16:9", locale = "en" } = {}) {
51
+ const f = FORMATS[format];
52
+ if (!f) throw new Error(`unknown format "${format}"`);
53
+ const W = f.width;
54
+ // Sizes follow the width, never below a readable 14.
55
+ const u = W >= 900 ? 1 : W >= 700 ? 0.85 : W >= 500 ? 0.7 : 0.55;
56
+ const fsHead = Math.max(14, Math.round(18 * u));
57
+ const fsLabel = Math.max(16, Math.round(36 * u));
58
+ const fsQuote = Math.max(14, Math.round(26 * u));
59
+ const x0 = Math.round(W * 0.1);
60
+ const pad = Math.round(fsQuote * 0.4); // the band's padding either side of the text
61
+ const chars = (/** @type {number} */ fs, /** @type {number} */ room) => Math.floor(room / (fs * 0.56));
62
+ const heading = localize(COPY.heading, locale);
63
+ const labels = COPY.labels.map((l) => wrapLabel(localize(l, locale), chars(fsLabel, W - 2 * x0), 1));
64
+ const quote = wrapLabel(localize(COPY.quote, locale), chars(fsQuote, W - 2 * x0 - 2 * pad), 3);
65
+
66
+ // Vertical layout, top to bottom, centred in the picture.
67
+ const rowLabel = Math.round(fsLabel * 1.5);
68
+ const rowQuote = Math.round(fsQuote * 1.6);
69
+ const headRow = Math.round(fsHead * 2.2);
70
+ const block = headRow + labels.length * rowLabel + Math.round(fsQuote * 1.4) + quote.length * rowQuote;
71
+ const H = f.height || block + 2 * Math.round(W * 0.1);
72
+ const top = Math.round((H - block) / 2);
73
+ const yHead = top + fsHead / 2;
74
+ const yLabel = (/** @type {number} */ i) => top + headRow + i * rowLabel + rowLabel / 2;
75
+ const quoteTop = top + headRow + labels.length * rowLabel + Math.round(fsQuote * 1.4);
76
+ const yQuote = (/** @type {number} */ i) => quoteTop + i * rowQuote + rowQuote / 2;
77
+
78
+ // Reveal times: the heading, then the labels in reading order.
79
+ const labelAt = (/** @type {number} */ i) => (i + 1) * GAP;
80
+ const labelsDone = labelAt(labels.length - 1) + ENTER;
81
+ const sweepDone = SWEEP_AT + SWEEP;
82
+ const steps = [
83
+ { at: labelsDone + PAUSE, ...COPY.steps[0] },
84
+ { at: Math.max(sweepDone, QUOTE_AT + ENTER) + PAUSE, ...COPY.steps[1] },
85
+ ];
86
+ const duration = steps[1].at + 0.4;
87
+
88
+ // One sweep over all the lines of the quote: line i fills while the sweep
89
+ // is inside its share of the total width.
90
+ // estimateWidth is a rough heuristic; 0.9 of it hugs a typical sans-serif for these fixed lines (checked by eye in the rendered frames; the gate does not measure glyph widths).
91
+ const widths = quote.map((line) => estimateWidth(line, fsQuote) * 0.9 + 2 * pad);
92
+ const total = widths.reduce((a, b) => a + b, 0);
93
+ const before = widths.map((_, i) => widths.slice(0, i).reduce((a, b) => a + b, 0));
94
+
95
+ /** @param {number} t @param {{ idPrefix: string, style?: any }} ctx */
96
+ function frame(t, { idPrefix, style }) {
97
+ const { easeOut } = easings(style?.motion);
98
+ const id = (/** @type {string} */ name) => `${idPrefix}-reveal-${name}`;
99
+ const out = [];
100
+ out.push(
101
+ blurReveal(
102
+ progress(t, 0, ENTER, easeOut),
103
+ { id: id("heading") },
104
+ text({ x: x0, y: yHead, "dominant-baseline": "central", "font-size": fsHead, "font-weight": 500, fill: tok("muted") }, heading),
105
+ ),
106
+ );
107
+ labels.forEach((lines, i) => {
108
+ out.push(
109
+ blurReveal(
110
+ progress(t, labelAt(i), ENTER, easeOut),
111
+ { id: id(`label-${i}`) },
112
+ text({ x: x0, y: yLabel(i), "dominant-baseline": "central", "font-size": fsLabel, "font-weight": 600, fill: tok("ink") }, lines),
113
+ ),
114
+ );
115
+ });
116
+ // The bands first, so the quote sits on top of them.
117
+ const swept = progress(t, SWEEP_AT, SWEEP, easeOut) * total;
118
+ quote.forEach((_, i) => {
119
+ out.push(
120
+ highlightSweep((swept - before[i]) / widths[i], {
121
+ x: x0 - pad,
122
+ y: yQuote(i) - rowQuote / 2 + 3,
123
+ width: widths[i],
124
+ height: rowQuote - 6,
125
+ radius: 6,
126
+ }),
127
+ );
128
+ });
129
+ out.push(
130
+ blurReveal(
131
+ progress(t, QUOTE_AT, ENTER, easeOut),
132
+ { id: id("quote") },
133
+ quote.map((line, i) => text({ x: x0, y: yQuote(i), "dominant-baseline": "central", "font-size": fsQuote, "font-weight": 500, fill: tok("ink") }, line)),
134
+ ),
135
+ );
136
+ return out.join("");
137
+ }
138
+
139
+ return {
140
+ id: `text-reveal-${format.replace(":", "x")}`,
141
+ width: W,
142
+ height: H,
143
+ duration,
144
+ title: localize(COPY.title, locale),
145
+ description: localize(COPY.description, locale),
146
+ // The steps are beats, not labels in the drawing: their text lives in the
147
+ // player's step buttons and captions.
148
+ stepLabelsInFrame: false,
149
+ steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
150
+ frame,
151
+ };
152
+ }