@liqweed/motion-kit 0.0.0-stage → 0.3.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.
Files changed (57) hide show
  1. package/.claude-plugin/marketplace.json +13 -0
  2. package/.claude-plugin/plugin.json +9 -0
  3. package/LICENSE +21 -0
  4. package/README.md +141 -2
  5. package/adapters/astro/AnimatedDiagram.astro +55 -0
  6. package/adapters/element/README.md +49 -0
  7. package/adapters/element/motion-diagram.mjs +123 -0
  8. package/adapters/page/README.md +22 -0
  9. package/adapters/slidev/AnimatedDiagram.vue +137 -0
  10. package/brand/logo.scene.mjs +115 -0
  11. package/cli/motion-kit.mjs +239 -0
  12. package/docs/spec/technique.md +465 -0
  13. package/examples/agent-loop.json +18 -0
  14. package/examples/custom-pulse.scene.mjs +141 -0
  15. package/examples/integrations.json +20 -0
  16. package/examples/order-flow.json +17 -0
  17. package/examples/release-pipeline.json +17 -0
  18. package/examples/smart-home.json +17 -0
  19. package/lib/build.mjs +62 -0
  20. package/lib/bundle.mjs +68 -0
  21. package/lib/check.mjs +86 -0
  22. package/lib/export.mjs +113 -0
  23. package/lib/icon.mjs +41 -0
  24. package/lib/load.mjs +53 -0
  25. package/lib/raster.mjs +69 -0
  26. package/lib/video.mjs +77 -0
  27. package/package.json +69 -5
  28. package/runtime/bake.mjs +61 -0
  29. package/runtime/motion.mjs +154 -0
  30. package/runtime/parts.mjs +123 -0
  31. package/runtime/player.mjs +255 -0
  32. package/runtime/scene.mjs +101 -0
  33. package/runtime/style.mjs +142 -0
  34. package/runtime/svg.mjs +165 -0
  35. package/runtime/types/hub-spoke.mjs +215 -0
  36. package/runtime/types/index.mjs +25 -0
  37. package/runtime/types/sequence.mjs +201 -0
  38. package/runtime/wrap.mjs +44 -0
  39. package/skills/animated-diagram/SKILL.md +90 -0
  40. package/skills/animated-diagram/references/custom-scenes.md +56 -0
  41. package/skills/animated-diagram/references/ecosystem.md +28 -0
  42. package/skills/animated-diagram/references/interactivity.md +51 -0
  43. package/skills/animated-diagram/references/motion-vocabulary.md +70 -0
  44. package/skills/animated-diagram/references/qc.md +41 -0
  45. package/skills/animated-diagram/references/scene-types.md +59 -0
  46. package/skills/animated-diagram/references/styles.md +55 -0
  47. package/skills/animated-diagram/references/targets.md +27 -0
  48. package/skills/animated-diagram/references/technique.md +148 -0
  49. package/skills/motion-render/SKILL.md +79 -0
  50. package/skills/motion-render/references/formats.md +18 -0
  51. package/skills/motion-render/references/slides.md +18 -0
  52. package/skills/motion-render/references/video.md +61 -0
  53. package/skills/project-logo/SKILL.md +72 -0
  54. package/skills/project-logo/references/design.md +22 -0
  55. package/skills/project-logo/references/discovery.md +15 -0
  56. package/skills/project-logo/references/external-prompt.md +23 -0
  57. package/styles/neutral.json +26 -0
@@ -0,0 +1,465 @@
1
+ ---
2
+ title: motion-kit technique — normative specification
3
+ status: draft
4
+ last_updated: 2026-11-15
5
+ ---
6
+
7
+ # motion-kit technique — normative specification
8
+
9
+ This is the authoritative contract for scenes, motion helpers, styles and
10
+ render targets. The design guidance (storyboards, timing taste, review
11
+ practice) stays in the skill references and is linked, not repeated:
12
+ [`technique.md`](../../skills/animated-diagram/references/technique.md),
13
+ [`motion-vocabulary.md`](../../skills/animated-diagram/references/motion-vocabulary.md),
14
+ [`styles.md`](../../skills/animated-diagram/references/styles.md),
15
+ [`interactivity.md`](../../skills/animated-diagram/references/interactivity.md),
16
+ [`qc.md`](../../skills/animated-diagram/references/qc.md),
17
+ [`scene-types.md`](../../skills/animated-diagram/references/scene-types.md),
18
+ [`formats.md`](../../skills/motion-render/references/formats.md),
19
+ [`video.md`](../../skills/motion-render/references/video.md).
20
+
21
+ **Conventions.** MUST / MUST NOT / SHOULD / MAY as in RFC 2119. **[gate]**
22
+ marks a rule `lib/check.mjs` or the CLI enforces; **[throws]** marks a rule the
23
+ runtime enforces by throwing; unmarked rules are by contract only. Citations are
24
+ `path:line` against the working tree of 2026-11-15; where code and skill docs
25
+ disagree, §12 records it.
26
+
27
+ ## 1. Scene contract
28
+
29
+ A scene is a plain object (`runtime/scene.mjs:1-18`).
30
+
31
+ | Field | Type | Req. | Rule |
32
+ |---|---|---|---|
33
+ | `id` | string | MUST | Non-empty [throws] (`runtime/scene.mjs:43-44`). Scene types suffix the format: `<spec.id>-16x9` (`runtime/types/sequence.mjs:187`). Used as the default `<title>`/`<desc>` id prefix. |
34
+ | `width`, `height` | number | MUST | The viewBox, in user units [throws if missing]. |
35
+ | `duration` | number, s | MUST | Time of the final state. |
36
+ | `title` | string | MUST | Accessible name (`<title>`) [throws if empty]. |
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] (`runtime/scene.mjs:46-53`). The last step is the finished diagram. |
39
+ | `frame(t)` | `(number) → string` | MUST | Inner SVG markup at `t` (§2). |
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
+ | `type`, `format`, `locale` | string | MAY | Set by scene types; recorded in the export manifest (`lib/export.mjs:75-77`). |
42
+
43
+ - A scene MUST be produced by either a registered scene type —
44
+ `createScene(spec, {format, locale})` (`runtime/types/index.mjs:19-23`) — or a
45
+ custom module whose default export is `(opts) → scene`
46
+ (`lib/load.mjs:29-32`). Both paths run `validateScene`.
47
+ - A custom module MUST import only from `runtime/` with single-line relative
48
+ `import { … } from "./x.mjs";` statements and use only the export forms the
49
+ inliner supports, or `build` throws (`lib/bundle.mjs:8-11,33,59`).
50
+ - `detail` SHOULD hold sentences; labels stay short (§7). `detail` feeds the
51
+ player caption and screen-reader list (§10.2).
52
+
53
+ ## 2. Time model and determinism
54
+
55
+ | # | Rule | Enforcement | Rationale |
56
+ |---|---|---|---|
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:42,80-81`) | Random access: a player can jump, an exporter can write exactly one frame, video samples `t = f/fps` (`runtime/scene.mjs:14-17`). |
58
+ | 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
+ | 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
+ | 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
+ | 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
+ | 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 (heuristic) | Same as T2. |
64
+
65
+ ## 3. Formats and layout per format
66
+
67
+ Formats map a name to a viewBox (`runtime/scene.mjs:23-30`):
68
+
69
+ | Name | viewBox | Height |
70
+ |---|---|---|
71
+ | `16:9` | 960×540 | fixed |
72
+ | `4:3` | 960×720 | fixed |
73
+ | `1:1` | 720×720 | fixed |
74
+ | `9:16` | 540×960 | fixed |
75
+ | `wide` | 960×auto | computed by the scene type |
76
+ | `tall` | 360×auto | computed by the scene type |
77
+
78
+ - Layout MUST be computed per format from the shared spec and timings; output
79
+ MUST NOT be produced by cropping or scaling another format's layout
80
+ (`runtime/scene.mjs:22`).
81
+ - An unknown format MUST throw (`runtime/types/sequence.mjs:125`,
82
+ `runtime/types/hub-spoke.mjs:92`, `examples/custom-pulse.scene.mjs:40`).
83
+ - Arrangement by aspect: "narrow" means `tall` or `W/H < 0.8` → column/tree;
84
+ `W/H ≥ 1.5` → row (or 2-row snake when cells are < 96 px) for `sequence`;
85
+ otherwise snake grid (`runtime/types/sequence.mjs:35-46`) or radial ellipse
86
+ (`runtime/types/hub-spoke.mjs:40,59-73`).
87
+ - **Auto-fit text**: a type MUST try the largest font size and step down by
88
+ 1 px to `FONT_MIN = 14` (`runtime/parts.mjs:12`) until every label wraps
89
+ into its budget; if none fits it MUST throw. Maxima: `sequence` 22 px fixed /
90
+ 16 px strips (`runtime/types/sequence.mjs:127`); `hub-spoke` 20 / 16
91
+ (`runtime/types/hub-spoke.mjs:97`); `spec.fontSize` overrides the maximum.
92
+ - **Collisions**: a layout whose boxes overlap (6 px gap) or leave the canvas
93
+ MUST throw rather than render (`runtime/types/hub-spoke.mjs:33-35,76-84,119`).
94
+ - Connectors MUST NOT cross labels; snake-grid row turns route as elbows
95
+ outside the column (`runtime/types/sequence.mjs:101-119`); the narrow
96
+ hub-spoke trunk runs outside the boxes (`runtime/types/hub-spoke.mjs:43-57`).
97
+ - Custom modules MUST either support every format or be checked with
98
+ `--format` restricted to the ones they ship
99
+ (`skills/animated-diagram/references/custom-scenes.md:34-35`).
100
+
101
+ Web breakpoint guidance (wide ↔ tall) is in
102
+ [`formats.md`](../../skills/motion-render/references/formats.md).
103
+
104
+ ## 4. Motion primitives (`runtime/motion.mjs`)
105
+
106
+ All helpers are pure number → number functions (`runtime/motion.mjs:1-7`).
107
+ None overshoot.
108
+
109
+ ### 4.1 Easing
110
+
111
+ `cubicBezier(x1, y1, x2, y2)` MUST reproduce CSS `cubic-bezier()` exactly
112
+ (`runtime/motion.mjs:24-55`):
113
+
114
+ - Polynomial coefficients `cx = 3x1`, `bx = 3(x2 − x1) − cx`, `ax = 1 − cx − bx`
115
+ (same for y); `x(s) = ((ax·s + bx)·s + cx)·s`.
116
+ - For progress `p`: return 0 if `p ≤ 0`, 1 if `p ≥ 1`; otherwise solve
117
+ `x(s) = p` by Newton's method from `s = p` (≤ 8 iterations, stop at
118
+ |error| < 1e-7, abort if |x′| < 1e-7), then fall back to bisection on
119
+ [0, 1] (≤ 60 iterations, interval < 1e-9); return `y(s)`.
120
+
121
+ | Export | Curve | Use |
122
+ |---|---|---|
123
+ | `easeOut` | `cubic-bezier(0, 0, .2, 1)` | entrances |
124
+ | `easeStandard` | `cubic-bezier(.4, 0, .2, 1)` | movement between visible states, fills, draw-on |
125
+ | `easeIn` | `cubic-bezier(.4, 0, 1, 1)` | exits |
126
+ | `linear` | `clamp01(p)` | mechanical progress only |
127
+
128
+ (`runtime/motion.mjs:57-63`.) Every ease MUST be monotonic on [0, 1] with
129
+ `ease(0) = 0`, `ease(1) = 1` (`test/runtime.test.mjs:20-31`). Bounce and
130
+ elastic curves MUST NOT be added (`runtime/motion.mjs:6`).
131
+
132
+ ### 4.2 Progress
133
+
134
+ - `progress(t, start, duration, ease = easeOut)` = `ease(clamp01((t − start)/duration))`;
135
+ holds 0 before `start` and 1 after; `duration ≤ 0` is a step at `start`
136
+ (`runtime/motion.mjs:69-72`).
137
+ - `window01(t, start, end)` is the un-eased linear window
138
+ (`runtime/motion.mjs:75-77`).
139
+ - Properties SHOULD be `lerp(a, b, progress(…))`; compose by multiplying
140
+ progress values or stacking layers, never by mutation.
141
+
142
+ ### 4.3 Critically damped spring
143
+
144
+ - Step response `s(τ) = 1 − (1 + ωτ)·e^(−ωτ)` for τ > 0, else 0; default
145
+ ω = 12 rad/s (`runtime/motion.mjs:97-102`).
146
+ - **Settle snap**: once `ωτ ≥ SPRING_SETTLE_X = 9.24`, `s` MUST return exactly 1
147
+ (`runtime/motion.mjs:86,100`). 9.24 solves `(1 + x)e^(−x) = 0.001`: the snap
148
+ moves a 100 px travel ≤ 0.1 px, and settled frames become byte-stable.
149
+ - `springSettleTime(ω) = 9.24 / ω` (ω = 12 → 0.77 s; ω = 16 → 0.58 s)
150
+ (`runtime/motion.mjs:105-107`). A spring started at `a` MUST settle by the
151
+ next step's `at`: `a + 9.24/ω ≤ at` (§8).
152
+ - MUST be monotonic, never overshoot (`test/runtime.test.mjs:32-41`).
153
+ Underdamped springs are out of scope.
154
+
155
+ ### 4.4 Retarget
156
+
157
+ `springTo(t, from, changes, ω)` = `from + Σ (toᵢ − toᵢ₋₁)·s(t − atᵢ)` over
158
+ target changes in time order (`runtime/motion.mjs:121-129`). Exact by
159
+ superposition (the spring is linear time-invariant), continuous at every change,
160
+ still random-access (`test/runtime.test.mjs:42-51`). Frame-by-frame spring
161
+ simulation MUST NOT be used.
162
+
163
+ ### 4.5 Split edges
164
+
165
+ `splitEdge(t, start, duration, lag = 0.07, ease = easeStandard)` →
166
+ `{lead, trail}`, where `trail` is the same curve delayed by `lag`
167
+ (`runtime/motion.mjs:139-144`). `trail ≤ lead` always
168
+ (`test/runtime.test.mjs:52-57`). Draw the shape from `trail` to `lead`; it
169
+ stretches in flight and lands at its own length. Lag SHOULD be 50–100 ms. The
170
+ move ends at `start + lag + duration`, which is what step timing MUST budget.
171
+
172
+ ### 4.6 Stagger
173
+
174
+ `stagger(count, start, gap)` → start times `start + i·gap` in reading order
175
+ (`runtime/motion.mjs:150-152`). Gap SHOULD be 80–150 ms; one entrance SHOULD be
176
+ ≤ `ENTRANCE_MAX = 0.6` s (`runtime/motion.mjs:10`). Neither is gate-enforced.
177
+
178
+ ### 4.7 Geometry: arc length and draw-on (`runtime/svg.mjs`)
179
+
180
+ - `polyline(points)` → `{length, d, at(f)}`; `at` returns the point at fraction
181
+ `f` of total arc length (`runtime/svg.mjs:92-113`).
182
+ - `cubic(p0…p3, samples = 64)` → `{length, d, at(f)}` with a 64-sample
183
+ arc-length lookup table and binary search, so a marker moves at constant
184
+ speed without a DOM in Node and browsers (`runtime/svg.mjs:119-152`).
185
+ - `drawOn(length, p)`: `null` for `p ≤ 0`, `{}` for `p ≥ 1`, else
186
+ `stroke-dasharray: L L; stroke-dashoffset: L·(1 − p)`
187
+ (`runtime/svg.mjs:159-163`). Callers MUST skip the element when it returns
188
+ `null`: a zero-length dash with round caps paints a dot.
189
+ - Two-state elements (pending → active) MUST cross-fade two layers with
190
+ opacities `1 − p` and `p` instead of interpolating colours, which would need
191
+ literals (`runtime/parts.mjs:1-8,68,94,109`).
192
+
193
+ ## 5. Markup
194
+
195
+ - Text and attribute values MUST be escaped (`& < > " '`) via `esc`, `text` or
196
+ `el`/`attrString` (`runtime/svg.mjs:10-14,24-33,45-57`). Labels MUST NOT be able
197
+ to inject markup (`test/runtime.test.mjs:118-124`).
198
+ - `el(tag, attrs, …children)` treats children as trusted markup; untrusted
199
+ strings MUST go through `text()`/`esc()`.
200
+ - Output MUST be well-formed: balanced tags, no stray `<`, no bare `&` [gate] G2.
201
+ - Icons are path data on a 24×24 grid supplied in the spec; motion-kit ships no
202
+ icon set (`runtime/parts.mjs:14-34`). Glyphs are ≤ 3 characters
203
+ (`runtime/parts.mjs:42`).
204
+
205
+ ## 6. Tokens, styles, themes and contrast (`runtime/style.mjs`)
206
+
207
+ - Scenes MUST NOT contain colour literals [gate] G4. Colours MUST be
208
+ `tok(name)` → `var(--mk-<name>)`; an unknown name throws
209
+ (`runtime/style.mjs:52-55`).
210
+ - Tokens (`runtime/style.mjs:14-23`): `bg`, `surface`, `ink`, `muted`, `line`,
211
+ `accent`, `onAccent`, `emphasis`. Roles: see
212
+ [`styles.md`](../../skills/animated-diagram/references/styles.md). Exactly one
213
+ element at a time SHOULD carry `emphasis`.
214
+ - A style is data: `{name, font, radius, stroke, light: {token: #rrggbb}, dark: {…}}`.
215
+ `normalizeStyle` fills missing fields from `NEUTRAL`
216
+ (`runtime/style.mjs:25-50,58-77`) and MUST throw on an unknown token or a
217
+ non-`#rrggbb` value (`runtime/style.mjs:70-73`). If `dark` is absent, dark
218
+ takes the `light` overrides on top of neutral dark (`runtime/style.mjs:66`).
219
+ - **Live** output MUST carry tokens as CSS custom properties on the container
220
+ (`runtime/player.mjs:52`, `lib/build.mjs:39-40`) so light/dark can switch
221
+ without re-rendering. **Standalone** output MUST resolve every token to a
222
+ literal (`runtime/scene.mjs:84`, `runtime/style.mjs:86-93`), because slide
223
+ apps, rasterizers and image viewers ignore CSS variables; an unresolvable
224
+ token throws.
225
+ - **Contrast** (`runtime/style.mjs:114-134`, WCAG relative luminance): in both
226
+ themes, text ≥ 4.5:1 — `ink`/`muted` on `bg` and `surface`, `onAccent` on
227
+ `accent`; shapes ≥ 3:1 — `line`, `accent`, `emphasis` on `bg`. `motion-kit
228
+ check` MUST fail when the selected style violates any pair [gate] G12
229
+ (`cli/motion-kit.mjs:83-85`). `neutral` MUST pass (`test/runtime.test.mjs:96-98`).
230
+ - motion-kit ships only `neutral` (`styles/neutral.json`); brand styles MUST
231
+ live in the consumer repo.
232
+
233
+ ## 7. Labels, wrapping and locales
234
+
235
+ - SVG text does not wrap: every layout MUST declare a character budget and
236
+ wrap with `wrapLabel(label, maxChars, maxLines = 2)` (`runtime/wrap.mjs:9-37`).
237
+ - Breaking: at whitespace and after `/`; a standalone separator
238
+ (`/ – — & + |`) sticks to the preceding word so no line starts with it
239
+ (`runtime/wrap.mjs:13-20`). No leading spaces.
240
+ - `wrapLabel` MUST throw on a single part longer than `maxChars` or more than
241
+ `maxLines` lines (`runtime/wrap.mjs:24,33-35`) — a long translation fails
242
+ the check instead of spilling out. [throws]
243
+ - Budgets use 0.56 × font size per character (`runtime/types/sequence.mjs:33`,
244
+ `runtime/types/hub-spoke.mjs:31`, `runtime/wrap.mjs:40-42`). Layouts SHOULD
245
+ budget for Dutch/German being ~30 % longer than English.
246
+ - Any string MAY be localized: `{en: "…", nl: "…"}`. `localize(value, locale)`
247
+ returns the plain string, the requested locale, else the first value, else ""
248
+ (`runtime/scene.mjs:33-40`).
249
+ - Labels are labels; sentences go in `detail`. Font size MUST NOT go below
250
+ 14 px at 1× (§3).
251
+ - Every shipped locale × format MUST pass the gate. `check` derives locales
252
+ from a `.json` spec's localized objects (keys `xx` or `xx-YY`)
253
+ (`cli/motion-kit.mjs:89,209-220`); see §12 D3 for modules.
254
+
255
+ ## 8. Steps and settled frames
256
+
257
+ - `steps[i].at` is the time step *i* is fully shown; its frame is what a slide,
258
+ a step button and Slidev show.
259
+ - Step frames MUST be settled: nothing moves at `at` [gate] G6
260
+ (`frame(at − 1 ms) === frame(at)`, `lib/check.mjs:55-58`).
261
+ - Authoring rule: the next motion MUST NOT start before `at`, and anything that
262
+ fades out by a step (a travelling dot) MUST reach 0 by `at`. Scene types
263
+ satisfy this by construction: `PERIOD ≥ HOP + FILL`
264
+ (`runtime/types/sequence.mjs:24-29`), step = fill end
265
+ (`runtime/types/sequence.mjs:147`, `runtime/types/hub-spoke.mjs:149`).
266
+ Springs and split edges MUST budget their settle time and lag (§4.3, §4.5).
267
+ - The step shown at `t` is the last step with `at ≤ t` (tolerance 1e-9), or
268
+ −1 before the first (`runtime/scene.mjs:93-99`).
269
+ - Unless `stepLabelsInFrame === false`, every word of every step label MUST be
270
+ visible in the final frame [gate] G10.
271
+ - Timeline constants SHOULD be named and every event derived from them
272
+ (pattern in [`technique.md` §3](../../skills/animated-diagram/references/technique.md)).
273
+
274
+ ## 9. Scene types
275
+
276
+ Registered types: `sequence` (2–12 nodes) and `hub-spoke` (2–10 spokes)
277
+ (`runtime/types/index.mjs:14-17`). Fields and storyboards:
278
+ [`scene-types.md`](../../skills/animated-diagram/references/scene-types.md).
279
+ Normative points:
280
+
281
+ - Out-of-range node/spoke counts, a missing hub and an unknown type MUST throw
282
+ (`runtime/types/sequence.mjs:123`, `runtime/types/hub-spoke.mjs:89-90`,
283
+ `runtime/types/index.mjs:21`).
284
+ - A new type MUST export `(spec, {format, locale}) → scene`, be registered in
285
+ `SCENE_TYPES`, and get a gate run across every format and locale
286
+ (`AGENTS.md:59-61`). A custom shape SHOULD be promoted to a type once used twice.
287
+
288
+ ## 10. Render targets
289
+
290
+ ### 10.1 `renderSvg(scene, t, options)` (`runtime/scene.mjs:68-85`)
291
+
292
+ Every target goes through this one function. It MUST emit `<svg>` with
293
+ `viewBox`, `role="img"`, `aria-labelledby` pointing at `<title>` and `<desc>`
294
+ (ids prefixed by `idPrefix ?? scene.id`), and the style's font.
295
+
296
+ | Option | Effect |
297
+ |---|---|
298
+ | `standalone` | Writes `width`/`height` (× `scale`) and resolves tokens to literals. |
299
+ | `theme` | `light`/`dark` for resolution or inline vars. |
300
+ | `live` | Omits inline vars; the container supplies them. |
301
+ | `background` | Paints a full-size `bg` rect behind the diagram. |
302
+ | `idPrefix` | MUST be unique per page when several diagrams share it. |
303
+
304
+ ### 10.2 Live player (`runtime/player.mjs`)
305
+
306
+ | Requirement | Source |
307
+ |---|---|
308
+ | 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; a server/no-JS fallback SHOULD put the final frame in the container. | `runtime/player.mjs` (initial-state block), `lib/build.mjs:25`, `adapters/astro/AnimatedDiagram.astro:31` |
310
+ | Autoplay `visible` (default): plays once from 0 when ≥ 40 % in view, then holds; `none` disables. MUST NOT loop. | `runtime/player.mjs` (`autoplay`, `autoplayPending`) |
311
+ | Play/pause MUST always be present when motion can play (WCAG 2.2.2); label shows Play/Pause/Replay. | `runtime/player.mjs` (`playBtn`, `draw`) |
312
+ | 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
+ | Optional range scrubber (`aria-label`, default "Timeline"); input pauses and seeks. | `runtime/player.mjs` (`options.scrubber`) |
314
+ | 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` (`stage.tabIndex`, `keydown` handler) |
316
+ | Visible focus style for every control. | `runtime/player.mjs` (`.mk-btn:focus-visible` rule) |
317
+ | `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
+ | `playToStep(i)` 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. Indices are zero-based; invalid indices throw `RangeError`. Retargeting replaces the target; `play()` continues to duration; `seek(t)` cancels playback. | `runtime/player.mjs`, `test/player.test.mjs` |
320
+ | `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
+ | **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
+
323
+ UI strings MAY be localized via `options.labels`.
324
+
325
+ ### 10.2.1 Custom element (`adapters/element/motion-diagram.mjs`)
326
+
327
+ - Vendoring with `--adapter element` MUST copy an unbuilt module importing the
328
+ adjacent vendored runtime. Importing it in a browser defines `<motion-diagram>`.
329
+ - The spec MUST come from the `spec` JSON attribute, a child
330
+ `script[type="application/json"]`, or a `src` URL, in that order. URLs resolve
331
+ against the document base URI. `format` and `locale` select the scene;
332
+ `theme` and JSON `style-spec` configure the player; HTML `style` remains CSS.
333
+ - Supplied final-frame child markup MUST remain visible without JavaScript,
334
+ while loading and on errors. Only a successful mount hides the fallback.
335
+ - `controller` MUST expose the mounted player, or be null when unmounted.
336
+ `motion-ready` carries `detail.controller`; `motion-error` carries `detail.error`.
337
+ - Observed attribute changes MUST remount. Disconnection MUST abort loading,
338
+ destroy the player and restore the fallback; reconnection mounts afresh.
339
+ Superseded asynchronous loads MUST NOT mount or publish errors.
340
+
341
+ ### 10.3 Self-contained HTML (`motion-kit build`, `lib/build.mjs`)
342
+
343
+ - MUST be one document with the runtime inlined by `lib/bundle.mjs`, no
344
+ external scripts, stylesheets or fetches (`test/cli.test.mjs:31-37`), so it
345
+ works under `connect-src 'none'` and from `file://`.
346
+ - MUST pre-render the final frame (`lib/build.mjs:25`) and set `<html lang>`
347
+ to the scene locale (`:31-33`).
348
+ - The CLI MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:112-113`)
349
+ and bundled code containing `</script>` (`:115`).
350
+ - The inlined runtime MUST render the same bytes as Node
351
+ (`test/runtime.test.mjs:150-160`).
352
+
353
+ ### 10.4 Baked SVG (`motion-kit bake`, `runtime/bake.mjs`)
354
+
355
+ - MUST contain no JavaScript.
356
+ - Sample at `fps` (default 15) for `f = 0…⌈duration·fps⌉`, `t = min(f/fps, duration)`
357
+ (`runtime/bake.mjs:18-23`); render standalone (tokens resolved); merge
358
+ identical consecutive frames (`:25-27`); each slice lasts until the next one
359
+ starts (`:30`).
360
+ - Each slice is a `<g class="mk-f">` made visible by a `steps(1,end)` CSS
361
+ animation delayed `0.3 s + start`; the last slice holds (`mk-hold`, fill
362
+ forwards) (`:35-47`). Plays once; MUST hold the final frame.
363
+ - Under `prefers-reduced-motion: reduce` only the final slice is visible (`:39`).
364
+ - One theme per file; for theme-following embeds publish a light and dark file
365
+ (`README.md:21-29`, `scripts/render-media.sh`).
366
+ - Size grows with fps × duration; README use SHOULD lower fps to 10–12.
367
+
368
+ ### 10.5 Step export (`motion-kit export`, `lib/export.mjs`)
369
+
370
+ - MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:125-126`).
371
+ - One standalone SVG per step at exactly `steps[i].at`, named
372
+ `NN-<slug(label)>.svg` (`lib/export.mjs:54-57`); tokens resolved
373
+ (`test/cli.test.mjs:26`); same viewBox for every frame so slides register.
374
+ - `--png`: PNG per frame at `--scale` (default 2) via resvg, else headless
375
+ Chrome; fails up front without a rasterizer (`cli/motion-kit.mjs:127`,
376
+ `lib/raster.mjs:39-64`). `--theme dark` resolves dark tokens; `--background`
377
+ makes the canvas opaque (transparent by default).
378
+ - `--qc`: frames at `max(0, at − 0.2)` and `at + 0.2` (not after the last step)
379
+ under `qc/` (`lib/export.mjs:58-65`).
380
+ - `index.html` contact sheet: steps, QC row, a 360 px phone row and the human
381
+ review checklist (`lib/export.mjs:93-108`).
382
+ - `manifest.json` MUST contain no timestamps: tool, version, scene, type,
383
+ format, locale, size, duration, style, theme, a 16-hex input hash
384
+ (source file + style), source commit, render settings, file list
385
+ (`lib/export.mjs:66-88`). Two exports of the same inputs MUST be equal
386
+ (`test/cli.test.mjs:20-30`).
387
+
388
+ ### 10.6 Video (`motion-kit video`, `lib/video.mjs`)
389
+
390
+ - Frame `f` maps to `t = clamp(f/fps − lead, 0, duration)`; total frames
391
+ `round((lead + duration + hold)·fps)`; defaults fps 30, scale 2, hold 1.5 s,
392
+ lead 0.25 s (`lib/video.mjs:32-36,45`).
393
+ - Each frame: standalone SVG with opaque background → PNG → ffmpeg stdin; no
394
+ per-frame files; a repeated `t` reuses the previous PNG (`:44-51`).
395
+ - Encoders by extension (`:18-24`): MP4 `libx264 -preset slow -crf 18
396
+ -pix_fmt yuv420p -movflags +faststart`, padded to even dimensions; WebM
397
+ `libvpx-vp9 -crf 32`; GIF two-pass palette, ≤ 20 fps, Bayer dither, loops.
398
+ - Missing `ffmpeg` MUST fail with an install hint (`:31`). Output is silent.
399
+ - Same inputs ⇒ same frames; encoded bytes are only stable per machine/ffmpeg
400
+ version.
401
+
402
+ ### 10.7 Adapters and vendoring
403
+
404
+ - **Slidev** (`adapters/slidev/AnimatedDiagram.vue`): registers `N − 1` clicks
405
+ itself (`:67-72`); forward by one click animates from the previous step's
406
+ `at` to the next, any other move seeks (`:93-100`); print/export, overview
407
+ and reduced motion show the settled step frame (`:65`).
408
+ - **Astro** (`adapters/astro/AnimatedDiagram.astro`): server-renders the final
409
+ frame and mounts the player; props MUST be serializable (a spec, not a scene).
410
+ - **Vendor** (`cli/motion-kit.mjs`, `vendor` command): copies `runtime/`, one
411
+ adapter, `lib/check.mjs` and the full MIT `LICENSE`; writes a spec-only gate
412
+ script and `MOTION_KIT_VERSION`. Consumers MUST retain `LICENSE` and the
413
+ SPDX headers when redistributing vendored files. Vendored files MUST NOT
414
+ be edited in the consumer.
415
+
416
+ ## 11. The gate
417
+
418
+ `checkScene(scene)` (`lib/check.mjs:33-84`) samples 121 evenly spaced times
419
+ (`SAMPLES = 120`, `:9`) and stops collecting after 13 problems (`:51`).
420
+ `motion-kit check` runs it for every file × format (all six unless `--format`)
421
+ × locale (§7) and adds the style contrast check; it exits 1 on any failure or
422
+ construction error (`cli/motion-kit.mjs:81-108`). `npm run gate` = unit tests +
423
+ `check` over `examples/` and `brand/` (`package.json:15-18`).
424
+
425
+ | ID | Rule | Code | Rationale |
426
+ |---|---|---|---|
427
+ | 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
+ | 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
+ | G3 | No number with ≥ 5 decimals in the full SVG. | `:45-46` | Rounding (T4). |
430
+ | G4 | No `#hex`, `rgb(a)(`, `hsl(a)(` in `frame()` output. | `:47-49` | Token-only colours: themes and brand styles must work everywhere. |
431
+ | G5 | No `NaN`, `undefined`, `Infinity` in `frame()` output. | `:50` | Silent geometry bugs. |
432
+ | G6 | `render(at − 0.001) === render(at)` for every step. | `:55-58` | Settled step frames (§8). |
433
+ | G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
434
+ | G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
435
+ | G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
436
+ | 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`. | `:80-81` | T1. Textual heuristic: helpers defined outside `frame` are not scanned. |
438
+ | G12 | Style passes WCAG contrast in both themes. | `cli/motion-kit.mjs:83-85`, `runtime/style.mjs:114-134` | Legibility in light and dark. |
439
+ | G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `cli/motion-kit.mjs:92-103` | Reject, don't invent: a broken picture never renders. |
440
+
441
+ The gate checks structure, not looks. Visual review (before/after frames,
442
+ phone size, real-time playback, dark mode) is required by
443
+ [`qc.md`](../../skills/animated-diagram/references/qc.md), and a human signs
444
+ off.
445
+
446
+ ## 12. Discrepancies
447
+
448
+ Recorded, not resolved. Each needs an owner decision.
449
+
450
+ | # | Topic | Code says | Docs say |
451
+ |---|---|---|---|
452
+ | D1 | Duration budget | Gate fails only above **12 s** (`lib/check.mjs:68`). | "≤ ~8–10 s" (`README.md:98`, `AGENTS.md:47`); "≤ ~8 s" (`skills/animated-diagram/SKILL.md:50`, `motion-vocabulary.md:21`). |
453
+ | D2 | Exporters refuse failing scenes | Only `build` and `export` run the gate; `bake` and `video` render any loadable scene (`cli/motion-kit.mjs:132-157`). | "Exporters refuse scenes that fail the gate" (`skills/motion-render/SKILL.md:17`). |
454
+ | 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
+ | 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
+ | 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 (no cross-call state detection; source scan limited to `frame`'s own text); 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
+ | 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
+ | 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
+ | 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 appends a random suffix (`adapters/astro/AnimatedDiagram.astro:51`); the Slidev adapter exposes none. | `window.__motionKit[sceneId]` / `[id]` (`adapters/page/README.md:22`, `interactivity.md:14-15`). |
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`). |
463
+ | 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
+ | 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 style only, 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`). |
@@ -0,0 +1,18 @@
1
+ {
2
+ "type": "sequence",
3
+ "id": "agent-loop",
4
+ "title": { "en": "An agent goes from brief to checked diagram", "nl": "Een agent gaat van opdracht naar gecontroleerd diagram" },
5
+ "description": {
6
+ "en": "Six steps: you brief, the agent storyboards, writes a spec, runs the gate, renders and you sign off.",
7
+ "nl": "Zes stappen: jij geeft de opdracht, de agent maakt een storyboard, schrijft een spec, draait de poort, rendert en jij tekent af."
8
+ },
9
+ "nodes": [
10
+ { "label": { "en": "Brief", "nl": "Opdracht" }, "detail": { "en": "You explain what the diagram must say, in plain language.", "nl": "Jij legt in gewone taal uit wat het diagram moet zeggen." } },
11
+ { "label": { "en": "Storyboard", "nl": "Storyboard" }, "detail": { "en": "The agent proposes the steps; you approve the story before anything is drawn.", "nl": "De agent stelt de stappen voor; jij keurt het verhaal goed voordat er iets getekend wordt." } },
12
+ { "label": { "en": "Spec", "nl": "Spec" }, "detail": { "en": "A spec is written: data, not animation code.", "nl": "Er wordt een spec geschreven: data, geen animatiecode." } },
13
+ { "label": { "en": "Gate", "nl": "Poort" }, "detail": { "en": "The gate runs for every format and locale; the agent fixes what it reports.", "nl": "De poort draait voor elk formaat en elke taal; de agent herstelt wat gemeld wordt." } },
14
+ { "label": { "en": "Render", "nl": "Renderen" }, "detail": { "en": "Step frames, a review sheet and a baked SVG are rendered.", "nl": "Stapframes, een controleblad en een gebakken SVG worden gerenderd." } },
15
+ { "label": { "en": "Sign-off", "nl": "Akkoord" }, "detail": { "en": "You review light, dark and phone width, and sign off.", "nl": "Jij bekijkt licht, donker en telefoonbreedte, en tekent af." } }
16
+ ],
17
+ "glyphs": "numbers"
18
+ }
@@ -0,0 +1,141 @@
1
+ /**
2
+ * Example custom scene: a request travelling Client → API → Database and back.
3
+ *
4
+ * Shows the escape hatch for diagrams no scene type covers, and exercises the
5
+ * derived motion helpers: a packet that stretches in flight (split edges) along
6
+ * curved links (arc-length lookup), and a retargetable spring for the response
7
+ * counter bar. Pure: frame(t) depends only on t and constants.
8
+ */
9
+ import { easeOut, easeStandard, progress, splitEdge, springTo } from "../runtime/motion.mjs";
10
+ import { FORMATS, localize } from "../runtime/scene.mjs";
11
+ import { tok } from "../runtime/style.mjs";
12
+ import { cubic, drawOn, el, fade, num, text } from "../runtime/svg.mjs";
13
+ import { wrapLabel } from "../runtime/wrap.mjs";
14
+
15
+ const COPY = {
16
+ title: { en: "A request, there and back", nl: "Een verzoek, heen en terug" },
17
+ description: {
18
+ en: "The client asks the API, the API reads the database, and the answer travels back.",
19
+ nl: "De client vraagt de API, de API leest de database en het antwoord gaat terug.",
20
+ },
21
+ nodes: [
22
+ { en: "Client", nl: "Client" },
23
+ { en: "API", nl: "API" },
24
+ { en: "Database", nl: "Database" },
25
+ ],
26
+ steps: [
27
+ { label: { en: "Request sent", nl: "Verzoek verstuurd" }, detail: { en: "The client calls the API.", nl: "De client roept de API aan." } },
28
+ { label: { en: "Data read", nl: "Gegevens gelezen" }, detail: { en: "The API queries the database.", nl: "De API bevraagt de database." } },
29
+ { label: { en: "Answer returned", nl: "Antwoord terug" }, detail: { en: "The response travels back to the client.", nl: "Het antwoord gaat terug naar de client." } },
30
+ ],
31
+ };
32
+
33
+ const ENTER = 0.4;
34
+ const GAP = 0.12;
35
+ const TRAVEL = 0.7;
36
+ const FILL = 0.25;
37
+
38
+ export default function make({ format = "16:9", locale = "en" } = {}) {
39
+ const f = FORMATS[format];
40
+ if (!f) throw new Error(`unknown format "${format}"`);
41
+ const W = f.width;
42
+ const H = f.height || (format === "tall" ? 560 : 300);
43
+ const horizontal = W / H >= 1;
44
+ const boxW = horizontal ? Math.min(180, W / 5) : Math.min(220, W - 80);
45
+ const boxH = 56;
46
+ const fs = 17;
47
+ const centers = [0, 1, 2].map((i) =>
48
+ horizontal ? { x: W * (0.18 + 0.32 * i), y: H / 2 } : { x: W / 2, y: H * (0.18 + 0.32 * i) },
49
+ );
50
+ const labels = COPY.nodes.map((n) => wrapLabel(localize(n, locale), Math.floor((boxW - 16) / (fs * 0.56)), 1));
51
+ // Curved links bow out (forward) and back (return) so they don't overlap.
52
+ const link = (a, b, bow) => {
53
+ // Leave from the side of `a` that faces `b`, arrive at the side of `b` that faces `a`.
54
+ const sx = Math.sign(b.x - a.x) || 1;
55
+ const sy = Math.sign(b.y - a.y) || 1;
56
+ const ax = horizontal ? a.x + sx * (boxW / 2 + 6) : a.x;
57
+ const ay = horizontal ? a.y : a.y + sy * (boxH / 2 + 6);
58
+ const bx = horizontal ? b.x - sx * (boxW / 2 + 6) : b.x;
59
+ const by = horizontal ? b.y : b.y - sy * (boxH / 2 + 6);
60
+ return horizontal
61
+ ? cubic({ x: ax, y: ay }, { x: ax + sx * 40, y: ay + bow }, { x: bx - sx * 40, y: by + bow }, { x: bx, y: by })
62
+ : cubic({ x: ax, y: ay }, { x: ax + bow, y: ay + sy * 40 }, { x: bx + bow, y: by - sy * 40 }, { x: bx, y: by });
63
+ };
64
+ const fwd = [link(centers[0], centers[1], -44), link(centers[1], centers[2], -44)];
65
+ const back = [link(centers[1], centers[0], 44), link(centers[2], centers[1], 44)];
66
+ const legs = [fwd[0], fwd[1], back[1], back[0]];
67
+
68
+ const T0 = ENTER + 2 * GAP + 0.15;
69
+ // Beats never overlap: a leg starts only after the previous arrival has
70
+ // filled and the packet's trailing edge has landed (settled step frames).
71
+ const LAG = 0.09;
72
+ const BEAT = TRAVEL + LAG + FILL + 0.05;
73
+ const legStart = (i) => T0 + i * BEAT;
74
+ const arrive = (i) => legStart(i) + TRAVEL + LAG;
75
+ const activeAt = [T0, arrive(0), arrive(1)];
76
+ const steps = [
77
+ { at: arrive(0) + FILL, ...COPY.steps[0] },
78
+ { at: arrive(1) + FILL, ...COPY.steps[1] },
79
+ { at: arrive(3) + 0.05, ...COPY.steps[2] },
80
+ ];
81
+ const duration = steps[2].at + 0.4;
82
+ // Progress bar: a critically damped spring retargeted at each leg; ω = 14
83
+ // settles in 9.24/14 ≈ 0.66 s, before each step's time.
84
+ const OMEGA = 14;
85
+ const bar = (t) => springTo(t, 0, [{ at: legStart(0), to: 0.33 }, { at: legStart(1), to: 0.66 }, { at: legStart(3), to: 1 }], OMEGA);
86
+
87
+ function frame(t) {
88
+ const out = [];
89
+ legs.forEach((leg, i) => {
90
+ const shown = progress(t, GAP * Math.min(i, 2), ENTER, easeOut);
91
+ if (shown > 0) out.push(el("path", { d: leg.d, fill: "none", stroke: tok("line"), "stroke-width": 2, "stroke-dasharray": "4 6", opacity: shown }));
92
+ const dash = drawOn(leg.length, progress(t, legStart(i), TRAVEL, easeStandard));
93
+ if (dash) out.push(el("path", { d: leg.d, fill: "none", stroke: tok("accent"), "stroke-width": 3, "stroke-linecap": "round", ...dash }));
94
+ });
95
+ centers.forEach((c, i) => {
96
+ const enter = progress(t, i * GAP, ENTER, easeOut);
97
+ const on = progress(t, activeAt[i], FILL, easeStandard);
98
+ const box = (fill, stroke, ink) =>
99
+ el(
100
+ "g",
101
+ {},
102
+ el("rect", { x: c.x - boxW / 2, y: c.y - boxH / 2, width: boxW, height: boxH, rx: 10, fill, stroke, "stroke-width": 2 }),
103
+ text({ x: c.x, y: c.y, "text-anchor": "middle", "dominant-baseline": "central", "font-size": fs, "font-weight": 600, fill: ink }, labels[i]),
104
+ );
105
+ out.push(
106
+ fade(enter, {}, fade(1 - on, {}, box(tok("surface"), tok("line"), tok("ink"))), fade(on, {}, box(tok("accent"), tok("accent"), tok("onAccent")))),
107
+ );
108
+ });
109
+ // The packet: a capsule from the trailing to the leading edge (split edges).
110
+ legs.forEach((leg, i) => {
111
+ const { lead, trail } = splitEdge(t, legStart(i), TRAVEL, LAG);
112
+ if (lead <= 0 || trail >= 1) return;
113
+ const a = leg.at(trail);
114
+ const b = leg.at(lead);
115
+ out.push(el("line", { x1: a.x, y1: a.y, x2: b.x, y2: b.y, stroke: tok("emphasis"), "stroke-width": 10, "stroke-linecap": "round" }));
116
+ });
117
+ const p = bar(t);
118
+ if (p > 0.0005) {
119
+ const bw = horizontal ? W * 0.5 : W * 0.7;
120
+ const x = (W - bw) / 2;
121
+ const y = H - 28;
122
+ out.push(el("rect", { x, y, width: bw, height: 6, rx: 3, fill: tok("surface") }));
123
+ out.push(el("rect", { x, y, width: num(bw * p), height: 6, rx: 3, fill: tok("accent") }));
124
+ }
125
+ return out.join("");
126
+ }
127
+
128
+ return {
129
+ id: `request-roundtrip-${format.replace(":", "x")}`,
130
+ width: W,
131
+ height: H,
132
+ duration,
133
+ title: localize(COPY.title, locale),
134
+ description: localize(COPY.description, locale),
135
+ // Steps here are events, not nodes: their labels live in the player's
136
+ // step buttons and captions, not in the drawing.
137
+ stepLabelsInFrame: false,
138
+ steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
139
+ frame,
140
+ };
141
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "type": "hub-spoke",
3
+ "id": "integrations",
4
+ "title": { "en": "One platform, many integrations", "nl": "Eén platform, veel koppelingen" },
5
+ "description": {
6
+ "en": "A platform connects to seven tools, one link at a time.",
7
+ "nl": "Een platform koppelt met zeven tools, één koppeling tegelijk."
8
+ },
9
+ "hub": { "label": { "en": "Platform", "nl": "Platform" }, "detail": { "en": "One place that every tool plugs into.", "nl": "Eén plek waar elke tool op aansluit." } },
10
+ "spokes": [
11
+ { "label": { "en": "Slack", "nl": "Slack" }, "detail": { "en": "Alerts arrive where the team already talks.", "nl": "Meldingen komen aan waar het team al praat." } },
12
+ { "label": { "en": "GitHub", "nl": "GitHub" }, "detail": { "en": "Pull requests start and report builds.", "nl": "Pull requests starten en melden builds." } },
13
+ { "label": { "en": "Jira", "nl": "Jira" }, "detail": { "en": "Tickets update themselves.", "nl": "Tickets werken zichzelf bij." } },
14
+ { "label": { "en": "Email", "nl": "E-mail" }, "detail": { "en": "Digests go to people who are not in the tool.", "nl": "Samenvattingen gaan naar mensen die de tool niet gebruiken." } },
15
+ { "label": { "en": "Calendar", "nl": "Agenda" }, "detail": { "en": "Deadlines appear as events.", "nl": "Deadlines verschijnen als afspraken." } },
16
+ { "label": { "en": "Drive", "nl": "Drive" }, "detail": { "en": "Files stay in one shared place.", "nl": "Bestanden blijven op één gedeelde plek." } },
17
+ { "label": { "en": "Webhooks", "nl": "Webhooks" }, "detail": { "en": "Anything else can listen in.", "nl": "Al het andere kan meeluisteren." } }
18
+ ],
19
+ "direction": "out"
20
+ }