@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/lib/load.mjs CHANGED
@@ -1,53 +1,83 @@
1
+ // SPDX-License-Identifier: MIT
2
+ // Copyright (c) 2026 Ophir Radnitz
1
3
  /**
2
4
  * motion-kit · load a scene from a spec (.json) or a custom module (.mjs).
3
5
  *
4
6
  * Custom modules: `export default (opts) => scene` with
5
- * opts = { format, locale, kit }. `kit` is the whole runtime in one flat
6
- * namespace (motion, svg, style, scene, wrap), so a scene that lives in
7
- * another repository (a project logo) needs no imports at all:
7
+ * opts = { ...options, format, locale, kit } (runtime/kit.mjs). `options` are
8
+ * the caller's scene options (`--options`), passed unchanged; `kit` is the
9
+ * whole runtime in one flat namespace, so a scene that lives in another
10
+ * repository (a project logo) needs no imports at all:
8
11
  *
9
- * export default ({ kit }) => { const { tok, el, num } = kit; … }
12
+ * export default ({ kit, labels }) => { const { tok, el, num } = kit; … }
10
13
  *
11
14
  * Scenes inside this repo (or a vendored copy) may import the runtime with
12
- * relative paths instead; `motion-kit build` (browser bundle) requires that.
15
+ * relative paths instead.
13
16
  */
14
17
  import { readFileSync } from "node:fs";
15
18
  import { resolve } from "node:path";
16
19
  import { pathToFileURL } from "node:url";
17
- import { validateScene } from "../runtime/scene.mjs";
20
+ import { KIT, sceneFromModule } from "../runtime/kit.mjs";
18
21
  import { normalizeStyle } from "../runtime/style.mjs";
19
22
  import { createScene } from "../runtime/types/index.mjs";
20
- import * as motion from "../runtime/motion.mjs";
21
- import * as scene from "../runtime/scene.mjs";
22
- import * as style from "../runtime/style.mjs";
23
- import * as svg from "../runtime/svg.mjs";
24
- import * as wrap from "../runtime/wrap.mjs";
25
23
 
26
- /** The runtime, flat, handed to custom scene modules as `opts.kit`. */
27
- export const KIT = Object.freeze({ ...motion, ...svg, ...style, ...scene, ...wrap });
24
+ export { KIT };
28
25
 
29
26
  /**
30
27
  * @typedef {{scene: any, spec?: any, kind: "spec" | "module", file: string}} LoadedScene
31
28
  */
29
+ /**
30
+ * Scene options for one format and locale (see loadOptions).
31
+ * @typedef {(ctx: { format: string, locale: string }) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>} OptionsSource
32
+ */
33
+
34
+ /** True for a file the CLI treats as a custom scene module rather than a spec. */
35
+ export function isModule(file) {
36
+ return !file.endsWith(".json");
37
+ }
32
38
 
33
39
  /**
34
40
  * @param {string} file path to a .json spec or an .mjs module
35
- * @param {{format?: string, locale?: string}} [opts]
41
+ * @param {{format?: string, locale?: string, options?: Record<string, unknown>}} [opts]
42
+ * `options` reach a module's factory unchanged; a spec takes none.
36
43
  * @returns {Promise<LoadedScene>}
37
44
  */
38
45
  export async function loadScene(file, opts = {}) {
39
46
  const abs = resolve(file);
40
- if (abs.endsWith(".json")) {
47
+ const { options, ...where } = opts;
48
+ if (!isModule(abs)) {
49
+ if (options != null) throw new Error(`${file}: scene options apply to custom scene modules, not to specs`);
41
50
  const spec = JSON.parse(readFileSync(abs, "utf8"));
42
- return { scene: createScene(spec, opts), spec, kind: "spec", file: abs };
51
+ return { scene: createScene(spec, where), spec, kind: "spec", file: abs };
43
52
  }
44
53
  const mod = await import(pathToFileURL(abs).href);
45
- const make = mod.default;
46
- if (typeof make !== "function") throw new Error(`${file}: default export must be (opts) => scene`);
47
- return { scene: validateScene(make({ ...opts, kit: KIT })), kind: "module", file: abs };
54
+ if (typeof mod.default !== "function") throw new Error(`${file}: default export must be (opts) => scene`);
55
+ return { scene: sceneFromModule(mod.default, { ...where, options }), kind: "module", file: abs };
48
56
  }
49
57
 
50
58
  export function loadStyle(arg) {
51
59
  if (!arg || arg === "neutral") return normalizeStyle("neutral");
52
60
  return normalizeStyle(JSON.parse(readFileSync(resolve(arg), "utf8")));
53
61
  }
62
+
63
+ /**
64
+ * Scene options from `--options`: inline JSON (`{"view":"short"}`), a .json
65
+ * file, or a module whose default export is the options or
66
+ * `({ format, locale }) => options` (to pick a locale's dictionary).
67
+ * @param {string | undefined} arg
68
+ * @returns {Promise<OptionsSource | undefined>}
69
+ */
70
+ export async function loadOptions(arg) {
71
+ if (arg == null) return undefined;
72
+ /** @param {unknown} v */
73
+ const fixed = (v) => {
74
+ if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error(`--options ${arg}: scene options must be a JSON object`);
75
+ return () => /** @type {Record<string, unknown>} */ (v);
76
+ };
77
+ if (arg.trim().startsWith("{")) return fixed(JSON.parse(arg));
78
+ const abs = resolve(arg);
79
+ if (abs.endsWith(".json")) return fixed(JSON.parse(readFileSync(abs, "utf8")));
80
+ const mod = await import(pathToFileURL(abs).href);
81
+ if (typeof mod.default === "function") return (ctx) => mod.default(ctx);
82
+ return fixed(mod.default);
83
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@liqweed/motion-kit",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Deterministic animated diagrams: scenes as pure functions of time, for live pages, slides, baked SVG and video.",
5
5
  "keywords": [
6
6
  "animation",
package/runtime/bake.mjs CHANGED
@@ -16,22 +16,36 @@
16
16
  import { renderSvg } from "./scene.mjs";
17
17
  import { num } from "./svg.mjs";
18
18
 
19
+ /**
20
+ * @param {import("./scene.mjs").Scene} scene
21
+ * @param {{ fps?: number, delay?: number, idPrefix?: string, style?: any, theme?: string, background?: boolean }} [options]
22
+ * idPrefix: prefix for the file's ids (default "mk-bake"); give each baked
23
+ * SVG inlined into one page its own.
24
+ * @returns {string}
25
+ */
19
26
  export function bake(scene, options = {}) {
20
27
  const fps = options.fps ?? 15;
21
28
  const delay = options.delay ?? 0.3;
29
+ const base = options.idPrefix ?? "mk-bake";
22
30
  const total = Math.ceil(scene.duration * fps);
31
+ /** @param {number} t @param {string} idPrefix */
32
+ const render = (t, idPrefix) => renderSvg(scene, t, { ...options, standalone: true, idPrefix });
23
33
  const frames = [];
24
34
  for (let f = 0; f <= total; f++) {
25
35
  const t = Math.min(f / fps, scene.duration);
26
- const inner = innerOf(renderSvg(scene, t, { ...options, standalone: true, idPrefix: "mk-bake" }));
36
+ const inner = innerOf(render(t, base));
27
37
  const last = frames[frames.length - 1];
28
38
  if (last && last.body === inner) last.end = t;
29
39
  else frames.push({ start: t, end: t, body: inner });
30
40
  }
31
- // Each slice lasts until the next one starts.
32
- for (let i = 0; i < frames.length - 1; i++) frames[i].end = frames[i + 1].start;
41
+ // Each slice lasts until the next one starts. Slices sit in one document,
42
+ // so a scene that defines ids gets a prefix per slice.
43
+ for (let i = 0; i < frames.length; i++) {
44
+ if (i < frames.length - 1) frames[i].end = frames[i + 1].start;
45
+ if (/\sid="/.test(frames[i].body)) frames[i].body = innerOf(render(frames[i].start, `${base}-${i + 1}`));
46
+ }
33
47
 
34
- const full = renderSvg(scene, scene.duration, { ...options, standalone: true, idPrefix: "mk-bake" });
48
+ const full = render(scene.duration, base);
35
49
  const open = full.slice(0, full.indexOf(">") + 1);
36
50
  const head = full.slice(open.length, full.indexOf("</desc>") + "</desc>".length);
37
51
  const css = [
@@ -0,0 +1,59 @@
1
+ // SPDX-License-Identifier: MIT
2
+ // Copyright (c) 2026 Ophir Radnitz
3
+ /**
4
+ * motion-kit · custom scene modules.
5
+ *
6
+ * A custom scene module's default export is a factory, `(opts) => scene`, for
7
+ * diagrams no scene type draws. It is called with
8
+ *
9
+ * opts = { ...options, format, locale, kit }
10
+ *
11
+ * - `options`: the caller's serializable scene options, unchanged (text from a
12
+ * site's dictionary, a view to draw). Keys `format`, `locale` and `kit` are
13
+ * reserved.
14
+ * - `format`, `locale`: what to build (see FORMATS).
15
+ * - `kit`: the whole runtime in one flat namespace, so a scene kept in another
16
+ * repository needs no imports: `const { tok, el, num } = kit`.
17
+ *
18
+ * The CLI and the vendored gate (lib/load.mjs) and the Astro adapter, on the
19
+ * server and in the browser, go through sceneFromModule, so one module, given
20
+ * the same options, format and locale, draws the same scene everywhere. A page
21
+ * from `motion-kit build` calls the factory the same way, with the bundled
22
+ * runtime as `kit`, after the CLI built it here once.
23
+ */
24
+ import { ENTRANCE_MAX, SPRING_SETTLE_X, clamp01, cubicBezier, easeIn, easeOut, easeStandard, lerp, linear, progress, splitEdge, springSettleTime, springStep, springTo, stagger, window01 } from "./motion.mjs";
25
+ import { FORMATS, localize, renderSvg, safeId, stepIndex, stepIndexAt, stepTimes, validateScene, withId } from "./scene.mjs";
26
+ import { NEUTRAL, TOKENS, checkContrast, contrast, cssVars, normalizeStyle, resolveTokens, tok } from "./style.mjs";
27
+ import { attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, translate, trimSegment } from "./svg.mjs";
28
+ import { estimateWidth, wrapLabel } from "./wrap.mjs";
29
+
30
+ /**
31
+ * The runtime, flat, handed to custom scene modules as `opts.kit`: the exports
32
+ * of motion, scene, style, svg and wrap (not the scene types or the player).
33
+ * Named imports, because lib/bundle.mjs inlines only that form; a new export
34
+ * in one of those modules is added here (test/runtime.test.mjs checks).
35
+ */
36
+ export const KIT = Object.freeze({
37
+ ...{ ENTRANCE_MAX, SPRING_SETTLE_X, clamp01, cubicBezier, easeIn, easeOut, easeStandard, lerp, linear, progress, splitEdge, springSettleTime, springStep, springTo, stagger, window01 },
38
+ ...{ FORMATS, localize, renderSvg, safeId, stepIndex, stepIndexAt, stepTimes, validateScene, withId },
39
+ ...{ NEUTRAL, TOKENS, checkContrast, contrast, cssVars, normalizeStyle, resolveTokens, tok },
40
+ ...{ attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, translate, trimSegment },
41
+ ...{ estimateWidth, wrapLabel },
42
+ });
43
+
44
+ const RESERVED = ["format", "locale", "kit"];
45
+
46
+ /**
47
+ * Build and validate a scene from a module's default export.
48
+ * @param {unknown} make the module's default export
49
+ * @param {{ format?: string, locale?: string, options?: Record<string, unknown> | null }} [opts]
50
+ * @returns {import("./scene.mjs").Scene}
51
+ */
52
+ export function sceneFromModule(make, { format = "16:9", locale = "en", options } = {}) {
53
+ if (typeof make !== "function") throw new TypeError("a scene module's default export must be (opts) => scene");
54
+ if (options != null && (typeof options !== "object" || Array.isArray(options))) throw new TypeError("scene options must be a plain object");
55
+ for (const key of RESERVED) {
56
+ if (options && Object.hasOwn(options, key)) throw new Error(`scene options must not set "${key}": it is passed separately`);
57
+ }
58
+ return validateScene(make({ ...options, format, locale, kit: KIT }));
59
+ }
@@ -0,0 +1,52 @@
1
+ // SPDX-License-Identifier: MIT
2
+ // Copyright (c) 2026 Ophir Radnitz
3
+ /**
4
+ * motion-kit · per-page bookkeeping for server-rendering adapters.
5
+ *
6
+ * DOM-free decisions an adapter shares: which id an instance gets, and whether
7
+ * the player stylesheet is out yet. The adapter owns where the page state lives
8
+ * (Astro: `Astro.locals`) and what it does with the answer.
9
+ */
10
+ import { safeId } from "./scene.mjs";
11
+
12
+ /**
13
+ * @typedef {{ count: number, ids: Set<string>, css: boolean }} PageState
14
+ */
15
+
16
+ /** @returns {PageState} */
17
+ export function newPageState() {
18
+ return { count: 0, ids: new Set(), css: false };
19
+ }
20
+
21
+ /**
22
+ * Take an id for one instance on the page: the requested one, validated, or a
23
+ * generated one from the scene id and the page's counter. Throws on a malformed
24
+ * or already used id.
25
+ * @param {PageState} page
26
+ * @param {string | undefined | null} requested
27
+ * @param {string} sceneId
28
+ * @returns {string}
29
+ */
30
+ export function claimId(page, requested, sceneId) {
31
+ if (requested != null && safeId(requested) !== requested) throw new Error(`id "${requested}" must be letters, digits, "_" and "-", starting with a letter`);
32
+ let id = requested;
33
+ if (id == null) {
34
+ // Skip ids an explicit request already took.
35
+ do id = safeId(`mk-${sceneId}-${++page.count}`);
36
+ while (page.ids.has(id));
37
+ }
38
+ if (page.ids.has(id)) throw new Error(`id "${id}" is already used on this page; give each instance (the wide and the tall one too) its own`);
39
+ page.ids.add(id);
40
+ return id;
41
+ }
42
+
43
+ /**
44
+ * True once per page: the first caller emits the player stylesheet.
45
+ * @param {PageState} page
46
+ * @returns {boolean}
47
+ */
48
+ export function claimStylesheet(page) {
49
+ if (page.css) return false;
50
+ page.css = true;
51
+ return true;
52
+ }