@liqweed/motion-kit 0.11.0 → 0.13.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.11.0"
10
+ "version": "0.13.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.11.0",
3
+ "version": "0.13.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,8 +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, several tokens
60
- iso.mjs isometric kit for custom scenes: camera, solids, depth order, label anchors
59
+ svg.mjs escaping, rounding, el/text/fade, polyline + Bézier arc-length, drawOn, several tokens, blur reveal, highlighter sweep
60
+ iso.mjs isometric kit for custom scenes: camera, solids (rounded too), depth order, grid backdrop, content on faces, label anchors and pills
61
61
  connectors.mjs dashed connectors, diamond junctions and single-pass light pulses for custom scenes
62
62
  wrap.mjs label wrapping with hard budgets
63
63
  style.mjs tokens, neutral style, contrast checks, token resolution
@@ -74,7 +74,9 @@ skills/ animated-diagram, motion-render, project-logo (Claude Code / Cra
74
74
  examples/ order-flow (sequence), smart-home (hub-spoke), incident (timeline),
75
75
  web-stack (stack), custom-pulse (custom module),
76
76
  isometric-swivel (custom module: isometric kit, several tokens),
77
- connectors (custom module: connectors, diamond junctions, pulses)
77
+ isometric-platform (custom module: rounded slabs, grid backdrop, mark on a top face, pill tags),
78
+ connectors (custom module: connectors, diamond junctions, pulses),
79
+ text-reveal (custom module: blur-and-fade reveal, highlighter sweep)
78
80
  bench/ heavy scene for npm run bench:player (live-player frame cost)
79
81
  brand/ logo scene (built with motion-kit); renders go to assets/ + .idea/ (npm run media)
80
82
  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` 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
+ | `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 —
@@ -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,13 +247,55 @@ 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
254
254
  far the face turns from screen left. Faces are `<path>`s outlined with
255
255
  `stroke`; only faces that face the camera are drawn (the top when elevation
256
256
  > 0, a side when its outward normal faces the camera and elevation < 90°).
257
+ - **Rounded solids.** `roundedBox({x, y, w, d, h, radius, segments = 8, …})`
258
+ and `roundedSlab` (default `h` 0.25) are a box whose four vertical corners
259
+ are arcs of `radius` sampled in `segments` straight pieces. `radius` MUST be
260
+ from 0 to half the shorter side and `segments` an integer ≥ 1 [throws];
261
+ radius 0 is a `box`, half the shorter side a stadium or a circle. The
262
+ footprint is an ordinary convex prism, so depth order treats it like any
263
+ solid. The solid is `smooth` and carries `groups` (one number per footprint
264
+ edge: each arc, and each straight side, is a group): its visible sides draw
265
+ as one wall, a single `<path>` outlined once, shaded by one unstroked layer
266
+ per group (so the number of side paths is bounded by the arcs and sides, at
267
+ most 8 layers, and does not grow with `segments`; an arc within one sample of
268
+ tangent to the view may add or lose its layer as `segments` changes). `prism` takes the same `groups` (in the
269
+ winding of its `points`) and `smooth`; without `smooth` a group is a face
270
+ outlined by itself, without `groups` (and without `smooth`) every edge is;
271
+ a `smooth` solid draws its visible sides as one wall with or without `groups`.
272
+ - **Content on a plane.** `planeMatrix(cam, {x, y, z = 0, w, d, view})` is the
273
+ SVG `matrix` that takes 2D content to the horizontal plane at height `z`,
274
+ the rectangle `w` (east) by `d` (north) centred on (`x`, `y`). The content is
275
+ drawn in its own `view` (`{width, height}`, origin at its top left, y down):
276
+ the view is fitted into the rectangle, centred, its aspect kept; its x runs
277
+ east, its y south. The matrix is the projection of the plane, so it follows
278
+ every camera, including each one of a `lerpCamera` swivel. Entries are
279
+ raw numbers; `drawOnPlane` serialises them through `num(v, 4)` (G3), and a
280
+ caller who writes its own transform MUST do the same. `drawOnPlane(cam, plane, markup, opacity = 1)`
281
+ wraps the markup in it, and returns `""` for a plane seen edge on (elevation
282
+ 0°) or too small to draw (its rounded matrix singular) or with `opacity` 0. A solid's `top` (`{markup, view, inset = 0, opacity
283
+ = 1}`, any prism) draws such content on its top face, on the footprint's
284
+ bounding box less `inset` (which MUST leave room [throws]), inside the solid's
285
+ own group, so it is ordered, and fades, with the solid; it is not drawn when
286
+ the top is edge on. Stroke widths and font sizes in the markup are in the
287
+ view's units; colours are tokens.
288
+ - **Grid backdrop.** `drawGrid(cam, {radius, step = 1, x = 0, y = 0, z = 0,
289
+ stroke = "line", strokeWidth = 1, opacity = 0.5, bands = 6})` draws grid
290
+ lines every `step` along x and y in the floor plane at height `z`, out to
291
+ about `radius` of (`x`, `y`) (a segment of one `step` is kept when its middle
292
+ is inside, so a line's end may lie up to half a `step` beyond): diamonds in isometric, squares in plan. The lines fade
293
+ radially in `bands` rings, one `<path>` each, faintest first, at up to
294
+ `opacity` (no gradient, no id). `radius` and `step` MUST be above 0, `bands`
295
+ an integer from 1 to 64, and the grid at most 200 cells each way from the centre
296
+ [throws]. It is static (a function of the camera alone) and has no depth: a
297
+ scene draws it before the solids. Any motion added to it (a shimmer, a pan)
298
+ is ambient motion, which the canon excludes: a scene plays once and holds (§2, §8).
257
299
  - **Depth order.** `orderSolids(solids, cam)` returns the solids far to near.
258
300
  Two solids whose projections overlap are ordered by the axes that separate
259
301
  them (a footprint edge, or height when seen from above); where the axes
@@ -263,8 +305,13 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
263
305
  - **Labels.** `labelAnchor(cam, {id, at, lines, fontSize, lift, side,
264
306
  opacity})` draws a dot on the projected point, a vertical stem `lift` pixels
265
307
  up and a label box above it (or beside its top), and returns the markup and
266
- the `LabelBox`. `labelProblems(boxes, {width, height, gap = 4})` lists the
267
- 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).
311
+ `labelPill({id, x, y, lines, fontSize, fill, stroke, ink, opacity})` is a
312
+ stemless tag: a rounded box of text centred on the screen point (`x`, `y`),
313
+ its colours tokens (`surface`, `line`, `ink` by default). It returns the
314
+ markup and a `LabelBox` without a stem, which G15 checks like any other.
268
315
  - **Paths.** `path3(points)` is a polyline through world points with its
269
316
  length in world units, so a token keeps a constant speed whatever the camera
270
317
  does when its progress is linear (`tokenPoints` defaults to `easeStandard`;
@@ -312,11 +359,67 @@ functions; a colour is a token name (G4 applies).
312
359
  its target has filled, and nothing repeats while a step rests, so the
313
360
  settled-frame rule (G6) holds. Several pulses may run in one beat.
314
361
 
362
+
363
+ ### 4.11 Text reveal and highlighter sweep (`runtime/svg.mjs`)
364
+
365
+ - `blurReveal(enter, {id, rise = 6, blur = 4}, ...children)` draws `children`
366
+ with an opacity that rises to one and a rise and a blur that go to zero as
367
+ `enter` (an eased progress, §4.2) goes from 0 to 1: one `<g transform opacity filter>` and,
368
+ while the blur is 0.005 or more, a `<defs>` holding one `<filter>` with one
369
+ `<feGaussianBlur>`. It returns `""` for `enter ≤ 0` and wherever the opacity rounds to zero.
370
+ - **Settled means bare.** Once `enter` reaches 1, as `fade` rounds it (0.9995
371
+ and above), `blurReveal` MUST return the children unchanged: no group, no
372
+ filter, no `<defs>`, so a settled frame is byte-identical to the same markup
373
+ drawn without the reveal, and every step frame, the final frame, a baked
374
+ last slice and a reduced-motion frame carry no filter. Between 0 and 1 the
375
+ `transform` and the `filter` are left off once they round to nothing
376
+ (a rise or a blur under 0.005 units), so a frame never carries
377
+ a `stdDeviation="0"`, which renderers read differently.
378
+ - **Ids.** `id` names the filter and MUST be built from `frame`'s `idPrefix`
379
+ (`${idPrefix}-reveal-1`), one per revealed element, so the sampled G14 check for ids shared across instances holds and a baked
380
+ SVG, which renders each slice with its own prefix, never repeats one
381
+ [throws unless `id` is a CSS-safe token]. `rise` is 0 to 24 and `blur` 0 to 12
382
+ [throws].
383
+ - **Renderers.** The filter is `feGaussianBlur` in sRGB over a region of
384
+ `x −25 %`, `y −100 %`, `width 150 %`, `height 300 %` of the element's box,
385
+ 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
386
+ 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
387
+ 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
388
+ in-place patch updates `stdDeviation` and the group's attributes, and drops
389
+ 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`,
390
+ `test/player.test.mjs`). A consumer that ignores SVG filters (some slide
391
+ applications) shows the fade and the rise without the blur, and only in a
392
+ frame taken mid-reveal: step frames carry no filter.
393
+ - **Timing.** The reveal is one entrance, 300 to 600 ms (§4.2), on the style's
394
+ entrance curve (`easings(style.motion).easeOut`), finished 50 ms or more
395
+ 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.
396
+ The blur is a paint cost no other motion helper has; the plain fade
397
+ (`fade`) stays the default for a label whose arrival does not need to be
398
+ watched
399
+ ([`motion-vocabulary.md`](../../skills/animated-diagram/references/motion-vocabulary.md)).
400
+ - `highlightSweep(p, {x, y, width, height, token = "emphasis", opacity = 0.3,
401
+ radius = 4})` draws a rounded `<rect>` filled with a token at `opacity`,
402
+ 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
403
+ rectangle is the same on every frame. It is drawn before the text it marks,
404
+ and `opacity` starts low (0.2 to 0.4): at the default 0.3 the neutral
405
+ style's ink reads on the tinted canvas at 4.5:1 or more in both themes
406
+ (`test/reveal.test.mjs`). The gate checks text against the canvas, not
407
+ against the band, so a custom style must check its ink against the
408
+ composited tint itself. `width` is the scene's to set; `estimateWidth` is a
409
+ rough heuristic (characters × size × 0.56), not a bound, so pass a
410
+ conservative width where the band must cover the whole line [throws on a
411
+ non-finite or non-positive size, an unknown token, or an `opacity` that is
412
+ not a finite number in (0, 1]].
413
+ - Both helpers are pure functions of their arguments. `examples/text-reveal.scene.mjs`
414
+ reveals three labels in reading order, then a quoted line with one band per
415
+ wrapped line swept first line to last.
416
+
417
+
315
418
  ## 5. Markup
316
419
 
317
420
  - Text and attribute values MUST be escaped (`& < > " '`) via `esc`, `text` or
318
- `el`/`attrString` (`runtime/svg.mjs:10-14,24-33,45-57`). Labels MUST NOT be able
319
- to inject markup (`test/runtime.test.mjs:118-124`).
421
+ `el`/`attrString` (`esc`, `text`, `el` in `runtime/svg.mjs`). Labels MUST NOT be able
422
+ to inject markup (the "escapes label text" test in `test/runtime.test.mjs`).
320
423
  - `el(tag, attrs, …children)` treats children as trusted markup; untrusted
321
424
  strings MUST go through `text()`/`esc()`.
322
425
  - Output MUST be well-formed: balanced tags, no stray `<`, no bare `&` [gate] G2.
@@ -643,14 +746,15 @@ that removes every listener, observer and mark they added.
643
746
  ## 11. The gate
644
747
 
645
748
  `checkScene(scene)` (`lib/check.mjs`) samples 121 evenly spaced times
646
- (`SAMPLES = 120`) and stops collecting after 13 problems.
749
+ (`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.
647
750
  `motion-kit check` and the vendored `check.mjs` both run `checkFiles`
648
751
  (`lib/gate.mjs`): every file × format (all six unless `--format`, repeatable)
649
752
  × locale (`--locale`, repeatable; else every locale a spec's strings carry, and
650
753
  `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
754
  for the shared pairs the style misses. A file that cannot be read, parsed or built fails on its own and the
652
- remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = unit tests +
653
- `check` over `examples/` and `brand/` (`package.json:15-18`).
755
+ remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = `gate:core`
756
+ (typecheck, version sync, unit tests, `check` over `examples/` and `brand/`,
757
+ media freshness) plus the site build (`package.json` scripts `gate:core`, `gate`).
654
758
 
655
759
  | ID | Rule | Code | Rationale |
656
760
  |---|---|---|---|
@@ -661,7 +765,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
661
765
  | G5 | No `NaN`, `undefined`, `Infinity` in `frame()` output. | `:50` | Silent geometry bugs. |
662
766
  | 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. |
663
767
  | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
664
- | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
768
+ | G8 | `frame(duration + 5) === frame(duration)`, called raw, unclamped. | `checkScene` in `lib/check.mjs` | Holds the final frame. |
665
769
  | G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
666
770
  | 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. |
667
771
  | 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,139 @@
1
+ /**
2
+ * Example custom scene: a rounded platform with a mark on its top face, seen in
3
+ * plan, then turned isometric, and two pill tags.
4
+ *
5
+ * Shows the rest of the isometric kit (runtime/iso.mjs): rounded slabs whose
6
+ * sides draw as one smooth face each (`roundedSlab`, `roundedBox`), a faint
7
+ * diamond-grid backdrop that fades out from the centre and sits under the
8
+ * solids (`drawGrid`), 2D content drawn on a solid's top face so it turns with
9
+ * the camera (`top`; `drawOnPlane` does the same for any horizontal plane), and
10
+ * stemless pill tags the label gate checks (`labelPill`). Nothing loops and the
11
+ * backdrop is static: the scene plays once, the swivel is one move between two
12
+ * settled steps, and the last frame holds. Pure: frame(t) depends only on t
13
+ * and constants.
14
+ */
15
+ import { easeOut, easeStandard, progress } from "../runtime/motion.mjs";
16
+ import { CAMERA_ISOMETRIC, CAMERA_PLAN, drawGrid, drawSolid, fitCamera, labelPill, lerpCamera, orderSolids, roundedBox, roundedSlab } from "../runtime/iso.mjs";
17
+ import { FORMATS, localize } from "../runtime/scene.mjs";
18
+ import { tok } from "../runtime/style.mjs";
19
+ import { el } from "../runtime/svg.mjs";
20
+
21
+ export const locales = ["en", "nl"];
22
+
23
+ const COPY = {
24
+ title: { en: "A platform that turns isometric", nl: "Een platform dat isometrisch draait" },
25
+ description: {
26
+ en: "A rounded platform with a mark on its top face stands on a floor, seen from above. The view swivels to isometric, the platform rises, and two tags appear below.",
27
+ nl: "Een afgerond platform met een teken op het bovenvlak staat op een vloer, van boven gezien. Het beeld draait naar isometrisch, het platform rijst op en twee labels verschijnen eronder.",
28
+ },
29
+ tags: [
30
+ { en: "Rounded slab", nl: "Afgeronde plaat" },
31
+ { en: "Mark on the top face", nl: "Teken op het bovenvlak" },
32
+ ],
33
+ steps: [
34
+ { label: { en: "Seen from above", nl: "Van boven gezien" }, detail: { en: "A rounded platform on a floor, with a mark on top.", nl: "Een afgerond platform op een vloer, met een teken erop." } },
35
+ { label: { en: "Turned isometric", nl: "Isometrisch gedraaid" }, detail: { en: "The platform has risen; the mark turned with its face.", nl: "Het platform is gerezen; het teken draaide met het vlak mee." } },
36
+ { label: { en: "Tagged", nl: "Gelabeld" }, detail: { en: "Two pill tags name what the picture shows.", nl: "Twee labels benoemen wat het beeld laat zien." } },
37
+ ],
38
+ };
39
+
40
+ // World, in units: a rounded 12 × 8 floor, a rounded 4.4 × 4.4 platform on it.
41
+ const FLOOR = { w: 12, d: 8, h: 0.3, radius: 1.4 };
42
+ const PLATFORM = { w: 4.4, d: 4.4, h: 1.2, radius: 1.1 };
43
+ const TOP = FLOOR.h;
44
+ const GRID = { radius: 8, step: 1 };
45
+ // The mark, on a 24 × 24 grid: an easing curve between two keyframes.
46
+ const MARK = { view: { width: 24, height: 24 }, curve: "M5 19 C 11 19, 9 5, 19 5", a: { x: 5, y: 19 }, b: { x: 19, y: 5 } };
47
+
48
+ // Timeline, in seconds. Every beat ends before the next one starts, so each
49
+ // step frame is settled (the gate checks it).
50
+ const FLOOR_IN = 0.4;
51
+ const GRID_IN = 0.5;
52
+ const PLATFORM_IN = 0.4;
53
+ const MARK_IN = 0.4;
54
+ const STEP_PLAN = 1.5;
55
+ const SWIVEL_AT = 1.8;
56
+ const SWIVEL = 1.4;
57
+ const RISE_AT = 1.9;
58
+ const STEP_ISO = 3.4;
59
+ const TAGS_AT = 3.6;
60
+ const TAG_FADE = 0.4;
61
+ const STEP_TAGS = 4.3;
62
+ const DURATION = 4.6;
63
+
64
+ export default function make({ format = "16:9", locale = "en" } = {}) {
65
+ const f = FORMATS[format];
66
+ if (!f) throw new Error(`unknown format "${format}"`);
67
+ const W = f.width;
68
+ const H = f.height || (format === "tall" ? 520 : 400);
69
+ const stacked = W < 600; // in a narrow picture the tags stand in two rows
70
+ const fs = 14;
71
+ const tags = COPY.tags.map((t) => localize(t, locale));
72
+
73
+ // The fit's room: the tags stand below the floor, so the bottom margin is theirs.
74
+ const margin = { top: 24, right: 24, bottom: stacked ? 108 : 68, left: 24 };
75
+ // What the camera must keep in view: the floor and the platform at full height.
76
+ const extent = [
77
+ ...[-1, 1].flatMap((sx) => [-1, 1].map((sy) => ({ x: (sx * FLOOR.w) / 2, y: (sy * FLOOR.d) / 2, z: 0 }))),
78
+ ...[-1, 1].flatMap((sx) => [-1, 1].map((sy) => ({ x: (sx * PLATFORM.w) / 2, y: (sy * PLATFORM.d) / 2, z: TOP + PLATFORM.h }))),
79
+ ];
80
+ const swivel = (/** @type {number} */ t) => progress(t, SWIVEL_AT, SWIVEL, easeStandard);
81
+ const cameraAt = (/** @type {number} */ t) => fitCamera(extent, lerpCamera(CAMERA_PLAN, CAMERA_ISOMETRIC, swivel(t)), { width: W, height: H, margin });
82
+
83
+ // The mark: the curve and its two keyframes, in the accent's text colour, in the view's own units.
84
+ const mark =
85
+ el("path", { d: MARK.curve, fill: "none", stroke: tok("onAccent"), "stroke-width": 2, "stroke-linecap": "round" }) +
86
+ [MARK.a, MARK.b].map((p) => el("circle", { cx: p.x, cy: p.y, r: 2.2, fill: tok("onAccent") })).join("");
87
+
88
+ /** The tags at time t, with their boxes: they stand on the picture's bottom edge, under whatever the camera shows. */
89
+ function pills(/** @type {number} */ t) {
90
+ const opacity = progress(t, TAGS_AT, TAG_FADE);
91
+ const row = stacked ? [0, 1].map((i) => ({ x: W / 2, y: H - margin.bottom + 34 + i * 40 })) : [{ x: W / 2 - 110, y: H - 34 }, { x: W / 2 + 110, y: H - 34 }];
92
+ return [
93
+ labelPill({ id: "tag-slab", ...row[0], lines: [tags[0]], fontSize: fs, opacity }),
94
+ labelPill({ id: "tag-mark", ...row[1], lines: [tags[1]], fontSize: fs, fill: "accent", stroke: "accent", ink: "onAccent", opacity }),
95
+ ];
96
+ }
97
+
98
+ function frame(/** @type {number} */ t) {
99
+ const cam = cameraAt(t);
100
+ const rise = progress(t, RISE_AT, SWIVEL - 0.1, easeOut);
101
+ const floor = roundedSlab({ x: 0, y: 0, w: FLOOR.w, d: FLOOR.d, h: FLOOR.h, radius: FLOOR.radius, fill: "surface", opacity: progress(t, 0, FLOOR_IN), id: "floor" });
102
+ const platform = roundedBox({
103
+ x: 0,
104
+ y: 0,
105
+ w: PLATFORM.w,
106
+ d: PLATFORM.d,
107
+ radius: PLATFORM.radius,
108
+ z: TOP,
109
+ h: Math.max(0.02, PLATFORM.h * rise),
110
+ fill: "accent",
111
+ opacity: progress(t, 0.2, PLATFORM_IN),
112
+ id: "platform",
113
+ top: { markup: mark, view: MARK.view, inset: 0.5, opacity: progress(t, 0.6, MARK_IN) },
114
+ });
115
+ // The grid first: under the solids, never over one. The floor is a solid like the platform, depth ordered.
116
+ const out = [drawGrid(cam, { ...GRID, stroke: "line", opacity: 0.6 * progress(t, 0.1, GRID_IN) })];
117
+ for (const s of orderSolids([floor, platform], cam)) out.push(drawSolid(s, cam));
118
+ out.push(...pills(t).map((p) => p.markup));
119
+ return out.join("");
120
+ }
121
+
122
+ return {
123
+ id: `isometric-platform-${format.replace(":", "x")}`,
124
+ width: W,
125
+ height: H,
126
+ duration: DURATION,
127
+ title: localize(COPY.title, locale),
128
+ description: localize(COPY.description, locale),
129
+ // Steps are beats of the story: their labels live in the player's controls, not in the drawing.
130
+ stepLabelsInFrame: false,
131
+ steps: [
132
+ { at: STEP_PLAN, ...COPY.steps[0] },
133
+ { at: STEP_ISO, ...COPY.steps[1] },
134
+ { at: STEP_TAGS, ...COPY.steps[2] },
135
+ ].map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
136
+ labelBoxes: (/** @type {number} */ t) => pills(t).map((p) => p.box),
137
+ frame,
138
+ };
139
+ }
@@ -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
+ }