@glissade/scene 0.19.0 → 0.20.0-pre.3

package/dist/diagnostics.js

@@ -0,0 +1,384 @@
+import { H as IDENTITY, K as matEquals, L as createDisplayListBuilder, V as collapseReplacer, f as roundedRectSegs, p as Node, r as Group } from "./nodes.js";
+import { a as evaluate } from "./scene.js";
+import { signal, vec2Signal } 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) {
+	const out = {};
+	for (const [k, v] of Object.entries(cmd)) out[k] = v;
+	if (cmd.op === "clip" || cmd.op === "fillPath" || cmd.op === "strokePath") out["path"] = resources[cmd.path];
+	else if (cmd.op === "drawImage") out["image"] = resources[cmd.image];
+	return out;
+}
+const stable = (v) => JSON.stringify(v, collapseReplacer);
+/** Field-level diff of two same-op command views (shallow over top-level props). */
+function diffFields(a, b) {
+	const changes = [];
+	const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const k of keys) {
+		if (k === "op") continue;
+		if (stable(a[k]) !== stable(b[k])) changes.push({
+			path: k,
+			from: a[k],
+			to: b[k]
+		});
+	}
+	return changes;
+}
+/**
+* Index-aligned positional diff of two DisplayLists. Command i in `a` is
+* compared to command i in `b`; trailing commands become `add`/`remove`. A
+* single insert/remove cascades — this is the documented v1 cliff.
+*/
+function diffDisplayLists(a, b) {
+	const deltas = [];
+	const n = Math.max(a.commands.length, b.commands.length);
+	for (let i = 0; i < n; i++) {
+		const ca = a.commands[i];
+		const cb = b.commands[i];
+		if (ca !== void 0 && cb !== void 0) {
+			const va = commandView(ca, a.resources);
+			const vb = commandView(cb, b.resources);
+			if (stable(va) === stable(vb)) continue;
+			if (ca.op !== cb.op) deltas.push({
+				index: i,
+				kind: "change",
+				opA: ca.op,
+				opB: cb.op,
+				fields: [{
+					path: "op",
+					from: ca.op,
+					to: cb.op
+				}]
+			});
+			else deltas.push({
+				index: i,
+				kind: "change",
+				opA: ca.op,
+				opB: cb.op,
+				fields: diffFields(va, vb)
+			});
+		} else if (cb !== void 0) deltas.push({
+			index: i,
+			kind: "add",
+			opB: cb.op,
+			fields: []
+		});
+		else if (ca !== void 0) deltas.push({
+			index: i,
+			kind: "remove",
+			opA: ca.op,
+			fields: []
+		});
+	}
+	const sizeDiffers = a.size.w !== b.size.w || a.size.h !== b.size.h;
+	return {
+		equal: deltas.length === 0 && !sizeDiffers,
+		deltas,
+		...sizeDiffers ? { size: {
+			from: a.size,
+			to: b.size
+		} } : {}
+	};
+}
+/** Human-readable, multi-line rendering of a DisplayDiff (CLI command-tree). */
+function formatDisplayDiff(diff) {
+	if (diff.equal) return "DisplayLists are identical.";
+	const lines = [];
+	if (diff.size) lines.push(`size  ${diff.size.from.w}x${diff.size.from.h} -> ${diff.size.to.w}x${diff.size.to.h}`);
+	for (const d of diff.deltas) if (d.kind === "add") lines.push(`+ [${d.index}] add    ${d.opB ?? "?"}`);
+	else if (d.kind === "remove") lines.push(`- [${d.index}] remove ${d.opA ?? "?"}`);
+	else {
+		const op = d.opA === d.opB ? d.opA : `${d.opA ?? "?"} -> ${d.opB ?? "?"}`;
+		lines.push(`~ [${d.index}] ${op}`);
+		for (const f of d.fields) lines.push(`      ${f.path}: ${stable(f.from)} -> ${stable(f.to)}`);
+	}
+	return lines.join("\n");
+}
+/**
+* The `.dl.json` snapshot interchange schema (DESIGN §7.4). Users commit
+* `.dl.json` baselines, so this carries the SAME break-policy obligation as
+* `Timeline.version` and `SidecarDoc.sidecarVersion`: bump on a breaking shape
+* change. Independent of the API version.
+*/
+const DL_SNAPSHOT_VERSION = 1;
+/**
+* Serialize a DisplayList to a stable `.dl.json` document string (reusing the
+* byte-preserving collapse-replacer). Round-trips through `parseDisplaySnapshot`.
+*/
+function serializeDisplayList(dl) {
+	const snapshot = {
+		dlSnapshotVersion: 1,
+		size: dl.size,
+		commands: dl.commands,
+		resources: dl.resources
+	};
+	return JSON.stringify(snapshot, collapseReplacer, 2);
+}
+var DlSnapshotError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DlSnapshotError";
+	}
+};
+/** Parse a `.dl.json` snapshot back into a DisplayList (validates the version). */
+function parseDisplaySnapshot(json) {
+	const doc = JSON.parse(json);
+	if (doc.dlSnapshotVersion !== 1) throw new DlSnapshotError(`unsupported dlSnapshotVersion ${String(doc.dlSnapshotVersion)}; this build reads 1`);
+	if (!doc.size || !Array.isArray(doc.commands) || !Array.isArray(doc.resources)) throw new DlSnapshotError("malformed .dl.json snapshot (need size, commands[], resources[])");
+	return {
+		size: doc.size,
+		commands: doc.commands,
+		resources: doc.resources
+	};
+}
+//#endregion
+//#region src/cacheColdAudit.ts
+/** Stable string of a DisplayList for comparison (opaque resources collapse to a marker). */
+function hashDisplayList(dl) {
+	return JSON.stringify(dl, collapseReplacer);
+}
+/**
+* Evaluate two fresh scenes from `createScene` at `t` and confirm the
+* DisplayLists are byte-identical. Returns `{ ok: true }` for a pure scene, or
+* `{ ok: false, node }` naming the first divergent node. DEV-only — never on
+* the render hot path.
+*/
+function auditCacheCold(createScene, doc, t) {
+	const warm = createScene();
+	const cold = createScene();
+	const a = evaluate(warm, doc, t);
+	const b = evaluate(cold, doc, t);
+	if (hashDisplayList(a) === hashDisplayList(b)) return { ok: true };
+	const frame = doc.fps !== void 0 ? Math.round(t * doc.fps) : -1;
+	const ctxA = {
+		time: t,
+		frame,
+		measurer: warm.textMeasurer
+	};
+	const ctxB = {
+		time: t,
+		frame,
+		measurer: cold.textMeasurer
+	};
+	let groupFallback;
+	for (const [id, nodeA] of warm.nodes) {
+		const nodeB = cold.nodes.get(id);
+		if (!nodeB) return {
+			ok: false,
+			node: id
+		};
+		const ea = createDisplayListBuilder(warm.size);
+		nodeA.emit(ea, ctxA);
+		const eb = createDisplayListBuilder(cold.size);
+		nodeB.emit(eb, ctxB);
+		const dlA = ea.finish();
+		const dlB = eb.finish();
+		if (hashDisplayList(dlA) === hashDisplayList(dlB)) continue;
+		if (nodeA instanceof Group) {
+			groupFallback ??= id;
+			continue;
+		}
+		const first = diffDisplayLists(dlA, dlB).deltas[0];
+		return {
+			ok: false,
+			node: id,
+			...first !== void 0 ? { delta: first } : {}
+		};
+	}
+	return {
+		ok: false,
+		...groupFallback !== void 0 ? { node: groupFallback } : {}
+	};
+}
+//#endregion
+//#region src/tokenHighlight.ts
+/**
+* Multi-range token highlight: sub-line ranges over a Text node's wordBoxes,
+* each with its OWN animatable fill/opacity/progress/scale — four-color
+* category passes, per-token flips, karaoke-with-color. Design answers from
+* downstream production (the NNDL verification ritual):
+*  - ranges VALIDATE at construction and THROW on copy drift at draw — the
+*    throw is load-bearing (it catches edited copy that no longer matches);
+*    `rematch: true` opts animated text into per-frame re-resolution.
+*  - a range spanning a wrap produces one rect per line segment.
+*  - string matches are whitespace-stripped consecutive box runs and must end
+*    boundary-exact (mid-segment end = error listing the actual segments);
+*    `[wordIndex, wordIndex]` ranges sidestep matching entirely.
+*/
+var TokenMatchError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TokenMatchError";
+	}
+};
+const stripWs = (s) => s.replace(/\s+/g, "");
+/**
+* Find the Nth whitespace-stripped consecutive run of boxes equal to token.
+* Boundary-exact: a run that diverges mid-segment is not a match; ending
+* mid-segment throws (with the real segment list) rather than half-boxing.
+*/
+function matchTokenRun(boxes, token, occurrence = 1) {
+	const want = stripWs(token);
+	if (want.length === 0) throw new TokenMatchError("empty token");
+	let seen = 0;
+	for (let i = 0; i < boxes.length; i++) {
+		let acc = "";
+		for (let j = i; j < boxes.length; j++) {
+			acc += stripWs(boxes[j].text);
+			if (acc === want) {
+				seen++;
+				if (seen === occurrence) return [i, j];
+				break;
+			}
+			if (!want.startsWith(acc)) break;
+		}
+	}
+	throw new TokenMatchError(`no match for token '${token}'${occurrence > 1 ? ` (occurrence ${occurrence})` : ""} — segments are [${boxes.map((b) => `'${b.text}'`).join(", ")}]`);
+}
+var TokenHighlight = class extends Node {
+	target;
+	padding;
+	cornerRadius;
+	rematch;
+	ranges;
+	constructor(props) {
+		super(props);
+		this.target = props.text;
+		this.padding = props.padding ?? [4, 2];
+		this.cornerRadius = props.cornerRadius ?? 4;
+		this.rematch = props.rematch ?? false;
+		const boxes = this.target.wordBoxes();
+		this.ranges = props.ranges.map((spec, index) => {
+			const run = this.resolveRun(boxes, spec);
+			const id = spec.id ?? `r${index}`;
+			const r = {
+				spec,
+				fill: init(signal("#ffe066"), spec.fill),
+				opacity: init(signal(1), spec.opacity),
+				progress: init(signal(1), spec.progress),
+				scale: init(signal(1), spec.scale),
+				offset: initVec(vec2Signal([0, 0]), spec.offset),
+				run,
+				bound: runText(boxes, run)
+			};
+			this.registerTarget(`${id}/fill`, r.fill, "color");
+			this.registerTarget(`${id}/opacity`, r.opacity, "number");
+			this.registerTarget(`${id}/progress`, r.progress, "number");
+			this.registerTarget(`${id}/scale`, r.scale, "number");
+			this.registerTarget(`${id}/offset`, r.offset, "vec2");
+			this.registerTarget(`${id}/offset.x`, r.offset.x, "number");
+			this.registerTarget(`${id}/offset.y`, r.offset.y, "number");
+			return r;
+		});
+	}
+	resolveRun(boxes, spec) {
+		if (typeof spec.match !== "string") {
+			const [from, to] = spec.match;
+			if (from < 0 || to >= boxes.length || from > to) throw new TokenMatchError(`word index range [${from}, ${to}] out of bounds (${boxes.length} boxes)`);
+			return [from, to];
+		}
+		return matchTokenRun(boxes, spec.match, spec.occurrence ?? 1);
+	}
+	draw(out, ctx) {
+		const boxes = this.target.wordBoxes(ctx.measurer);
+		if (boxes.length === 0) return;
+		const tm = this.target.localMatrix();
+		const [px, py] = this.padding;
+		let pushedTransform = false;
+		for (const r of this.ranges) {
+			const opacity = r.opacity();
+			if (opacity <= 0) continue;
+			const progress = Math.min(1, Math.max(0, r.progress()));
+			if (progress <= 0) continue;
+			let run = r.run;
+			if (this.rematch && typeof r.spec.match === "string") run = matchTokenRun(boxes, r.spec.match, r.spec.occurrence ?? 1);
+			else if (runText(boxes, run) !== r.bound) throw new TokenMatchError(`bound token '${r.bound}' no longer matches boxes [${run[0]}, ${run[1]}] — the text changed (segments now [${boxes.slice(run[0], run[1] + 1).map((b) => `'${b.text}'`).join(", ")}]); pass rematch: true for animated text`);
+			const lineRects = [];
+			for (let i = run[0]; i <= run[1]; i++) {
+				const b = boxes[i];
+				const last = lineRects[lineRects.length - 1];
+				const cur = i > run[0] && boxes[i - 1].line === b.line ? last : void 0;
+				if (cur) {
+					cur.w = b.x + b.w + px - cur.x;
+					cur.y = Math.min(cur.y, b.y - py);
+					cur.h = Math.max(cur.h, b.y + b.h + py - cur.y);
+				} else lineRects.push({
+					x: b.x - px,
+					y: b.y - py,
+					w: b.w + 2 * px,
+					h: b.h + 2 * py
+				});
+			}
+			if (!pushedTransform && !matEquals(tm, IDENTITY)) {
+				out.push({
+					op: "transform",
+					m: tm
+				});
+				pushedTransform = true;
+			}
+			const grouped = opacity < 1;
+			if (grouped) out.push({
+				op: "pushGroup",
+				opacity,
+				blend: "source-over",
+				filters: []
+			});
+			const fill = r.fill();
+			const scale = r.scale();
+			const [ox, oy] = r.offset();
+			let remaining = progress * lineRects.reduce((sum, q) => sum + q.w, 0);
+			for (const q of lineRects) {
+				const fillW = Math.min(q.w, remaining);
+				remaining -= fillW;
+				if (fillW <= 0) break;
+				const cx = q.x + q.w / 2 + ox;
+				const cy = q.y + q.h / 2 + oy;
+				const w = fillW * scale;
+				const h = q.h * scale;
+				const x = cx - q.w / 2 * scale;
+				const y = cy - h / 2;
+				const rad = Math.min(this.cornerRadius, w / 2, h / 2);
+				const path = out.resource({
+					kind: "path",
+					segs: roundedRectSegs(x, y, w, h, rad)
+				});
+				out.push({
+					op: "fillPath",
+					path,
+					paint: {
+						kind: "color",
+						color: fill
+					}
+				});
+				if (remaining <= 0) break;
+			}
+			if (grouped) out.push({ op: "popGroup" });
+		}
+	}
+};
+function runText(boxes, run) {
+	return boxes.slice(run[0], run[1] + 1).map((b) => stripWs(b.text)).join("");
+}
+/**
+* `children: [tokenHighlight(para, { ranges: [{ match: '$48,200', fill: cat.money }] }), para]`
+* — each range animates independently via '<id>/<rangeId>/fill|opacity|progress|scale'.
+*/
+function tokenHighlight(text, props) {
+	return new TokenHighlight({
+		...props,
+		text
+	});
+}
+function init(sig, v) {
+	if (typeof v === "function") sig.bindSource(v);
+	else if (v !== void 0) sig.set(v);
+	return sig;
+}
+function initVec(sig, v) {
+	if (typeof v === "function") sig.bindSource(v);
+	else if (v !== void 0) sig.set(v);
+	return sig;
+}
+//#endregion
+export { DL_SNAPSHOT_VERSION, DlSnapshotError, TokenHighlight, TokenMatchError, auditCacheCold, collapseReplacer, diffDisplayLists, formatDisplayDiff, matchTokenRun, parseDisplaySnapshot, serializeDisplayList, tokenHighlight };

package/dist/displayList.d.ts

@@ -46,6 +46,18 @@ interface FontSpec {
   size: number;
   weight?: number;
   style?: 'normal' | 'italic';
+  /**
+   * Variable-font axis settings in CSS `font-variation-settings` form
+   * (e.g. `'"wght" 700, "opsz" 14'`). 0.20 STATIC passthrough: applied on the
+   * Skia/export path (`@napi-rs/canvas` exposes `ctx.fontVariationSettings`),
+   * best-effort in the browser (the DOM 2D context has no such property — a
+   * guarded no-op there). OMITTED for default Text, so a node without axes
+   * emits a byte-identical FontSpec (the golden corpus depends on this).
+   * Animatable axes (a `wght` track) are deferred to 1.0 — the string isn't
+   * lerp-able, and a track targeting `<id>/fontVariationSettings` already
+   * hard-throws `UnboundTargetError` (no signal resolves to it).
+   */
+  fontVariationSettings?: string;
 }
 /**
  * Group filters (§3.4): a CLOSED union — validated data, never a CSS
@@ -183,6 +195,21 @@ interface DisplayListBuilder {
   cacheKey?(start: number, end: number): string | undefined;
   /** Stamp a cacheKey onto the pushGroup already emitted at index `i`. */
   patchCacheKey?(i: number, key: string): void;
+  /**
+   * OUT-OF-BAND node-identity seam (S1, the DOM-backend readiness prerequisite —
+   * see docs/design/dom-backend.md "Seam 1"). `Node.emit` announces the node it
+   * is about to emit (`enterNode(this.id)`) and announces completion
+   * (`exitNode()`) — a strictly LIFO pair around the whole save…restore slice,
+   * so the instrumented builder can attribute each `push` to the emitting node
+   * and produce a positional `NodeIdStream` ALONGSIDE the DisplayList, never
+   * inside it. Both are OPTIONAL: the default `createDisplayListBuilder` does NOT
+   * implement them, so `Node.emit`'s guarded `out.enterNode?.()` /
+   * `out.exitNode?.()` calls are no-ops on the normal evaluate/render path and
+   * every DrawCommand stays byte-identical (the 262-golden contract). Only the
+   * opt-in `emitWithIds` builder (`@glissade/scene/identity`) supplies them.
+   */
+  enterNode?(id: string | undefined): void;
+  exitNode?(): void;
 }
 declare function createDisplayListBuilder(size: {
   w: number;

package/dist/grid.d.ts

@@ -0,0 +1,56 @@
+import { B as NodeProps, i as Group, z as Node } from "./nodes.js";
+
+//#region src/grid.d.ts
+
+declare class GridError extends Error {
+  constructor(message: string);
+}
+/**
+ * A single column track. A bare number is a FIXED px width; `{ fr }` is a
+ * flexible track that shares the leftover width (after fixed tracks + gaps)
+ * proportionally — the CSS `fr` unit. The array form `columns: [1, { fr: 1 }, …]`
+ * mixes them; the scalar form `columns: 3` is sugar for three equal `{ fr: 1 }`.
+ */
+type GridTrack = number | {
+  fr: number;
+};
+interface GridProps extends NodeProps {
+  /**
+   * Column tracks. A number N is sugar for N equal `fr` columns; an array spells
+   * each track (`5` = 5px fixed, `{ fr: 2 }` = a 2-fraction flexible track).
+   */
+  columns: number | readonly GridTrack[];
+  /** The nodes to place, row-major (child[i] → row floor(i/cols), col i%cols). */
+  children?: Node[];
+  /** Gap between columns AND rows (px). Overridden per-axis by columnGap/rowGap. */
+  gap?: number;
+  /** Horizontal gap between columns (px). Defaults to `gap`. */
+  columnGap?: number;
+  /** Vertical gap between rows (px). Defaults to `gap`. */
+  rowGap?: number;
+  /**
+   * Total content width the tracks divide (px). REQUIRED when any `fr` track is
+   * present (an `fr` needs a total to resolve against). Fixed-only track lists
+   * may omit it — the width is then the sum of the fixed tracks + gaps.
+   */
+  width?: number;
+  /**
+   * Row pitch (px) — the center-to-center distance between rows is
+   * `cellHeight + rowGap`. REQUIRED when the children span more than one row.
+   * (v1 is position-only, so the grid does not measure child heights.)
+   */
+  cellHeight?: number;
+}
+/**
+ * Lay `children` out into a column grid and return a `Group` holding them, each
+ * repositioned to its cell center. Center-anchored: the grid's own origin is the
+ * center of its content box, so child positions are symmetric about [0, 0]
+ * (matching every other glissade node's center-anchor convention).
+ *
+ * The children are NOT cloned — their `position` signal is SET to the resolved
+ * cell center (a plain `signal.set`, so a later bind still wins if the author
+ * rebinds it). Pass freshly constructed nodes for a clean, deterministic layout.
+ */
+declare function Grid(props: GridProps): Group;
+//#endregion
+export { Grid, GridError, GridProps, GridTrack };

package/dist/grid.js

@@ -0,0 +1,83 @@
+import { r as Group } from "./nodes.js";
+//#region src/grid.ts
+var GridError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "GridError";
+	}
+};
+/** Resolve the column spec into per-column [centerX] offsets from the grid's left edge. */
+function resolveColumns(spec, columnGap, totalWidth) {
+	const tracks = typeof spec === "number" ? (() => {
+		if (!Number.isInteger(spec) || spec < 1) throw new GridError(`Grid columns must be a positive integer (got ${spec})`);
+		return Array.from({ length: spec }, () => ({ fr: 1 }));
+	})() : [...spec];
+	if (tracks.length === 0) throw new GridError("Grid needs at least one column");
+	const cols = tracks.length;
+	const gapTotal = columnGap * (cols - 1);
+	const fixedTotal = tracks.reduce((s, t) => s + (typeof t === "number" ? t : 0), 0);
+	const frTotal = tracks.reduce((s, t) => s + (typeof t === "number" ? 0 : t.fr), 0);
+	let widths;
+	let width;
+	if (frTotal > 0) {
+		if (totalWidth === void 0) throw new GridError("Grid with fr columns needs an explicit `width` to resolve fractions against");
+		const free = Math.max(0, totalWidth - fixedTotal - gapTotal);
+		widths = tracks.map((t) => typeof t === "number" ? t : free * t.fr / frTotal);
+		width = totalWidth;
+	} else {
+		widths = tracks.map((t) => t);
+		width = totalWidth ?? fixedTotal + gapTotal;
+	}
+	const centers = [];
+	let x = 0;
+	for (let c = 0; c < cols; c++) {
+		centers.push(x + widths[c] / 2);
+		x += widths[c] + columnGap;
+	}
+	return {
+		centers,
+		width
+	};
+}
+/**
+* Lay `children` out into a column grid and return a `Group` holding them, each
+* repositioned to its cell center. Center-anchored: the grid's own origin is the
+* center of its content box, so child positions are symmetric about [0, 0]
+* (matching every other glissade node's center-anchor convention).
+*
+* The children are NOT cloned — their `position` signal is SET to the resolved
+* cell center (a plain `signal.set`, so a later bind still wins if the author
+* rebinds it). Pass freshly constructed nodes for a clean, deterministic layout.
+*/
+function Grid(props) {
+	const { columns, gap = 0, columnGap, rowGap, width, cellHeight } = props;
+	const children = props.children ?? [];
+	const colGap = columnGap ?? gap;
+	const rowGapPx = rowGap ?? gap;
+	const { centers, width: gridWidth } = resolveColumns(columns, colGap, width);
+	const cols = centers.length;
+	const rows = Math.ceil(children.length / cols);
+	if (rows > 1 && cellHeight === void 0) throw new GridError("Grid spanning more than one row needs `cellHeight` (the row pitch) — v1 is position-only and does not measure child heights");
+	const rowPitch = (cellHeight ?? 0) + rowGapPx;
+	const gridHeight = rows > 0 ? rows * (cellHeight ?? 0) + (rows - 1) * rowGapPx : 0;
+	const ox = -gridWidth / 2;
+	const oy = -gridHeight / 2;
+	children.forEach((child, i) => {
+		const col = i % cols;
+		const row = Math.floor(i / cols);
+		const cx = ox + centers[col];
+		const cy = oy + row * rowPitch + (cellHeight ?? 0) / 2;
+		child.position.set([cx, cy]);
+	});
+	return new Group({
+		children,
+		...stripGridOnly(props)
+	});
+}
+/** Strip Grid's own props so the rest (id/position/opacity/…) pass to the Group. */
+function stripGridOnly(props) {
+	const { columns, children, gap, columnGap, rowGap, width, cellHeight, ...nodeProps } = props;
+	return nodeProps;
+}
+//#endregion
+export { Grid, GridError };

package/dist/identity.d.ts

@@ -0,0 +1,33 @@
+import { n as DisplayList } from "./displayList.js";
+import { r as Scene } from "./scene.js";
+import { Timeline } from "@glissade/core";
+
+//#region src/identity.d.ts
+
+/**
+ * The out-of-band identity stream: one optional stable id per DisplayList
+ * command INDEX. Positional, aligned 1:1 with `displayList.commands` — command
+ * *i* was emitted by the node whose explicit id is `ids[i]` (or `undefined` for
+ * a node without one). Because the emit walk is stable + deterministic (the
+ * §3.3 positional discipline `diffDisplayLists` relies on), the stream is stable
+ * across re-emits of an unchanged graph at a given `t`.
+ */
+type NodeIdStream = readonly (string | undefined)[];
+interface EmitWithIdsResult {
+  /** Byte/deep-equal to the normal `evaluate(scene, timeline, t)` DisplayList. */
+  readonly displayList: DisplayList;
+  /** Positional id stream, `ids.length === displayList.commands.length`. */
+  readonly ids: NodeIdStream;
+}
+/**
+ * Opt-in instrumented emit: the SAME pure evaluation as `evaluate(scene, doc, t)`,
+ * but additionally producing the out-of-band `NodeIdStream`. Returns
+ * `{ displayList, ids }`. The `displayList` is byte/deep-equal to `evaluate()`'s
+ * (the producer never alters geometry); `ids` is positional by command index.
+ *
+ * Off the hot path: this is a tree-shakeable subpath; the normal evaluate/render
+ * never touches it, so canvas/export pay nothing.
+ */
+declare function emitWithIds(scene: Scene, doc: Timeline, t: number): EmitWithIdsResult;
+//#endregion
+export { EmitWithIdsResult, NodeIdStream, emitWithIds };

package/dist/identity.js

@@ -0,0 +1,67 @@
+import { L as createDisplayListBuilder } from "./nodes.js";
+import { r as bindScene } from "./scene.js";
+import { evaluateAt } from "@glissade/core";
+//#region src/identity.ts
+/**
+* Wrap a real `DisplayListBuilder` so it records the emitting node's id per
+* command index. It delegates every command/resource to the inner builder
+* UNCHANGED (so the produced DisplayList is byte-identical), and adds only the
+* `enterNode`/`exitNode` seam + an `ids` side array. The inner builder's
+* §3.5 cacheKey methods (mark/cacheKey/patchCacheKey) are forwarded so a
+* `cache:true` node behaves exactly as on the normal path.
+*/
+function instrument(inner) {
+	const ids = [];
+	const stack = [];
+	const builder = {
+		push(cmd) {
+			ids.push(stack.length > 0 ? stack[stack.length - 1] : void 0);
+			inner.push(cmd);
+		},
+		resource(res) {
+			return inner.resource(res);
+		},
+		enterNode(id) {
+			stack.push(id);
+		},
+		exitNode() {
+			stack.pop();
+		},
+		finish() {
+			return inner.finish();
+		},
+		ids
+	};
+	if (inner.mark) builder.mark = () => inner.mark();
+	if (inner.cacheKey) builder.cacheKey = (s, e) => inner.cacheKey(s, e);
+	if (inner.patchCacheKey) builder.patchCacheKey = (i, k) => inner.patchCacheKey(i, k);
+	return builder;
+}
+/**
+* Opt-in instrumented emit: the SAME pure evaluation as `evaluate(scene, doc, t)`,
+* but additionally producing the out-of-band `NodeIdStream`. Returns
+* `{ displayList, ids }`. The `displayList` is byte/deep-equal to `evaluate()`'s
+* (the producer never alters geometry); `ids` is positional by command index.
+*
+* Off the hot path: this is a tree-shakeable subpath; the normal evaluate/render
+* never touches it, so canvas/export pay nothing.
+*/
+function emitWithIds(scene, doc, t) {
+	bindScene(scene, doc);
+	const fps = doc.fps;
+	const ctx = {
+		time: t,
+		frame: fps !== void 0 ? Math.round(t * fps) : -1,
+		measurer: scene.textMeasurer
+	};
+	return evaluateAt(scene.playhead, t, () => {
+		const builder = instrument(createDisplayListBuilder(scene.size));
+		scene.root.emit(builder, ctx);
+		return {
+			displayList: builder.finish(),
+			ids: builder.ids
+		};
+	});
+}
+//#endregion
+export { emitWithIds };