@liqweed/motion-kit 0.5.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.
@@ -109,3 +109,17 @@ export default function make({ format = "1:1", kit }) {
109
109
  Every command supports this, `motion-kit build` included (it bundles the whole
110
110
  runtime and passes it as `kit`). A module that imports instead must use
111
111
  relative imports to a vendored runtime.
112
+
113
+ ## Declared locales and narrative steps
114
+
115
+ Export `const locales = ["en", "nl"]` alongside the default factory so both
116
+ CLI and vendored checks test every shipped locale. Without a declaration the
117
+ check uses `en`; explicit `--locale` flags override the declaration.
118
+ `localize()` accepts shared plain strings or an exact locale translation;
119
+ a missing dictionary entry throws. It never silently selects another language.
120
+
121
+ A scene whose step labels narrate actions rather than name visible objects
122
+ sets `stepLabelsInFrame: false`. Those labels still belong in the player's
123
+ controls and accessible transcript; G10 otherwise requires each label in the
124
+ final frame. `frame(t, { idPrefix, style })` also receives the normalized style
125
+ when called through `renderSvg`; custom shape styling is opt-in.
@@ -184,3 +184,21 @@ animate, reduced })` (`"play"`, `"seek"` or null).
184
184
  - Don't hide information only in hover states; touch devices have no hover.
185
185
  - Test: keyboard only, a screen reader pass (VoiceOver: the step list is read),
186
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
 
@@ -83,6 +83,61 @@ for `down`, bottom → top for `up`). Layout: one column of layers with the rail
83
83
  on the right in every format; labels take one line, two when needed. Throws
84
84
  when the layers do not fit: fewer layers, shorter labels or a larger format.
85
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
+
86
141
  ## Storyboards for types not built yet
87
142
 
88
143
  Build these as custom scenes (`custom-scenes.md`) first. Promote one to a type
@@ -92,8 +147,6 @@ once it has been used twice.
92
147
  |---|---|---|
93
148
  | `before-after` | what changes | left state fully shown → a divider sweeps → right state builds; differences highlighted with the emphasis colour |
94
149
  | `comparison` | option A vs B on criteria | two columns appear → criteria rows fill one at a time → the deciding row emphasised |
95
- | `state-machine` | states and transitions | all states (pending) → a token walks a path of transitions, the current state accent |
96
- | `request-journey` | a request crossing system components | components in regions/boundaries → a dot travels the path, each hop lights, async edges dashed |
97
150
  | `funnel` / `data-flow` | volume or data narrowing/merging | sources appear → streams draw on and merge → result fills |
98
151
 
99
152
  Auto-layout for larger graphs: lay out with ELK.js or dagre once (Node, at
@@ -32,8 +32,17 @@ properties (light + dark); standalone exports resolve them to literals.
32
32
  }
33
33
  ```
34
34
 
35
- Missing tokens fall back to neutral. Colours must be `#rrggbb`. Unknown tokens
36
- throw.
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.
37
46
 
38
47
  ## Contrast
39
48
 
@@ -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).
@@ -97,7 +101,7 @@ Never crop one master. Timings and the spec are shared; geometry is a function
97
101
  of the format (`16:9`, `4:3`, `1:1`, `9:16`, `wide` strip, `tall` column):
98
102
 
99
103
  - Row for wide aspects, snake grid for square-ish, column or tree for tall.
100
- - **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)
101
105
  and step down to 14 px until every label wraps into its budget; fail if even
102
106
  14 px doesn't fit. Never shrink below 14 px at 1×.
103
107
  - **Collision checks:** nodes must not overlap or leave the canvas; the layout
@@ -100,3 +100,10 @@ Re-exporting into the same folder replaces the previous export: files its
100
100
  `manifest.json` listed that the new export does not write are deleted, so the
101
101
  folder holds exactly what the new manifest lists. Files no export wrote are
102
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.
@@ -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,