@glissade/scene 0.60.0 → 0.61.0-pre.1

package/dist/describe.d.ts

@@ -157,12 +157,16 @@ interface SurfaceEntry {
    * `'value'` = a runtime binding on the bundle (a class / function / object);
    * `'type'` = a TS type-only name that erases at runtime (opaque, referenced by
    * signatures); `'diagnostic'` = a runtime AUTHORING-DIAGNOSTIC function
-   * (`critique`/`validateScene`/`resolveAt`/`instanceProps`, 0.60) — a real
-   * `window.glissade.<name>` callable that is PERCEPTION/self-check tooling, not
-   * scene-building surface. An agent BUILDING a scene filters `kind !== 'diagnostic'`;
-   * an agent CRITIQUING a rendered scene filters `kind === 'diagnostic'`.
+   * (`critique`/`validateScene`/`resolveAt`/`instanceProps`/`exportFidelity`) — a
+   * real `window.glissade.<name>` callable that reports PROBLEMS (self-check tooling),
+   * not scene-building surface; `'tool'` (0.61) = a runtime OPERATION function
+   * (`diff`) that transforms/compares scenes and returns a RESULT (a ChangeSet), not
+   * a problem list — distinct from a diagnostic so a consumer never misuses its
+   * output as a defect report. A scalable CATEGORY (diagnostics=problems /
+   * tools=operations / values=authoring surface): an agent BUILDING a scene filters
+   * `kind === 'value'`; a self-check agent filters `kind === 'diagnostic'`.
    */
-  kind: 'value' | 'type' | 'diagnostic';
+  kind: 'value' | 'type' | 'diagnostic' | 'tool';
   /** `true` when it is reachable as `window.glissade.<name>` on the single-file IIFE bundle. */
   iife: boolean;
   /** How to consume it: `'constructor'` needs `new`, `'function'` is a plain call, `'object'` is a value namespace (e.g. `easings`), `'type'` is type-only. */

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.60.0";
+const RAW_VERSION = "0.61.0-pre.1";
 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
@@ -207,9 +207,24 @@ const SURFACE_DIAGNOSTICS = [
 	{
 		name: "instanceProps",
 		arity: 1
+	},
+	{
+		name: "exportFidelity",
+		arity: 1
 	}
 ];
 /**
+* 0.61 machine-readable TOOL functions on `window.glissade` — runtime OPERATIONS
+* that transform/compare scenes and return a RESULT, not a problem list. `diff(a,b)`
+* returns a ChangeSet (the blast-radius of an edit). Marked `kind:'tool'` so a
+* consumer never treats its output as a diagnostic (no severity/defect semantics).
+* `arity` = the documented required positional-arg count.
+*/
+const SURFACE_TOOLS = [{
+	name: "diff",
+	arity: 2
+}];
+/**
 * The opaque, type-ONLY names the API surface references (they erase at runtime —
 * `window.glissade.Paint` is `undefined`). `gs types --global` emits a best-effort
 * alias per name; `gs describe --lint` guards they stay type-only (a type surfaced
@@ -270,6 +285,13 @@ function buildSurface() {
 		form: "function",
 		arity: d.arity
 	});
+	for (const t of SURFACE_TOOLS) out.push({
+		name: t.name,
+		kind: "tool",
+		iife: true,
+		form: "function",
+		arity: t.arity
+	});
 	for (const name of SURFACE_TYPE_ONLY) out.push({
 		name,
 		kind: "type",

package/dist/diagnostics.d.ts

@@ -178,7 +178,7 @@ type DiagnosticSeverity = 'error' | 'warning' | 'info';
  *   a built Scene structurally cannot contain a duplicate id, so validateScene
  *   never reaches this case. Kept for the shared contract / `gs parity` surface.
  */
-type DiagnosticCode = 'UNKNOWN_TARGET' | 'ID_COLLISION' | 'OFF_CANVAS' | 'YOGA_CHILD_POSITION' | 'MEASURER_FALLBACK' | 'TEXT_OVERFLOW' | 'OCCLUSION';
+type DiagnosticCode = 'UNKNOWN_TARGET' | 'ID_COLLISION' | 'OFF_CANVAS' | 'YOGA_CHILD_POSITION' | 'MEASURER_FALLBACK' | 'TEXT_OVERFLOW' | 'OCCLUSION' | 'RENDER_ONLY_EXPORT' | 'LOTTIE_DROP' | 'LOTTIE_APPROXIMATE' | 'ANCHOR_RECENTER' | 'UNEXPLAINED_RESIDUAL' | 'BACKEND_DIVERGE';
 /**
  * 0.60: which enforcement SURFACE produced a diagnostic — distinguishes a CERTAIN
  * static fact (`validateScene`) from a HEURISTIC rendered judgment (`critique`,
@@ -327,4 +327,100 @@ declare function critique(scene: Scene, timeline: Timeline, opts?: CritiqueOptio
  */
 declare function sortDiagnostics(diags: SceneDiagnostic[]): SceneDiagnostic[];
 //#endregion
-export { type CacheColdResult, type CommandDelta, type CritiqueOptions, type CritiqueResult, DIAGNOSTIC_SCHEMA_VERSION, DL_SNAPSHOT_VERSION, type DiagnosticCode, type DiagnosticSeverity, type DiagnosticSource, type DisplayDiff, type DlSnapshot, DlSnapshotError, type FieldChange, type FontByteLoader, type InstancePropState, type SceneDiagnostic, type ValidateSceneFontsOptions, type ValidateSceneResult, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, critique, diffDisplayLists, formatDisplayDiff, instanceProps, levenshtein, nearestId, parseDisplaySnapshot, resolveAt, serializeDisplayList, sortDiagnostics, validateScene, validateSceneFonts };
+//#region src/diff.d.ts
+/** A node reference in the added/removed lists — its id + node type. */
+interface NodeRef {
+  /** the node id (only id-bearing nodes are diffed by identity). */
+  node: string;
+  /** the node's `describeType` (e.g. `'Rect'`, `'Text'`). */
+  type: string;
+}
+/** A composed-world bbox (rendered layer), same shape as critique's geometry. */
+interface Region {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+/**
+ * One change. The `op` tags WHAT KIND of change it is:
+ * - `'moved'` — a node was RE-PARENTED (structural) or its rendered box shifted
+ *   (rendered layer). `from`/`to` are the parent ids (structural) or bboxes.
+ * - `'retargeted'` — a track now points at a different target (its keys are
+ *   unchanged; only `target` moved). `from`/`to` are the old/new target strings.
+ * - `'changed'` — a node prop value, a track's keys, a track's presence, or a
+ *   rendered command field changed. `from`/`to` are the old/new values.
+ */
+type ChangeOp = 'moved' | 'retargeted' | 'changed';
+interface Change {
+  op: ChangeOp;
+  /** the node id this change concerns (node-level changes). */
+  node?: string;
+  /** the track/prop target this change concerns (track-level + prop changes). */
+  target?: string;
+  /** the specific property that changed (e.g. `'position'`, `'keys'`, `'type'`). */
+  property?: string;
+  /** the value BEFORE (in `a`). */
+  from: unknown;
+  /** the value AFTER (in `b`). */
+  to: unknown;
+  /** rendered layer: the composed-world region the change occupies. */
+  region?: Region;
+}
+/**
+ * The typed change-set `diff(a, b)` returns. Programmatically checkable — an agent
+ * asserts `diff == exactly my intended change-set`, never parses a text blob.
+ * `empty` is a convenience (`added=removed=changed=[]`), so `diff(a,a).empty` is
+ * the one-liner clean check.
+ */
+interface ChangeSet {
+  /** nodes present in `b` but not `a` (by id). */
+  added: NodeRef[];
+  /** nodes present in `a` but not `b` (by id). */
+  removed: NodeRef[];
+  /** every moved / retargeted / changed entry, canonically sorted. */
+  changed: Change[];
+  /** true iff `added`, `removed`, and `changed` are all empty. */
+  empty: boolean;
+}
+/** The two sides of a diff — a bound-or-buildable scene + its optional document. */
+interface DiffInput {
+  scene: Scene;
+  timeline?: Timeline;
+}
+interface DiffOptions {
+  /**
+   * ALSO run the rendered (DisplayList) layer at `at` — surfaces VISUAL deltas the
+   * semantic structural layer ignores (a paint that moved, a color that changed
+   * mid-flight). Default false (structural only).
+   */
+  rendered?: boolean;
+  /** the time (seconds) the rendered layer samples. Default 0. */
+  at?: number;
+}
+/**
+ * Diff two scenes (+ optional timelines) into a typed {@link ChangeSet}. Default
+ * is the SEMANTIC structural layer (node tree + timeline); pass `{ rendered: true }`
+ * to also diff the DisplayList at `at`. Pure read; `diff(a, a)` is EMPTY.
+ */
+declare function diff(a: DiffInput, b: DiffInput, opts?: DiffOptions): ChangeSet;
+//#endregion
+//#region src/fidelity.d.ts
+/** exportFidelity result — the CLI-lint `{ hasErrors, diagnostics }` shape. */
+interface ExportFidelityResult {
+  schemaVersion: typeof DIAGNOSTIC_SCHEMA_VERSION;
+  /** true iff any diagnostic is severity `error` — always false here (render-only
+   *  use is a warning, never a build error), kept for shape-parity with the family. */
+  hasErrors: boolean;
+  /** every RENDER_ONLY_EXPORT finding, canonically sorted. */
+  diagnostics: SceneDiagnostic[];
+}
+/**
+ * Statically scan `scene` (+ optional `timeline`, for reveal-track detection) for
+ * render-only features that won't survive Lottie export, aggregating one
+ * RENDER_ONLY_EXPORT warning per affected node. Pure read; a scene with no
+ * render-only feature returns an EMPTY diagnostics list.
+ */
+declare function exportFidelity(scene: Scene, timeline?: Timeline): ExportFidelityResult;
+//#endregion
+export { type CacheColdResult, type Change, type ChangeOp, type ChangeSet, type CommandDelta, type CritiqueOptions, type CritiqueResult, DIAGNOSTIC_SCHEMA_VERSION, DL_SNAPSHOT_VERSION, type DiagnosticCode, type DiagnosticSeverity, type DiagnosticSource, type DiffInput, type DiffOptions, type DisplayDiff, type DlSnapshot, DlSnapshotError, type ExportFidelityResult, type FieldChange, type FontByteLoader, type InstancePropState, type NodeRef, type Region, type SceneDiagnostic, type ValidateSceneFontsOptions, type ValidateSceneResult, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, critique, diff, diffDisplayLists, exportFidelity, formatDisplayDiff, instanceProps, levenshtein, nearestId, parseDisplaySnapshot, resolveAt, serializeDisplayList, sortDiagnostics, validateScene, validateSceneFonts };

package/dist/diagnostics.js

@@ -1,6 +1,7 @@
 import { I as isEstimatingMeasurer, J as collapseReplacer, P as estimatingMeasurer, R as quantize, W as createDisplayListBuilder, Y as IDENTITY, et as multiply, r as Group, s as Text } from "./nodes.js";
 import { a as evaluate, r as bindScene } from "./scene.js";
 import { emitWithIds } from "./identity.js";
+import { i as shakenSpec } from "./shake.js";
 import { buildFontRegistry, compileTimeline, evaluateAt, parseCmap, parseColor, untracked, validateFonts } from "@glissade/core";
 //#region src/displayDiff.ts
 /** A flat, stable JSON value for one command with its resource ids INLINED to content. */
@@ -921,4 +922,401 @@ function sortDiagnostics(diags) {
 	}).map(([d]) => d);
 }
 //#endregion
-export { DIAGNOSTIC_SCHEMA_VERSION, DL_SNAPSHOT_VERSION, DlSnapshotError, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, critique, diffDisplayLists, formatDisplayDiff, instanceProps, levenshtein, nearestId, parseDisplaySnapshot, resolveAt, serializeDisplayList, sortDiagnostics, validateScene, validateSceneFonts };
+//#region src/diff.ts
+/**
+* `diff` takes two `{ scene, timeline }` STATE PAIRS, not two `(scene, timeline)`
+* args like its sibling diagnostics (critique/exportFidelity) — a plausible misuse.
+* Passing a raw `Scene` would fall through to `evaluate` and throw the cryptic
+* "Invalid value used as weak map key"; catch it here with an actionable message.
+*/
+function assertDiffInput(x, which) {
+	if (x !== null && typeof x === "object" && typeof x.scene === "object" && x.scene !== null) return;
+	const looksLikeScene = x !== null && typeof x === "object" && "nodes" in x && "root" in x && typeof x.resolveTarget === "function";
+	throw new TypeError(looksLikeScene ? `diff expects { scene, timeline } state objects (got a Scene) — did you mean diff({ scene, timeline }, { scene, timeline })? (unlike critique/exportFidelity, diff takes two STATE PAIRS, not scene+timeline args)` : `diff's ${which} argument must be a { scene, timeline } state object`);
+}
+/** Stable JSON of any value — object keys sorted so key ORDER never reads as a
+*  change. NaN/Infinity/undefined are normalized to stable sentinels. */
+function canonical(v) {
+	return JSON.stringify(normalize(v));
+}
+function normalize(v) {
+	if (v === void 0) return "\0undef";
+	if (typeof v === "number") return Number.isFinite(v) ? v : `num:${String(v)}`;
+	if (Array.isArray(v)) return v.map(normalize);
+	if (v && typeof v === "object") {
+		const out = {};
+		for (const k of Object.keys(v).sort()) out[k] = normalize(v[k]);
+		return out;
+	}
+	return v;
+}
+function equalValue(a, b) {
+	return canonical(a) === canonical(b);
+}
+/** Collect every id-bearing node's structural facts, keyed by id. */
+function nodeFacts(scene) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [id, node] of scene.nodes) out.set(id, {
+		type: node.describeType,
+		parent: nearestIdedParent(node)
+	});
+	return out;
+}
+/** The id of the nearest id-bearing ancestor (skipping id-less wrappers like a
+*  bare `motionBlur(...)`), or '' at the root. */
+function nearestIdedParent(node) {
+	let p = node.parent;
+	while (p) {
+		if (p.id !== void 0 && p.id !== "__root") return p.id;
+		p = p.parent;
+	}
+	return "";
+}
+/** Read a node's registered animatable targets → the static (or t=0) resolved
+*  value per path. Guarded: a computed prop that throws when read outside a full
+*  render is simply omitted (favor no-spurious over a crash). */
+function propValues(scene, node) {
+	const out = /* @__PURE__ */ new Map();
+	untracked(() => {
+		for (const { path } of node.listTargets()) {
+			const sig = node.resolveTarget(path);
+			if (typeof sig !== "function") continue;
+			try {
+				out.set(path, sig());
+			} catch {}
+		}
+	});
+	return out;
+}
+/** A track's identity-independent value signature (target excluded, so a retarget
+*  is detectable as "same keys, new target"). */
+function trackSignature(track) {
+	return canonical({
+		keys: track.keys,
+		type: track.type,
+		expr: track.expr ?? null
+	});
+}
+/**
+* Diff two scenes (+ optional timelines) into a typed {@link ChangeSet}. Default
+* is the SEMANTIC structural layer (node tree + timeline); pass `{ rendered: true }`
+* to also diff the DisplayList at `at`. Pure read; `diff(a, a)` is EMPTY.
+*/
+function diff(a, b, opts = {}) {
+	assertDiffInput(a, "first");
+	assertDiffInput(b, "second");
+	const added = [];
+	const removed = [];
+	const changed = [];
+	const emptyDoc = {
+		version: 1,
+		tracks: []
+	};
+	const docA = a.timeline ?? emptyDoc;
+	const docB = b.timeline ?? emptyDoc;
+	evaluate(a.scene, docA, 0);
+	evaluate(b.scene, docB, 0);
+	const factsA = nodeFacts(a.scene);
+	const factsB = nodeFacts(b.scene);
+	for (const [id, f] of factsA) if (!factsB.has(id)) removed.push({
+		node: id,
+		type: f.type
+	});
+	for (const [id, f] of factsB) if (!factsA.has(id)) added.push({
+		node: id,
+		type: f.type
+	});
+	const animated = /* @__PURE__ */ new Set();
+	for (const tr of docA.tracks) animated.add(tr.target);
+	for (const tr of docB.tracks) animated.add(tr.target);
+	for (const [id, fa] of factsA) {
+		const fb = factsB.get(id);
+		if (!fb) continue;
+		if (fa.type !== fb.type) {
+			changed.push({
+				op: "changed",
+				node: id,
+				property: "type",
+				from: fa.type,
+				to: fb.type
+			});
+			continue;
+		}
+		if (fa.parent !== fb.parent) changed.push({
+			op: "moved",
+			node: id,
+			from: fa.parent || null,
+			to: fb.parent || null
+		});
+		const nodeA = a.scene.nodes.get(id);
+		const nodeB = b.scene.nodes.get(id);
+		const pvA = propValues(a.scene, nodeA);
+		const pvB = propValues(b.scene, nodeB);
+		for (const [path, va] of pvA) {
+			const target = `${id}/${path}`;
+			if (animated.has(target)) continue;
+			if (!pvB.has(path)) continue;
+			const vb = pvB.get(path);
+			if (!equalValue(va, vb)) changed.push({
+				op: "changed",
+				node: id,
+				property: path,
+				from: va,
+				to: vb
+			});
+		}
+	}
+	diffTracks(docA.tracks, docB.tracks, changed);
+	if (opts.rendered) diffRendered(a.scene, docA, b.scene, docB, opts.at ?? 0, changed);
+	sortChanges(changed);
+	sortRefs(added);
+	sortRefs(removed);
+	return {
+		added,
+		removed,
+		changed,
+		empty: added.length === 0 && removed.length === 0 && changed.length === 0
+	};
+}
+/** Track diff: match by target for keys-change + add/remove, then pair an unmatched
+*  removed target with an unmatched added target of identical signature as a RETARGET. */
+function diffTracks(tracksA, tracksB, changed) {
+	const byTargetA = /* @__PURE__ */ new Map();
+	const byTargetB = /* @__PURE__ */ new Map();
+	for (const t of tracksA) byTargetA.set(t.target, t);
+	for (const t of tracksB) byTargetB.set(t.target, t);
+	const removedTargets = [];
+	const addedTargets = [];
+	for (const [target, ta] of byTargetA) {
+		const tb = byTargetB.get(target);
+		if (!tb) {
+			removedTargets.push(ta);
+			continue;
+		}
+		if (trackSignature(ta) !== trackSignature(tb)) changed.push({
+			op: "changed",
+			target,
+			property: "keys",
+			from: ta.keys,
+			to: tb.keys
+		});
+	}
+	for (const [target, tb] of byTargetB) if (!byTargetA.has(target)) addedTargets.push(tb);
+	removedTargets.sort((x, y) => x.target < y.target ? -1 : x.target > y.target ? 1 : 0);
+	addedTargets.sort((x, y) => x.target < y.target ? -1 : x.target > y.target ? 1 : 0);
+	const usedAdded = /* @__PURE__ */ new Set();
+	for (const rem of removedTargets) {
+		const remSig = trackSignature(rem);
+		let matched = -1;
+		for (let i = 0; i < addedTargets.length; i++) {
+			if (usedAdded.has(i)) continue;
+			if (trackSignature(addedTargets[i]) === remSig) {
+				matched = i;
+				break;
+			}
+		}
+		if (matched >= 0) {
+			usedAdded.add(matched);
+			changed.push({
+				op: "retargeted",
+				target: rem.target,
+				from: rem.target,
+				to: addedTargets[matched].target
+			});
+		} else changed.push({
+			op: "changed",
+			target: rem.target,
+			property: "track",
+			from: "present",
+			to: "absent"
+		});
+	}
+	for (let i = 0; i < addedTargets.length; i++) {
+		if (usedAdded.has(i)) continue;
+		changed.push({
+			op: "changed",
+			target: addedTargets[i].target,
+			property: "track",
+			from: "absent",
+			to: "present"
+		});
+	}
+}
+/** Rendered layer: diff the two DisplayLists at `t` via the shipped
+*  `diffDisplayLists`; translate each field delta into a `changed` entry. */
+function diffRendered(sceneA, docA, sceneB, docB, t, changed) {
+	const d = diffDisplayLists(evaluate(sceneA, docA, t), evaluate(sceneB, docB, t));
+	if (d.equal) return;
+	for (const delta of d.deltas) if (delta.kind === "add") changed.push({
+		op: "changed",
+		property: `render:command[${delta.index}]`,
+		from: "absent",
+		to: delta.opB ?? "present"
+	});
+	else if (delta.kind === "remove") changed.push({
+		op: "changed",
+		property: `render:command[${delta.index}]`,
+		from: delta.opA ?? "present",
+		to: "absent"
+	});
+	else for (const fc of delta.fields) changed.push({
+		op: "changed",
+		property: `render:command[${delta.index}].${fc.path}`,
+		from: fc.from,
+		to: fc.to
+	});
+}
+function sortRefs(refs) {
+	refs.sort((a, b) => a.node < b.node ? -1 : a.node > b.node ? 1 : 0);
+}
+/** Canonical change order: by (target||node) key, then op, then property, then a
+*  value tiebreak — so a shuffled emission order sorts to the same sequence
+*  (assert sort-invariance). Sorts `changed` IN PLACE. */
+function sortChanges(changed) {
+	const keyOf = (c) => c.target ?? c.node ?? "";
+	const paired = changed.map((c, i) => [c, i]);
+	paired.sort((A, B) => {
+		const [a, ai] = A;
+		const [b, bi] = B;
+		const ka = keyOf(a);
+		const kb = keyOf(b);
+		if (ka !== kb) return ka < kb ? -1 : 1;
+		if (a.op !== b.op) return a.op < b.op ? -1 : 1;
+		const pa = a.property ?? "";
+		const pb = b.property ?? "";
+		if (pa !== pb) return pa < pb ? -1 : 1;
+		const va = canonical(a.to);
+		const vb = canonical(b.to);
+		if (va !== vb) return va < vb ? -1 : 1;
+		return ai - bi;
+	});
+	const sorted = paired.map(([c]) => c);
+	for (let i = 0; i < sorted.length; i++) changed[i] = sorted[i];
+}
+//#endregion
+//#region src/fidelity.ts
+/** Per-feature actionable hint tail (after the "won't survive Lottie export" clause). */
+const HINT = {
+	"motion-blur": "the round-trip shows the un-blurred shape; if export-bound, pre-bake the blur into keyframed copies or accept the loss",
+	"echo-trails": "only the base shape exports (no ghost copies); if export-bound, bake the trail into real staggered layers or accept the loss",
+	shake: "the closed-form jitter is not a keyframe track; if export-bound, bake() the shake into position/rotation tracks or accept the loss",
+	"camera-shake": "whole-frame camera shake is not exported; if export-bound, bake it into the camera pose tracks or accept the loss",
+	"text-cursor": "the caret sibling is not exportable and is dropped; if export-bound, drop the cursor or accept the loss",
+	reveal: "Lottie has no range selector, so the FULL text shows on the round-trip; if export-bound, use per-word/line reveal tracks (revealWords/revealLines) or accept the loss",
+	"mesh-fill": "a mesh fill has no Lottie gradient ramp; if export-bound, thread a PNG encoder to rasterize it (gs render does), use a solid/linear/radial fill, or accept the loss"
+};
+function label(feature) {
+	switch (feature) {
+		case "motion-blur": return "motionBlur";
+		case "echo-trails": return "echo trails";
+		case "shake": return "shake() jitter";
+		case "camera-shake": return "camera shake";
+		case "text-cursor": return "a text cursor";
+		case "reveal": return "a typewriter reveal mask";
+		case "mesh-fill": return "a mesh fill";
+	}
+}
+/**
+* Statically scan `scene` (+ optional `timeline`, for reveal-track detection) for
+* render-only features that won't survive Lottie export, aggregating one
+* RENDER_ONLY_EXPORT warning per affected node. Pure read; a scene with no
+* render-only feature returns an EMPTY diagnostics list.
+*/
+function exportFidelity(scene, timeline) {
+	const diagnostics = [];
+	const revealTargets = /* @__PURE__ */ new Set();
+	if (timeline) {
+		for (const tr of timeline.tracks) if (/\/reveal(Fraction)?$/.test(tr.target)) revealTargets.add(tr.target);
+	}
+	const push = (node, feature) => {
+		const id = displayId(node);
+		diagnostics.push({
+			schemaVersion: 1,
+			code: "RENDER_ONLY_EXPORT",
+			severity: "warning",
+			source: "parity",
+			...node.id !== void 0 ? { node: node.id } : {},
+			message: `${label(feature)} on '${id}' is render-only — won't survive Lottie export (${HINT[feature]}).`,
+			detail: {
+				feature,
+				node: id,
+				...node.id !== void 0 ? {} : { unnamed: true }
+			}
+		});
+	};
+	untracked(() => {
+		const visit = (node) => {
+			const type = node.describeType;
+			if (type === "MotionBlur") push(node, "motion-blur");
+			else if (type === "Echo") push(node, "echo-trails");
+			else if (type === "TextCursor") push(node, "text-cursor");
+			else if (type === "Camera") {
+				if (node.shakeSpec !== void 0) push(node, "camera-shake");
+			} else if (shakenSpec(node) !== void 0) push(node, "shake");
+			if (type === "Text") {
+				const id = node.id;
+				const hasRevealTrack = id !== void 0 && (revealTargets.has(`${id}/reveal`) || revealTargets.has(`${id}/revealFraction`));
+				const rf = readNumber(node, "revealFraction");
+				const rv = readNumber(node, "reveal");
+				if (hasRevealTrack || rf !== void 0 && !Number.isNaN(rf) || rv !== void 0 && Number.isFinite(rv)) push(node, "reveal");
+			}
+			const fill = node.fill;
+			if (typeof fill === "function") try {
+				const v = fill();
+				if (v && typeof v === "object" && v.kind === "mesh") push(node, "mesh-fill");
+			} catch {}
+			if (node instanceof Group) for (const c of node.children) visit(c);
+			else {
+				const children = node.children;
+				if (Array.isArray(children)) for (const c of children) visit(c);
+			}
+		};
+		visit(scene.root);
+	});
+	return {
+		schemaVersion: 1,
+		hasErrors: false,
+		diagnostics: sortFidelity(diagnostics)
+	};
+}
+/** Canonical order — by node id, then feature (detail.feature). Shuffle-stable. */
+function sortFidelity(diags) {
+	const featureOf = (d) => String(d.detail?.feature ?? "");
+	return diags.map((d, i) => [d, i]).sort((A, B) => {
+		const [a, ai] = A;
+		const [b, bi] = B;
+		const na = String(a.detail?.node ?? a.node ?? "");
+		const nb = String(b.detail?.node ?? b.node ?? "");
+		if (na !== nb) return na < nb ? -1 : 1;
+		const fa = featureOf(a);
+		const fb = featureOf(b);
+		if (fa !== fb) return fa < fb ? -1 : 1;
+		return ai - bi;
+	}).map(([d]) => d);
+}
+/** A readable id for a node: its own id, else the first id-bearing descendant
+*  (a wrapper like `motionBlur(rect)` reports the wrapped child), else its type. */
+function displayId(node) {
+	if (node.id !== void 0) return node.id;
+	const stack = [node];
+	while (stack.length) {
+		const n = stack.shift();
+		if (n !== node && n.id !== void 0) return n.id;
+		const children = n.children;
+		if (Array.isArray(children)) stack.push(...children);
+	}
+	return `<${node.describeType}>`;
+}
+/** Read a node's numeric signal by prop name under untracked, or undefined. */
+function readNumber(node, prop) {
+	const sig = node[prop];
+	if (typeof sig !== "function") return void 0;
+	try {
+		const v = sig();
+		return typeof v === "number" ? v : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { DIAGNOSTIC_SCHEMA_VERSION, DL_SNAPSHOT_VERSION, DlSnapshotError, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, critique, diff, diffDisplayLists, exportFidelity, formatDisplayDiff, instanceProps, levenshtein, nearestId, parseDisplaySnapshot, resolveAt, serializeDisplayList, sortDiagnostics, validateScene, validateSceneFonts };

package/dist/motion.js

@@ -1,127 +1,8 @@
 import { C as Node, Z as fromTRS, _ as hashStr, et as multiply, r as Group, s as Text, t as Circle } from "./nodes.js";
+import { i as shakenSpec, n as shakeMatrix, r as shakeOffset, t as shake } from "./shake.js";
 import { a as FollowPath, c as pathLength, i as orientToPath, l as pointAtLength, n as OrientToPath, o as followPath, r as lookAt, s as motionPath, t as LookAt } from "./orient.js";
 import { n as each } from "./each.js";
-import { bake, signal, valueNoise, vec2Signal } from "@glissade/core";
-//#region src/shake.ts
-/**
-* `shake` (0.55) — a standalone jitter driver that wobbles ANY node's pose with
-* deterministic value noise. It subsumes the hand-rolled per-element jitters
-* (desk-cursor jitterX/Y, glitch shakeAmp, typewriter jitterRate) behind one
-* primitive with SEPARATE translate / rotate / frequency amplitudes.
-*
-* The jitter is realized AT EMIT (the Echo/MotionBlur idiom): `shake` overrides
-* the node's `emit` to wrap it in a save → shake-transform → emit → restore, where
-* the transform is a pure function of `ctx.time` via `valueNoise` — so it composes
-* on top of WHATEVER already drives the node (keyframes, layout, followPath) as a
-* parent-space offset, and stays byte-identical across two `evaluate()` passes (no
-* cross-frame state, no `Date.now`/`Math.random`). The camera whole-frame shake
-* reuses {@link shakeOffset} directly on its pose.
-*
-* Lives on `@glissade/scene/motion` (off the base embed). Note (like Echo/
-* MotionBlur, both emit-time re-eval): the offset is not a Timeline TRACK, so it
-* is a runtime/render effect — it is NOT emitted as animated Lottie keyframes.
-*/
-/** Default temporal frequency (noise cycles per second) when `frequency` is unset. */
-const DEFAULT_FREQUENCY = 8;
-const K_Y = 101;
-const K_ROT = 211;
-/** Signed value noise in [-1, 1) — the bipolar form a shake offset needs. */
-function snoise(seed, t) {
-	return valueNoise(seed, t) * 2 - 1;
-}
-/**
-* Render-INVISIBLE marker: which nodes a {@link shake} driver is applied to, and
-* with what spec. The render path NEVER reads this (shake works purely by wrapping
-* `emit`), so it is byte-neutral for goldens — it exists ONLY so an EXPORTER
-* (which reads signals, not `emit`) can detect the render-only jitter and warn
-* honestly instead of silently dropping it. A WeakMap keeps it off the Node type.
-*/
-const SHAKEN = /* @__PURE__ */ new WeakMap();
-/** The shake spec applied to `node` via {@link shake}, or undefined — the seam an
-*  exporter uses to emit an honest "shake is render-only" warn (never a silent drop). */
-function shakenSpec(node) {
-	return SHAKEN.get(node);
-}
-/**
-* The pure per-time shake offset for a spec: `{ dx, dy }` px + `dr` degrees, each
-* a deterministic function of `(seed, t)`. Both the {@link shake} node driver and
-* the Camera whole-frame shake fold this in.
-*/
-function shakeOffset(spec, t) {
-	const tr = spec.translate ?? 0;
-	const rot = spec.rotate ?? 0;
-	const tf = t * (spec.frequency ?? DEFAULT_FREQUENCY);
-	return {
-		dx: tr === 0 ? 0 : tr * snoise(spec.seed, tf),
-		dy: tr === 0 ? 0 : tr * snoise(spec.seed + K_Y, tf),
-		dr: rot === 0 ? 0 : rot * snoise(spec.seed + K_ROT, tf)
-	};
-}
-/**
-* A shake transform about the point `p` (parent space): translate by `(dx, dy)`
-* then rotate `dr` degrees about `p`, so a rotational jitter spins the node around
-* its own origin rather than the parent's.
-*/
-function shakeMatrix(p, dx, dy, dr) {
-	const translate = [
-		1,
-		0,
-		0,
-		1,
-		dx,
-		dy
-	];
-	if (dr === 0) return translate;
-	const toP = [
-		1,
-		0,
-		0,
-		1,
-		p[0],
-		p[1]
-	];
-	const fromP = [
-		1,
-		0,
-		0,
-		1,
-		-p[0],
-		-p[1]
-	];
-	return multiply(translate, multiply(toP, multiply(fromTRS([0, 0], dr, [1, 1]), fromP)));
-}
-/**
-* Jitter `node`'s pose with deterministic value noise, then return it (mutate-and-
-* return, like Grid/orientToPath). SEPARATE `translate` (px) / `rotate` (deg) /
-* `frequency` (Hz) amplitudes; pass at least one nonzero amplitude. The jitter is
-* a parent-space offset applied at emit, so it composes with any existing driver.
-*
-* `children: [shake(cursor, { seed: 7, translate: 3 })]` — the cursor wobbles ±3px
-* around wherever else it is (its position track, a followPath, …).
-*/
-function shake(node, spec) {
-	const tr = spec.translate ?? 0;
-	const rot = spec.rotate ?? 0;
-	if (tr === 0 && rot === 0) throw new Error("shake(): pass a nonzero `translate` (px) or `rotate` (deg) amplitude — both are 0/omitted, so nothing would move.");
-	SHAKEN.set(node, spec);
-	const origEmit = node.emit.bind(node);
-	node.emit = (out, ctx) => {
-		const { dx, dy, dr } = shakeOffset(spec, ctx.time);
-		if (dx === 0 && dy === 0 && dr === 0) {
-			origEmit(out, ctx);
-			return;
-		}
-		out.push({ op: "save" });
-		out.push({
-			op: "transform",
-			m: shakeMatrix(node.position(), dx, dy, dr)
-		});
-		origEmit(out, ctx);
-		out.push({ op: "restore" });
-	};
-	return node;
-}
-//#endregion
+import { bake, signal, vec2Signal } from "@glissade/core";
 //#region src/camera.ts
 /**
 * `Camera` (0.55) — a cinematic camera rig for cuts, push-ins, pans, rolls, and

package/dist/shake.js

@@ -0,0 +1,123 @@
+import { Z as fromTRS, et as multiply } from "./nodes.js";
+import { valueNoise } from "@glissade/core";
+//#region src/shake.ts
+/**
+* `shake` (0.55) — a standalone jitter driver that wobbles ANY node's pose with
+* deterministic value noise. It subsumes the hand-rolled per-element jitters
+* (desk-cursor jitterX/Y, glitch shakeAmp, typewriter jitterRate) behind one
+* primitive with SEPARATE translate / rotate / frequency amplitudes.
+*
+* The jitter is realized AT EMIT (the Echo/MotionBlur idiom): `shake` overrides
+* the node's `emit` to wrap it in a save → shake-transform → emit → restore, where
+* the transform is a pure function of `ctx.time` via `valueNoise` — so it composes
+* on top of WHATEVER already drives the node (keyframes, layout, followPath) as a
+* parent-space offset, and stays byte-identical across two `evaluate()` passes (no
+* cross-frame state, no `Date.now`/`Math.random`). The camera whole-frame shake
+* reuses {@link shakeOffset} directly on its pose.
+*
+* Lives on `@glissade/scene/motion` (off the base embed). Note (like Echo/
+* MotionBlur, both emit-time re-eval): the offset is not a Timeline TRACK, so it
+* is a runtime/render effect — it is NOT emitted as animated Lottie keyframes.
+*/
+/** Default temporal frequency (noise cycles per second) when `frequency` is unset. */
+const DEFAULT_FREQUENCY = 8;
+const K_Y = 101;
+const K_ROT = 211;
+/** Signed value noise in [-1, 1) — the bipolar form a shake offset needs. */
+function snoise(seed, t) {
+	return valueNoise(seed, t) * 2 - 1;
+}
+/**
+* Render-INVISIBLE marker: which nodes a {@link shake} driver is applied to, and
+* with what spec. The render path NEVER reads this (shake works purely by wrapping
+* `emit`), so it is byte-neutral for goldens — it exists ONLY so an EXPORTER
+* (which reads signals, not `emit`) can detect the render-only jitter and warn
+* honestly instead of silently dropping it. A WeakMap keeps it off the Node type.
+*/
+const SHAKEN = /* @__PURE__ */ new WeakMap();
+/** The shake spec applied to `node` via {@link shake}, or undefined — the seam an
+*  exporter uses to emit an honest "shake is render-only" warn (never a silent drop). */
+function shakenSpec(node) {
+	return SHAKEN.get(node);
+}
+/**
+* The pure per-time shake offset for a spec: `{ dx, dy }` px + `dr` degrees, each
+* a deterministic function of `(seed, t)`. Both the {@link shake} node driver and
+* the Camera whole-frame shake fold this in.
+*/
+function shakeOffset(spec, t) {
+	const tr = spec.translate ?? 0;
+	const rot = spec.rotate ?? 0;
+	const tf = t * (spec.frequency ?? DEFAULT_FREQUENCY);
+	return {
+		dx: tr === 0 ? 0 : tr * snoise(spec.seed, tf),
+		dy: tr === 0 ? 0 : tr * snoise(spec.seed + K_Y, tf),
+		dr: rot === 0 ? 0 : rot * snoise(spec.seed + K_ROT, tf)
+	};
+}
+/**
+* A shake transform about the point `p` (parent space): translate by `(dx, dy)`
+* then rotate `dr` degrees about `p`, so a rotational jitter spins the node around
+* its own origin rather than the parent's.
+*/
+function shakeMatrix(p, dx, dy, dr) {
+	const translate = [
+		1,
+		0,
+		0,
+		1,
+		dx,
+		dy
+	];
+	if (dr === 0) return translate;
+	const toP = [
+		1,
+		0,
+		0,
+		1,
+		p[0],
+		p[1]
+	];
+	const fromP = [
+		1,
+		0,
+		0,
+		1,
+		-p[0],
+		-p[1]
+	];
+	return multiply(translate, multiply(toP, multiply(fromTRS([0, 0], dr, [1, 1]), fromP)));
+}
+/**
+* Jitter `node`'s pose with deterministic value noise, then return it (mutate-and-
+* return, like Grid/orientToPath). SEPARATE `translate` (px) / `rotate` (deg) /
+* `frequency` (Hz) amplitudes; pass at least one nonzero amplitude. The jitter is
+* a parent-space offset applied at emit, so it composes with any existing driver.
+*
+* `children: [shake(cursor, { seed: 7, translate: 3 })]` — the cursor wobbles ±3px
+* around wherever else it is (its position track, a followPath, …).
+*/
+function shake(node, spec) {
+	const tr = spec.translate ?? 0;
+	const rot = spec.rotate ?? 0;
+	if (tr === 0 && rot === 0) throw new Error("shake(): pass a nonzero `translate` (px) or `rotate` (deg) amplitude — both are 0/omitted, so nothing would move.");
+	SHAKEN.set(node, spec);
+	const origEmit = node.emit.bind(node);
+	node.emit = (out, ctx) => {
+		const { dx, dy, dr } = shakeOffset(spec, ctx.time);
+		if (dx === 0 && dy === 0 && dr === 0) {
+			origEmit(out, ctx);
+			return;
+		}
+		out.push({ op: "save" });
+		out.push({
+			op: "transform",
+			m: shakeMatrix(node.position(), dx, dy, dr)
+		});
+		origEmit(out, ctx);
+		out.push({ op: "restore" });
+	};
+	return node;
+}
+//#endregion
+export { shakenSpec as i, shakeMatrix as n, shakeOffset as r, shake as t };

package/package.json

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