@liqweed/motion-kit 0.3.0 → 0.4.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/runtime/scene.mjs CHANGED
@@ -9,18 +9,36 @@
9
9
  * id, width, height, // viewBox
10
10
  * duration, // seconds until the final state
11
11
  * title, description, // accessible name + description
12
- * steps: [{ at, label, detail? }], // build steps; last = finished diagram
13
- * frame(t) → string // inner SVG markup at time t
12
+ * steps: [{ at, label, detail?, id? }], // build steps; last = finished diagram
13
+ * frame(t, { idPrefix }) → string // inner SVG markup at time t
14
14
  * }
15
15
  *
16
16
  * frame(t) may depend on nothing but t and the scene's own constants: no Date,
17
17
  * no Math.random(), no performance.now(), no state from earlier frames. That is
18
18
  * what lets a player jump anywhere, an exporter write exactly the frame a slide
19
19
  * needs, and a video renderer sample frame f at t = f / fps.
20
+ *
21
+ * Every render passes an `idPrefix` unique to that instance on the page. A
22
+ * scene that defines ids (clip paths, gradients, masks, markers, filters) MUST
23
+ * build them from it (`${idPrefix}-clip`), so two instances never share an id.
20
24
  */
21
25
  import { esc, num } from "./svg.mjs";
22
26
  import { normalizeStyle, cssVars, resolveTokens } from "./style.mjs";
23
27
 
28
+ /**
29
+ * One build step. `at` is a settled time; `id` is an optional stable name that
30
+ * page scripts can use instead of the step's index.
31
+ * @typedef {{ at: number, label: string, detail?: string, id?: string }} Step
32
+ */
33
+ /**
34
+ * What `renderSvg` passes to `frame` besides the time.
35
+ * @typedef {{ idPrefix: string }} FrameContext
36
+ */
37
+ /**
38
+ * An animated diagram as a pure function of time (see the module comment).
39
+ * @typedef {{ id: string, width: number, height: number, duration: number, title: string, description: string, steps: Step[], frame: (t: number, ctx: FrameContext) => string, stepLabelsInFrame?: boolean, type?: string, format?: string, locale?: string }} Scene
40
+ */
41
+
24
42
  /** Formats: name → viewBox. Layouts are computed per format, never cropped. */
25
43
  export const FORMATS = {
26
44
  "16:9": { width: 960, height: 540 },
@@ -41,21 +59,72 @@ export function localize(value, locale = "en") {
41
59
  return first;
42
60
  }
43
61
 
62
+ /**
63
+ * A valid, CSS-safe id token from any string: letters, digits, "_" and "-",
64
+ * starting with a letter. Ids that already are one come back unchanged.
65
+ * @param {unknown} value
66
+ * @returns {string}
67
+ */
68
+ export function safeId(value) {
69
+ const s = String(value).replace(/[^A-Za-z0-9_-]+/g, "-");
70
+ return /^[A-Za-z]/.test(s) ? s : `mk-${s}`;
71
+ }
72
+
73
+ /**
74
+ * Throw unless `scene` meets the contract; returns it unchanged.
75
+ * @template {Scene} S
76
+ * @param {S} scene
77
+ * @returns {S}
78
+ */
44
79
  export function validateScene(scene) {
45
80
  for (const k of ["id", "width", "height", "duration", "title", "description", "steps", "frame"]) {
46
81
  if (scene[k] === undefined || scene[k] === "") throw new Error(`scene ${scene.id ?? "?"} is missing "${k}"`);
47
82
  }
48
83
  if (!scene.steps.length) throw new Error(`scene ${scene.id}: needs at least one step`);
49
84
  let prev = -Infinity;
85
+ const ids = new Set();
50
86
  for (const s of scene.steps) {
51
87
  if (!(s.at > prev)) throw new Error(`scene ${scene.id}: steps must be strictly increasing in time`);
52
88
  if (s.at > scene.duration + 1e-9) throw new Error(`scene ${scene.id}: step "${s.label}" is after the duration`);
53
89
  if (!s.label) throw new Error(`scene ${scene.id}: every step needs a label`);
90
+ if (s.id !== undefined) {
91
+ if (typeof s.id !== "string" || !s.id) throw new Error(`scene ${scene.id}: step "${s.label}" has an id that is not a non-empty string`);
92
+ if (ids.has(s.id)) throw new Error(`scene ${scene.id}: two steps share the id "${s.id}"`);
93
+ ids.add(s.id);
94
+ }
54
95
  prev = s.at;
55
96
  }
56
97
  return scene;
57
98
  }
58
99
 
100
+ /**
101
+ * `step` with `id` added when one is given (scene types pass a spec's ids on).
102
+ * @template {Step} S
103
+ * @param {S} step
104
+ * @param {unknown} id
105
+ * @returns {S}
106
+ */
107
+ export function withId(step, id) {
108
+ return id == null ? step : { ...step, id: /** @type {string} */ (id) };
109
+ }
110
+
111
+ /**
112
+ * The index of a step given by index or by id. Throws RangeError for an
113
+ * index outside the steps, or an id no step has.
114
+ * @param {{ steps: Step[] }} scene
115
+ * @param {number | string} ref
116
+ * @returns {number}
117
+ */
118
+ export function stepIndex(scene, ref) {
119
+ if (typeof ref === "string") {
120
+ const i = scene.steps.findIndex((s) => s.id === ref);
121
+ if (i < 0) throw new RangeError(`Unknown step id: ${ref}`);
122
+ return i;
123
+ }
124
+ if (!Number.isInteger(ref) || ref < 0 || ref >= scene.steps.length) throw new RangeError(`Invalid step index: ${ref}`);
125
+ return ref;
126
+ }
127
+
59
128
  /**
60
129
  * Complete, accessible <svg> for `scene` at time t (clamped to the scene).
61
130
  *
@@ -65,12 +134,18 @@ export function validateScene(scene) {
65
134
  * style style object or "neutral"
66
135
  * background paint the style's bg colour behind the diagram (video, PNG for slides)
67
136
  * scale width/height multiplier for standalone output
68
- * idPrefix unique prefix for <title>/<desc> ids when several diagrams share a page
137
+ * idPrefix prefix for every id in the output: <title>/<desc>, and the scene's
138
+ * own ids through frame(t, { idPrefix }). Unique per instance on a
139
+ * page; made a safe id token (safeId). Default: scene.id
140
+ * @param {Scene} scene
141
+ * @param {number} t
142
+ * @param {{ standalone?: boolean, theme?: string, style?: any, background?: boolean, scale?: number, idPrefix?: string, live?: boolean }} [options]
143
+ * @returns {string}
69
144
  */
70
145
  export function renderSvg(scene, t, options = {}) {
71
146
  const style = normalizeStyle(options.style);
72
147
  const time = Math.min(Math.max(t, 0), scene.duration);
73
- const id = esc(options.idPrefix ?? scene.id);
148
+ const id = safeId(options.idPrefix ?? scene.id);
74
149
  const scale = options.scale ?? 1;
75
150
  const size = options.standalone ? ` width="${num(scene.width * scale)}" height="${num(scene.height * scale)}"` : "";
76
151
  const vars = options.standalone ? "" : ` style="${cssVars(style, options.theme ?? "light")}"`;
@@ -81,7 +156,7 @@ export function renderSvg(scene, t, options = {}) {
81
156
  `<title id="${id}-title">${esc(scene.title)}</title>` +
82
157
  `<desc id="${id}-desc">${esc(scene.description)}</desc>` +
83
158
  bg +
84
- scene.frame(time) +
159
+ scene.frame(time, { idPrefix: id }) +
85
160
  `</svg>`;
86
161
  return options.standalone ? resolveTokens(markup, style, options.theme ?? "light") : markup;
87
162
  }
package/runtime/style.mjs CHANGED
@@ -72,6 +72,8 @@ export function normalizeStyle(style) {
72
72
  light: { ...NEUTRAL.light, ...(style.light ?? {}) },
73
73
  dark: { ...NEUTRAL.dark, ...(style.dark ?? style.light ?? {}) },
74
74
  };
75
+ // The font goes into CSS and markup: a family list never needs these characters.
76
+ if (typeof out.font !== "string" || /[<>{};\\]/.test(out.font)) throw new Error(`style "${out.name}": font must be a CSS font-family list, got ${JSON.stringify(out.font)}`);
75
77
  for (const theme of ["light", "dark"]) {
76
78
  for (const key of Object.keys(out[theme])) {
77
79
  if (!TOKENS.includes(key)) throw new Error(`style "${out.name}": unknown token "${key}" in ${theme}`);
@@ -11,14 +11,14 @@
11
11
  *
12
12
  * Spec:
13
13
  * { type: "hub-spoke", id, title, description,
14
- * hub: { label, detail? },
15
- * spokes: [{ label, detail? }], // 2–10
14
+ * hub: { label, detail?, id? }, // id names the step
15
+ * spokes: [{ label, detail?, id? }], // 2–10
16
16
  * direction?: "out" | "in", // default "out"
17
17
  * fontSize?: number }
18
18
  */
19
19
  import { easeOut, easeStandard, progress, window01 } from "../motion.mjs";
20
20
  import { boxNode, FONT_MIN, rectEdge } from "../parts.mjs";
21
- import { FORMATS, localize } from "../scene.mjs";
21
+ import { FORMATS, localize, withId } from "../scene.mjs";
22
22
  import { tok } from "../style.mjs";
23
23
  import { drawOn, el, pointOnLine } from "../svg.mjs";
24
24
  import { wrapLabel } from "../wrap.mjs";
@@ -207,8 +207,8 @@ export function hubSpoke(spec, { format = "16:9", locale = "en" } = {}) {
207
207
  title: localize(spec.title, locale),
208
208
  description: localize(spec.description, locale),
209
209
  steps: [
210
- { at: HUB_ON + FILL, label: hubLabel, detail: localize(spec.hub.detail, locale) },
211
- ...spokes.map((s, i) => ({ at: stepAt(i), label: s.label, detail: s.detail })),
210
+ withId({ at: HUB_ON + FILL, label: hubLabel, detail: localize(spec.hub.detail, locale) }, spec.hub.id),
211
+ ...spokes.map((s, i) => withId({ at: stepAt(i), label: s.label, detail: s.detail }, spokesSpec[i].id)),
212
212
  ],
213
213
  frame,
214
214
  };
@@ -11,14 +11,14 @@
11
11
  *
12
12
  * Spec:
13
13
  * { type: "sequence", id, title, description,
14
- * nodes: [{ label, detail?, glyph?, icon? }], // 2–12 nodes
14
+ * nodes: [{ label, detail?, glyph?, icon?, id? }], // 2–12 nodes; id names the node's step
15
15
  * glyphs?: "numbers" | "none" // default "numbers"
16
16
  * fontSize?: number }
17
17
  * Strings may be localized objects: { en: "...", nl: "..." }.
18
18
  */
19
19
  import { easeOut, easeStandard, progress } from "../motion.mjs";
20
20
  import { circleNode, FONT_MIN, stateLabel } from "../parts.mjs";
21
- import { FORMATS, localize } from "../scene.mjs";
21
+ import { FORMATS, localize, withId } from "../scene.mjs";
22
22
  import { tok } from "../style.mjs";
23
23
  import { drawOn, el, polyline, trimSegment } from "../svg.mjs";
24
24
  import { wrapLabel } from "../wrap.mjs";
@@ -195,7 +195,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
195
195
  duration,
196
196
  title: localize(spec.title, locale),
197
197
  description: localize(spec.description, locale),
198
- steps: items.map((it, k) => ({ at: stepAt(k), label: it.label, detail: it.detail })),
198
+ steps: items.map((it, k) => withId({ at: stepAt(k), label: it.label, detail: it.detail }, nodes[k].id)),
199
199
  frame,
200
200
  };
201
201
  }
@@ -63,11 +63,13 @@ Node ≥ 22. PNG/video need `@resvg/resvg-js` (`npm install` in `$MK`) and `ffmp
63
63
  mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
64
64
  mk types; mk formats
65
65
  mk check diagram.json # all formats × locales
66
+ mk check flow.scene.mjs -l en -l nl --options labels.mjs # a custom module, with its text from the caller
66
67
  mk build diagram.json -o diagram.html -f wide -l nl # Craft Page / standalone
67
68
  mk export diagram.json -o out/ --png --qc # slides + review sheet
68
69
  mk bake diagram.json -o diagram.svg -f wide # zero-JS animated SVG
69
70
  mk video diagram.json -f 9:16 -o reel.mp4 --sheet sheet.png
70
- mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page
71
+ mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page / element
72
+ node <repo>/components/motion-kit/check.mjs flow.scene.mjs -l en -l nl --style brand.json --options labels.mjs # the vendored gate, same checks
71
73
  ```
72
74
 
73
75
  Vendoring includes the full MIT `LICENSE`. Keep that file and the SPDX
@@ -18,8 +18,10 @@ export default function make({ format = "16:9", locale = "en" } = {}) {
18
18
  duration: 4.2,
19
19
  title: localize({ en: "…", nl: "…" }, locale),
20
20
  description: localize({ en: "…", nl: "…" }, locale),
21
- steps: [{ at: 1.2, label: "…", detail: "…" }, …],
22
- frame(t) { /* return inner SVG markup for time t */ },
21
+ steps: [{ at: 1.2, label: "…", detail: "…", id: "request" }, …],
22
+ frame(t, { idPrefix }) {
23
+ // inner SVG markup for time t; ids are `${idPrefix}-…`
24
+ },
23
25
  };
24
26
  }
25
27
  ```
@@ -30,6 +32,12 @@ Rules:
30
32
  no module-level mutable state.
31
33
  - Colours only via `tok()`; numbers in strings via `num()`.
32
34
  - Use `fade()`/`el()` so invisible elements disappear; `drawOn()` for lines.
35
+ - Ids (clip paths, gradients, masks, markers, filters) MUST be built from
36
+ `idPrefix`, the second argument's field: `${idPrefix}-clip`, referenced as
37
+ `url(#${idPrefix}-clip)`. Every render gets a prefix unique to its instance,
38
+ so two copies on one page never share an id. The gate refuses fixed ids.
39
+ - Give steps an `id` when page scripts or links address them
40
+ (`controller.playToStep("request")`); ids are unique within the scene.
33
41
  - Lay out per format; throw if labels don't fit (`wrapLabel`).
34
42
  - Gate: `motion-kit check my-diagram.scene.mjs` (all formats you support; pass
35
43
  `--format` to limit).
@@ -38,11 +46,53 @@ Rules:
38
46
  - If the same shape is needed twice, promote it to a scene type in
39
47
  `runtime/types/` with a spec and tests.
40
48
 
49
+ ## Scene options: text and views from the caller
50
+
51
+ Every caller builds a module through `sceneFromModule` (`runtime/kit.mjs`):
52
+
53
+ ```js
54
+ make({ ...options, format, locale, kit })
55
+ ```
56
+
57
+ `options` are the caller's serializable scene options, passed unchanged: a
58
+ site's dictionary entry (`labels`), a `view` to draw. `format`, `locale` and
59
+ `kit` are reserved. The same module, options, format and locale give the same
60
+ scene in the gate, the exporters and the browser.
61
+
62
+ ```js
63
+ export default function make({ format = "16:9", labels, view = "full" }) {
64
+ // labels: { title, description, steps: [{ id, label, detail }] } from the caller
65
+ }
66
+ ```
67
+
68
+ - CLI: `--options` takes inline JSON, a `.json` file, or an `.mjs` whose
69
+ default export is the options or `({ format, locale }) => options`, so the
70
+ gate checks each locale with that locale's text:
71
+
72
+ ```js
73
+ // labels.mjs
74
+ import en from "../i18n/en.json" with { type: "json" };
75
+ import nl from "../i18n/nl.json" with { type: "json" };
76
+ export default ({ locale }) => ({ labels: { en, nl }[locale].flow });
77
+ ```
78
+
79
+ ```bash
80
+ motion-kit check flow.scene.mjs -l en -l nl --options labels.mjs --style brand.json
81
+ ```
82
+
83
+ A vendored copy runs the same gate: `node <vendored>/check.mjs` takes the
84
+ same files and flags.
85
+ - Astro adapter: `<AnimatedDiagram module="/src/diagrams/flow.scene.mjs"
86
+ options={{ labels: t.flow }} locale={lang} format="wide" />`. The module
87
+ lives under `src/` and ends in `.scene.mjs` or `.scene.js`; the adapter
88
+ renders it on the server and loads it in the browser on demand. Only the
89
+ page's locale's text ships.
90
+
41
91
  ## Scenes outside this repository: `kit`
42
92
 
43
- The CLI calls `make({ format, locale, kit })`, where `kit` is the whole
44
- runtime in one flat namespace (`lib/load.mjs` `KIT`). A scene file kept in
45
- another repository can destructure what it needs instead of importing:
93
+ `kit` is the whole runtime in one flat namespace (`runtime/kit.mjs` `KIT`). A
94
+ scene file kept in another repository can destructure what it needs instead of
95
+ importing:
46
96
 
47
97
  ```js
48
98
  export default function make({ format = "1:1", kit }) {
@@ -51,6 +101,6 @@ export default function make({ format = "1:1", kit }) {
51
101
  }
52
102
  ```
53
103
 
54
- Every Node-side command (check, export, bake, icon, video) supports this.
55
- `motion-kit build` bundles the module for the browser and needs relative
56
- imports; vendor the runtime for that.
104
+ Every command supports this, `motion-kit build` included (it bundles the whole
105
+ runtime and passes it as `kit`). A module that imports instead must use
106
+ relative imports to a vendored runtime.
@@ -2,24 +2,41 @@
2
2
 
3
3
  ## The player (`runtime/player.mjs`, used by `build`, the Astro adapter, Craft Pages)
4
4
 
5
- - Starts on the **final frame** (also the no-JS / server-rendered fallback).
6
- - Replays once when ~40 % visible, then holds.
5
+ - Starts on the **final frame**. A server render can emit the player's whole
6
+ first state with `playerMarkup(scene, { id, … })`, `PLAYER_CSS` and
7
+ `themeCss(selector, style, theme)`: the final frame, the step list and the
8
+ colours without JavaScript, with the controls inert, and nothing moves when
9
+ the player mounts. The Astro adapter and `build` do this.
10
+ - Replays once when ~40 % of the diagram, or 40 % of the viewport, shows, so a
11
+ diagram taller than the screen starts too; then holds. While the diagram is
12
+ out of view or not rendered (`display: none`), its clock waits and nothing
13
+ is drawn; it resumes where it stopped.
7
14
  - Controls: play/pause (always present, WCAG 2.2.2), one button per step (jumps
8
15
  by default), optional scrubber, caption with the active step's `detail`.
9
- - Keyboard on the diagram: ← / → step, Home / End, Space play/pause.
16
+ Every control is at least 44 × 44 px. The caption and the play button keep
17
+ the size of their longest text, so playback does not move the page.
18
+ - Keyboard on the diagram (a focusable group named by the title, described by
19
+ a hint, `labels.keys`): ← / → step, Home / End, Space play/pause.
10
20
  - `prefers-reduced-motion`: final frame, no autoplay, no play button.
11
- - `prefers-color-scheme`: light/dark tokens switch live.
21
+ - `prefers-color-scheme`: light/dark tokens switch live, unless `theme` is set.
22
+ Tokens are set one property at a time, so CSS on the container stays.
12
23
  - Screen readers: `role="img"` + `<title>`/`<desc>`, a visually hidden ordered
13
24
  list of all steps with details; the visible caption is `aria-hidden`.
25
+ - Ids: every player renders with its own id prefix (`options.id`, else the
26
+ scene id plus a counter), so scenes that define ids can share a page.
27
+ - The stylesheet is added to the document whenever a player mounts and none is
28
+ there, so a page swap (Astro view transitions) cannot leave players unstyled.
14
29
  - Capture hook: `window.__motionKit[id].seek(t)` (for Playwright/HyperFrames-
15
30
  style renderers).
16
31
 
17
- The controller's step indices are zero-based. `controller.seekStep(i)` jumps;
18
- `controller.playToStep(i)` plays forward from the current time and stops at the
19
- step's exact settled time. Backward and same-step calls jump, and reduced
20
- motion always jumps. A new call replaces the previous target; `pause()` holds
21
- the current frame, `seek(t)` cancels playback, and `play()` continues to the end.
22
- Invalid indices throw `RangeError`.
32
+ Steps are addressed by zero-based index or by step `id` (a spec node's or
33
+ spoke's `id`, or a custom scene's `steps[i].id`): ids survive steps being added
34
+ or reordered. `controller.seekStep(ref)` jumps; `controller.playToStep(ref)`
35
+ plays forward from the current time and stops at the step's exact settled time.
36
+ Backward and same-step calls jump, and reduced motion always jumps. A new call
37
+ replaces the previous target; `pause()` holds the current frame, `seek(t)`
38
+ cancels playback, and `play()` continues to the end. An invalid index or an
39
+ unknown id throws `RangeError`.
23
40
 
24
41
  Pass `{ animateSteps: true }` to `mountPlayer(container, scene, options)` to
25
42
  enable this behavior for the step buttons and arrow/Home/End keys. The default
@@ -27,11 +44,24 @@ keeps instant navigation. Call `controller.destroy()` before removing or
27
44
  replacing a player: it cancels playback, visibility observation, theme listening
28
45
  and its capture-hook entry.
29
46
 
47
+ Reaching a player from page scripts: `mountPlayer` returns the controller; the
48
+ `<motion-diagram>` element and the Astro adapter's root element expose it as
49
+ `.controller` and dispatch `motion-ready` (bubbling, `detail.controller`) once
50
+ it is mounted. The player may already be mounted when your script runs, so use
51
+ whichever comes first. Give an Astro diagram an `id` to find it:
52
+
53
+ ```js
54
+ const el = document.getElementById("flow");
55
+ const go = (c) => c.playToStep("payment");
56
+ el.controller ? go(el.controller) : el.addEventListener("motion-ready", (e) => go(e.detail.controller), { once: true });
57
+ ```
58
+
30
59
  ## Patterns worth adding per diagram (in the page around the player)
31
60
 
32
61
  - **Hover/focus linking:** terms in the surrounding text highlight the matching
33
62
  part of the diagram (and back). Wrap the term in
34
- `<span data-mk-step="3">`; on hover, `controller.seekStep(3)`.
63
+ `<span data-mk-step="payment">`; on hover and on focus,
64
+ `controller.seekStep("payment")`. Use step ids, not positions.
35
65
  - **Scroll-driven steps:** for long-form explainers, map section visibility to
36
66
  steps (IntersectionObserver per text section → `seekStep(i)`). Don't scrub
37
67
  continuously on scroll; jump to settled steps.
@@ -10,8 +10,8 @@ Model screenshots are evidence, not approval. **A human signs off on the look.**
10
10
  2. **Timing:** QC frames 0.2 s before/after each step: overlapping text, abrupt
11
11
  jumps, elements vanishing, half-drawn lines, stray dots. Regular sampling
12
12
  misses broken transitions; look *around* the transitions.
13
- 3. **Phone size:** the 360 px row in the sheet; the `tall`/`9:16` layout; no
14
- text under 14 px at 1×.
13
+ 3. **Phone size:** the 360 px row in the sheet (the scene's `tall` layout); the
14
+ `9:16` layout; no text under 14 px at 1×.
15
15
  4. **Brand and facts:** tokens only, approved style, approved copy, no invented
16
16
  numbers or superlatives, every locale checked.
17
17
  5. **Final file:**
@@ -6,7 +6,7 @@
6
6
  | **Craft in-chat preview** | **no** (`html-preview` iframe blocks scripts) | baked SVG, or step PNGs | `bake -o x.svg` → `image-preview`; or `export --png` → `image-preview` items |
7
7
  | **Slidev** (stagewright, docomply-presentations) | yes | one step per click (component registers its own clicks; composes with `v-click`) | `vendor <deck>/components/motion-kit --adapter slidev` → `<AnimatedDiagram :spec="spec" />`; `maxHeight` (default 380px fits under a title) |
8
8
  | **Marp / PowerPoint / Keynote** | no | one slide per step, same position; transition None/Dissolve/Morph | `export --png --scale 2` (Marp, Google Slides) or the SVGs (PowerPoint 365, Keynote) |
9
- | **Website** (Astro, React, static) | yes | server-rendered final frame + player | `vendor <repo>/src/motion-kit --adapter astro`; wide + tall instances switched with CSS |
9
+ | **Website** (Astro, React, static) | yes | server-rendered first state (final frame, step list, colours) + player | `vendor <repo>/src/motion-kit --adapter astro`; `<AnimatedDiagram spec={…}>` or `module="/src/…/x.scene.mjs" options={…}`; `theme`, `style`; wide + tall instances switched with CSS; CI runs the vendored `check.mjs` |
10
10
  | **README / Obsidian / email / docs** | no | baked SVG (animated) or a GIF | `bake` (CSS animation inside SVG: works in browsers and GitHub `<img>`); `video -o x.gif` for email |
11
11
  | **Video** (social, demos, talks) | n/a | MP4/WebM/GIF | `video -f 9:16 -o reel.mp4`; see motion-render |
12
12
 
@@ -19,9 +19,11 @@
19
19
  - **Slides:** frames from one scene share a viewBox, so consecutive step slides
20
20
  register exactly. Fonts in standalone SVG fall back to the viewer's system
21
21
  font: send PNGs for decks that travel.
22
- - **Websites:** pass serializable props (spec JSON) to islands; keep label
23
- dictionaries out of client bundles; mount wide and tall, switch with CSS
24
- (`display:none` also removes the hidden one from the a11y tree and its
25
- autoplay observer).
22
+ - **Websites:** pass serializable props (a spec, or a module path and its
23
+ options) to islands; pass the page's locale's text as options, so the other
24
+ dictionaries stay out of client bundles; mount wide and tall, switch with CSS
25
+ (`display:none` also removes the hidden one from the a11y tree and stops its
26
+ clock). The server render reserves the controls' space: mounting causes no
27
+ layout shift.
26
28
  - **Brand repos** keep their own style file next to their specs; motion-kit
27
29
  ships only `neutral`.
@@ -37,6 +37,11 @@ Video maps frame `f` at `fps` to `t = f / fps` (30 fps × 25 s = 750 frames).
37
37
  11. Visibility decisions use rounded values: an element whose opacity rounds to
38
38
  0 is dropped, and an opacity that rounds to 1 is omitted, so frames that
39
39
  look identical are byte-identical (`fade()`, `el()` do this).
40
+ 12. Ids come from the instance: anything in `<defs>` (clip path, gradient,
41
+ mask, marker, filter) is named `${idPrefix}-name`, with `idPrefix` from
42
+ `frame(t, { idPrefix })`. Two instances on one page (wide and tall, or the
43
+ same diagram twice) then never share an id. The gate renders with two
44
+ prefixes and refuses an id both share.
40
45
 
41
46
  ## 3. Authoring a timeline
42
47
 
@@ -32,8 +32,8 @@ animated-diagram skill, `references/targets.md`.
32
32
  ```bash
33
33
  mk export spec.json -o out/review --png --qc
34
34
  ```
35
- `index.html` holds the steps, frames 0.2 s before and after each step, a phone-size row and the
36
- review checklist. Fill in the review report (animated-diagram
35
+ `index.html` holds the steps, frames 0.2 s before and after each step, a phone-size row (the
36
+ scene's `tall` layout at 360 px, as a phone shows it) and the review checklist. Fill in the review report (animated-diagram
37
37
  `references/qc.md`) and get a human approval line before delivery.
38
38
 
39
39
  ## Video
@@ -53,6 +53,11 @@ mk build spec.json -o out/page.html -f wide # Craft Page / standalone in
53
53
  mk bake spec.json -o out/diagram.svg -f wide --fps 12 # zero-JS animated SVG
54
54
  ```
55
55
 
56
+ A custom module whose text comes from the caller (a site's dictionary) takes
57
+ scene options: `--options labels.json`, inline JSON, or an `.mjs` whose default
58
+ export is `({ format, locale }) => options`. `check`, `export`, `build`, `bake`,
59
+ `video` and `icon` pass them to the module's factory unchanged.
60
+
56
61
  For plain HTML or a framework-independent live embed, use
57
62
  `mk vendor public/motion-kit --adapter element`, then load
58
63
  `./motion-kit/adapter/motion-diagram.mjs` with `type="module"` and place