@liqweed/motion-kit 0.0.0-stage → 0.2.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 +13 -0
- package/.claude-plugin/plugin.json +9 -0
- package/LICENSE +21 -0
- package/README.md +119 -2
- package/adapters/astro/AnimatedDiagram.astro +55 -0
- package/adapters/page/README.md +22 -0
- package/adapters/slidev/AnimatedDiagram.vue +137 -0
- package/brand/logo.scene.mjs +115 -0
- package/cli/motion-kit.mjs +239 -0
- package/docs/spec/technique.md +447 -0
- package/examples/agent-loop.json +18 -0
- package/examples/custom-pulse.scene.mjs +141 -0
- package/examples/integrations.json +20 -0
- package/examples/order-flow.json +17 -0
- package/examples/release-pipeline.json +17 -0
- package/examples/smart-home.json +17 -0
- package/lib/build.mjs +62 -0
- package/lib/bundle.mjs +68 -0
- package/lib/check.mjs +86 -0
- package/lib/export.mjs +113 -0
- package/lib/icon.mjs +41 -0
- package/lib/load.mjs +53 -0
- package/lib/raster.mjs +69 -0
- package/lib/video.mjs +77 -0
- package/package.json +69 -5
- package/runtime/bake.mjs +61 -0
- package/runtime/motion.mjs +154 -0
- package/runtime/parts.mjs +123 -0
- package/runtime/player.mjs +207 -0
- package/runtime/scene.mjs +101 -0
- package/runtime/style.mjs +142 -0
- package/runtime/svg.mjs +165 -0
- package/runtime/types/hub-spoke.mjs +215 -0
- package/runtime/types/index.mjs +25 -0
- package/runtime/types/sequence.mjs +201 -0
- package/runtime/wrap.mjs +44 -0
- package/skills/animated-diagram/SKILL.md +90 -0
- package/skills/animated-diagram/references/custom-scenes.md +56 -0
- package/skills/animated-diagram/references/ecosystem.md +28 -0
- package/skills/animated-diagram/references/interactivity.md +38 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +70 -0
- package/skills/animated-diagram/references/qc.md +41 -0
- package/skills/animated-diagram/references/scene-types.md +59 -0
- package/skills/animated-diagram/references/styles.md +55 -0
- package/skills/animated-diagram/references/targets.md +27 -0
- package/skills/animated-diagram/references/technique.md +148 -0
- package/skills/motion-render/SKILL.md +68 -0
- package/skills/motion-render/references/formats.md +18 -0
- package/skills/motion-render/references/slides.md +18 -0
- package/skills/motion-render/references/video.md +61 -0
- package/skills/project-logo/SKILL.md +72 -0
- package/skills/project-logo/references/design.md +22 -0
- package/skills/project-logo/references/discovery.md +15 -0
- package/skills/project-logo/references/external-prompt.md +23 -0
- package/styles/neutral.json +26 -0
|
@@ -0,0 +1,447 @@
|
|
|
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:15,135-149`, `AGENTS.md:31` |
|
|
309
|
+
| Initial state MUST be the final frame; a server/no-JS fallback SHOULD put the final frame in the container. | `:172`, `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. | `:173-191` |
|
|
311
|
+
| Play/pause MUST always be present when motion can play (WCAG 2.2.2); label shows Play/Pause/Replay. | `:69-75,129` |
|
|
312
|
+
| One `<button>` per step, labelled `N. label`; activating it pauses and jumps (no animation); `aria-current="step"` marks the active step. | `:76-87,126` |
|
|
313
|
+
| Optional range scrubber (`aria-label`, default "Timeline"); input pauses and seeks. | `:88-102` |
|
|
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. | `:103-115` |
|
|
315
|
+
| Keyboard on the focusable stage: ←/→ step, Home/End first/last, Space play/pause. | `:59,156-165` |
|
|
316
|
+
| Visible focus style for every control. | `:26` |
|
|
317
|
+
| `prefers-reduced-motion: reduce`: final frame, no autoplay, no play button, Space ignored. | `:38,70,142,162,174` |
|
|
318
|
+
| Theme: `options.theme`, else follows `prefers-color-scheme` live. | `:50-54,192-194` |
|
|
319
|
+
| **Capture hook**: the controller `{seek, play, pause, seekStep, time, scene}` MUST be exposed at `globalThis.__motionKit[options.id ?? scene.id]`. | `:196-200` |
|
|
320
|
+
|
|
321
|
+
UI strings MAY be localized via `options.labels`.
|
|
322
|
+
|
|
323
|
+
### 10.3 Self-contained HTML (`motion-kit build`, `lib/build.mjs`)
|
|
324
|
+
|
|
325
|
+
- MUST be one document with the runtime inlined by `lib/bundle.mjs`, no
|
|
326
|
+
external scripts, stylesheets or fetches (`test/cli.test.mjs:31-37`), so it
|
|
327
|
+
works under `connect-src 'none'` and from `file://`.
|
|
328
|
+
- MUST pre-render the final frame (`lib/build.mjs:25`) and set `<html lang>`
|
|
329
|
+
to the scene locale (`:31-33`).
|
|
330
|
+
- The CLI MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:112-113`)
|
|
331
|
+
and bundled code containing `</script>` (`:115`).
|
|
332
|
+
- The inlined runtime MUST render the same bytes as Node
|
|
333
|
+
(`test/runtime.test.mjs:150-160`).
|
|
334
|
+
|
|
335
|
+
### 10.4 Baked SVG (`motion-kit bake`, `runtime/bake.mjs`)
|
|
336
|
+
|
|
337
|
+
- MUST contain no JavaScript.
|
|
338
|
+
- Sample at `fps` (default 15) for `f = 0…⌈duration·fps⌉`, `t = min(f/fps, duration)`
|
|
339
|
+
(`runtime/bake.mjs:18-23`); render standalone (tokens resolved); merge
|
|
340
|
+
identical consecutive frames (`:25-27`); each slice lasts until the next one
|
|
341
|
+
starts (`:30`).
|
|
342
|
+
- Each slice is a `<g class="mk-f">` made visible by a `steps(1,end)` CSS
|
|
343
|
+
animation delayed `0.3 s + start`; the last slice holds (`mk-hold`, fill
|
|
344
|
+
forwards) (`:35-47`). Plays once; MUST hold the final frame.
|
|
345
|
+
- Under `prefers-reduced-motion: reduce` only the final slice is visible (`:39`).
|
|
346
|
+
- One theme per file; for theme-following embeds publish a light and dark file
|
|
347
|
+
(`README.md:21-29`, `scripts/render-media.sh`).
|
|
348
|
+
- Size grows with fps × duration; README use SHOULD lower fps to 10–12.
|
|
349
|
+
|
|
350
|
+
### 10.5 Step export (`motion-kit export`, `lib/export.mjs`)
|
|
351
|
+
|
|
352
|
+
- MUST refuse a scene that fails the gate (`cli/motion-kit.mjs:125-126`).
|
|
353
|
+
- One standalone SVG per step at exactly `steps[i].at`, named
|
|
354
|
+
`NN-<slug(label)>.svg` (`lib/export.mjs:54-57`); tokens resolved
|
|
355
|
+
(`test/cli.test.mjs:26`); same viewBox for every frame so slides register.
|
|
356
|
+
- `--png`: PNG per frame at `--scale` (default 2) via resvg, else headless
|
|
357
|
+
Chrome; fails up front without a rasterizer (`cli/motion-kit.mjs:127`,
|
|
358
|
+
`lib/raster.mjs:39-64`). `--theme dark` resolves dark tokens; `--background`
|
|
359
|
+
makes the canvas opaque (transparent by default).
|
|
360
|
+
- `--qc`: frames at `max(0, at − 0.2)` and `at + 0.2` (not after the last step)
|
|
361
|
+
under `qc/` (`lib/export.mjs:58-65`).
|
|
362
|
+
- `index.html` contact sheet: steps, QC row, a 360 px phone row and the human
|
|
363
|
+
review checklist (`lib/export.mjs:93-108`).
|
|
364
|
+
- `manifest.json` MUST contain no timestamps: tool, version, scene, type,
|
|
365
|
+
format, locale, size, duration, style, theme, a 16-hex input hash
|
|
366
|
+
(source file + style), source commit, render settings, file list
|
|
367
|
+
(`lib/export.mjs:66-88`). Two exports of the same inputs MUST be equal
|
|
368
|
+
(`test/cli.test.mjs:20-30`).
|
|
369
|
+
|
|
370
|
+
### 10.6 Video (`motion-kit video`, `lib/video.mjs`)
|
|
371
|
+
|
|
372
|
+
- Frame `f` maps to `t = clamp(f/fps − lead, 0, duration)`; total frames
|
|
373
|
+
`round((lead + duration + hold)·fps)`; defaults fps 30, scale 2, hold 1.5 s,
|
|
374
|
+
lead 0.25 s (`lib/video.mjs:32-36,45`).
|
|
375
|
+
- Each frame: standalone SVG with opaque background → PNG → ffmpeg stdin; no
|
|
376
|
+
per-frame files; a repeated `t` reuses the previous PNG (`:44-51`).
|
|
377
|
+
- Encoders by extension (`:18-24`): MP4 `libx264 -preset slow -crf 18
|
|
378
|
+
-pix_fmt yuv420p -movflags +faststart`, padded to even dimensions; WebM
|
|
379
|
+
`libvpx-vp9 -crf 32`; GIF two-pass palette, ≤ 20 fps, Bayer dither, loops.
|
|
380
|
+
- Missing `ffmpeg` MUST fail with an install hint (`:31`). Output is silent.
|
|
381
|
+
- Same inputs ⇒ same frames; encoded bytes are only stable per machine/ffmpeg
|
|
382
|
+
version.
|
|
383
|
+
|
|
384
|
+
### 10.7 Adapters and vendoring
|
|
385
|
+
|
|
386
|
+
- **Slidev** (`adapters/slidev/AnimatedDiagram.vue`): registers `N − 1` clicks
|
|
387
|
+
itself (`:67-72`); forward by one click animates from the previous step's
|
|
388
|
+
`at` to the next, any other move seeks (`:93-100`); print/export, overview
|
|
389
|
+
and reduced motion show the settled step frame (`:65`).
|
|
390
|
+
- **Astro** (`adapters/astro/AnimatedDiagram.astro`): server-renders the final
|
|
391
|
+
frame and mounts the player; props MUST be serializable (a spec, not a scene).
|
|
392
|
+
- **Vendor** (`cli/motion-kit.mjs`, `vendor` command): copies `runtime/`, one
|
|
393
|
+
adapter, `lib/check.mjs` and the full MIT `LICENSE`; writes a spec-only gate
|
|
394
|
+
script and `MOTION_KIT_VERSION`. Consumers MUST retain `LICENSE` and the
|
|
395
|
+
SPDX headers when redistributing vendored files. Vendored files MUST NOT
|
|
396
|
+
be edited in the consumer.
|
|
397
|
+
|
|
398
|
+
## 11. The gate
|
|
399
|
+
|
|
400
|
+
`checkScene(scene)` (`lib/check.mjs:33-84`) samples 121 evenly spaced times
|
|
401
|
+
(`SAMPLES = 120`, `:9`) and stops collecting after 13 problems (`:51`).
|
|
402
|
+
`motion-kit check` runs it for every file × format (all six unless `--format`)
|
|
403
|
+
× locale (§7) and adds the style contrast check; it exits 1 on any failure or
|
|
404
|
+
construction error (`cli/motion-kit.mjs:81-108`). `npm run gate` = unit tests +
|
|
405
|
+
`check` over `examples/` and `brand/` (`package.json:15-18`).
|
|
406
|
+
|
|
407
|
+
| ID | Rule | Code | Rationale |
|
|
408
|
+
|---|---|---|---|
|
|
409
|
+
| 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. |
|
|
410
|
+
| 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. |
|
|
411
|
+
| G3 | No number with ≥ 5 decimals in the full SVG. | `:45-46` | Rounding (T4). |
|
|
412
|
+
| G4 | No `#hex`, `rgb(a)(`, `hsl(a)(` in `frame()` output. | `:47-49` | Token-only colours: themes and brand styles must work everywhere. |
|
|
413
|
+
| G5 | No `NaN`, `undefined`, `Infinity` in `frame()` output. | `:50` | Silent geometry bugs. |
|
|
414
|
+
| G6 | `render(at − 0.001) === render(at)` for every step. | `:55-58` | Settled step frames (§8). |
|
|
415
|
+
| G7 | First frame ≠ last frame. | `:61-63` | Something must animate. |
|
|
416
|
+
| G8 | `render(duration + 5) === render(duration)`. | `:65` | Holds the final frame. |
|
|
417
|
+
| G9 | `duration ≤ 12` s. | `:68` | Explainer budget (see §12 D1). |
|
|
418
|
+
| 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. |
|
|
419
|
+
| 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. |
|
|
420
|
+
| G12 | Style passes WCAG contrast in both themes. | `cli/motion-kit.mjs:83-85`, `runtime/style.mjs:114-134` | Legibility in light and dark. |
|
|
421
|
+
| 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. |
|
|
422
|
+
|
|
423
|
+
The gate checks structure, not looks. Visual review (before/after frames,
|
|
424
|
+
phone size, real-time playback, dark mode) is required by
|
|
425
|
+
[`qc.md`](../../skills/animated-diagram/references/qc.md), and a human signs
|
|
426
|
+
off.
|
|
427
|
+
|
|
428
|
+
## 12. Discrepancies
|
|
429
|
+
|
|
430
|
+
Recorded, not resolved. Each needs an owner decision.
|
|
431
|
+
|
|
432
|
+
| # | Topic | Code says | Docs say |
|
|
433
|
+
|---|---|---|---|
|
|
434
|
+
| 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`). |
|
|
435
|
+
| 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`). |
|
|
436
|
+
| 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`). |
|
|
437
|
+
| 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. |
|
|
438
|
+
| 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`. |
|
|
439
|
+
| 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`). |
|
|
440
|
+
| 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`). |
|
|
441
|
+
| 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`). |
|
|
442
|
+
| 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`). |
|
|
443
|
+
| 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`). |
|
|
444
|
+
| 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`). |
|
|
445
|
+
| 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. |
|
|
446
|
+
| 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`). |
|
|
447
|
+
| 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
|
+
}
|