@liqweed/motion-kit 0.5.0 → 0.7.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 (41) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.md +17 -2
  4. package/adapters/page/README.md +5 -0
  5. package/cli/motion-kit.mjs +91 -4
  6. package/docs/spec/technique.md +49 -25
  7. package/examples/checkout.json +104 -0
  8. package/examples/connection.json +80 -0
  9. package/examples/custom-pulse.scene.mjs +2 -0
  10. package/examples/player-states.json +97 -0
  11. package/examples/pull-request.json +93 -0
  12. package/examples/pull-request.mmd +15 -0
  13. package/lib/check.mjs +11 -8
  14. package/lib/export.mjs +12 -0
  15. package/lib/gate.mjs +4 -4
  16. package/lib/layout.mjs +236 -0
  17. package/lib/load.mjs +15 -0
  18. package/lib/mermaid.mjs +382 -0
  19. package/lib/outdated.mjs +122 -0
  20. package/package.json +6 -3
  21. package/runtime/links.mjs +5 -1
  22. package/runtime/player.mjs +40 -1
  23. package/runtime/scene.mjs +21 -8
  24. package/runtime/style.mjs +3 -0
  25. package/runtime/types/flowchart.mjs +402 -0
  26. package/runtime/types/hub-spoke.mjs +8 -6
  27. package/runtime/types/index.mjs +5 -0
  28. package/runtime/types/sequence.mjs +8 -6
  29. package/runtime/types/stack.mjs +13 -10
  30. package/runtime/types/timeline.mjs +14 -12
  31. package/runtime/types/walk.mjs +162 -0
  32. package/skills/animated-diagram/SKILL.md +8 -3
  33. package/skills/animated-diagram/references/custom-scenes.md +14 -0
  34. package/skills/animated-diagram/references/ecosystem.md +2 -2
  35. package/skills/animated-diagram/references/interactivity.md +18 -0
  36. package/skills/animated-diagram/references/motion-vocabulary.md +1 -1
  37. package/skills/animated-diagram/references/scene-types.md +118 -6
  38. package/skills/animated-diagram/references/styles.md +11 -2
  39. package/skills/animated-diagram/references/technique.md +6 -2
  40. package/skills/motion-render/SKILL.md +7 -0
  41. package/skills/motion-render/references/video.md +1 -1
@@ -0,0 +1,93 @@
1
+ {
2
+ "type": "flowchart",
3
+ "id": "pull-request",
4
+ "title": "How a pull request lands",
5
+ "description": "A pull request runs CI and review; a failed build or requested changes loop back until it merges and is released.",
6
+ "direction": "down",
7
+ "nodes": [
8
+ {
9
+ "id": "open",
10
+ "label": "Open a PR",
11
+ "shape": "pill",
12
+ "rank": 0,
13
+ "pos": 0.25
14
+ },
15
+ {
16
+ "id": "ci",
17
+ "label": "CI passes?",
18
+ "shape": "decision",
19
+ "rank": 1,
20
+ "pos": 0.25
21
+ },
22
+ {
23
+ "id": "fix",
24
+ "label": "Fix the build",
25
+ "rank": 2,
26
+ "pos": 0
27
+ },
28
+ {
29
+ "id": "review",
30
+ "label": "Approved?",
31
+ "shape": "decision",
32
+ "rank": 2,
33
+ "pos": 1
34
+ },
35
+ {
36
+ "id": "revise",
37
+ "label": "Revise",
38
+ "rank": 3,
39
+ "pos": 0.75
40
+ },
41
+ {
42
+ "id": "merge",
43
+ "label": "Merge",
44
+ "rank": 3,
45
+ "pos": 1.75
46
+ },
47
+ {
48
+ "id": "release",
49
+ "label": "Release",
50
+ "shape": "pill",
51
+ "rank": 4,
52
+ "pos": 1.75
53
+ }
54
+ ],
55
+ "edges": [
56
+ {
57
+ "from": "open",
58
+ "to": "ci"
59
+ },
60
+ {
61
+ "from": "ci",
62
+ "to": "fix",
63
+ "label": "No"
64
+ },
65
+ {
66
+ "from": "fix",
67
+ "to": "ci"
68
+ },
69
+ {
70
+ "from": "ci",
71
+ "to": "review",
72
+ "label": "Yes"
73
+ },
74
+ {
75
+ "from": "review",
76
+ "to": "revise",
77
+ "label": "Changes"
78
+ },
79
+ {
80
+ "from": "revise",
81
+ "to": "review"
82
+ },
83
+ {
84
+ "from": "review",
85
+ "to": "merge",
86
+ "label": "Yes"
87
+ },
88
+ {
89
+ "from": "merge",
90
+ "to": "release"
91
+ }
92
+ ]
93
+ }
@@ -0,0 +1,15 @@
1
+ ---
2
+ title: How a pull request lands
3
+ ---
4
+ %% Source of examples/pull-request.json:
5
+ %% node cli/motion-kit.mjs import examples/pull-request.mmd --out examples/pull-request.json
6
+ flowchart TD
7
+ accDescr: A pull request runs CI and review; a failed build or requested changes loop back until it merges and is released.
8
+ open([Open a PR]) --> ci{CI passes?}
9
+ ci -- No --> fix[Fix the build]
10
+ fix --> ci
11
+ ci -- Yes --> review{Approved?}
12
+ review -->|Changes| revise[Revise]
13
+ revise --> review
14
+ review -->|Yes| merge[Merge]
15
+ merge --> release([Release])
package/lib/check.mjs CHANGED
@@ -8,8 +8,8 @@
8
8
  *
9
9
  * Over files, formats and locales (the CLI and the vendored gate): lib/gate.mjs.
10
10
  */
11
- import { renderSvg } from "../runtime/scene.mjs";
12
- import { checkContrast } from "../runtime/style.mjs";
11
+ import { renderSvg, validateScene } from "../runtime/scene.mjs";
12
+ import { checkContrast, normalizeStyle } from "../runtime/style.mjs";
13
13
 
14
14
  const SAMPLES = 120;
15
15
 
@@ -197,7 +197,10 @@ export const SETTLE_AFTER = Object.freeze([0.001, 0.015, 0.03, 0.045]);
197
197
  */
198
198
  export function checkScene(scene, { samples = SAMPLES, style } = {}) {
199
199
  const problems = [];
200
- const render = (/** @type {number} */ t) => renderSvg(scene, t);
200
+ style = normalizeStyle(style);
201
+ try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)] }; }
202
+ for (const p of checkContrast(style)) problems.push(`contrast: ${p}`);
203
+ const render = (/** @type {number} */ t) => renderSvg(scene, t, { style });
201
204
  const at = (/** @type {number} */ i) => (scene.duration * i) / samples;
202
205
 
203
206
  // 1. Deterministic + well-formed + rounded + token-only, across the timeline,
@@ -212,7 +215,7 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
212
215
  if (wf) problems.push(`malformed at t=${t.toFixed(3)}: ${wf}`);
213
216
  const long = a.match(/-?\d+\.\d{5,}/);
214
217
  if (long) problems.push(`unrounded number ${long[0]} at t=${t.toFixed(3)} (use num())`);
215
- const frame = scene.frame(Math.min(t, scene.duration), { idPrefix: scene.id });
218
+ const frame = scene.frame(Math.min(t, scene.duration), { idPrefix: scene.id, style });
216
219
  const lit = findColourLiteral(frame);
217
220
  if (lit) problems.push(`colour literal ${lit} at t=${t.toFixed(3)} (use tok())`);
218
221
  if (/NaN|undefined|Infinity/.test(frame)) problems.push(`NaN/undefined/Infinity in frame at t=${t.toFixed(3)}`);
@@ -251,10 +254,10 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
251
254
  const lastFrame = render(scene.duration);
252
255
  if (first === lastFrame) problems.push("first and last frame are identical: nothing animates");
253
256
  if (scene.steps[scene.steps.length - 1].at > scene.duration) problems.push("last step is after duration");
254
- if (render(scene.duration + 5) !== lastFrame) problems.push("frames after the end differ from the final frame (must hold)");
257
+ if (scene.frame(scene.duration + 5, { idPrefix: scene.id, style }) !== scene.frame(scene.duration, { idPrefix: scene.id, style })) problems.push("frames after the end differ from the final frame (must hold)");
255
258
 
256
- // 4. Budget: whole scene under ~10 s (design guidance: ≤ 8 s for explainers).
257
- if (scene.duration > 12) problems.push(`duration ${scene.duration.toFixed(1)}s is long for an explainer (≤ 8–10 s)`);
259
+ // 4. Hard limit: 12 s. Authoring target: 8 s; these are distinct.
260
+ if (scene.duration > 12) problems.push(`duration ${scene.duration.toFixed(1)}s exceeds the 12 s limit (aim for ≤ 8 s)`);
258
261
 
259
262
  // 5. Every step label is visible in the final frame (escaped form), unless
260
263
  // the scene declares narrative steps (stepLabelsInFrame: false).
@@ -274,7 +277,7 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
274
277
  // never share one: render with two prefixes and look for common ids.
275
278
  const fixed = new Set();
276
279
  for (let i = 0; i <= samples; i += 10) {
277
- const ids = (/** @type {string} */ prefix) => new Set([...renderSvg(scene, at(i), { idPrefix: prefix }).matchAll(/\sid="([^"]*)"/g)].map((m) => m[1]));
280
+ const ids = (/** @type {string} */ prefix) => new Set([...renderSvg(scene, at(i), { idPrefix: prefix, style }).matchAll(/\sid="([^"]*)"/g)].map((m) => m[1]));
278
281
  const second = ids("mk-gate-b");
279
282
  for (const id of ids("mk-gate-a")) if (second.has(id)) fixed.add(id);
280
283
  }
package/lib/export.mjs CHANGED
@@ -16,6 +16,7 @@
16
16
  * them, unless the new export writes a file of the same name: that one is
17
17
  * overwritten.
18
18
  */
19
+ import { fileURLToPath } from "node:url";
19
20
  import { createHash } from "node:crypto";
20
21
  import { execFileSync } from "node:child_process";
21
22
  import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
@@ -148,7 +149,17 @@ export async function exportSteps(scene, { out, style, theme = "light", png = fa
148
149
  phoneError = e instanceof Error ? e.message : String(e);
149
150
  }
150
151
  }
152
+ // Include the actual runtime bytes, not only its package version: local
153
+ // runtime edits must invalidate an export even before a release is made.
154
+ const runtimeDir = fileURLToPath(new URL("../runtime/", import.meta.url));
155
+ const runtimeDigest = createHash("sha256");
156
+ for (const file of listFiles(runtimeDir).filter((f) => f.endsWith(".mjs"))) {
157
+ runtimeDigest.update(file).update("\0").update(readFileSync(join(runtimeDir, file))).update("\0");
158
+ }
159
+ const runtimeHash = runtimeDigest.digest("hex");
151
160
  const inputHash = createHash("sha256")
161
+ .update(runtimeHash)
162
+ .update(JSON.stringify({ format: scene.format ?? format, locale: scene.locale ?? locale, theme, png, scale, qc, background }))
152
163
  .update(sourceFile ? readFileSync(sourceFile) : scene.frame.toString())
153
164
  .update(JSON.stringify(style ?? "neutral"))
154
165
  .update(JSON.stringify(options ?? null))
@@ -169,6 +180,7 @@ export async function exportSteps(scene, { out, style, theme = "light", png = fa
169
180
  style: style?.name ?? "neutral",
170
181
  theme,
171
182
  inputHash,
183
+ runtimeHash,
172
184
  sourceCommit: source.commit,
173
185
  sourceDirty: source.dirty,
174
186
  render: { png, scale: png ? scale : null, background, qc },
package/lib/gate.mjs CHANGED
@@ -11,7 +11,7 @@
11
11
  * - Every file × format (all of FORMATS unless given) × locale passes
12
12
  * checkScene, which also checks the style against the pairs that scene
13
13
  * declares it draws besides (`scene.contrastPairs`). Locales: the given ones; else, for a spec, every locale its
14
- * strings carry, and `en` for a module.
14
+ * strings carry, and a module’s exported `locales` (default `en`).
15
15
  * - A file that cannot be read, parsed or built is a failure for that file
16
16
  * only; the remaining files are still checked.
17
17
  */
@@ -19,7 +19,7 @@ import { readFileSync } from "node:fs";
19
19
  import { FORMATS } from "../runtime/scene.mjs";
20
20
  import { checkContrast } from "../runtime/style.mjs";
21
21
  import { checkScene } from "./check.mjs";
22
- import { isModule, loadScene } from "./load.mjs";
22
+ import { isModule, loadScene, moduleLocales } from "./load.mjs";
23
23
 
24
24
  /** @param {unknown} e */
25
25
  const message = (e) => (e instanceof Error ? e.message : String(e));
@@ -59,9 +59,9 @@ export async function checkFiles(files, { formats, locales, style, options, log
59
59
  for (const file of files) {
60
60
  const module = isModule(file);
61
61
  let fileLocales = locales?.length ? locales : ["en"];
62
- if (!locales?.length && !module) {
62
+ if (!locales?.length) {
63
63
  try {
64
- fileLocales = detectLocales(JSON.parse(readFileSync(file, "utf8")));
64
+ fileLocales = module ? await moduleLocales(file) : detectLocales(JSON.parse(readFileSync(file, "utf8")));
65
65
  } catch (e) {
66
66
  bad++;
67
67
  error(`✗ ${file}: ${message(e)}`);
package/lib/layout.mjs ADDED
@@ -0,0 +1,236 @@
1
+ // SPDX-License-Identifier: MIT
2
+ // Copyright (c) 2026 Ophir Radnitz
3
+ /**
4
+ * motion-kit · layered graph layout, run once at build time (Node).
5
+ *
6
+ * layered(nodeIds, edges) → { ranks: Map<id, number>, pos: Map<id, number>, via: [rank, pos][][] }
7
+ *
8
+ * A small Sugiyama layout with no dependencies and no randomness, so the same
9
+ * graph always gets the same coordinates:
10
+ *
11
+ * 1. Cycles are broken by reversing the edges a depth-first search (in
12
+ * declaration order) finds going back to a node still on its stack.
13
+ * 2. Ranks: longest path from the sources, then every node that is not a
14
+ * source moves as close to its successors as its predecessors allow.
15
+ * 3. Edges spanning more than one rank get a waypoint on every rank between.
16
+ * 4. Order within a rank: barycenter sweeps down and up, keeping the order with
17
+ * the fewest crossings; ties keep declaration order.
18
+ * 5. Positions: each rank is placed as close as possible to the mean position
19
+ * of its neighbours, with a minimum gap (1 between nodes, less next to and
20
+ * between waypoints), by isotonic regression. Positions start at 0.
21
+ *
22
+ * The scene type maps ranks and positions to pixels per format; it never lays
23
+ * the graph out itself. Positions are in node pitches; ranks are integers.
24
+ */
25
+
26
+ const GAP_NODE = 1;
27
+ const GAP_MIXED = 0.75;
28
+ const GAP_VIA = 0.4;
29
+ const SWEEPS = 12;
30
+ const PLACE_ROUNDS = 8;
31
+
32
+ /**
33
+ * @typedef {{ from: string, to: string }} LayoutEdge
34
+ * @typedef {{ ranks: Map<string, number>, pos: Map<string, number>, via: [number, number][][] }} Layout
35
+ */
36
+
37
+ /**
38
+ * @param {string[]} nodeIds in declaration order
39
+ * @param {LayoutEdge[]} edges no self-loops
40
+ * @returns {Layout}
41
+ */
42
+ export function layered(nodeIds, edges) {
43
+ const index = new Map(nodeIds.map((id, i) => [id, i]));
44
+ const n = nodeIds.length;
45
+ for (const e of edges) {
46
+ if (!index.has(e.from) || !index.has(e.to)) throw new Error(`layout: edge ${e.from} → ${e.to} names an unknown node`);
47
+ if (e.from === e.to) throw new Error(`layout: self-loop on ${e.from}`);
48
+ }
49
+
50
+ // 1. Break cycles: reverse back edges found by a DFS in declaration order.
51
+ const out = nodeIds.map(() => /** @type {number[]} */ ([]));
52
+ edges.forEach((e, i) => out[/** @type {number} */ (index.get(e.from))].push(i));
53
+ const state = new Array(n).fill(0); // 0 new, 1 on stack, 2 done
54
+ const reversed = new Set();
55
+ /** @param {number} v */
56
+ const visit = (v) => {
57
+ state[v] = 1;
58
+ for (const ei of out[v]) {
59
+ const w = /** @type {number} */ (index.get(edges[ei].to));
60
+ if (state[w] === 1) reversed.add(ei);
61
+ else if (state[w] === 0) visit(w);
62
+ }
63
+ state[v] = 2;
64
+ };
65
+ for (let v = 0; v < n; v++) if (state[v] === 0) visit(v);
66
+ // Directed, acyclic edges as [tail, head] node indices.
67
+ const dag = edges.map((e, i) => {
68
+ const a = /** @type {number} */ (index.get(e.from));
69
+ const b = /** @type {number} */ (index.get(e.to));
70
+ return reversed.has(i) ? [b, a] : [a, b];
71
+ });
72
+
73
+ // 2. Ranks: longest path, then pull nodes down toward their successors.
74
+ const preds = nodeIds.map(() => /** @type {number[]} */ ([]));
75
+ const succs = nodeIds.map(() => /** @type {number[]} */ ([]));
76
+ for (const [a, b] of dag) {
77
+ preds[b].push(a);
78
+ succs[a].push(b);
79
+ }
80
+ const rank = new Array(n).fill(-1);
81
+ /** @param {number} v @returns {number} */
82
+ const rankOf = (v) => {
83
+ if (rank[v] < 0) rank[v] = preds[v].length ? Math.max(...preds[v].map(rankOf)) + 1 : 0;
84
+ return rank[v];
85
+ };
86
+ for (let v = 0; v < n; v++) rankOf(v);
87
+ for (let changed = true; changed;) {
88
+ changed = false;
89
+ for (let v = n - 1; v >= 0; v--) {
90
+ if (!preds[v].length || !succs[v].length) continue;
91
+ const best = Math.min(...succs[v].map((w) => rank[w])) - 1;
92
+ if (best > rank[v]) {
93
+ rank[v] = best;
94
+ changed = true;
95
+ }
96
+ }
97
+ }
98
+
99
+ // 3. Chains of waypoints for edges that span ranks. Items: real nodes are
100
+ // 0..n-1; waypoints follow. Each item has a rank.
101
+ /** @type {{ rank: number, node: boolean }[]} */
102
+ const items = rank.map((r) => ({ rank: r, node: true }));
103
+ /** @type {[number, number][]} */
104
+ const links = [];
105
+ /** @type {number[][]} */
106
+ const chains = dag.map(([a, b]) => {
107
+ const chain = [];
108
+ let prev = a;
109
+ for (let r = rank[a] + 1; r < rank[b]; r++) {
110
+ const id = items.length;
111
+ items.push({ rank: r, node: false });
112
+ links.push([prev, id]);
113
+ chain.push(id);
114
+ prev = id;
115
+ }
116
+ links.push([prev, b]);
117
+ return chain;
118
+ });
119
+ const R = Math.max(...rank) + 1;
120
+ const up = items.map(() => /** @type {number[]} */ ([]));
121
+ const down = items.map(() => /** @type {number[]} */ ([]));
122
+ for (const [a, b] of links) {
123
+ down[a].push(b);
124
+ up[b].push(a);
125
+ }
126
+
127
+ // 4. Order within ranks: barycenter sweeps, keep the fewest crossings.
128
+ /** @type {number[][]} */
129
+ let layers = Array.from({ length: R }, () => []);
130
+ items.forEach((it, i) => layers[it.rank].push(i));
131
+ const crossings = (/** @type {number[][]} */ ls) => {
132
+ const at = new Map();
133
+ ls.forEach((l) => l.forEach((v, i) => at.set(v, i)));
134
+ let c = 0;
135
+ for (let r = 0; r + 1 < ls.length; r++) {
136
+ const es = [];
137
+ for (const v of ls[r]) for (const w of down[v]) es.push([at.get(v), at.get(w)]);
138
+ for (let i = 0; i < es.length; i++) for (let j = i + 1; j < es.length; j++) {
139
+ if ((es[i][0] - es[j][0]) * (es[i][1] - es[j][1]) < 0) c++;
140
+ }
141
+ }
142
+ return c;
143
+ };
144
+ let best = layers.map((l) => [...l]);
145
+ let bestC = crossings(best);
146
+ for (let s = 0; s < SWEEPS && bestC > 0; s++) {
147
+ const downward = s % 2 === 0;
148
+ const at = new Map();
149
+ layers.forEach((l) => l.forEach((v, i) => at.set(v, i)));
150
+ const order = downward ? [...layers.keys()].slice(1) : [...layers.keys()].reverse().slice(1);
151
+ for (const r of order) {
152
+ const bary = new Map();
153
+ for (const v of layers[r]) {
154
+ const ns = downward ? up[v] : down[v];
155
+ bary.set(v, ns.length ? ns.reduce((sum, w) => sum + at.get(w), 0) / ns.length : at.get(v));
156
+ }
157
+ layers[r] = [...layers[r]].sort((a, b) => bary.get(a) - bary.get(b) || at.get(a) - at.get(b));
158
+ layers[r].forEach((v, i) => at.set(v, i));
159
+ }
160
+ const c = crossings(layers);
161
+ if (c < bestC) {
162
+ best = layers.map((l) => [...l]);
163
+ bestC = c;
164
+ }
165
+ }
166
+ layers = best;
167
+
168
+ // 5. Positions: pull toward neighbours' mean, keep minimum gaps.
169
+ const gap = (/** @type {number} */ a, /** @type {number} */ b) => (items[a].node && items[b].node ? GAP_NODE : items[a].node || items[b].node ? GAP_MIXED : GAP_VIA);
170
+ const x = new Array(items.length).fill(0);
171
+ for (const l of layers) l.forEach((v, i) => (x[v] = i === 0 ? 0 : x[l[i - 1]] + gap(l[i - 1], v)));
172
+ const centre = (/** @type {number[]} */ l) => (x[l[0]] + x[l[l.length - 1]]) / 2;
173
+ const widest = Math.max(...layers.map((l) => x[l[l.length - 1]] - x[l[0]]));
174
+ for (const l of layers) {
175
+ const shift = widest / 2 - centre(l);
176
+ for (const v of l) x[v] += shift;
177
+ }
178
+ for (let round = 0; round < PLACE_ROUNDS; round++) {
179
+ const downward = round % 2 === 0;
180
+ const order = downward ? [...layers.keys()] : [...layers.keys()].reverse();
181
+ for (const r of order) {
182
+ const l = layers[r];
183
+ const want = l.map((v) => {
184
+ const ns = [...up[v], ...down[v]];
185
+ return ns.length ? ns.reduce((sum, w) => sum + x[w], 0) / ns.length : x[v];
186
+ });
187
+ const placed = placeInOrder(want, l.slice(1).map((v, i) => gap(l[i], v)));
188
+ l.forEach((v, i) => (x[v] = placed[i]));
189
+ }
190
+ }
191
+ // Snap to a quarter-pitch grid, so a chain whose ends sit a hair apart
192
+ // draws straight, then restore the gaps left to right.
193
+ for (const l of layers) {
194
+ l.forEach((v, i) => {
195
+ x[v] = Math.round(x[v] * 4) / 4;
196
+ if (i > 0) x[v] = Math.max(x[v], x[l[i - 1]] + Math.ceil(gap(l[i - 1], v) * 4) / 4);
197
+ });
198
+ }
199
+ const min = Math.min(...x);
200
+ const round2 = (/** @type {number} */ v) => Math.round((v - min) * 100) / 100;
201
+
202
+ const ranks = new Map(nodeIds.map((id, i) => [id, rank[i]]));
203
+ const pos = new Map(nodeIds.map((id, i) => [id, round2(x[i])]));
204
+ const via = chains.map((chain, i) => {
205
+ /** @type {[number, number][]} */
206
+ const pts = chain.map((v) => [items[v].rank, round2(x[v])]);
207
+ return reversed.has(i) ? pts.reverse() : pts;
208
+ });
209
+ return { ranks, pos, via };
210
+ }
211
+
212
+ /**
213
+ * Positions closest (least squares) to `want`, in the same order, with
214
+ * position[i + 1] − position[i] ≥ gaps[i]: pool-adjacent-violators on the
215
+ * gap-shifted targets.
216
+ * @param {number[]} want
217
+ * @param {number[]} gaps
218
+ * @returns {number[]}
219
+ */
220
+ export function placeInOrder(want, gaps) {
221
+ const offset = [0];
222
+ for (const g of gaps) offset.push(offset[offset.length - 1] + g);
223
+ /** @type {{ sum: number, count: number }[]} */
224
+ const blocks = [];
225
+ want.forEach((w, i) => {
226
+ blocks.push({ sum: w - offset[i], count: 1 });
227
+ while (blocks.length > 1 && blocks[blocks.length - 2].sum / blocks[blocks.length - 2].count > blocks[blocks.length - 1].sum / blocks[blocks.length - 1].count) {
228
+ const b = /** @type {{ sum: number, count: number }} */ (blocks.pop());
229
+ blocks[blocks.length - 1].sum += b.sum;
230
+ blocks[blocks.length - 1].count += b.count;
231
+ }
232
+ });
233
+ const out = [];
234
+ for (const b of blocks) for (let k = 0; k < b.count; k++) out.push(b.sum / b.count + offset[out.length]);
235
+ return out;
236
+ }
package/lib/load.mjs CHANGED
@@ -81,3 +81,18 @@ export async function loadOptions(arg) {
81
81
  if (typeof mod.default === "function") return (ctx) => mod.default(ctx);
82
82
  return fixed(mod.default);
83
83
  }
84
+
85
+ /**
86
+ * Locales a custom module promises to ship. Undeclared modules keep the
87
+ * backwards-compatible English default; --locale explicitly overrides this.
88
+ * @param {string} file
89
+ * @returns {Promise<string[]>}
90
+ */
91
+ export async function moduleLocales(file) {
92
+ const mod = await import(pathToFileURL(resolve(file)).href);
93
+ if (mod.locales === undefined) return ["en"];
94
+ if (!Array.isArray(mod.locales) || !mod.locales.length || mod.locales.some((l) => typeof l !== "string" || !/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(l)) || new Set(mod.locales).size !== mod.locales.length) {
95
+ throw new Error(`${file}: locales must be a non-empty array of unique locale tags`);
96
+ }
97
+ return mod.locales;
98
+ }