@glissade/scene 0.56.0-pre.0 → 0.57.0-pre.0

package/dist/describe.js

@@ -23,7 +23,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.56.0-pre.0";
+const RAW_VERSION = "0.57.0-pre.0";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /**
 * Parse the documented positional-arg count from a helper `usage` string — the
@@ -582,6 +582,30 @@ const HELPERS = [
 		import: "@glissade/scene/motion",
 		usage: "shake(node: Node, opts: { seed: number, translate?: number, rotate?: number, frequency?: number }): Node"
 	},
+	{
+		name: "particles",
+		summary: "A small SEEDED, BAKED particle emitter (FACTORY, no `new`): composes each() (count fixed slot nodes at `${id}/${i}`) + bake() (seeded physics → position/opacity/scale/rotation tracks on those SAME ids). Every slot is a real node with real tracks → a real exportable Lottie layer, faithful BY CONSTRUCTION (no render-only/custom-draw path). `count` is the MAX-CONCURRENT ring-buffer pool (bounded 200 — over THROWS, never clamps), NOT total emitted; opacity-0-for-the-whole-window slots are pruned so the layer count stays proportional. Seed defaults to hashStr(id); byte-identical run-to-run, a different seed varies. ESCAPE HATCH: `appearance` (any Node/glyph template), `step` (raw per-particle sim), `...` velocity/forces/lifetime. Tree-shakeable (@glissade/scene/motion).",
+		import: "@glissade/scene/motion",
+		usage: "particles(spec: { id, count, box: {w,h}, duration, fps, origin: [fx,fy], lifetime: number | [min,max], velocity: { speed:[min,max], angle:[min,max] (deg) }, appearance: (i, ctx) => Node | { node, opacityOverLife?, scaleOverLife? }, rate?, burst?: number | {at,n}[], seed?, area?, forces?: { gravity?, drag?, wind? }, spin?, opacityOverLife?, scaleOverLife?, step?: (p, dt, rng) => void }): { node: Group, tracks: Track[], end }  —  supply rate and/or burst; count > 200 throws."
+	},
+	{
+		name: "drift",
+		summary: "Particles preset: ambient low-opacity motes floating gently up (a bokeh companion). Continuous low-rate; DEFAULTS to a small max-concurrent count (24) so the exported layer count stays proportional, NOT 200 near-empty layers. `appearance` is the primary control (a themed dot); `...rest` forwards to particles() (velocity/forces/lifetime/step). Factory (no `new`). Tree-shakeable (@glissade/scene/motion).",
+		import: "@glissade/scene/motion",
+		usage: "drift(opts: { box: {w,h}, duration, fps, count?, rate?, origin?, color?, radius?, seed?, id?, ...rest (lifetime/velocity/forces/appearance/step) }): { node: Group, tracks: Track[], end }"
+	},
+	{
+		name: "sparks",
+		summary: "Particles preset: a subtle corporate-safe radial impact burst (win-beat / habit-stamp flourish) — short-life dots thrown outward from origin, shrinking + fading with a touch of gravity. LOW density by default. `...rest` forwards to particles() (the escape-hatch appearance/step/velocity). Factory (no `new`). Tree-shakeable (@glissade/scene/motion).",
+		import: "@glissade/scene/motion",
+		usage: "sparks(origin: [fx,fy], opts: { box: {w,h}, duration, fps, count?, at?, color?, radius?, seed?, id?, ...rest (lifetime/velocity/forces/appearance/step) }): { node: Group, tracks: Track[], end }"
+	},
+	{
+		name: "dispense",
+		summary: "Particles preset: a DIRECTIONAL sparks variant — a small themed sparkle emanating one way at a beat (the vending \"AS ASKED\" flourish ON the drop, not a stream). Directional angle bias + an optional GLYPH node-template. `...rest` forwards to particles(). Factory (no `new`). Tree-shakeable (@glissade/scene/motion).",
+		import: "@glissade/scene/motion",
+		usage: "dispense(origin: [fx,fy], opts: { box: {w,h}, duration, fps, angle?, spread?, glyph?, glyphSize?, glyphFamily?, count?, at?, color?, seed?, id?, ...rest (appearance/step/velocity/forces) }): { node: Group, tracks: Track[], end }"
+	},
 	{
 		name: "valueNoise",
 		summary: "Closed-form smooth value noise: a PURE function of (seed, t) — lerp(rand(⌊t⌋), rand(⌊t⌋+1), smoothstep(fract t)) with core’s seeded hash. No state, no bake; deterministic by construction (byte-identical run-to-run), fps-independent, O(1), seekable — the closed-form sibling of a spring. Range [0,1); center a signed wobble with *2-1. The primitive behind shake + camera shake.",

package/dist/diagnostics.d.ts

@@ -1,7 +1,7 @@
 import { i as DrawCommand, m as Resource, n as DisplayList } from "./displayList.js";
 import { t as collapseReplacer } from "./collapseReplacer.js";
 import { r as Scene } from "./scene.js";
-import { Timeline } from "@glissade/core";
+import { CoverageReport, FontMode, FontUsage, Timeline } from "@glissade/core";
 
 //#region src/displayDiff.d.ts
 
@@ -103,4 +103,43 @@ interface CacheColdResult {
  */
 declare function auditCacheCold(createScene: () => Scene, doc: Timeline, t: number): CacheColdResult;
 //#endregion
-export { type CacheColdResult, type CommandDelta, DL_SNAPSHOT_VERSION, type DisplayDiff, type DlSnapshot, DlSnapshotError, type FieldChange, auditCacheCold, collapseReplacer, diffDisplayLists, formatDisplayDiff, parseDisplaySnapshot, serializeDisplayList };
+//#region src/fontUsage.d.ts
+/** Walk `scene` for Text nodes; one usage per node carrying its full text. */
+declare function collectTextUsages(scene: Scene): FontUsage[];
+/**
+ * Collect font usages from the POST-localize document's STRING tracks (FIX 3,
+ * 0.14 canary). For every `'string'` track whose target node is a Text node,
+ * emit one usage per distinct localized KEY VALUE under that node's fontFamily —
+ * so a localized CJK message bound to a Latin-only font surfaces as an uncovered
+ * glyph. `collectTextUsages` only sees the authored BASE `node.text()`, which is
+ * resolved BEFORE the localized string tracks bind, so it misses this.
+ */
+declare function collectLocalizedTextUsages(scene: Scene, doc: Timeline): FontUsage[];
+/**
+ * Caller-supplied I/O: fetch the raw bytes for a font face URL (the export
+ * paths read a file / fetch a URL; this keeps core pure). Returning undefined
+ * means "could not load" — that family contributes no coverage, surfacing as
+ * missing glyphs (strict) / a dev warning, never a hang.
+ */
+type FontByteLoader = (url: string) => Promise<ArrayBuffer | undefined>;
+interface ValidateSceneFontsOptions {
+  mode?: FontMode;
+  /** OS-installed families to treat as registered (case-insensitive). */
+  osFamilies?: ReadonlySet<string> | undefined;
+  /**
+   * Additional usages to validate alongside the scene's authored Text (FIX 3):
+   * the POST-localize document's localized string-track values, which the
+   * scene-walk can't see (they bind AFTER `node.text()` is read). Build them
+   * with `collectLocalizedTextUsages(scene, localizedDoc)`.
+   */
+  extraUsages?: readonly FontUsage[] | undefined;
+}
+/**
+ * Run §3.6 font validation for a scene + its timeline document. Builds the
+ * registry from `doc.assets`, loads each registered face's cmap via `loadBytes`
+ * (once per family — the first face's URL is enough for coverage), and runs the
+ * pure `validateFonts`. Strict mode throws FontValidationError; dev warns.
+ */
+declare function validateSceneFonts(scene: Scene, doc: Timeline, loadBytes: FontByteLoader, options?: ValidateSceneFontsOptions): Promise<CoverageReport>;
+//#endregion
+export { type CacheColdResult, type CommandDelta, DL_SNAPSHOT_VERSION, type DisplayDiff, type DlSnapshot, DlSnapshotError, type FieldChange, type FontByteLoader, type ValidateSceneFontsOptions, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, diffDisplayLists, formatDisplayDiff, parseDisplaySnapshot, serializeDisplayList, validateSceneFonts };

package/dist/diagnostics.js

@@ -1,5 +1,6 @@
-import { U as createDisplayListBuilder, q as collapseReplacer, r as Group } from "./nodes.js";
+import { U as createDisplayListBuilder, q as collapseReplacer, r as Group, s as Text } from "./nodes.js";
 import { a as evaluate } from "./scene.js";
+import { buildFontRegistry, parseCmap, validateFonts } from "@glissade/core";
 //#region src/displayDiff.ts
 /** A flat, stable JSON value for one command with its resource ids INLINED to content. */
 function commandView(cmd, resources) {
@@ -193,4 +194,82 @@ function auditCacheCold(createScene, doc, t) {
 	};
 }
 //#endregion
-export { DL_SNAPSHOT_VERSION, DlSnapshotError, auditCacheCold, collapseReplacer, diffDisplayLists, formatDisplayDiff, parseDisplaySnapshot, serializeDisplayList };
+//#region src/fontUsage.ts
+/**
+* Scene → font-validation bridge (DESIGN.md §3.6). Core owns the AssetRef,
+* FontRegistry, cmap reader, and the pure validation; this module owns the
+* node-walk (which only `scene` can do) and the I/O seam that loads a font
+* face's bytes so core stays DOM/Node-free.
+*
+* `collectTextUsages` walks every Text node and reads the FULL `.text()` (not
+* the reveal-masked prefix) — coverage is a property of the authored content,
+* independent of the playhead, so it stays out of the pure evaluate() path.
+*/
+/** Walk `scene` for Text nodes; one usage per node carrying its full text. */
+function collectTextUsages(scene) {
+	const out = [];
+	const visit = (node) => {
+		if (node instanceof Text) {
+			const text = node.text();
+			if (text) out.push({
+				family: node.fontFamily,
+				text
+			});
+		}
+		if (node instanceof Group) for (const child of node.children) visit(child);
+	};
+	visit(scene.root);
+	return out;
+}
+/** The node-id of a track target ('<nodeId>/<prop.path>' → '<nodeId>'). */
+function nodeIdOf(target) {
+	const slash = target.indexOf("/");
+	return slash >= 0 ? target.slice(0, slash) : target;
+}
+/**
+* Collect font usages from the POST-localize document's STRING tracks (FIX 3,
+* 0.14 canary). For every `'string'` track whose target node is a Text node,
+* emit one usage per distinct localized KEY VALUE under that node's fontFamily —
+* so a localized CJK message bound to a Latin-only font surfaces as an uncovered
+* glyph. `collectTextUsages` only sees the authored BASE `node.text()`, which is
+* resolved BEFORE the localized string tracks bind, so it misses this.
+*/
+function collectLocalizedTextUsages(scene, doc) {
+	const out = [];
+	for (const tr of doc.tracks) {
+		if (tr.type !== "string") continue;
+		const node = scene.nodes.get(nodeIdOf(tr.target));
+		if (!(node instanceof Text)) continue;
+		for (const k of tr.keys) {
+			const value = k.value;
+			if (typeof value === "string" && value) out.push({
+				family: node.fontFamily,
+				text: value
+			});
+		}
+	}
+	return out;
+}
+/**
+* Run §3.6 font validation for a scene + its timeline document. Builds the
+* registry from `doc.assets`, loads each registered face's cmap via `loadBytes`
+* (once per family — the first face's URL is enough for coverage), and runs the
+* pure `validateFonts`. Strict mode throws FontValidationError; dev warns.
+*/
+async function validateSceneFonts(scene, doc, loadBytes, options = {}) {
+	const mode = options.mode ?? "dev";
+	const registry = buildFontRegistry(doc.assets);
+	const usages = [...collectTextUsages(scene), ...options.extraUsages ?? []];
+	const wanted = /* @__PURE__ */ new Set();
+	for (const u of usages) if (registry.has(u.family)) for (const f of registry.fallbackChain(u.family)) wanted.add(f);
+	const cmaps = /* @__PURE__ */ new Map();
+	for (const family of wanted) {
+		const face = registry.resolveFace(family);
+		if (!face) continue;
+		const bytes = await loadBytes(face.url);
+		if (bytes) cmaps.set(family, parseCmap(bytes));
+	}
+	return validateFonts(usages, registry, cmaps, mode, { ...options.osFamilies !== void 0 ? { osFamilies: options.osFamilies } : {} });
+}
+//#endregion
+export { DL_SNAPSHOT_VERSION, DlSnapshotError, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, diffDisplayLists, formatDisplayDiff, parseDisplaySnapshot, serializeDisplayList, validateSceneFonts };

package/dist/each.d.ts

@@ -0,0 +1,125 @@
+import { B as Node, a as Group } from "./nodes.js";
+import { Rng, Track } from "@glissade/core";
+import { ChannelOverride, Clip } from "@glissade/core/clips";
+
+//#region src/each.d.ts
+
+/** An aspect-fraction placement: [fx, fy], each conventionally in [0, 1]. */
+type Place = readonly [number, number];
+/**
+ * Built-in layouts (a discriminated union — NOT factory fns) plus the escape
+ * hatch `(i, n) => [fx, fy]`. Every built-in is PURE arithmetic in aspect
+ * fractions; mapping to px happens only when `box` is given (see `places`).
+ */
+type EachLayout = {
+  kind: 'row';
+  gap?: number;
+  align?: number;
+} | {
+  kind: 'column';
+  gap?: number;
+  align?: number;
+} | {
+  kind: 'grid';
+  cols: number;
+  rows?: number;
+  gapX?: number;
+  gapY?: number;
+  order?: 'row' | 'column';
+} | {
+  kind: 'ring';
+  radius?: number;
+  center?: Place;
+  startAngle?: number;
+  sweep?: number;
+} | ((i: number, n: number) => Place);
+/** How a `stagger` delay distributes across the clones. */
+type EachDistribute = 'delay' | 'from-center' | 'from-edges';
+/** Per-index motion: a clip fanned across the clones with stagger + jitter. */
+interface EachMotion {
+  /** The motion clip applied to every clone (TYPE: `Clip` from core/clips). */
+  clip: Clip;
+  /** Wall-clock start second of the first clone. Default 0. */
+  startSec?: number;
+  /** Per-index delay (seconds) or a function of the index. Default 0. */
+  stagger?: number | ((i: number) => number);
+  /**
+   * Shape a numeric `stagger` gap into a distribution. `from-center` ramps the
+   * delay outward from the middle clone, `from-edges` inward toward it; `delay`
+   * (the default) is the plain `i * gap` ramp. Ignored when `stagger` is a fn.
+   */
+  distribute?: EachDistribute;
+  /** Per-index clip overrides, seeded — `(i, rng, n) => overrides`. */
+  jitter?: (i: number, rng: Rng, n: number) => Record<string, ChannelOverride>;
+  /** Clip speed (passed straight to `clip.apply`). */
+  speed?: number;
+}
+/** Pixel box for mapping aspect-fraction places to a concrete coordinate frame. */
+interface EachBox {
+  w: number;
+  h: number;
+  /** Top-left of the box in scene coords; default [0, 0]. */
+  origin?: Place;
+}
+interface EachOpts {
+  /** Stable id prefix; clones are `${id}/${i}`, the wrapping group is `${id}`. */
+  id: string;
+  layout: EachLayout;
+  motion?: EachMotion;
+  /** Seed for per-clone RNG; defaults to a stable hash of `id`. */
+  seed?: number;
+  /** When given, `places` also carries the px-mapped points (see EachResult). */
+  box?: EachBox;
+}
+/** The per-clone authoring context handed to the factory. */
+interface EachContext {
+  /** Clone index, 0..n-1. */
+  i: number;
+  /** Total clone count. */
+  n: number;
+  /** This clone's id (`${opts.id}/${i}`). */
+  id: string;
+  /** Aspect-fraction placement [fx, fy] — ALWAYS a fraction (px is separate). */
+  place: Place;
+  /** Seeded generator for this clone: `random(mix(seed, i))`. */
+  rng: Rng;
+  /** The resolved base seed (`opts.seed ?? hash(id)`). */
+  seed: number;
+}
+interface EachResult {
+  /** The wrapping group (`id: opts.id`) holding every generated child. */
+  node: Group;
+  /** The generated children, in index order. */
+  children: Node[];
+  /** The compiled motion tracks (empty when no `motion`). */
+  tracks: Track[];
+  /** Max child clip end (== startSec when no motion). */
+  end: number;
+  /**
+   * Per-clone placement. `frac` is the aspect-fraction [fx, fy] every layout
+   * produces; `px` is present only when `opts.box` was given (frac mapped into
+   * the box). Authoring a `box` once here is the single place fraction→px lives.
+   */
+  places: {
+    frac: Place;
+    px?: Place;
+  }[];
+}
+declare class EachError extends Error {
+  constructor(message: string);
+}
+/**
+ * Generate `n` clones from `factory`, lay them out, and (optionally) stagger a
+ * motion clip across them.
+ *
+ *   const grid = each(9, (i) => new Rect({ width: 40, height: 40, fill: '#9ef0c0' }), {
+ *     id: 'card',
+ *     layout: { kind: 'grid', cols: 3 },
+ *     box: { w: 600, h: 360 },
+ *     motion: { clip: popIn(), stagger: 0.08, distribute: 'from-center' },
+ *   });
+ *   // scene children: [grid.node]; timeline tracks: [...grid.tracks]
+ */
+declare function each(n: number, factory: (i: number, ctx: EachContext) => Node, opts: EachOpts): EachResult;
+//#endregion
+export { EachLayout as a, EachResult as c, EachError as i, Place as l, EachContext as n, EachMotion as o, EachDistribute as r, EachOpts as s, EachBox as t, each as u };

package/dist/each.js

@@ -0,0 +1,168 @@
+import { C as Node, _ as hashStr, r as Group } from "./nodes.js";
+import { random } from "@glissade/core";
+//#region src/each.ts
+/**
+* `each()` — deterministic parametric instancing (0.13 clip-tier sugar). Pure
+* BUILD-TIME fan-out: it generates N scene nodes from a factory, lays them out
+* in aspect-fraction space, and (optionally) staggers a motion `clip` across
+* them — compiling to ordinary keyed `Track[]` plus a `Group` of children with
+* stable `${id}/${i}` ids. Nothing executes at play time; the emitted tracks are
+* byte-indistinguishable from hand-authored ones, so goldens hold by
+* construction and every `--workers` export shard reconstructs the same id set.
+*
+* The clip runtime is imported TYPE-ONLY (the `Clip` instance the author passes
+* carries its own `apply`), so `each` adds no clip bytes to the embed: the
+* `@glissade/core/clips` runtime lands in the consumer's bundle, never scene's.
+*/
+var EachError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EachError";
+	}
+};
+/**
+* Fold a base seed and an index into a fresh per-clone seed. splitmix-style
+* avalanche so adjacent indices decorrelate (a bare `seed + i` would hand
+* near-identical streams to neighbours).
+*/
+function mix(seed, i) {
+	let h = (seed ^ Math.imul(i + 1, 2654435769)) >>> 0;
+	h = Math.imul(h ^ h >>> 16, 569420461);
+	h = Math.imul(h ^ h >>> 15, 1935289751);
+	return (h ^ h >>> 15) >>> 0;
+}
+/**
+* Salt folded into the motion-jitter seed so the per-index jitter rng
+* decorrelates from `ctx.rng` (the factory rng). Both axes derive from
+* `mix(baseSeed, i)`; without a distinct salt they would be the SAME stream,
+* so a factory that draws from `ctx.rng` and a `jitter` callback would see
+* correlated "independent" randomness. An arbitrary fixed odd constant.
+*/
+const JITTER_SALT = 1779033703;
+/** Resolve a built-in layout (or call the escape-hatch fn) to a fraction. */
+function placeAt(layout, i, n) {
+	if (typeof layout === "function") return layout(i, n);
+	switch (layout.kind) {
+		case "row": {
+			const gap = layout.gap ?? (n > 1 ? 1 / (n - 1) : 0);
+			const align = layout.align ?? .5;
+			const x0 = .5 - gap * (n - 1) / 2;
+			return [n === 1 ? .5 : x0 + gap * i, align];
+		}
+		case "column": {
+			const gap = layout.gap ?? (n > 1 ? 1 / (n - 1) : 0);
+			const align = layout.align ?? .5;
+			const y0 = .5 - gap * (n - 1) / 2;
+			return [align, n === 1 ? .5 : y0 + gap * i];
+		}
+		case "grid": {
+			const cols = layout.cols;
+			if (!(cols >= 1)) throw new EachError(`grid layout needs cols >= 1 (got ${cols})`);
+			const rows = layout.rows ?? Math.ceil(n / cols);
+			const order = layout.order ?? "row";
+			const col = order === "row" ? i % cols : Math.floor(i / rows);
+			const row = order === "row" ? Math.floor(i / cols) : i % rows;
+			const gapX = layout.gapX ?? (cols > 1 ? 1 / (cols - 1) : 0);
+			const gapY = layout.gapY ?? (rows > 1 ? 1 / (rows - 1) : 0);
+			const spanX = gapX * (cols - 1);
+			const spanY = gapY * (rows - 1);
+			return [cols === 1 ? .5 : .5 - spanX / 2 + gapX * col, rows === 1 ? .5 : .5 - spanY / 2 + gapY * row];
+		}
+		case "ring": {
+			const radius = layout.radius ?? .5;
+			const [cx, cy] = layout.center ?? [.5, .5];
+			const theta = (layout.startAngle ?? -Math.PI / 2) + (layout.sweep ?? Math.PI * 2) * (n === 0 ? 0 : i / n);
+			return [cx + radius * Math.cos(theta), cy + radius * Math.sin(theta)];
+		}
+	}
+}
+/** Compile a `distribute` mode + numeric gap into a stagger delay fn. */
+function distributeFn(distribute, gap, n) {
+	const mid = (n - 1) / 2;
+	switch (distribute) {
+		case "from-center": return (i) => Math.abs(i - mid) * gap;
+		case "from-edges": return (i) => (mid - Math.abs(i - mid)) * gap;
+		case "delay": return (i) => i * gap;
+	}
+}
+/** Resolve the motion's per-index delay into a plain `(i) => seconds` fn. */
+function staggerFn(motion, n) {
+	const s = motion.stagger ?? 0;
+	if (typeof s === "function") return s;
+	return distributeFn(motion.distribute ?? "delay", s, n);
+}
+/**
+* Generate `n` clones from `factory`, lay them out, and (optionally) stagger a
+* motion clip across them.
+*
+*   const grid = each(9, (i) => new Rect({ width: 40, height: 40, fill: '#9ef0c0' }), {
+*     id: 'card',
+*     layout: { kind: 'grid', cols: 3 },
+*     box: { w: 600, h: 360 },
+*     motion: { clip: popIn(), stagger: 0.08, distribute: 'from-center' },
+*   });
+*   // scene children: [grid.node]; timeline tracks: [...grid.tracks]
+*/
+function each(n, factory, opts) {
+	if (!Number.isInteger(n) || n < 0) throw new EachError(`each() count must be a non-negative integer (got ${n})`);
+	const baseSeed = (opts.seed ?? hashStr(opts.id)) >>> 0;
+	const box = opts.box;
+	const [ox, oy] = box?.origin ?? [0, 0];
+	const children = [];
+	const places = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (let i = 0; i < n; i++) {
+		const id = `${opts.id}/${i}`;
+		const frac = placeAt(opts.layout, i, n);
+		const ctx = {
+			i,
+			n,
+			id,
+			place: frac,
+			rng: random(mix(baseSeed, i)),
+			seed: baseSeed
+		};
+		const child = factory(i, ctx);
+		if (!(child instanceof Node)) throw new EachError(`each() factory must return a Node for index ${i} (got ${typeof child})`);
+		if (seen.has(child)) throw new EachError(`each() factory returned the same Node instance for index ${i} — the factory must construct a new node per index (it is called once per clone)`);
+		seen.add(child);
+		if (child.id === void 0) child.id = id;
+		else if (child.id !== id) throw new EachError(`each() factory set id '${child.id}' on index ${i}, but each owns the id namespace — leave it unset so it becomes '${id}'`);
+		children.push(child);
+		places.push(box ? {
+			frac,
+			px: [ox + frac[0] * box.w, oy + frac[1] * box.h]
+		} : { frac });
+	}
+	const node = new Group({
+		id: opts.id,
+		children
+	});
+	const tracks = [];
+	let end = opts.motion?.startSec ?? 0;
+	if (opts.motion) {
+		const m = opts.motion;
+		const start = m.startSec ?? 0;
+		const at = staggerFn(m, n);
+		for (let i = 0; i < n; i++) {
+			const rngI = random(mix(mix(baseSeed, i), JITTER_SALT));
+			const overrides = m.jitter?.(i, rngI, n);
+			const applyOpts = {
+				...overrides !== void 0 ? { overrides } : {},
+				...m.speed !== void 0 ? { speed: m.speed } : {}
+			};
+			const r = m.clip.apply(`${opts.id}/${i}`, start + at(i), applyOpts);
+			tracks.push(...r.tracks);
+			if (r.end > end) end = r.end;
+		}
+	}
+	return {
+		node,
+		children,
+		tracks,
+		end,
+		places
+	};
+}
+//#endregion
+export { each as n, EachError as t };