@liqweed/motion-kit 0.4.0 → 0.6.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 (45) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +26 -6
  4. package/adapters/element/README.md +5 -0
  5. package/adapters/page/README.md +10 -0
  6. package/cli/motion-kit.mjs +14 -4
  7. package/docs/spec/technique.md +129 -51
  8. package/examples/checkout.json +104 -0
  9. package/examples/connection.json +80 -0
  10. package/examples/custom-pulse.scene.mjs +5 -0
  11. package/examples/incident.json +18 -0
  12. package/examples/player-states.json +97 -0
  13. package/examples/web-stack.json +17 -0
  14. package/lib/build.mjs +1 -1
  15. package/lib/check.mjs +215 -21
  16. package/lib/export.mjs +116 -7
  17. package/lib/gate.mjs +9 -7
  18. package/lib/load.mjs +15 -0
  19. package/package.json +6 -3
  20. package/runtime/kit.mjs +2 -2
  21. package/runtime/links.mjs +318 -0
  22. package/runtime/parts.mjs +15 -0
  23. package/runtime/patch.mjs +297 -0
  24. package/runtime/player.mjs +45 -2
  25. package/runtime/scene.mjs +24 -9
  26. package/runtime/style.mjs +65 -16
  27. package/runtime/types/hub-spoke.mjs +10 -8
  28. package/runtime/types/index.mjs +7 -0
  29. package/runtime/types/sequence.mjs +10 -8
  30. package/runtime/types/stack.mjs +230 -0
  31. package/runtime/types/timeline.mjs +407 -0
  32. package/runtime/types/walk.mjs +162 -0
  33. package/skills/animated-diagram/SKILL.md +28 -7
  34. package/skills/animated-diagram/references/custom-scenes.md +20 -1
  35. package/skills/animated-diagram/references/interactivity.md +129 -6
  36. package/skills/animated-diagram/references/motion-vocabulary.md +1 -1
  37. package/skills/animated-diagram/references/qc.md +3 -0
  38. package/skills/animated-diagram/references/scene-types.md +100 -4
  39. package/skills/animated-diagram/references/styles.md +55 -6
  40. package/skills/animated-diagram/references/technique.md +15 -6
  41. package/skills/motion-render/SKILL.md +31 -6
  42. package/skills/motion-render/references/formats.md +8 -8
  43. package/skills/motion-render/references/video.md +1 -1
  44. package/skills/project-logo/SKILL.md +15 -4
  45. package/styles/neutral.json +2 -2
@@ -26,6 +26,11 @@
26
26
  scene id plus a counter), so scenes that define ids can share a page.
27
27
  - The stylesheet is added to the document whenever a player mounts and none is
28
28
  there, so a page swap (Astro view transitions) cannot leave players unstyled.
29
+ - Each frame updates the SVG in place (`patchMarkup`, `runtime/patch.mjs`):
30
+ nodes that persist keep their identity and only changed attributes and text
31
+ are written, so hover state survives playback. Page CSS must not put
32
+ transitions or animations on the diagram's SVG: with persistent nodes they
33
+ would run between frames, and exports would no longer match what plays.
29
34
  - Capture hook: `window.__motionKit[id].seek(t)` (for Playwright/HyperFrames-
30
35
  style renderers).
31
36
 
@@ -56,15 +61,115 @@ const go = (c) => c.playToStep("payment");
56
61
  el.controller ? go(el.controller) : el.addEventListener("motion-ready", (e) => go(e.detail.controller), { once: true });
57
62
  ```
58
63
 
64
+ ## Linking the page to the diagram (`runtime/links.mjs`)
65
+
66
+ Two helpers bind a controller to the page around the player. Both are
67
+ dependency-free browser code (no DOM at import), take a step by `id` or index,
68
+ throw `RangeError` for an unknown id when they bind (not when the reader gets
69
+ there), never move focus or layout, and return a `dispose()` that removes
70
+ their listeners, observers and marks. Call it before removing the elements or
71
+ the player (Astro: on `astro:before-swap`).
72
+
73
+ - **Hover/focus linking:** `linkSteps(controller, rootOrElements, options)`.
74
+ Every element with `data-mk-step` under the root (or the elements given)
75
+ selects its step on hover (mouse and pen), keyboard focus (also focus inside
76
+ it) and click; touch selects on tap, so nothing is hover-only. Make terms
77
+ `<button type="button" data-mk-step="payment">` so the keyboard reaches
78
+ them. A selection jumps to the settled step; `animate: true` plays forward
79
+ to a later step, except under reduced motion. The step stays when the
80
+ pointer or focus leaves; `restore: true` turns hover and focus into a
81
+ preview: once neither is on a term, the diagram returns to the frame it
82
+ showed before, and a click keeps its step. The terms of the selected step
83
+ get `aria-current="step"` (`mark: false` to style them yourself);
84
+ `onChange(step, element)` reports each selection (`-1, null` on restore).
85
+ Terms are collected when binding; bind again for terms added later. When
86
+ scroll sections carry `data-mk-step` as well, pass the terms themselves
87
+ rather than a root that contains the sections.
88
+ - **Scroll-driven steps:** `scrollSteps(controller, sections, options)`.
89
+ Each section names its step with `data-mk-step`, else by order (the third
90
+ section shows step 2). The active section is the last one whose top has
91
+ crossed a line across the viewport (`line`, a share of its height from the
92
+ top, default 0.5; `root` for a scrolling container), found with an
93
+ IntersectionObserver whose root ends at that line. It stays active through
94
+ the gap after it, and the last section stays active below it. Moving one
95
+ section forward plays to its step (`playToStep`); moving back, skipping
96
+ sections, the first section and reduced motion jump (`seekStep`);
97
+ `animate: false` always jumps. Above the first section the diagram keeps its
98
+ frame. The active section gets `aria-current="step"` (style it without
99
+ changing its size, e.g. opacity); `onChange(index, section)` reports each
100
+ change (`-1, null` above the first). It never scrubs continuously: the
101
+ diagram only ever rests on settled steps. Mount the player with
102
+ `autoplay: "none"`, and leave room below the last section (e.g.
103
+ `padding-bottom: 50vh`) so its top can reach the line. Without
104
+ IntersectionObserver it does nothing and the text still reads.
105
+
106
+ Plain HTML (`motion-kit vendor … --adapter page`):
107
+
108
+ ```html
109
+ <article id="story">
110
+ <section data-mk-step="order"><h2>The order</h2><p>…</p></section>
111
+ <section data-mk-step="payment"><h2>Payment</h2><p>The <button type="button" data-mk-step="payment">card check</button> …</p></section>
112
+ <section data-mk-step="shipping"><h2>Shipping</h2><p>…</p></section>
113
+ </article>
114
+ <div id="flow"></div>
115
+ <script type="module">
116
+ import { mountPlayer } from "./motion-kit/runtime/player.mjs";
117
+ import { linkSteps, scrollSteps } from "./motion-kit/runtime/links.mjs";
118
+ const player = mountPlayer(document.getElementById("flow"), scene, { autoplay: "none" });
119
+ const story = document.getElementById("story");
120
+ const stopScroll = scrollSteps(player, story.querySelectorAll("section"));
121
+ // The sections carry data-mk-step too: pass the terms, not the article.
122
+ const stopLinks = linkSteps(player, story.querySelectorAll("button[data-mk-step]"));
123
+ </script>
124
+ ```
125
+
126
+ `<motion-diagram>` (`--adapter element`): wait for the controller.
127
+
128
+ ```js
129
+ import { scrollSteps } from "./motion-kit/runtime/links.mjs";
130
+ const el = document.querySelector("motion-diagram");
131
+ const bind = (c) => scrollSteps(c, document.querySelectorAll("#story section"));
132
+ el.controller ? bind(el.controller) : el.addEventListener("motion-ready", (e) => bind(e.detail.controller), { once: true });
133
+ ```
134
+
135
+ The element remounts when an attribute changes, which makes a new controller:
136
+ listen to every `motion-ready` (not `once`) and dispose the previous binding
137
+ first if the page changes attributes.
138
+
139
+ Astro (`--adapter astro`), with `id` on the diagram:
140
+
141
+ ```astro
142
+ <AnimatedDiagram spec={spec} format="tall" id="flow" />
143
+ <script>
144
+ import { linkSteps, scrollSteps } from "../motion-kit/runtime/links.mjs";
145
+ const el = document.getElementById("flow");
146
+ const bind = (c) => {
147
+ const stops = [scrollSteps(c, document.querySelectorAll("#story section")), linkSteps(c, document.querySelectorAll("#story button[data-mk-step]"))];
148
+ document.addEventListener("astro:before-swap", () => stops.forEach((stop) => stop()), { once: true });
149
+ };
150
+ el.controller ? bind(el.controller) : el.addEventListener("motion-ready", (e) => bind(e.detail.controller), { once: true });
151
+ </script>
152
+ ```
153
+
154
+ Module scripts run once per load: with view transitions (`<ClientRouter />`),
155
+ run the binding code in an `astro:page-load` listener so each page binds its
156
+ own diagram; the `astro:before-swap` dispose releases the previous one.
157
+
158
+ A page from `motion-kit build` has them on the `MotionKitRuntime` global.
159
+
160
+ The step mapping is pure and exported for tests and custom bindings:
161
+ `stepRef(scene, ref)` (id first, then a whole-number index),
162
+ `sectionSteps(scene, refs)` (a section's reference, else its position),
163
+ `activeSection(tops, line)` and `scrollMove({ from, to, fromStep, toStep,
164
+ animate, reduced })` (`"play"`, `"seek"` or null).
165
+
59
166
  ## Patterns worth adding per diagram (in the page around the player)
60
167
 
61
168
  - **Hover/focus linking:** terms in the surrounding text highlight the matching
62
- part of the diagram (and back). Wrap the term in
63
- `<span data-mk-step="payment">`; on hover and on focus,
64
- `controller.seekStep("payment")`. Use step ids, not positions.
65
- - **Scroll-driven steps:** for long-form explainers, map section visibility to
66
- steps (IntersectionObserver per text section → `seekStep(i)`). Don't scrub
67
- continuously on scroll; jump to settled steps.
169
+ part of the diagram: `linkSteps` above. Use step ids, not positions.
170
+ - **Scroll-driven steps:** for long-form explainers, one text section per step:
171
+ `scrollSteps` above. Don't scrub continuously on scroll; jump to settled
172
+ steps.
68
173
  - **Details on demand:** step buttons + caption first; tooltips only for
69
174
  secondary facts.
70
175
  - **Explorables:** a parameter slider can change the *spec* (e.g. number of
@@ -79,3 +184,21 @@ el.controller ? go(el.controller) : el.addEventListener("motion-ready", (e) => g
79
184
  - Don't hide information only in hover states; touch devices have no hover.
80
185
  - Test: keyboard only, a screen reader pass (VoiceOver: the step list is read),
81
186
  phone width, reduced motion, dark mode.
187
+
188
+ ## Step notifications
189
+
190
+ `controller.onStep(index => { … })` calls immediately with the current settled
191
+ step index, then once whenever it changes through playback, seek, scrubber,
192
+ buttons or keyboard. The index is `-1` before the first step. It returns an
193
+ unsubscribe function; `destroy()` releases every subscription. `scrollSteps`
194
+ and `linkSteps` subscribe when available so marks also follow player controls.
195
+ No polling or extra animation loop is needed. Callbacks should observe state,
196
+ not seek the player recursively.
197
+
198
+ For outside drivers, use the returned controller or the adapter element's
199
+ `.controller` after `motion-ready`. `seek(t)` is public, requires a finite time,
200
+ clamps to the scene, pauses playback and cancels pending autoplay. Mount with
201
+ `autoplay: "none"`; honor reduced motion in the driver. Visibility pauses the
202
+ player's clock, not explicit seeks. Capture tools may use
203
+ `globalThis.__motionKit[options.id ?? scene.id]`; default scene ids contain the
204
+ format suffix, while Astro generates an instance key unless given `id`.
@@ -18,7 +18,7 @@
18
18
  | State fill (pending → active) | 200–300 ms |
19
19
  | Travel between nodes | 350–500 ms |
20
20
  | Pause between beats | ≥ 50 ms, so step frames settle |
21
- | Whole explainer | ≤ ~8 s, then hold |
21
+ | Whole explainer | aim for ≤ 8 s, then hold; gate limit 12 s |
22
22
 
23
23
  ## Springs, without breaking random access (derived)
24
24
 
@@ -20,6 +20,9 @@ Model screenshots are evidence, not approval. **A human signs off on the look.**
20
20
  reads the step list.
21
21
  - Video: `video --sheet` contact sheet; duration, aspect and size via the
22
22
  printed probe; watch it once at full size.
23
+ - Exports: `manifest.json` names the source commit and says
24
+ `"sourceDirty": false`; a `true` means the frames come from uncommitted
25
+ changes. Re-exporting into a folder replaces what the last export wrote.
23
26
 
24
27
  **Don't trust virtual time.** Headless `--virtual-time-budget` doesn't advance
25
28
  the player's animation clock faithfully. Use `--timeout=<ms>` (real time) or a
@@ -38,6 +38,106 @@ time draws (carrying an emphasis dot) and the spoke fills. Steps = hub, then
38
38
  each spoke. Layouts: radial ellipse (wide/square), tree with an outside trunk
39
39
  (9:16, tall). Throws when boxes would overlap: fewer spokes or a larger format.
40
40
 
41
+ ### `timeline`: events in time
42
+
43
+ ```json
44
+ { "type": "timeline", "id": "incident",
45
+ "title": "…", "description": "…",
46
+ "events": [ { "when": "09:02", "label": "Alert fires", "detail": "…" },
47
+ …,
48
+ { "when": "Thursday", "label": "Review", "planned": true } ],
49
+ "now": { "label": "Now", "detail": "…" }, // optional
50
+ "fontSize": 18 } // optional max; auto-fit otherwise
51
+ ```
52
+
53
+ 2–8 events in time order, each with a short `when` (one line: "09:02",
54
+ "Q3 2026") and a `label`. `planned: true` marks an event still to come;
55
+ planned events go last and need a `now`. Events and `now` may carry an `id`
56
+ for their step. Storyboard: the axis draws on → milestones drop onto it in
57
+ order; an event that has happened fills accent and the axis behind it turns
58
+ accent, a planned one stays pending → the "now" marker (the emphasis element)
59
+ settles on the axis after the last past event. Steps = one per event, then
60
+ `now`. Events are spaced evenly, not to scale. Layouts: horizontal axis with
61
+ labels below, or alternating above and below when that saves lines (wide
62
+ aspects, 1:1); vertical axis with labels on the right (9:16, tall). Throws when
63
+ a label or the now marker does not fit: fewer events, shorter labels or a
64
+ larger format.
65
+
66
+ ### `stack`: layers that build on each other
67
+
68
+ ```json
69
+ { "type": "stack", "id": "web-stack",
70
+ "title": "…", "description": "…",
71
+ "layers": [ { "label": "Browser", "detail": "…" }, …,
72
+ { "label": "Database", "detail": "…" } ],
73
+ "direction": "down", // or "up": the packet enters at the bottom
74
+ "fontSize": 18 } // optional max; auto-fit otherwise
75
+ ```
76
+
77
+ 2–8 layers, listed top to bottom as drawn; a layer may carry an `id` for its
78
+ step. Storyboard: the layers rise into place bottom-up → a packet (the emphasis
79
+ dot) enters on a rail beside the stack and hops layer to layer; the layer it
80
+ reaches fills accent, a layer it has left keeps an accent outline, and the rail
81
+ behind it turns accent. Steps = one per layer, in travel order (top → bottom
82
+ for `down`, bottom → top for `up`). Layout: one column of layers with the rail
83
+ on the right in every format; labels take one line, two when needed. Throws
84
+ when the layers do not fit: fewer layers, shorter labels or a larger format.
85
+
86
+ ### `state-machine`: states and explicit transitions
87
+
88
+ ```json
89
+ { "type": "state-machine", "id": "connection",
90
+ "title": "A connection", "description": "Connect and disconnect.",
91
+ "states": [{ "id": "off", "label": "Offline" }, { "id": "on", "label": "Online" }],
92
+ "transitions": [
93
+ { "id": "connect", "from": "off", "to": "on", "label": "Connect" },
94
+ { "id": "close", "from": "on", "to": "off", "label": "Disconnect" }
95
+ ],
96
+ "initial": "off", "path": ["connect", "close"] }
97
+ ```
98
+
99
+ 2–8 states, 1–12 transitions and 1–10 narrated transitions in `path`.
100
+ State and transition ids are required and unique within their list. `initial`
101
+ names a state. Each path edge must start where the previous one ended; branches,
102
+ cycles, repeated transitions and self-transitions are supported. The path is
103
+ explicit: the runtime never decides which branch to take. All states appear
104
+ pending, the initial state fills, then a single token follows the path while
105
+ the current state fills accent. Completed edges retain their accent.
106
+
107
+ Layouts use a column in reading order with separate connector lanes outside
108
+ the labels; each fixed format centers the fitted graph, and strips grow to
109
+ fit. Labels auto-fit to two lines at 14 px or above. Oversized graphs and labels
110
+ fail with a remedy. `fontSize` sets the optional maximum.
111
+
112
+ Steps are the initial state (`initial`), then one per path entry (`visit-1`,
113
+ `visit-2`, …). Transition labels and optional `detail` sentences appear in
114
+ controls, captions and the accessible transcript; they are narrative steps
115
+ (`stepLabelsInFrame: false`), not labels drawn on every edge. State labels stay
116
+ visible in every settled frame. Labels, title, description and details accept
117
+ localized strings. See `examples/player-states.json` and `connection.json`.
118
+
119
+ ### `request-journey`: a request crossing components
120
+
121
+ Uses the same explicit walk, timing, bounds and step ids as `state-machine`,
122
+ with `components` instead of `states` and `hops` instead of `transitions`:
123
+
124
+ ```json
125
+ { "type": "request-journey", "id": "request",
126
+ "title": "Queue a job", "description": "The API queues work asynchronously.",
127
+ "components": [
128
+ { "id": "api", "label": "API", "region": "Service" },
129
+ { "id": "queue", "label": "Queue", "region": "Worker" }
130
+ ],
131
+ "hops": [{ "id": "send", "from": "api", "to": "queue", "label": "Enqueue", "async": true }],
132
+ "initial": "api", "path": ["send"] }
133
+ ```
134
+
135
+ A component's optional localized `region` names its boundary, shown as a
136
+ one-line heading above a dashed enclosure. Components sharing a region keep
137
+ separate enclosures with the same name. Hops with `async: true` stay dashed,
138
+ including after activation. Return paths are ordinary hops in the opposite
139
+ direction. See `examples/checkout.json`.
140
+
41
141
  ## Storyboards for types not built yet
42
142
 
43
143
  Build these as custom scenes (`custom-scenes.md`) first. Promote one to a type
@@ -45,12 +145,8 @@ once it has been used twice.
45
145
 
46
146
  | Type | Helps the viewer understand | Storyboard |
47
147
  |---|---|---|
48
- | `stack` | layers build on each other (architecture, security layers) | layers rise bottom-up; then a request/data packet travels down/up, each layer lighting as it passes |
49
148
  | `before-after` | what changes | left state fully shown → a divider sweeps → right state builds; differences highlighted with the emphasis colour |
50
- | `timeline` | events in time | axis draws on → milestones drop in order → "now" marker settles |
51
149
  | `comparison` | option A vs B on criteria | two columns appear → criteria rows fill one at a time → the deciding row emphasised |
52
- | `state-machine` | states and transitions | all states (pending) → a token walks a path of transitions, the current state accent |
53
- | `request-journey` | a request crossing system components | components in regions/boundaries → a dot travels the path, each hop lights, async edges dashed |
54
150
  | `funnel` / `data-flow` | volume or data narrowing/merging | sources appear → streams draw on and merge → result fills |
55
151
 
56
152
  Auto-layout for larger graphs: lay out with ELK.js or dagre once (Node, at
@@ -27,15 +27,64 @@ properties (light + dark); standalone exports resolve them to literals.
27
27
  "font": "Inter, ui-sans-serif, system-ui, sans-serif",
28
28
  "radius": 10,
29
29
  "stroke": 2,
30
- "light": { "accent": "#0b5fff", "emphasis": "#00a37a" },
31
- "dark": { "accent": "#3d7eff", "emphasis": "#2fd3a0" }
30
+ "light": { "accent": "#0a2a8a", "emphasis": "#05966a" },
31
+ "dark": { "accent": "#2563eb", "emphasis": "#a7f3d0" }
32
32
  }
33
33
  ```
34
34
 
35
- Missing tokens fall back to neutral. Colours must be `#rrggbb`. Unknown tokens
36
- throw. `motion-kit check --style acme.json …` also checks contrast (WCAG):
37
- text ≥ 4.5:1 (ink/muted on bg and surface, onAccent on accent), shapes ≥ 3:1
38
- (line, accent, emphasis on bg), in both themes.
35
+ Missing tokens fall back to neutral within each theme. If the entire `dark`
36
+ object is absent, the light overrides are also applied over neutral dark;
37
+ provide both theme objects when they need different values. Colours must be
38
+ `#rrggbb`; unknown tokens throw.
39
+
40
+ `radius` (0–24, default 10) sets built-in rectangular node corners; circles,
41
+ region borders and timeline pills retain their geometry. `stroke` (1–4,
42
+ default 2) sets the base line width, with accent lines at 1.5× and timeline
43
+ stems at 0.75×. These settings affect live, SVG, PNG, bake and video rendering.
44
+ Custom scenes receive the normalized style through `frame(t, { style })` and
45
+ may use it explicitly; their own geometry is not rewritten.
46
+
47
+ ## Contrast
48
+
49
+ `motion-kit check --style acme.json …` checks every token pair the scene types
50
+ draw where the pair carries meaning in a step frame (`CONTRAST_PAIRS` in
51
+ `runtime/style.mjs`), in both themes, at WCAG thresholds: 4.5:1 for text,
52
+ 3:1 for shapes and strokes.
53
+
54
+ | Pair | Needs | Where it is drawn |
55
+ |---|---|---|
56
+ | ink on bg | 4.5 | labels of reached nodes, on the canvas |
57
+ | ink on surface | 4.5 | labels inside pending boxes |
58
+ | muted on bg | 4.5 | labels of pending nodes, on the canvas |
59
+ | muted on surface | 4.5 | glyphs and icons inside pending circles |
60
+ | onAccent on accent | 4.5 | labels, glyphs and icons inside reached nodes |
61
+ | line on bg | 3 | connectors, outlines of pending nodes |
62
+ | accent on bg | 3 | reached nodes, drawn connectors |
63
+ | emphasis on bg | 3 | the emphasis ring and dot on the canvas |
64
+ | emphasis on accent | 3 | the ring around the reached node it marks: "here" told from "reached" without relying on hue |
65
+
66
+ Exempt (`CONTRAST_EXEMPT`), each for a reason:
67
+
68
+ | Pair | Why it is not checked |
69
+ |---|---|
70
+ | line on surface | a pending node's outline is its edge, told from the canvas outside it (line on bg), not from its own fill |
71
+ | accent on surface | the reached layer covers the pending one only while a node fills; a scene that draws accent on surface (a bar on a track) declares the pair |
72
+ | emphasis on surface | the ring crosses pending nodes only mid-hop, never in a step frame |
73
+ | accent on line | the accent draw-on covers the pending line; they meet only at the moving tip |
74
+ | onAccent on emphasis | no scene type draws it; the motion-kit logo does, and logos are exempt from WCAG 1.4.11 |
75
+
76
+ Emphasis on accent is the pair most palettes miss: two saturated colours of
77
+ the same lightness (blue and orange, teal and rust) are about 1:1 apart once
78
+ hue is gone. On a white canvas it usually means a dark accent (neutral light
79
+ uses `#1d36a8`) with a mid-tone emphasis; on a dark canvas, a light emphasis
80
+ (neutral dark uses `#fbbf24`).
81
+
82
+ A custom scene that draws another pair declares it, and the gate checks the
83
+ style against it for that scene:
84
+
85
+ ```js
86
+ return { …, contrastPairs: [{ fg: "accent", bg: "surface", min: 3, use: "progress bar on its track" }] };
87
+ ```
39
88
 
40
89
  ## Where style files live
41
90
 
@@ -20,7 +20,11 @@ authoring a timeline and recording it. Consequences:
20
20
 
21
21
  Video maps frame `f` at `fps` to `t = f / fps` (30 fps × 25 s = 750 frames).
22
22
 
23
- ## 2. Determinism rules (enforced by `motion-kit check`)
23
+ ## 2. Determinism rules (sampled by `motion-kit check`)
24
+
25
+ The gate samples outputs and stubs clocks; this is evidence, not a proof of
26
+ purity. Aliases captured at import time, unsampled code paths, CSS motion and
27
+ cross-call state still require code review.
24
28
 
25
29
  1. No dependence on previous frames.
26
30
  2. No uncontrolled randomness (derive variation from a seed and `t` if needed).
@@ -31,7 +35,9 @@ Video maps frame `f` at `fps` to `t = f / fps` (30 fps × 25 s = 750 frames).
31
35
  7. Round every number. `el()` rounds numeric attributes; numbers you put in a
32
36
  template string (`transform`, `points`, path `d`) must go through `num()`.
33
37
  The gate rejects any number with 5+ decimals.
34
- 8. No `Date`, `Math.random()`, `performance.now()` inside a scene.
38
+ 8. No `Date`, `Math.random()`, `performance.now()` inside a scene, nor in the
39
+ helpers it calls: the gate renders every sample under two stubbed clocks
40
+ and refuses a frame whose bytes change.
35
41
  9. **Step frames are settled** (§4).
36
42
  10. Markup is balanced and escaped: labels cannot inject markup.
37
43
  11. Visibility decisions use rounded values: an element whose opacity rounds to
@@ -82,9 +88,12 @@ Patterns:
82
88
 
83
89
  `steps[i].at` is when build step *i* is fully shown, and its frame is what a
84
90
  slide shows. It must look intentional on its own: nothing mid-motion, no
85
- half-drawn line pointing at nothing, no fading dot. Rule: **the next motion may
86
- not start before `at`.** The gate asserts `frame(at − 1 ms) === frame(at)`.
87
- Anything that fades out by a step (a travelling dot) must reach 0 by `at`.
91
+ half-drawn line pointing at nothing, no fading dot. Rule: **the step's own
92
+ motion comes to rest by `at`, and the next motion starts no earlier than
93
+ 50 ms after it.** The gate asserts `frame(at − 1 ms) === frame(at)` and that
94
+ the frames 1, 15, 30 and 45 ms after `at` equal it too, so a slow fade passing
95
+ through `at` fails even when rounding hides it over 1 ms. Anything that fades
96
+ out by a step (a travelling dot) must reach 0 by `at`.
88
97
 
89
98
  ## 5. Layouts are computed per format
90
99
 
@@ -92,7 +101,7 @@ Never crop one master. Timings and the spec are shared; geometry is a function
92
101
  of the format (`16:9`, `4:3`, `1:1`, `9:16`, `wide` strip, `tall` column):
93
102
 
94
103
  - Row for wide aspects, snake grid for square-ish, column or tree for tall.
95
- - **Auto-fit text:** try the largest font (fixed formats ≤ 22 px, strips ≤ 16 px)
104
+ - **Auto-fit text:** try the largest font (fixed formats ≤ 22 px (hub-spoke: 20 px), strips ≤ 16 px)
96
105
  and step down to 14 px until every label wraps into its budget; fail if even
97
106
  14 px doesn't fit. Never shrink below 14 px at 1×.
98
107
  - **Collision checks:** nodes must not overlap or leave the canvas; the layout
@@ -6,12 +6,22 @@ description: "Render motion-kit scenes (animated diagrams) to deliverables: slid
6
6
  # Motion render
7
7
 
8
8
  All outputs come from the same pure scene, so they always agree. Locate the
9
- toolkit as in the animated-diagram skill (`MK=$HOME/workspace/motion-kit`, else
10
- the plugin root two levels above this skill). PNG and video need
11
- `@resvg/resvg-js` (`npm install` in `$MK`) and `ffmpeg`.
9
+ toolkit as in the animated-diagram skill's "Locate the toolkit": first
10
+ `MOTION_KIT_HOME`, then the npm package through `npx` (at the version of these
11
+ skills), then the plugin copy two levels above this skill. PNG and video need
12
+ `@resvg/resvg-js`, which the `npx` route installs; video also needs `ffmpeg`.
13
+ The plugin copy alone has neither, so prefer `npx` there.
12
14
 
13
15
  ```bash
14
- mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
16
+ PLUGIN="$(cd -P "<this skill's base directory>" && cd ../.. && pwd -P)" # -P: the base may be a symlink to a clone
17
+ V="$(node -p "require(process.argv[1] + '/package.json').version" "$PLUGIN")"
18
+ if [ -n "${MOTION_KIT_HOME:-}" ]; then
19
+ MK="$MOTION_KIT_HOME"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
20
+ elif npx -y "@liqweed/motion-kit@$V" --help >/dev/null 2>&1; then
21
+ MK="$PLUGIN"; mk() { npx -y "@liqweed/motion-kit@$V" "$@"; }
22
+ else
23
+ MK="$PLUGIN"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
24
+ fi
15
25
  ```
16
26
 
17
27
  **Always run `mk check <scene>` first.** Exporters refuse scenes that fail the gate.
@@ -80,5 +90,20 @@ errors, and cleans up on disconnect. Full usage: `adapters/element/README.md`.
80
90
  REVIEW.md review report with human approval line
81
91
  ```
82
92
  `manifest.json` records scene, type, format, locale, size, duration, style,
83
- theme, an input hash and the source commit, with no timestamps, so a re-render
84
- from the same inputs is byte-identical and a stale export is easy to spot.
93
+ theme, an input hash, the source commit and `sourceDirty` (`true` when the
94
+ source file has uncommitted changes, so the frames match no commit; `null`
95
+ outside git), with no timestamps, so a re-render from the same inputs is
96
+ byte-identical and a stale export is easy to spot. Deliver from a clean
97
+ source (`sourceDirty: false`).
98
+
99
+ Re-exporting into the same folder replaces the previous export: files its
100
+ `manifest.json` listed that the new export does not write are deleted, so the
101
+ folder holds exactly what the new manifest lists. Files no export wrote are
102
+ left alone and named in a warning; keep notes and review files elsewhere.
103
+
104
+ The CLI gates `build`, `export`, `bake`, `video` and `icon` before writing
105
+ output, including shared style contrast and scene-specific pairs. Exports
106
+ include `runtimeHash`, a SHA-256 of runtime module paths and bytes, in the
107
+ manifest and in `inputHash`, together with format, locale and render settings.
108
+ A changed runtime invalidates the hash even before its package version changes.
109
+ The hash does not recursively fingerprint arbitrary imports of custom scenes.
@@ -2,17 +2,17 @@
2
2
 
3
3
  | Name | viewBox | Typical use | Layout behaviour |
4
4
  |---|---|---|---|
5
- | `16:9` | 960×540 | slides, YouTube, web hero | sequence row (or 2-row snake when crowded); hub-spoke radial |
6
- | `4:3` | 960×720 | older decks, docs | snake grid; radial |
7
- | `1:1` | 720×720 | LinkedIn/Instagram feed | snake grid; radial |
8
- | `9:16` | 540×960 | Reels/Shorts/TikTok, phone | column with labels right; hub-spoke tree |
9
- | `wide` | 960×auto | web strip inside a page | row; height computed |
10
- | `tall` | 360×auto | phone column on a page | column / tree; height computed |
5
+ | `16:9` | 960×540 | slides, YouTube, web hero | sequence row (or 2-row snake when crowded); hub-spoke radial; timeline horizontal axis |
6
+ | `4:3` | 960×720 | older decks, docs | snake grid; radial; horizontal axis |
7
+ | `1:1` | 720×720 | LinkedIn/Instagram feed | snake grid; radial; horizontal axis |
8
+ | `9:16` | 540×960 | Reels/Shorts/TikTok, phone | column with labels right; hub-spoke tree; timeline vertical axis |
9
+ | `wide` | 960×auto | web strip inside a page | row; horizontal axis; height computed |
10
+ | `tall` | 360×auto | phone column on a page | column / tree / vertical axis; height computed |
11
11
 
12
- Fixed formats auto-fit text up to 22 px (sequence) / 20 px (hub-spoke) and
12
+ Fixed formats auto-fit text up to 22 px (sequence, timeline, stack) / 20 px (hub-spoke) and
13
13
  step down to 14 px; strips max 16 px. A spec that cannot fit fails `check`
14
14
  with a reason. Fix it with shorter labels, fewer nodes, or another format.
15
- Never by cropping.
15
+ Never by cropping. A `stack` is one column of layers in every format.
16
16
 
17
17
  Web pages: mount `wide` + `tall` and switch at the width where the wide
18
18
  layout's text would fall below ~14 px on screen.
@@ -6,7 +6,7 @@
6
6
  frame f → t = f/fps − lead → renderSvg(standalone, opaque bg) → PNG (resvg) → ffmpeg stdin
7
7
  ```
8
8
 
9
- - No browser, no per-frame files; identical consecutive frames are rasterized once.
9
+ - No browser, no per-frame files; repeated timestamps (lead and final hold) reuse their PNG.
10
10
  - `--hold` (default 1.5 s) keeps the final frame readable; `lead` 0.25 s.
11
11
  - Encoders: MP4 `libx264 -preset slow -crf 18 -pix_fmt yuv420p -movflags +faststart`
12
12
  (even dimensions padded); WebM `libvpx-vp9 -crf 32`; GIF two-pass palette,
@@ -12,12 +12,23 @@ Same gate, same determinism as any diagram.
12
12
 
13
13
  ## Locate the toolkit
14
14
 
15
+ As in the animated-diagram skill: first `MOTION_KIT_HOME`, then the npm
16
+ package through `npx` (at the version of these skills), then the plugin copy.
17
+ `$MK` holds the template files (`brand/`, `styles/`); `mk` runs the CLI.
18
+
15
19
  ```bash
16
- MK="$HOME/workspace/motion-kit" # canonical clone (has node_modules)
17
- [ -d "$MK" ] || MK="$(cd "<this skill's base directory>/../.." && pwd)" # plugin copy
18
- mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
20
+ PLUGIN="$(cd -P "<this skill's base directory>" && cd ../.. && pwd -P)" # -P: the base may be a symlink to a clone
21
+ V="$(node -p "require(process.argv[1] + '/package.json').version" "$PLUGIN")"
22
+ if [ -n "${MOTION_KIT_HOME:-}" ]; then
23
+ MK="$MOTION_KIT_HOME"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
24
+ elif npx -y "@liqweed/motion-kit@$V" --help >/dev/null 2>&1; then
25
+ MK="$PLUGIN"; mk() { npx -y "@liqweed/motion-kit@$V" "$@"; }
26
+ else
27
+ MK="$PLUGIN"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
28
+ fi
19
29
  ```
20
- Node ≥ 22. PNG needs `@resvg/resvg-js` (`npm install` in `$MK`).
30
+ Node ≥ 22. PNG needs `@resvg/resvg-js`: the `npx` route installs it; in
31
+ `$MOTION_KIT_HOME`, run `npm install`. The plugin copy alone renders SVG only.
21
32
 
22
33
  ## Workflow
23
34
 
@@ -9,7 +9,7 @@
9
9
  "ink": "#111827",
10
10
  "muted": "#4b5563",
11
11
  "line": "#8b929c",
12
- "accent": "#2563eb",
12
+ "accent": "#1d36a8",
13
13
  "onAccent": "#ffffff",
14
14
  "emphasis": "#d97706"
15
15
  },
@@ -21,6 +21,6 @@
21
21
  "line": "#6b7280",
22
22
  "accent": "#2563eb",
23
23
  "onAccent": "#ffffff",
24
- "emphasis": "#f59e0b"
24
+ "emphasis": "#fbbf24"
25
25
  }
26
26
  }