@glissade/scene 0.12.1 → 0.13.0-pre.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { $ as breakLines, A as Polyline, At as invert, B as validateHachure, C as Video, Ct as filtersToCanvasFilter, D as revealSchedule, Dt as Mat2x3, E as pathFromSegs, Et as IDENTITY, F as flatten, G as HitArea, H as AnchorSpec, I as hachureLines, J as PropInit, K as Node, L as resolveSketch, M as SketchStyle, Mt as multiply, N as SketchValidationError, O as roundedRectSegs, Ot as applyToPoint, P as arcLength, Q as TextMetricsLite, R as roughen, S as TextProps, St as createDisplayListBuilder, T as WordBox, Tt as validateFilters, U as BindablePropTarget, V as validateSketch, W as EvalContext, X as MEASURE_QUANTUM_PX, Y as resolveAnchor, Z as TextMeasurer, _ as PathProps, _t as Rect$1, a as LayoutEngineMissingError, at as BlendMode, b as ShapeProps, bt as ShaderRef, c as requireLayoutEngine, ct as DrawCommand, d as Custom, dt as FontSpec, et as estimatingMeasurer, f as Group, ft as MeshInterpolation, g as Path, gt as PathSeg, h as LineBox, ht as Paint, i as LayoutEngine, it as setDefaultMeasurer, j as ResolvedSketch, jt as matEquals, k as HachureSpec, kt as fromTRS, l as setLayoutEngine, lt as FilterSpec, m as ImageProps, mt as MeshPoint, n as LayoutChildSpec, nt as segmentGraphemes, ot as DisplayList, p as ImageNode, pt as MeshPaint, q as NodeProps, r as LayoutContainerSpec, rt as segmentWords, s as getLayoutEngine, st as DisplayListBuilder, t as LayoutBox, tt as quantize, u as Circle, ut as FilterValidationError, v as Rect, vt as Resource, w as VideoProps, wt as glow, x as Text, xt as StrokeStyle, y as RevealMark, yt as ResourceId, z as sketchStrokes } from "./layoutEngine.js";
-import { BindableSignal, BoundTimeline, CompiledTimeline, CoverageReport, EaseSpec, FontMode, FontUsage, MeshPaint as MeshPaint$1, PathValue, Playhead, Timeline, Track, Vec2 } from "@glissade/core";
+import { BindableSignal, BoundTimeline, CompiledTimeline, CoverageReport, EaseSpec, FontMode, FontUsage, MeshPaint as MeshPaint$1, PathValue, Playhead, Rng, Timeline, Track, Vec2 } from "@glissade/core";
+import { ChannelOverride, Clip } from "@glissade/core/clips";
 
 //#region src/taxonomy.d.ts
 
@@ -137,6 +138,125 @@ declare function typewriter(target: string, edits: readonly TypeEdit[], opts?: {
   gap?: number;
 }): TypewriterResult;
 //#endregion
+//#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
 //#region src/drawOn.d.ts
 interface DrawOnOptions {
   /** when the stroke-on starts, seconds; default 0 */
@@ -192,12 +312,21 @@ declare function withDeterminismGuards<T>(mode: GuardMode, fn: () => T): T;
  *  - ArrayBuffer / typed-array views collapse to a `ab:<len>` / `view:<len>`
  *    length marker (opaque binary never belongs in a structural key).
  *  - Functions drop (JSON would already drop them; explicit for parity).
+ *  - Non-finite numbers (`NaN`/`Infinity`/`-Infinity`) collapse to DISTINCT
+ *    string sentinels. `JSON.stringify` natively serializes all three to the
+ *    SAME token (`null`), which would collide the cacheKey of two DisplayLists
+ *    that differ only in WHICH non-finite value reaches a draw field — a stale
+ *    raster + an `auditCacheCold` false-OK. The distinct sentinels keep them
+ *    apart. This does NOT touch FINITE numbers (the common path): only the
+ *    three non-finite inputs change, so the §3.5 cacheKey bytes for every real
+ *    (finite) list are byte-identical — pinned by the regression guard.
  *
  * NOTE: `-0` is intentionally NOT normalized here. The matrix layer
  * (`matrix.ts`) already normalizes `-0 → 0` at the source, and adding a `-0`
  * pass to THIS replacer would change the cacheKey bytes for any list that ever
- * carried a raw `-0` — silently invalidating the cache cluster-wide. Byte
- * preservation wins; the regression guard pins the exact key.
+ * carried a raw `-0` — silently invalidating the cache cluster-wide. (`-0` is
+ * finite, so the non-finite branch never touches it.) Byte preservation wins;
+ * the regression guard pins the exact key.
  */
 declare function collapseReplacer(_key: string, value: unknown): unknown;
 /**
@@ -747,4 +876,4 @@ declare function meshRasterSize(bw: number, bh: number): {
   h: number;
 };
 //#endregion
-export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CacheColdResult, type CanvasLike, Circle, ColdAssetError, type CommandDelta, type Ctx2DLike, Custom, DL_SNAPSHOT_VERSION, DeterminismViolationError, type DisplayDiff, type DisplayList, type DisplayListBuilder, type DlSnapshot, DlSnapshotError, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EditMark, type EvalContext, type FieldChange, type FilterKind, type FilterSpec, FilterValidationError, FollowPath, type FollowPathProps, type FontByteLoader, type FontSpec, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, ImageNode as Image, ImageNode, type ImageDataLike, type ImageHandle, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, type Mat2x3, type MeshInterpolation, type MeshPaint, type MeshPoint, NODE_TAXONOMY, Node, type NodeProps, type NodeTypeName, type Paint, Path, type PathLike, type PathProps, type PathSampler, type PathSeg, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type RenderBackend, ReservedNodeIdError, type ResolvedSketch, type Resource, type ResourceId, type RevealMark, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type SketchStyle, SketchValidationError, type StepMark, type StrokeStyle, Text, TextCursor, type TextCursorProps, type TextMeasurer, type TextMetricsLite, type TextProps, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, type TypeEdit, type TypewriterResult, type ValidateSceneFontsOptions, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, collapseReplacer, collectTextUsages, createDisplayListBuilder, createScene, diffDisplayLists, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, formatDisplayDiff, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, meshRasterSize, motionPath, multiply, parseDisplaySnapshot, pathFromSegs, pathLength, pointAtLength, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, serializeDisplayList, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CacheColdResult, type CanvasLike, Circle, ColdAssetError, type CommandDelta, type Ctx2DLike, Custom, DL_SNAPSHOT_VERSION, DeterminismViolationError, type DisplayDiff, type DisplayList, type DisplayListBuilder, type DlSnapshot, DlSnapshotError, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EachBox, type EachContext, type EachDistribute, EachError, type EachLayout, type EachMotion, type EachOpts, type EachResult, type EditMark, type EvalContext, type FieldChange, type FilterKind, type FilterSpec, FilterValidationError, FollowPath, type FollowPathProps, type FontByteLoader, type FontSpec, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, ImageNode as Image, ImageNode, type ImageDataLike, type ImageHandle, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, type Mat2x3, type MeshInterpolation, type MeshPaint, type MeshPoint, NODE_TAXONOMY, Node, type NodeProps, type NodeTypeName, type Paint, Path, type PathLike, type PathProps, type PathSampler, type PathSeg, type Place, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type RenderBackend, ReservedNodeIdError, type ResolvedSketch, type Resource, type ResourceId, type RevealMark, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type SketchStyle, SketchValidationError, type StepMark, type StrokeStyle, Text, TextCursor, type TextCursorProps, type TextMeasurer, type TextMetricsLite, type TextProps, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, type TypeEdit, type TypewriterResult, type ValidateSceneFontsOptions, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, collapseReplacer, collectTextUsages, createDisplayListBuilder, createScene, diffDisplayLists, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, formatDisplayDiff, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, meshRasterSize, motionPath, multiply, parseDisplaySnapshot, pathFromSegs, pathLength, pointAtLength, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, serializeDisplayList, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { A as fallbackMeasurer, B as DL_SNAPSHOT_VERSION, C as validateHachure, D as MEASURE_QUANTUM_PX, E as resolveAnchor, F as FilterValidationError, G as parseDisplaySnapshot, H as collapseReplacer, I as createDisplayListBuilder, J as applyToPoint, K as serializeDisplayList, L as filtersToCanvasFilter, M as segmentGraphemes, N as segmentWords, O as breakLines, P as setDefaultMeasurer, Q as multiply, R as glow, S as sketchStrokes, T as Node, U as diffDisplayLists, V as DlSnapshotError, W as formatDisplayDiff, X as invert, Y as fromTRS, Z as matEquals, _ as arcLength, a as Circle, b as resolveSketch, c as ImageNode, d as Text, f as Video, g as SketchValidationError, h as roundedRectSegs, i as setLayoutEngine, j as quantize, k as estimatingMeasurer, l as Path, m as revealSchedule, n as getLayoutEngine, o as Custom, p as pathFromSegs, q as IDENTITY, r as requireLayoutEngine, s as Group, t as LayoutEngineMissingError, u as Rect, v as flatten, w as validateSketch, x as roughen, y as hachureLines, z as validateFilters } from "./layoutEngine.js";
-import { bindTimeline, buildFontRegistry, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, key, lerpColor, oklabToRgba, parseCmap, parseColor, rgbaToOklab, signal, stagger, track, validateFonts, vec2Signal } from "@glissade/core";
+import { $ as multiply, A as estimatingMeasurer, B as validateFilters, C as sketchStrokes, D as resolveAnchor, E as Node, F as setDefaultMeasurer, G as formatDisplayDiff, H as DlSnapshotError, I as FilterValidationError, J as IDENTITY, K as parseDisplaySnapshot, L as createDisplayListBuilder, M as quantize, N as segmentGraphemes, O as MEASURE_QUANTUM_PX, P as segmentWords, Q as matEquals, R as filtersToCanvasFilter, S as roughen, T as validateSketch, U as collapseReplacer, V as DL_SNAPSHOT_VERSION, W as diffDisplayLists, X as fromTRS, Y as applyToPoint, Z as invert, _ as arcLength, a as Circle, b as hashStr, c as ImageNode, d as Text, f as Video, g as SketchValidationError, h as roundedRectSegs, i as setLayoutEngine, j as fallbackMeasurer, k as breakLines, l as Path, m as revealSchedule, n as getLayoutEngine, o as Custom, p as pathFromSegs, q as serializeDisplayList, r as requireLayoutEngine, s as Group, t as LayoutEngineMissingError, u as Rect, v as flatten, w as validateHachure, x as resolveSketch, y as hachureLines, z as glow } from "./layoutEngine.js";
+import { bindTimeline, buildFontRegistry, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, key, lerpColor, oklabToRgba, parseCmap, parseColor, random, rgbaToOklab, signal, stagger, track, validateFonts, vec2Signal } from "@glissade/core";
 //#region src/taxonomy.ts
 /**
 * The CLOSED node taxonomy (DESIGN.md §3.1): exactly nine built-in node TYPES.
@@ -257,6 +257,163 @@ function typewriter(target, edits, opts = {}) {
 	};
 }
 //#endregion
+//#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;
+}
+/** 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(baseSeed, i));
+			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
 //#region src/drawOn.ts
 /**
 * Whiteboard kit: one-call "draw this shape on" tracks. A stroked or sketched
@@ -404,9 +561,10 @@ function createScene(init) {
 		size: init.size,
 		playhead,
 		resolveTarget: (target) => {
-			const slash = target.indexOf("/");
-			if (slash < 0) return void 0;
-			return nodes.get(target.slice(0, slash))?.resolveTarget(target.slice(slash + 1));
+			for (let slash = target.lastIndexOf("/"); slash > 0; slash = target.lastIndexOf("/", slash - 1)) {
+				const node = nodes.get(target.slice(0, slash));
+				if (node) return node.resolveTarget(target.slice(slash + 1));
+			}
 		},
 		setTextMeasurer: (m) => {
 			measurer.set(m);
@@ -1655,4 +1813,4 @@ var Raster2D = class {
 	}
 };
 //#endregion
-export { ALL_FILTER_KINDS, Circle, ColdAssetError, Custom, DL_SNAPSHOT_VERSION, DeterminismViolationError, DlSnapshotError, DuplicateNodeIdError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, NODE_TAXONOMY, Node, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, collapseReplacer, collectTextUsages, createDisplayListBuilder, createScene, diffDisplayLists, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, formatDisplayDiff, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, meshRasterSize, motionPath, multiply, parseDisplaySnapshot, pathFromSegs, pathLength, pointAtLength, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, serializeDisplayList, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, Circle, ColdAssetError, Custom, DL_SNAPSHOT_VERSION, DeterminismViolationError, DlSnapshotError, DuplicateNodeIdError, EachError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, NODE_TAXONOMY, Node, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, collapseReplacer, collectTextUsages, createDisplayListBuilder, createScene, diffDisplayLists, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, formatDisplayDiff, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, meshRasterSize, motionPath, multiply, parseDisplaySnapshot, pathFromSegs, pathLength, pointAtLength, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, serializeDisplayList, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/layout.js

@@ -1,4 +1,4 @@
-import { A as fallbackMeasurer, i as setLayoutEngine, n as getLayoutEngine, r as requireLayoutEngine, s as Group, t as LayoutEngineMissingError } from "./layoutEngine.js";
+import { i as setLayoutEngine, j as fallbackMeasurer, n as getLayoutEngine, r as requireLayoutEngine, s as Group, t as LayoutEngineMissingError } from "./layoutEngine.js";
 import { computed, signal } from "@glissade/core";
 //#region src/layout.ts
 /**

package/dist/layoutEngine.js

@@ -73,17 +73,30 @@ function matEquals(a, b) {
 *  - ArrayBuffer / typed-array views collapse to a `ab:<len>` / `view:<len>`
 *    length marker (opaque binary never belongs in a structural key).
 *  - Functions drop (JSON would already drop them; explicit for parity).
+*  - Non-finite numbers (`NaN`/`Infinity`/`-Infinity`) collapse to DISTINCT
+*    string sentinels. `JSON.stringify` natively serializes all three to the
+*    SAME token (`null`), which would collide the cacheKey of two DisplayLists
+*    that differ only in WHICH non-finite value reaches a draw field — a stale
+*    raster + an `auditCacheCold` false-OK. The distinct sentinels keep them
+*    apart. This does NOT touch FINITE numbers (the common path): only the
+*    three non-finite inputs change, so the §3.5 cacheKey bytes for every real
+*    (finite) list are byte-identical — pinned by the regression guard.
 *
 * NOTE: `-0` is intentionally NOT normalized here. The matrix layer
 * (`matrix.ts`) already normalizes `-0 → 0` at the source, and adding a `-0`
 * pass to THIS replacer would change the cacheKey bytes for any list that ever
-* carried a raw `-0` — silently invalidating the cache cluster-wide. Byte
-* preservation wins; the regression guard pins the exact key.
+* carried a raw `-0` — silently invalidating the cache cluster-wide. (`-0` is
+* finite, so the non-finite branch never touches it.) Byte preservation wins;
+* the regression guard pins the exact key.
 */
 function collapseReplacer(_key, value) {
 	if (value instanceof ArrayBuffer) return `ab:${value.byteLength}`;
 	if (ArrayBuffer.isView(value)) return `view:${value.byteLength}`;
 	if (typeof value === "function") return void 0;
+	if (typeof value === "number" && !Number.isFinite(value)) {
+		if (Number.isNaN(value)) return "NaN";
+		return value > 0 ? "Infinity" : "-Infinity";
+	}
 	return value;
 }
 /** A flat, stable JSON value for one command with its resource ids INLINED to content. */
@@ -2004,4 +2017,4 @@ function requireLayoutEngine() {
 	return engine;
 }
 //#endregion
-export { fallbackMeasurer as A, DL_SNAPSHOT_VERSION as B, validateHachure as C, MEASURE_QUANTUM_PX as D, resolveAnchor as E, FilterValidationError as F, parseDisplaySnapshot as G, collapseReplacer as H, createDisplayListBuilder as I, applyToPoint as J, serializeDisplayList as K, filtersToCanvasFilter as L, segmentGraphemes as M, segmentWords as N, breakLines as O, setDefaultMeasurer as P, multiply as Q, glow as R, sketchStrokes as S, Node as T, diffDisplayLists as U, DlSnapshotError as V, formatDisplayDiff as W, invert as X, fromTRS as Y, matEquals as Z, arcLength as _, Circle as a, resolveSketch as b, ImageNode as c, Text as d, Video as f, SketchValidationError as g, roundedRectSegs as h, setLayoutEngine as i, quantize as j, estimatingMeasurer as k, Path as l, revealSchedule as m, getLayoutEngine as n, Custom as o, pathFromSegs as p, IDENTITY as q, requireLayoutEngine as r, Group as s, LayoutEngineMissingError as t, Rect as u, flatten as v, validateSketch as w, roughen as x, hachureLines as y, validateFilters as z };
+export { multiply as $, estimatingMeasurer as A, validateFilters as B, sketchStrokes as C, resolveAnchor as D, Node as E, setDefaultMeasurer as F, formatDisplayDiff as G, DlSnapshotError as H, FilterValidationError as I, IDENTITY as J, parseDisplaySnapshot as K, createDisplayListBuilder as L, quantize as M, segmentGraphemes as N, MEASURE_QUANTUM_PX as O, segmentWords as P, matEquals as Q, filtersToCanvasFilter as R, roughen as S, validateSketch as T, collapseReplacer as U, DL_SNAPSHOT_VERSION as V, diffDisplayLists as W, fromTRS as X, applyToPoint as Y, invert as Z, arcLength as _, Circle as a, hashStr as b, ImageNode as c, Text as d, Video as f, SketchValidationError as g, roundedRectSegs as h, setLayoutEngine as i, fallbackMeasurer as j, breakLines as k, Path as l, revealSchedule as m, getLayoutEngine as n, Custom as o, pathFromSegs as p, serializeDisplayList as q, requireLayoutEngine as r, Group as s, LayoutEngineMissingError as t, Rect as u, flatten as v, validateHachure as w, resolveSketch as x, hachureLines as y, glow as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.12.1",
+  "version": "0.13.0-pre.1",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -23,7 +23,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.12.1"
+    "@glissade/core": "0.13.0-pre.1"
   },
   "repository": {
     "type": "git",