@liqweed/motion-kit 0.3.0 → 0.5.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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +63 -10
- package/adapters/astro/AnimatedDiagram.astro +150 -24
- package/adapters/element/README.md +6 -1
- package/adapters/element/motion-diagram.mjs +4 -3
- package/adapters/page/README.md +8 -2
- package/adapters/slidev/AnimatedDiagram.vue +24 -0
- package/cli/motion-kit.mjs +85 -81
- package/docs/spec/technique.md +166 -63
- package/examples/custom-pulse.scene.mjs +3 -0
- package/examples/incident.json +18 -0
- package/examples/web-stack.json +17 -0
- package/lib/build.mjs +26 -12
- package/lib/bundle.mjs +9 -2
- package/lib/check.mjs +219 -15
- package/lib/export.mjs +135 -16
- package/lib/gate.mjs +90 -0
- package/lib/load.mjs +49 -19
- package/package.json +6 -3
- package/runtime/bake.mjs +18 -4
- package/runtime/kit.mjs +59 -0
- package/runtime/links.mjs +314 -0
- package/runtime/page.mjs +52 -0
- package/runtime/parts.mjs +15 -0
- package/runtime/patch.mjs +297 -0
- package/runtime/player.mjs +334 -130
- package/runtime/scene.mjs +82 -5
- package/runtime/style.mjs +64 -16
- package/runtime/types/hub-spoke.mjs +7 -7
- package/runtime/types/index.mjs +4 -0
- package/runtime/types/sequence.mjs +5 -5
- package/runtime/types/stack.mjs +227 -0
- package/runtime/types/timeline.mjs +405 -0
- package/skills/animated-diagram/SKILL.md +30 -7
- package/skills/animated-diagram/references/custom-scenes.md +64 -9
- package/skills/animated-diagram/references/interactivity.md +150 -15
- package/skills/animated-diagram/references/qc.md +5 -2
- package/skills/animated-diagram/references/scene-types.md +45 -2
- package/skills/animated-diagram/references/styles.md +45 -5
- package/skills/animated-diagram/references/targets.md +7 -5
- package/skills/animated-diagram/references/technique.md +14 -4
- package/skills/motion-render/SKILL.md +31 -8
- package/skills/motion-render/references/formats.md +8 -8
- package/skills/project-logo/SKILL.md +15 -4
- package/styles/neutral.json +2 -2
package/docs/spec/technique.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: motion-kit technique — normative specification
|
|
3
3
|
status: draft
|
|
4
|
-
last_updated: 2026-11-
|
|
4
|
+
last_updated: 2026-11-17
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# motion-kit technique — normative specification
|
|
@@ -35,18 +35,28 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
|
|
|
35
35
|
| `duration` | number, s | MUST | Time of the final state. |
|
|
36
36
|
| `title` | string | MUST | Accessible name (`<title>`) [throws if empty]. |
|
|
37
37
|
| `description` | string | MUST | Accessible description (`<desc>`) [throws if empty]. |
|
|
38
|
-
| `steps` | `{at, label, detail?}[]` | MUST | ≥ 1 step; `at` strictly increasing; `at ≤ duration` (+1e-9); every `label` non-empty [throws] (`
|
|
39
|
-
| `frame(t)` | `(number) → string` | MUST | Inner SVG markup at `t` (§2). |
|
|
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
|
+
| `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
42
|
| `type`, `format`, `locale` | string | MAY | Set by scene types; recorded in the export manifest (`lib/export.mjs:75-77`). |
|
|
42
43
|
|
|
43
44
|
- A scene MUST be produced by either a registered scene type —
|
|
44
|
-
`createScene(spec, {format, locale})` (`runtime/types/index.mjs:
|
|
45
|
-
custom module whose default export is `(opts) → scene
|
|
46
|
-
(`
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
45
|
+
`createScene(spec, {format, locale})` (`runtime/types/index.mjs:25-29`) — or a
|
|
46
|
+
custom module whose default export is `(opts) → scene`, called by
|
|
47
|
+
`sceneFromModule` (`runtime/kit.mjs`) with
|
|
48
|
+
`opts = { ...options, format, locale, kit }`. `options` are the caller's
|
|
49
|
+
serializable scene options, passed unchanged; option names `format`,
|
|
50
|
+
`locale` and `kit` throw. `kit` is the flat exports of the `motion`, `svg`, `style`, `scene` and `wrap` runtime modules (`KIT`); it has no `createScene`, scene types or player. Both paths
|
|
51
|
+
run `validateScene`. The CLI (`--options`), the vendored gate and the Astro
|
|
52
|
+
adapter call `sceneFromModule`, so one module with the same options, format
|
|
53
|
+
and locale gives the same scene everywhere. A `build` page calls the factory
|
|
54
|
+
with the same object, its `kit` being the bundled runtime, after the CLI has
|
|
55
|
+
built the scene once through `sceneFromModule`.
|
|
56
|
+
- A custom module MUST take the runtime from `kit`, or import only from
|
|
57
|
+
`runtime/` with single-line relative `import { … } from "./x.mjs";`
|
|
58
|
+
statements and use only the export forms the inliner supports, or `build`
|
|
59
|
+
throws (`lib/bundle.mjs:8-11,33,59`).
|
|
50
60
|
- `detail` SHOULD hold sentences; labels stay short (§7). `detail` feeds the
|
|
51
61
|
player caption and screen-reader list (§10.2).
|
|
52
62
|
|
|
@@ -54,13 +64,13 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
|
|
|
54
64
|
|
|
55
65
|
| # | Rule | Enforcement | Rationale |
|
|
56
66
|
|---|---|---|---|
|
|
57
|
-
| 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 scans the source (`lib/check.mjs
|
|
67
|
+
| 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`). |
|
|
58
68
|
| T2 | Same `t` (and same style/options) MUST give byte-identical output. | [gate] G1 | Tests, diffs, caching and committed media all depend on it. |
|
|
59
69
|
| 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". |
|
|
60
70
|
| 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`). |
|
|
61
71
|
| 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). |
|
|
62
72
|
| 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. |
|
|
63
|
-
| T7 | Variation, if any, MUST derive from constants and `t` (seeded), never from runtime randomness. | [gate] G11
|
|
73
|
+
| T7 | Variation, if any, MUST derive from constants and `t` (seeded), never from runtime randomness. | [gate] G1, G11 | Same as T2. |
|
|
64
74
|
|
|
65
75
|
## 3. Formats and layout per format
|
|
66
76
|
|
|
@@ -83,12 +93,16 @@ Formats map a name to a viewBox (`runtime/scene.mjs:23-30`):
|
|
|
83
93
|
- Arrangement by aspect: "narrow" means `tall` or `W/H < 0.8` → column/tree;
|
|
84
94
|
`W/H ≥ 1.5` → row (or 2-row snake when cells are < 96 px) for `sequence`;
|
|
85
95
|
otherwise snake grid (`runtime/types/sequence.mjs:35-46`) or radial ellipse
|
|
86
|
-
(`runtime/types/hub-spoke.mjs:40,59-73`).
|
|
96
|
+
(`runtime/types/hub-spoke.mjs:40,59-73`). `timeline` runs its axis
|
|
97
|
+
vertically when narrow and horizontally otherwise (`runtime/types/timeline.mjs:239`);
|
|
98
|
+
`stack` is one column of layers with a rail on the right in every format.
|
|
87
99
|
- **Auto-fit text**: a type MUST try the largest font size and step down by
|
|
88
100
|
1 px to `FONT_MIN = 14` (`runtime/parts.mjs:12`) until every label wraps
|
|
89
101
|
into its budget; if none fits it MUST throw. Maxima: `sequence` 22 px fixed /
|
|
90
102
|
16 px strips (`runtime/types/sequence.mjs:127`); `hub-spoke` 20 / 16
|
|
91
|
-
(`runtime/types/hub-spoke.mjs:97`); `
|
|
103
|
+
(`runtime/types/hub-spoke.mjs:97`); `timeline` 22 / 16
|
|
104
|
+
(`runtime/types/timeline.mjs:280`); `stack` 22 / 16
|
|
105
|
+
(`runtime/types/stack.mjs:129`); `spec.fontSize` overrides the maximum.
|
|
92
106
|
- **Collisions**: a layout whose boxes overlap (6 px gap) or leave the canvas
|
|
93
107
|
MUST throw rather than render (`runtime/types/hub-spoke.mjs:33-35,76-84,119`).
|
|
94
108
|
- Connectors MUST NOT cross labels; snake-grid row turns route as elbows
|
|
@@ -206,7 +220,17 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
|
|
|
206
220
|
|
|
207
221
|
- Scenes MUST NOT contain colour literals [gate] G4. Colours MUST be
|
|
208
222
|
`tok(name)` → `var(--mk-<name>)`; an unknown name throws
|
|
209
|
-
(`runtime/style.mjs:52-55`).
|
|
223
|
+
(`runtime/style.mjs:52-55`). Besides tokens, a colour attribute (`fill`,
|
|
224
|
+
`stroke`, `stop-color`, `color`, `flood-color`, `lighting-color`) or colour
|
|
225
|
+
property (in `style="…"` or a `<style>` element: those, `background` and
|
|
226
|
+
any `*-color`) MAY hold only `url(#…)` references and the keywords `none`,
|
|
227
|
+
`currentColor`, `transparent`, `inherit`, `initial`, `unset`, `revert`,
|
|
228
|
+
`revert-layer`, `context-fill` and `context-stroke`. None of them names a
|
|
229
|
+
colour, so they look the same under every style and theme; `transparent`
|
|
230
|
+
is allowed because it paints nothing in either theme. Named colours
|
|
231
|
+
(`red`), hex, colour functions and other custom properties (`var(--brand)`,
|
|
232
|
+
`var(--mk-accent, red)`) are literals. Text content is not checked: a label
|
|
233
|
+
may say "#1".
|
|
210
234
|
- Tokens (`runtime/style.mjs:14-23`): `bg`, `surface`, `ink`, `muted`, `line`,
|
|
211
235
|
`accent`, `onAccent`, `emphasis`. Roles: see
|
|
212
236
|
[`styles.md`](../../skills/animated-diagram/references/styles.md). Exactly one
|
|
@@ -222,11 +246,21 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
|
|
|
222
246
|
literal (`runtime/scene.mjs:84`, `runtime/style.mjs:86-93`), because slide
|
|
223
247
|
apps, rasterizers and image viewers ignore CSS variables; an unresolvable
|
|
224
248
|
token throws.
|
|
225
|
-
- **Contrast** (`runtime/style.mjs
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
249
|
+
- **Contrast** (`runtime/style.mjs`, `checkContrast`, WCAG relative
|
|
250
|
+
luminance): in both themes, every pair in `CONTRAST_PAIRS`, the token pairs
|
|
251
|
+
the scene types and shared parts draw where the pair carries meaning in a
|
|
252
|
+
step frame. Text ≥ 4.5:1 — `ink`/`muted` on `bg` and `surface`, `onAccent`
|
|
253
|
+
on `accent`; shapes ≥ 3:1 — `line`, `accent`, `emphasis` on `bg`, and
|
|
254
|
+
`emphasis` on `accent` (the ring marking the current node sits 3.5 units
|
|
255
|
+
from the reached node it surrounds, and tells "here" from "reached" without
|
|
256
|
+
hue). `CONTRAST_EXEMPT` lists, with a reason each, the pairs left out:
|
|
257
|
+
`line` on `surface` (an outline is told from the canvas outside it),
|
|
258
|
+
`accent` on `surface` and `emphasis` on `surface` and `accent` on `line`
|
|
259
|
+
(only in motion), `onAccent` on `emphasis` (only the logo; logos are exempt
|
|
260
|
+
from WCAG 1.4.11). A scene adds the pairs it draws besides through
|
|
261
|
+
`contrastPairs` (§1). `motion-kit check` MUST fail when the selected style
|
|
262
|
+
violates any shared pair, once per run, or a scene's own, per scene [gate]
|
|
263
|
+
G12 (`lib/gate.mjs`). `neutral` MUST pass (`test/runtime.test.mjs`).
|
|
230
264
|
- motion-kit ships only `neutral` (`styles/neutral.json`); brand styles MUST
|
|
231
265
|
live in the consumer repo.
|
|
232
266
|
|
|
@@ -256,11 +290,17 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
|
|
|
256
290
|
|
|
257
291
|
- `steps[i].at` is the time step *i* is fully shown; its frame is what a slide,
|
|
258
292
|
a step button and Slidev show.
|
|
259
|
-
- Step frames MUST be settled: nothing moves at `at` [gate] G6
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
293
|
+
- Step frames MUST be settled: nothing moves at `at` [gate] G6. The step's
|
|
294
|
+
own motion MAY end exactly at `at` but MUST be at rest there
|
|
295
|
+
(`frame(at − 1 ms) === frame(at)`), and nothing MAY change in the 50 ms
|
|
296
|
+
after it (`frame(at + δ) === frame(at)` for δ = 1, 15, 30 and 45 ms, up to
|
|
297
|
+
the next step; `SETTLE_AFTER` in `lib/check.mjs`). The look-ahead is what
|
|
298
|
+
catches slow motion passing through `at`, which rounding hides over 1 ms.
|
|
299
|
+
- Authoring rule: the next motion MUST NOT start earlier than 50 ms after
|
|
300
|
+
`at` (the "pause between beats" in
|
|
301
|
+
[`motion-vocabulary.md`](../../skills/animated-diagram/references/motion-vocabulary.md)),
|
|
302
|
+
and anything that fades out by a step (a travelling dot) MUST reach 0 by
|
|
303
|
+
`at`. Scene types satisfy this by construction: `PERIOD = HOP + FILL + 0.05`
|
|
264
304
|
(`runtime/types/sequence.mjs:24-29`), step = fill end
|
|
265
305
|
(`runtime/types/sequence.mjs:147`, `runtime/types/hub-spoke.mjs:149`).
|
|
266
306
|
Springs and split edges MUST budget their settle time and lag (§4.3, §4.5).
|
|
@@ -273,14 +313,18 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
|
|
|
273
313
|
|
|
274
314
|
## 9. Scene types
|
|
275
315
|
|
|
276
|
-
Registered types: `sequence` (2–12 nodes)
|
|
277
|
-
|
|
316
|
+
Registered types: `sequence` (2–12 nodes), `hub-spoke` (2–10 spokes),
|
|
317
|
+
`timeline` (2–8 events) and `stack` (2–8 layers)
|
|
318
|
+
(`runtime/types/index.mjs:18-23`). Fields and storyboards:
|
|
278
319
|
[`scene-types.md`](../../skills/animated-diagram/references/scene-types.md).
|
|
279
320
|
Normative points:
|
|
280
321
|
|
|
281
|
-
- Out-of-range node/spoke counts, a missing hub and an unknown type MUST throw
|
|
322
|
+
- Out-of-range node/spoke/event/layer counts, a missing hub and an unknown type MUST throw
|
|
282
323
|
(`runtime/types/sequence.mjs:123`, `runtime/types/hub-spoke.mjs:89-90`,
|
|
283
|
-
`runtime/types/
|
|
324
|
+
`runtime/types/timeline.mjs:203-231`, `runtime/types/stack.mjs:117-126`,
|
|
325
|
+
`runtime/types/index.mjs:27`). A timeline event without `when` or `label`, a
|
|
326
|
+
past event after a planned one, planned events without `now`, a stack layer
|
|
327
|
+
without `label` and a stack `direction` other than `down`/`up` MUST throw.
|
|
284
328
|
- A new type MUST export `(spec, {format, locale}) → scene`, be registered in
|
|
285
329
|
`SCENE_TYPES`, and get a gate run across every format and locale
|
|
286
330
|
(`AGENTS.md:59-61`). A custom shape SHOULD be promoted to a type once used twice.
|
|
@@ -299,28 +343,39 @@ Every target goes through this one function. It MUST emit `<svg>` with
|
|
|
299
343
|
| `theme` | `light`/`dark` for resolution or inline vars. |
|
|
300
344
|
| `live` | Omits inline vars; the container supplies them. |
|
|
301
345
|
| `background` | Paints a full-size `bg` rect behind the diagram. |
|
|
302
|
-
| `idPrefix` | MUST be unique per page when several diagrams share it. |
|
|
346
|
+
| `idPrefix` | Prefix for every id in the output: `<title>`/`<desc>`, and the scene's own through `frame(t, { idPrefix })`. Made a safe id token (`safeId`: letters, digits, `_`, `-`). MUST be unique per page when several diagrams share it. |
|
|
303
347
|
|
|
304
348
|
### 10.2 Live player (`runtime/player.mjs`)
|
|
305
349
|
|
|
306
350
|
| Requirement | Source |
|
|
307
351
|
|---|---|
|
|
308
352
|
| MUST touch the DOM only when mounted; scenes stay pure, the player owns the clock (`requestAnimationFrame`, wall time). | `runtime/player.mjs` (`mountPlayer`, `tick`), `AGENTS.md` |
|
|
309
|
-
| Initial state MUST be the final frame
|
|
310
|
-
| Autoplay `visible` (default): plays once from 0 when ≥ 40 % in view, then holds; `none` disables. MUST NOT loop. | `runtime/player.mjs` (`
|
|
311
|
-
|
|
|
353
|
+
| Initial state MUST be the final frame. A server/no-JS fallback SHOULD be `playerMarkup(scene, { id, … })` inside a `.mk-player` container, with `PLAYER_CSS` in a `style[data-mk-player-css]` and the tokens from `themeCss(selector, style, theme)`: the markup the player builds, with the controls `inert`. The step list and the colours then exist without JavaScript, and mounting moves nothing. A plain final-frame SVG MAY be used instead. | `runtime/player.mjs` (`view`, `playerMarkup`, `themeCss`), `lib/build.mjs`, `adapters/astro/AnimatedDiagram.astro`, `test/player.test.mjs` |
|
|
354
|
+
| Autoplay `visible` (default): plays once from 0 when ≥ 40 % of the diagram, or ≥ 40 % of the viewport's height, is in view (decided from the intersection, not `isIntersecting` alone), then holds; `none` disables. MUST NOT loop. | `runtime/player.mjs` (`shown`, `THRESHOLDS`) |
|
|
355
|
+
| While a playing diagram does not intersect the viewport (scrolled away, `display: none`), its clock MUST stop and no frame be drawn; when it intersects again, playback resumes from the same time. Visibility is observed until `destroy()`. | `runtime/player.mjs` (`onVisibility`, `run`) |
|
|
356
|
+
| Each frame MUST update the stage's SVG in place (`patchMarkup`): nodes that persist between frames are kept, only changed attributes and text are written, and nodes are added, removed or replaced (by position; a different tag replaces the subtree) only where the markup's structure changes. The DOM after each frame MUST equal what `innerHTML` would build from the same markup. Markup outside the subset the patch reproduces exactly (comments, CDATA, single-quoted or bare attributes, named entities beyond the XML five, elements inside `<title>`, `<desc>` or `<foreignObject>`, HTML elements that leave SVG) MUST fall back to `innerHTML` for that frame. Because nodes persist, a CSS transition on the diagram would run between frames: T6 keeps them out of scenes, and pages MUST NOT add them. | `runtime/patch.mjs`, `runtime/player.mjs` (`draw`), `test/patch.test.mjs`, `test/player.test.mjs`, `scripts/bench-player.mjs` |
|
|
357
|
+
| Play/pause MUST always be present when motion can play (WCAG 2.2.2); label shows Play/Pause/Replay. | `runtime/player.mjs` (`playLabel`, `draw`) |
|
|
358
|
+
| Every control (buttons, scrubber) MUST be at least 44 × 44 px. The caption and the play button MUST keep the size of their longest content, so playback does not shift the layout. | `PLAYER_CSS` (`.mk-btn`, `.mk-scrub`, `.mk-caption`, `.mk-play`) |
|
|
312
359
|
| One `<button>` per step, labelled `N. label`; activating it jumps by default. `animateSteps: true` opts buttons and keyboard navigation into `playToStep`. `aria-current="step"` marks the active step. | `runtime/player.mjs` |
|
|
313
360
|
| Optional range scrubber (`aria-label`, default "Timeline"); input pauses and seeks. | `runtime/player.mjs` (`options.scrubber`) |
|
|
314
361
|
| Caption shows the active step's `detail` and is `aria-hidden`; a visually hidden ordered list of all steps (`label: detail`) MUST be present for screen readers. | `runtime/player.mjs` (`caption`, `sr`) |
|
|
315
|
-
| Keyboard on the focusable stage: ←/→ step, Home/End first/last, Space play/pause. | `runtime/player.mjs` (`
|
|
316
|
-
| Visible focus style for every control. | `
|
|
362
|
+
| Keyboard on the focusable stage, a `role="group"` named by the scene title and described by a visually hidden hint (`labels.keys`): ←/→ step, Home/End first/last, Space play/pause. Every element with `tabindex="0"` has a role. | `runtime/player.mjs` (`view`, `keydown` handler) |
|
|
363
|
+
| Visible focus style for the stage and every control. | `PLAYER_CSS` (`:focus-visible` rule) |
|
|
317
364
|
| `prefers-reduced-motion: reduce`: final frame, no autoplay, no play button, Space ignored. | `runtime/player.mjs` (`reduced`) |
|
|
318
|
-
| Theme: `options.theme`, else follows `prefers-color-scheme` live. | `runtime/player.mjs` (`applyTheme`, `themeQuery`) |
|
|
319
|
-
|
|
|
365
|
+
| Theme: `options.theme`, else follows `prefers-color-scheme` live. Tokens MUST be set one custom property at a time, keeping the container's other inline CSS. | `runtime/player.mjs` (`applyTheme`, `themeQuery`) |
|
|
366
|
+
| The player stylesheet MUST be in the document whenever a player mounts: it is added to `<head>` unless a `style[data-mk-player-css]` is present, so a page swap that removed it cannot leave players unstyled. `injectCss: false` opts out. | `runtime/player.mjs` (`ensureStyle`), `test/player.test.mjs` |
|
|
367
|
+
| Ids: each player renders with its own prefix, `options.id`, else `scene.id` plus a per-page counter, so two players of one scene share no ids. | `runtime/player.mjs` (`prefix`) |
|
|
368
|
+
| `playToStep(ref)` MUST play forward from the current time, clamp to the target step's exact `at` and hold. Backward, same-time and reduced-motion calls MUST jump. `seekStep(ref)` jumps. `ref` is a zero-based index or a step `id`; an invalid index or unknown id throws `RangeError` (`stepIndex`). Retargeting replaces the target; `play()` continues to duration; `seek(t)` cancels playback. | `runtime/player.mjs`, `runtime/scene.mjs`, `test/player.test.mjs` |
|
|
320
369
|
| `destroy()` MUST cancel the animation frame, disconnect visibility observation, remove theme listening and remove this controller's capture entry. | `runtime/player.mjs`, `test/player.test.mjs` |
|
|
321
370
|
| **Capture hook**: the controller `{seek, play, pause, seekStep, playToStep, destroy, time, scene}` MUST be exposed at `globalThis.__motionKit[options.id ?? scene.id]`. | `runtime/player.mjs` |
|
|
322
371
|
|
|
323
|
-
UI strings MAY be localized via `options.labels
|
|
372
|
+
UI strings MAY be localized via `options.labels`: a flat `{ play, pause, replay, steps, scrubber, keys }` object (`steps` names the controls group, `keys` is the stage's keyboard hint), or a dictionary keyed by locale (`{ en: {…}, nl: {…} }`) resolved with `options.locale`, then its language subtag, then `en`, then the first entry. Missing keys keep the English defaults (`resolveLabels`, `runtime/player.mjs`).
|
|
373
|
+
|
|
374
|
+
Keyboard step changes (←/→/Home/End) MUST be announced through a visually hidden `role="status"` polite live region (`N. label: detail`); autoplay, pointer and scrubber use stay silent.
|
|
375
|
+
|
|
376
|
+
`mountPlayer` MUST release any player already mounted on the same container (`destroy()`), so remounting never leaks clocks, observers or capture entries. The build output passes `locale` through, so label dictionaries resolve there too; the Slidev adapter announces each click's step through the same kind of live region.
|
|
377
|
+
|
|
378
|
+
The Astro adapter mounts each diagram once, tears the players down on `astro:before-swap` and mounts the new page's diagrams on `astro:page-load`. Its root element exposes the controller as `.controller` from mount, and dispatches `motion-ready` (bubbling, `detail.controller`) or `motion-error` (`detail.error`) once the page's own scripts and their `DOMContentLoaded` and `astro:page-load` handlers have run, so a script placed after the diagram can still listen. Its `id` prop sets the element id, the capture-hook key and the id prefix; it MUST be a safe id token, used once per page, or the build fails.
|
|
324
379
|
|
|
325
380
|
### 10.2.1 Custom element (`adapters/element/motion-diagram.mjs`)
|
|
326
381
|
|
|
@@ -338,13 +393,32 @@ UI strings MAY be localized via `options.labels`.
|
|
|
338
393
|
destroy the player and restore the fallback; reconnection mounts afresh.
|
|
339
394
|
Superseded asynchronous loads MUST NOT mount or publish errors.
|
|
340
395
|
|
|
396
|
+
### 10.2.2 Page links (`runtime/links.mjs`)
|
|
397
|
+
|
|
398
|
+
Helpers that drive a player controller from the page around it. They MUST
|
|
399
|
+
touch the DOM only when called, never move focus, never change layout (the
|
|
400
|
+
only marks are `aria-current="step"` attributes), and return a `dispose()`
|
|
401
|
+
that removes every listener, observer and mark they added.
|
|
402
|
+
|
|
403
|
+
| Requirement | Source |
|
|
404
|
+
|---|---|
|
|
405
|
+
| A step reference (`data-mk-step`, or a number) MUST resolve to the step with that `id`, else to a whole-number index; an unknown id or an index out of range throws `RangeError` when the helper binds. | `runtime/links.mjs` (`stepRef`, `sectionSteps`), `test/links.test.mjs` |
|
|
406
|
+
| `scrollSteps(controller, sections, options)`: a section's step is its `data-mk-step`, else its position. The active section MUST be the last one, in order, whose top has reached a line at `line` (default 0.5) of the viewport's or `root`'s height (`activeSection`), observed with one IntersectionObserver whose root margin ends at that line. Before the first section nothing changes. | `runtime/links.mjs` (`scrollSteps`, `activeSection`) |
|
|
407
|
+
| Moving one section forward to a later step MUST play to it (`playToStep`); every other change (back, skipping, the first section, `animate: false`, `prefers-reduced-motion: reduce`) MUST jump (`seekStep`); a change to the same step calls nothing (`scrollMove`). The diagram MUST only rest on settled steps: no continuous scrubbing. | `runtime/links.mjs` (`scrollMove`), `test/links.test.mjs` |
|
|
408
|
+
| `linkSteps(controller, rootOrElements, options)`: every element with `data-mk-step` (under the root, or given) MUST select its step on `pointerenter` (not touch), `focusin` and `click`, so keyboard focus selects the same step as hover. A selection jumps; `animate: true` plays forward unless reduced motion. With `restore: true`, once neither hover nor focus is on a term, the frame shown before the preview returns (`seek`), unless a click committed a step. | `runtime/links.mjs` (`linkSteps`), `test/links.test.mjs` |
|
|
409
|
+
| Without IntersectionObserver, `scrollSteps` MUST do nothing (the text still reads). | `runtime/links.mjs` |
|
|
410
|
+
|
|
341
411
|
### 10.3 Self-contained HTML (`motion-kit build`, `lib/build.mjs`)
|
|
342
412
|
|
|
343
413
|
- MUST be one document with the runtime inlined by `lib/bundle.mjs`, no
|
|
344
414
|
external scripts, stylesheets or fetches (`test/cli.test.mjs:31-37`), so it
|
|
345
415
|
works under `connect-src 'none'` and from `file://`.
|
|
346
|
-
- MUST pre-render the
|
|
347
|
-
to the scene locale (
|
|
416
|
+
- MUST pre-render the player's first state (`playerMarkup`, `PLAYER_CSS`,
|
|
417
|
+
`themeCss`) and set `<html lang>` to the scene locale (`lib/build.mjs`).
|
|
418
|
+
- A custom module is built with the caller's `--options` and `kit`: every
|
|
419
|
+
runtime module is a bundle entry, so the `MotionKit` global is the kit.
|
|
420
|
+
The page-link helpers (§10.2.2) are bundled too (`MotionKitRuntime.scrollSteps`,
|
|
421
|
+
`MotionKitRuntime.linkSteps`).
|
|
348
422
|
- The CLI MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:112-113`)
|
|
349
423
|
and bundled code containing `</script>` (`:115`).
|
|
350
424
|
- The inlined runtime MUST render the same bytes as Node
|
|
@@ -361,6 +435,8 @@ UI strings MAY be localized via `options.labels`.
|
|
|
361
435
|
animation delayed `0.3 s + start`; the last slice holds (`mk-hold`, fill
|
|
362
436
|
forwards) (`:35-47`). Plays once; MUST hold the final frame.
|
|
363
437
|
- Under `prefers-reduced-motion: reduce` only the final slice is visible (`:39`).
|
|
438
|
+
- Slices share one document: a slice whose markup defines ids is rendered with
|
|
439
|
+
its own prefix (`<idPrefix>-<n>`, base `mk-bake` or `options.idPrefix`).
|
|
364
440
|
- One theme per file; for theme-following embeds publish a light and dark file
|
|
365
441
|
(`README.md:21-29`, `scripts/render-media.sh`).
|
|
366
442
|
- Size grows with fps × duration; README use SHOULD lower fps to 10–12.
|
|
@@ -377,13 +453,27 @@ UI strings MAY be localized via `options.labels`.
|
|
|
377
453
|
makes the canvas opaque (transparent by default).
|
|
378
454
|
- `--qc`: frames at `max(0, at − 0.2)` and `at + 0.2` (not after the last step)
|
|
379
455
|
under `qc/` (`lib/export.mjs:58-65`).
|
|
380
|
-
- `index.html` contact sheet: steps, QC row, a
|
|
381
|
-
|
|
456
|
+
- `index.html` contact sheet: steps, QC row, a phone row and the human review
|
|
457
|
+
checklist (`lib/export.mjs`, `contactSheet`). The phone row MUST show the
|
|
458
|
+
scene built for the `tall` format, in the same locale, options, style and
|
|
459
|
+
theme, at 360 px (`qc/phone.svg`, manifest `kind: "phone"`); when the tall
|
|
460
|
+
layout cannot be built, it shows the exported frame and says why.
|
|
382
461
|
- `manifest.json` MUST contain no timestamps: tool, version, scene, type,
|
|
383
|
-
format, locale, size, duration, style, theme, a 16-hex input
|
|
384
|
-
(source file + style), source commit,
|
|
385
|
-
(`lib/export.mjs
|
|
386
|
-
(`test/cli.test.mjs
|
|
462
|
+
format, locale, scene options, size, duration, style, theme, a 16-hex input
|
|
463
|
+
hash (source file + style + scene options), source commit, source dirty
|
|
464
|
+
flag, render settings, file list (`lib/export.mjs`). Two exports of the
|
|
465
|
+
same inputs MUST be equal (`test/cli.test.mjs`).
|
|
466
|
+
- `sourceCommit` is the short `HEAD` of the repository holding the source
|
|
467
|
+
file. `sourceDirty` is `true` when that file differs from it (modified,
|
|
468
|
+
staged or untracked: `status --porcelain -- <file>` is not empty), `false`
|
|
469
|
+
when it does not, and `null`, like `sourceCommit`, outside a repository.
|
|
470
|
+
Only the source file counts: modules a custom scene imports, the style file
|
|
471
|
+
and the options file do not (the input hash covers the style and options).
|
|
472
|
+
- A re-export into the same folder MUST replace the previous one: files the
|
|
473
|
+
folder's previous `manifest.json` listed and the new one does not are
|
|
474
|
+
removed, so the folder holds what the new manifest lists. Files no manifest
|
|
475
|
+
listed MUST NOT be touched; the export names them in a warning on stderr
|
|
476
|
+
(`lib/export.mjs`, `test/cli.test.mjs`).
|
|
387
477
|
|
|
388
478
|
### 10.6 Video (`motion-kit video`, `lib/video.mjs`)
|
|
389
479
|
|
|
@@ -405,21 +495,34 @@ UI strings MAY be localized via `options.labels`.
|
|
|
405
495
|
itself (`:67-72`); forward by one click animates from the previous step's
|
|
406
496
|
`at` to the next, any other move seeks (`:93-100`); print/export, overview
|
|
407
497
|
and reduced motion show the settled step frame (`:65`).
|
|
408
|
-
- **Astro** (`adapters/astro/AnimatedDiagram.astro`): server-renders the
|
|
409
|
-
|
|
498
|
+
- **Astro** (`adapters/astro/AnimatedDiagram.astro`): server-renders the
|
|
499
|
+
player's first state (§10.2) and mounts the player. It takes a `spec`, or a
|
|
500
|
+
custom module by path (`module`, a `/src/…/*.scene.mjs|js` file found with
|
|
501
|
+
`import.meta.glob`, loaded on demand in the browser) with its `options`;
|
|
502
|
+
`theme` (`light`/`dark`, else the system), `style` (token data), `id`,
|
|
503
|
+
`scrubber`, `labels`, `class`. Props MUST be serializable (a spec or a module
|
|
504
|
+
path, not a scene). The player stylesheet is emitted once per page; each
|
|
505
|
+
instance carries its tokens and a page-unique id (`mk-<scene.id>-<n>` unless
|
|
506
|
+
`id` is given). It fails the build for a missing module, options with a spec,
|
|
507
|
+
or an invalid theme.
|
|
410
508
|
- **Vendor** (`cli/motion-kit.mjs`, `vendor` command): copies `runtime/`, one
|
|
411
|
-
adapter, `lib/check.mjs` and the full MIT
|
|
412
|
-
|
|
509
|
+
adapter, `lib/check.mjs`, `lib/gate.mjs`, `lib/load.mjs` and the full MIT
|
|
510
|
+
`LICENSE`; writes `check.mjs`, which runs the same gate as `motion-kit
|
|
511
|
+
check` (§11) with `--format`, `--locale`, `--style` and `--options`, and
|
|
512
|
+
`MOTION_KIT_VERSION`. Consumers MUST retain `LICENSE` and the
|
|
413
513
|
SPDX headers when redistributing vendored files. Vendored files MUST NOT
|
|
414
514
|
be edited in the consumer.
|
|
415
515
|
|
|
416
516
|
## 11. The gate
|
|
417
517
|
|
|
418
|
-
`checkScene(scene)` (`lib/check.mjs
|
|
419
|
-
(`SAMPLES = 120
|
|
420
|
-
`motion-kit check`
|
|
421
|
-
|
|
422
|
-
|
|
518
|
+
`checkScene(scene)` (`lib/check.mjs`) samples 121 evenly spaced times
|
|
519
|
+
(`SAMPLES = 120`) and stops collecting after 13 problems.
|
|
520
|
+
`motion-kit check` and the vendored `check.mjs` both run `checkFiles`
|
|
521
|
+
(`lib/gate.mjs`): every file × format (all six unless `--format`, repeatable)
|
|
522
|
+
× locale (`--locale`, repeatable; else every locale a spec's strings carry, and
|
|
523
|
+
`en` for a module, §7), with `--options` for modules, plus the style contrast
|
|
524
|
+
check. A file that cannot be read, parsed or built fails on its own and the
|
|
525
|
+
remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = unit tests +
|
|
423
526
|
`check` over `examples/` and `brand/` (`package.json:15-18`).
|
|
424
527
|
|
|
425
528
|
| ID | Rule | Code | Rationale |
|
|
@@ -427,16 +530,17 @@ construction error (`cli/motion-kit.mjs:81-108`). `npm run gate` = unit tests +
|
|
|
427
530
|
| G1 | Rendering the same `t` twice MUST yield identical bytes. | `lib/check.mjs:41-42` | Determinism (T1/T2). Catches clocks/randomness and call-to-call state; cannot catch state that is consistent between two calls. |
|
|
428
531
|
| G2 | Each sampled frame MUST be well-formed (balanced tags, no stray `<`, entities only `amp lt gt quot #39 #n`). | `:12-31,43-44` | Escaping failures and broken markup break every target. |
|
|
429
532
|
| G3 | No number with ≥ 5 decimals in the full SVG. | `:45-46` | Rounding (T4). |
|
|
430
|
-
| G4 | No
|
|
533
|
+
| G4 | No colour literal in `frame()` markup: colour attributes and properties hold only tokens, `url(#…)` and the colourless keywords of §6; no hex or colour function (`rgb()`, `hsl()`, `oklch()`, …) in any attribute or `<style>`. Id references (`url(#…)`, `href="#…"`) are not colours; text content is not checked. | `lib/check.mjs` (`findColourLiteral`) | Token-only colours: themes and brand styles must work everywhere. |
|
|
431
534
|
| G5 | No `NaN`, `undefined`, `Infinity` in `frame()` output. | `:50` | Silent geometry bugs. |
|
|
432
|
-
| G6 | `render(at −
|
|
535
|
+
| 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. |
|
|
433
536
|
| G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
|
|
434
537
|
| G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
|
|
435
538
|
| G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
|
|
436
539
|
| 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. |
|
|
437
|
-
| G11 | `frame.toString()` MUST NOT contain `Date.now`, `new Date`, `Math.random`, `performance.now`. |
|
|
438
|
-
| G12 | Style passes WCAG contrast in both themes. | `
|
|
439
|
-
| G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `
|
|
540
|
+
| 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. |
|
|
541
|
+
| 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). |
|
|
542
|
+
| G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `lib/gate.mjs` | Reject, don't invent: a broken picture never renders. |
|
|
543
|
+
| 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. |
|
|
440
544
|
|
|
441
545
|
The gate checks structure, not looks. Visual review (before/after frames,
|
|
442
546
|
phone size, real-time playback, dark mode) is required by
|
|
@@ -454,12 +558,11 @@ Recorded, not resolved. Each needs an owner decision.
|
|
|
454
558
|
| D3 | Every locale is checked | `.mjs` modules are checked in `en` only (`cli/motion-kit.mjs:89`), although `examples/custom-pulse.scene.mjs` ships `nl`. | "Labels fit … in every locale" (`README.md:97`, `AGENTS.md:48-49`). |
|
|
455
559
|
| D4 | Missing copy | `localize` silently falls back to the first available language (`runtime/scene.mjs:36-39`). | "Missing label → throw" (`skills/animated-diagram/references/technique.md:111`). Only an empty *step* label throws. |
|
|
456
560
|
| D5 | Gate rule G10 and `stepLabelsInFrame` | Enforced (`lib/check.mjs:70-77`). | Absent from the scene contract comment (`runtime/scene.mjs:4-12`), `custom-scenes.md`, and the rule lists in `README.md:94-99` and `AGENTS.md:38-49`. |
|
|
457
|
-
| D6 | "Enforced by `motion-kit check`" | G1 and G11 only partly verify purity
|
|
561
|
+
| D6 | "Enforced by `motion-kit check`" | G1 and G11 only partly verify purity: no cross-call state detection, and a clock reference taken at import time escapes G11's stub; CSS-transition and "no earlier-frame state" rules are not checked. Escaping is guaranteed by `esc`/`text`, and only detected by G2 for `<` and `&`. | All 11 determinism rules listed as "enforced by `motion-kit check`" (`skills/animated-diagram/references/technique.md:23-39`). |
|
|
458
562
|
| D7 | Style `radius` / `stroke` | Normalized (`runtime/style.mjs:63-64`) but never read; parts default to radius 10, stroke 2 (`runtime/parts.mjs:52,75`). | Documented as style fields (`styles.md:28-29`). |
|
|
459
563
|
| D8 | Dark fallback | A style with no `dark` applies its **light** overrides to dark (`runtime/style.mjs:66`). | "Missing tokens fall back to neutral" (`styles.md:35`). |
|
|
460
564
|
| D9 | Video frame reuse | PNGs are reused only when `t` repeats (lead and hold) (`lib/video.mjs:46`). | "Identical consecutive frames are rasterized once" (`skills/motion-render/references/video.md:9`). |
|
|
461
|
-
| D10 | Capture-hook key | Key is `options.id ?? scene.id`, i.e. format-suffixed (`order-flow-16x9`); the Astro adapter
|
|
462
|
-
| D11 | Vendored gate | `check.mjs` written by `vendor` handles `.json` only, skips the contrast check, and detects locales with `^[a-z]{2}$` (no region, no string-value test) (`cli/motion-kit.mjs:177-207`). | Implied parity with `motion-kit check` (`README.md:90-92`). |
|
|
565
|
+
| D10 | Capture-hook key | Key is `options.id ?? scene.id`, i.e. format-suffixed (`order-flow-16x9`); the Astro adapter uses its `id` prop or `mk-<scene.id>-<n>`; the Slidev adapter exposes none. | `window.__motionKit[sceneId]` / `[id]` (`adapters/page/README.md:22`, `interactivity.md`). |
|
|
463
566
|
| D12 | Auto-fit maximum | Sequence 22 px, hub-spoke 20 px (`runtime/types/hub-spoke.mjs:97`). | "Fixed formats ≤ 22 px" without type distinction (`technique.md:90`); `formats.md:12` is correct. |
|
|
464
567
|
| D13 | Timing budgets | `ENTRANCE_MAX` is exported but unused; stagger and entrance limits are not checked. | Listed as "Hard rules" (`skills/animated-diagram/SKILL.md:50`). |
|
|
465
|
-
| D14 | Manifest reproducibility | `inputHash` covers the source file and
|
|
568
|
+
| D14 | Manifest reproducibility | `inputHash` covers the source file, style and scene options, not the runtime; a runtime change keeps the hash while frames change (only `version` hints at it) (`lib/export.mjs:66-70`). | "A stale export is easy to spot" (`skills/motion-render/SKILL.md:66-68`). |
|
|
@@ -135,6 +135,9 @@ export default function make({ format = "16:9", locale = "en" } = {}) {
|
|
|
135
135
|
// Steps here are events, not nodes: their labels live in the player's
|
|
136
136
|
// step buttons and captions, not in the drawing.
|
|
137
137
|
stepLabelsInFrame: false,
|
|
138
|
+
// Beyond the pairs every scene draws: the progress bar's accent fill on
|
|
139
|
+
// its surface track. The gate checks the style against it too.
|
|
140
|
+
contrastPairs: [{ fg: "accent", bg: "surface", min: 3, use: "the progress bar's fill on its track" }],
|
|
138
141
|
steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
|
|
139
142
|
frame,
|
|
140
143
|
};
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"type": "timeline",
|
|
3
|
+
"id": "incident",
|
|
4
|
+
"title": { "en": "An incident, start to review", "nl": "Een storing, van begin tot evaluatie" },
|
|
5
|
+
"description": {
|
|
6
|
+
"en": "An outage from the first alert to the all-clear, with the review still to come.",
|
|
7
|
+
"nl": "Een storing van het eerste alarm tot het sein veilig, met de evaluatie nog te gaan."
|
|
8
|
+
},
|
|
9
|
+
"events": [
|
|
10
|
+
{ "when": "09:02", "label": { "en": "Alert fires", "nl": "Alarm gaat af" }, "detail": { "en": "Error rates cross the threshold and on-call is paged.", "nl": "Het foutpercentage gaat over de drempel en de dienstdoende wordt opgeroepen." } },
|
|
11
|
+
{ "when": "09:06", "label": { "en": "On-call responds", "nl": "Dienstdoende reageert" }, "detail": { "en": "The engineer on call acknowledges and opens an incident channel.", "nl": "De dienstdoende engineer bevestigt en opent een storingskanaal." } },
|
|
12
|
+
{ "when": "09:24", "label": { "en": "Cause found", "nl": "Oorzaak gevonden" }, "detail": { "en": "A configuration change from the morning release is the cause.", "nl": "Een configuratiewijziging uit de ochtendrelease is de oorzaak." } },
|
|
13
|
+
{ "when": "09:41", "label": { "en": "Fix deployed", "nl": "Herstel uitgerold" }, "detail": { "en": "The change is rolled back and error rates fall.", "nl": "De wijziging wordt teruggedraaid en het foutpercentage daalt." } },
|
|
14
|
+
{ "when": "10:15", "label": { "en": "All clear", "nl": "Sein veilig" }, "detail": { "en": "Metrics are back to normal and the incident is closed.", "nl": "De metrieken zijn weer normaal en de storing is gesloten." } },
|
|
15
|
+
{ "when": { "en": "Thursday", "nl": "Donderdag" }, "label": { "en": "Review", "nl": "Evaluatie" }, "planned": true, "detail": { "en": "The team writes down what happened and what changes, without blame.", "nl": "Het team legt vast wat er gebeurde en wat er verandert, zonder schuldvraag." } }
|
|
16
|
+
],
|
|
17
|
+
"now": { "label": { "en": "Now", "nl": "Nu" }, "detail": { "en": "The service is healthy; the review is still to come.", "nl": "De dienst is gezond; de evaluatie moet nog komen." } }
|
|
18
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"type": "stack",
|
|
3
|
+
"id": "web-stack",
|
|
4
|
+
"title": { "en": "A request through the layers", "nl": "Een verzoek door de lagen" },
|
|
5
|
+
"description": {
|
|
6
|
+
"en": "A request from the browser passes the CDN, the API gateway and the service before it reaches the database.",
|
|
7
|
+
"nl": "Een verzoek uit de browser passeert het CDN, de API-gateway en de dienst voordat het de database bereikt."
|
|
8
|
+
},
|
|
9
|
+
"layers": [
|
|
10
|
+
{ "label": { "en": "Browser", "nl": "Browser" }, "detail": { "en": "The user's click becomes an HTTPS request.", "nl": "De klik van de gebruiker wordt een HTTPS-verzoek." } },
|
|
11
|
+
{ "label": { "en": "CDN", "nl": "CDN" }, "detail": { "en": "The edge answers cached pages and passes everything else on.", "nl": "De rand beantwoordt gecachete pagina's en geeft de rest door." } },
|
|
12
|
+
{ "label": { "en": "API gateway", "nl": "API-gateway" }, "detail": { "en": "Checks who is asking and how often.", "nl": "Controleert wie er vraagt en hoe vaak." } },
|
|
13
|
+
{ "label": { "en": "Order service", "nl": "Bestelservice" }, "detail": { "en": "The business logic decides what the request means.", "nl": "De bedrijfslogica bepaalt wat het verzoek betekent." } },
|
|
14
|
+
{ "label": { "en": "Database", "nl": "Database" }, "detail": { "en": "The data is read or written, and the answer travels back.", "nl": "De gegevens worden gelezen of geschreven, en het antwoord gaat terug." } }
|
|
15
|
+
],
|
|
16
|
+
"direction": "down"
|
|
17
|
+
}
|
package/lib/build.mjs
CHANGED
|
@@ -2,32 +2,44 @@
|
|
|
2
2
|
* motion-kit · build a self-contained interactive HTML file.
|
|
3
3
|
*
|
|
4
4
|
* One document, runtime inlined, no network requests: safe for Craft Pages
|
|
5
|
-
* (connect-src 'none'), file:// and any static host. The
|
|
6
|
-
* pre-rendered into the markup, so it
|
|
5
|
+
* (connect-src 'none'), file:// and any static host. The player's first state
|
|
6
|
+
* (final frame, step list, colours) is pre-rendered into the markup, so it
|
|
7
|
+
* reads correctly before (or without) JS, and mounting moves nothing.
|
|
8
|
+
*
|
|
9
|
+
* A custom module gets its scene options and `kit` (every runtime export),
|
|
10
|
+
* as it does from the CLI.
|
|
7
11
|
*/
|
|
8
12
|
import { fileURLToPath } from "node:url";
|
|
9
13
|
import { bundle } from "./bundle.mjs";
|
|
10
14
|
import { escapeHtml } from "./export.mjs";
|
|
11
|
-
import {
|
|
15
|
+
import { PLAYER_CSS, playerMarkup, themeCss } from "../runtime/player.mjs";
|
|
12
16
|
import { cssVars } from "../runtime/style.mjs";
|
|
13
17
|
|
|
14
18
|
const RUNTIME = fileURLToPath(new URL("../runtime/", import.meta.url));
|
|
15
19
|
|
|
20
|
+
/** JSON for an inline script: `<` escaped, so no value can close the script element. */
|
|
21
|
+
const scriptJson = (/** @type {unknown} */ value) => JSON.stringify(value).replace(/</g, "\\u003c");
|
|
22
|
+
|
|
16
23
|
/**
|
|
17
24
|
* @param {import("./load.mjs").LoadedScene} loaded
|
|
18
|
-
* @param {{style:import("../runtime/style.mjs").Style, format:string, locale:string, scrubber?:boolean, heading?:boolean, theme?:string, labels?:Record<string,string>}} o
|
|
25
|
+
* @param {{style:import("../runtime/style.mjs").Style, format:string, locale:string, scrubber?:boolean, heading?:boolean, theme?:string, labels?:Record<string,string|Record<string,string>>, options?:Record<string,unknown>}} o
|
|
26
|
+
* options: scene options for a custom module's factory
|
|
19
27
|
*/
|
|
20
28
|
export function buildHtml(loaded, o) {
|
|
21
|
-
|
|
29
|
+
// Every runtime module is an entry, so the MotionKit global is the whole kit.
|
|
30
|
+
const entries = ["motion", "svg", "style", "wrap", "scene", "types/index", "player", "links"].map((m) => `${RUNTIME}${m}.mjs`);
|
|
31
|
+
const runtimeCount = entries.length;
|
|
22
32
|
if (loaded.kind === "module") entries.push(loaded.file);
|
|
23
|
-
|
|
33
|
+
// MotionKitRuntime is the runtime alone: a custom module's exports, spread
|
|
34
|
+
// after it into MotionKit, may reuse a runtime name without breaking `kit`.
|
|
35
|
+
const code = bundle(entries, { runtimeName: "MotionKitRuntime", runtimeCount });
|
|
24
36
|
const { scene } = loaded;
|
|
25
|
-
const
|
|
37
|
+
const options = { style: o.style, scrubber: o.scrubber !== false, theme: o.theme, labels: o.labels, locale: o.locale };
|
|
38
|
+
const fallback = playerMarkup(scene, { ...options, id: "mk-fallback" });
|
|
26
39
|
const make =
|
|
27
40
|
loaded.kind === "spec"
|
|
28
|
-
? `MotionKit.createScene(${
|
|
29
|
-
: `MotionKit.default(${
|
|
30
|
-
const options = { style: o.style, scrubber: o.scrubber !== false, theme: o.theme, labels: o.labels };
|
|
41
|
+
? `MotionKit.createScene(${scriptJson(loaded.spec)}, ${scriptJson({ format: o.format, locale: o.locale })})`
|
|
42
|
+
: `MotionKitRuntime.validateScene(MotionKit.default(Object.assign(${scriptJson(o.options ?? {})}, ${scriptJson({ format: o.format, locale: o.locale })}, { kit: MotionKitRuntime })))`;
|
|
31
43
|
const lang = scene.locale ?? o.locale ?? "en";
|
|
32
44
|
return `<!doctype html>
|
|
33
45
|
<html lang="${escapeHtml(lang)}">
|
|
@@ -42,18 +54,20 @@ body{margin:0;padding:24px;background:var(--mk-bg);color:var(--mk-ink);font-fami
|
|
|
42
54
|
main{max-width:${Math.max(scene.width, 360)}px;margin:0 auto}
|
|
43
55
|
h1{font-size:20px;line-height:1.3;margin:0 0 4px}
|
|
44
56
|
.lede{margin:0 0 16px;color:var(--mk-muted);font-size:15px;line-height:1.45}
|
|
57
|
+
${themeCss("#mk", o.style, o.theme)}
|
|
45
58
|
</style>
|
|
59
|
+
<style data-mk-player-css>${PLAYER_CSS}</style>
|
|
46
60
|
</head>
|
|
47
61
|
<body>
|
|
48
62
|
<main>
|
|
49
63
|
${o.heading === false ? "" : `<h1>${escapeHtml(scene.title)}</h1>\n<p class="lede">${escapeHtml(scene.description)}</p>`}
|
|
50
|
-
<div id="mk">${fallback}</div>
|
|
64
|
+
<div id="mk" class="mk-player">${fallback}</div>
|
|
51
65
|
</main>
|
|
52
66
|
<script>
|
|
53
67
|
${code}
|
|
54
68
|
(function () {
|
|
55
69
|
var scene = ${make};
|
|
56
|
-
|
|
70
|
+
MotionKitRuntime.mountPlayer(document.getElementById("mk"), scene, ${scriptJson(options)});
|
|
57
71
|
})();
|
|
58
72
|
</script>
|
|
59
73
|
</body>
|
package/lib/bundle.mjs
CHANGED
|
@@ -15,7 +15,11 @@ import { dirname, resolve } from "node:path";
|
|
|
15
15
|
|
|
16
16
|
const IMPORT_RE = /^import\s*\{([^}]*)\}\s*from\s*["'](\.{1,2}\/[^"']+)["'];?\s*$/;
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
/**
|
|
19
|
+
* @param {string[]} entries
|
|
20
|
+
* @param {{ globalName?: string, runtimeName?: string, runtimeCount?: number }} [o]
|
|
21
|
+
*/
|
|
22
|
+
export function bundle(entries, { globalName = "MotionKit", runtimeName = "", runtimeCount = entries.length } = {}) {
|
|
19
23
|
const order = [];
|
|
20
24
|
const seen = new Map();
|
|
21
25
|
function visit(file) {
|
|
@@ -64,5 +68,8 @@ export function bundle(entries, { globalName = "MotionKit" } = {}) {
|
|
|
64
68
|
}
|
|
65
69
|
const ids = entries.map((e) => visit(e));
|
|
66
70
|
const merged = ids.map((id) => `...${id}`).join(", ");
|
|
67
|
-
|
|
71
|
+
// runtimeName: a second global of the first `runtimeCount` entries only, so a
|
|
72
|
+
// later entry's exports cannot shadow theirs.
|
|
73
|
+
const runtime = runtimeName ? `\nglobalThis.${runtimeName} = Object.freeze({ ${ids.slice(0, runtimeCount).map((id) => `...${id}`).join(", ")} });` : "";
|
|
74
|
+
return `(() => {\n"use strict";\n${order.join("\n")}\nglobalThis.${globalName} = Object.freeze({ ${merged} });${runtime}\n})();\n`;
|
|
68
75
|
}
|