@glissade/scene 0.59.0-pre.1 → 0.60.0-pre.0

package/dist/describe.js

@@ -23,7 +23,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.59.0-pre.1";
+const RAW_VERSION = "0.60.0-pre.0";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /**
 * Parse the documented positional-arg count from a helper `usage` string — the

package/dist/diagnostics.d.ts

@@ -178,9 +178,17 @@ 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';
+type DiagnosticCode = 'UNKNOWN_TARGET' | 'ID_COLLISION' | 'OFF_CANVAS' | 'YOGA_CHILD_POSITION' | 'MEASURER_FALLBACK' | 'TEXT_OVERFLOW' | 'OCCLUSION';
+/**
+ * 0.60: which enforcement SURFACE produced a diagnostic — distinguishes a CERTAIN
+ * static fact (`validateScene`) from a HEURISTIC rendered judgment (`critique`,
+ * which CAN false-positive) from a perceptual parity result (`parity`). Additive,
+ * optional (a pre-0.60 consumer ignores it). Certification reads it to keep "zero
+ * static errors" and "zero critique false-positives" as distinct claims.
+ */
+type DiagnosticSource = 'validateScene' | 'critique' | 'parity';
 /** One diagnostic. The `{schemaVersion, code, severity, message, node?, track?}`
- *  core shape is PINNED; future fields are ADDITIVE only. */
+ *  core shape is PINNED; future fields (`source`/`detail`, 0.60) are ADDITIVE only. */
 interface SceneDiagnostic {
   schemaVersion: typeof DIAGNOSTIC_SCHEMA_VERSION;
   code: DiagnosticCode;
@@ -190,6 +198,11 @@ interface SceneDiagnostic {
   node?: string;
   /** The track target string the diagnostic concerns, when applicable. */
   track?: string;
+  /** 0.60: the enforcement surface that produced this diagnostic. */
+  source?: DiagnosticSource;
+  /** 0.60: structured evidence (e.g. `{ measured, threshold }` for a critique
+   *  code), so a consumer digs into the numbers without parsing the message. */
+  detail?: Record<string, unknown>;
 }
 /** `validateScene` result — the CLI-lint `{ hasErrors, diagnostics }` shape,
  *  plus a top-level `schemaVersion`. */
@@ -261,4 +274,43 @@ interface InstancePropState {
  */
 declare function instanceProps(node: Node): InstancePropState[];
 //#endregion
-export { type CacheColdResult, type CommandDelta, DIAGNOSTIC_SCHEMA_VERSION, DL_SNAPSHOT_VERSION, type DiagnosticCode, type DiagnosticSeverity, type DisplayDiff, type DlSnapshot, DlSnapshotError, type FieldChange, type FontByteLoader, type InstancePropState, type SceneDiagnostic, type ValidateSceneFontsOptions, type ValidateSceneResult, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, diffDisplayLists, formatDisplayDiff, instanceProps, levenshtein, nearestId, parseDisplaySnapshot, resolveAt, serializeDisplayList, validateScene, validateSceneFonts };
+//#region src/critique.d.ts
+interface CritiqueOptions {
+  /**
+   * frames-per-second for the sampling grid. Default: the timeline's own fps,
+   * else 60 (aligning critique verdicts with what `gs render` produces). Kept an
+   * override for tooling; a fixed INTEGER-frame grid is the determinism contract.
+   */
+  fps?: number;
+}
+interface CritiqueResult {
+  schemaVersion: typeof DIAGNOSTIC_SCHEMA_VERSION;
+  /** true iff any diagnostic has severity `error` (always a static error — the
+   *  rendered pass emits only warnings/info). */
+  hasErrors: boolean;
+  /** FLAT merged, CANONICALLY-SORTED diagnostics (static + rendered). */
+  diagnostics: SceneDiagnostic[];
+  /** true when the rendered pass was skipped because static validation errored. */
+  renderedSkipped: boolean;
+  /** why the rendered pass was skipped (present iff `renderedSkipped`). */
+  renderedSkipReason?: string;
+  /** how many integer-frame grid samples the rendered pass took (0 if skipped). */
+  sampledFrames: number;
+}
+/**
+ * Rendered-geometric diagnostics for `(scene, timeline)`. Runs `validateScene`
+ * first; short-circuits the rendered pass on any static error. Otherwise binds the
+ * scene, samples a fixed integer-frame grid, and emits OFF_CANVAS / TEXT_OVERFLOW
+ * / OCCLUSION where a span check fires. PURE READ — never changes evaluate() or a
+ * render path; canonically-sorted (frame, then code, then node-id) output.
+ */
+declare function critique(scene: Scene, timeline: Timeline, opts?: CritiqueOptions): CritiqueResult;
+/**
+ * CANONICAL SORT — by frame (detail.frame, undefined last), then code, then
+ * node-id. An unordered diagnostic array is golden-unstable; this is the HARD emit
+ * requirement (assert sort-invariance: shuffle-then-sort ≡ emitted order). Stable
+ * for equal keys (the static-then-rendered concat order is deterministic).
+ */
+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 };

package/dist/diagnostics.js

@@ -1,6 +1,7 @@
-import { I as isEstimatingMeasurer, J as collapseReplacer, P as estimatingMeasurer, W as createDisplayListBuilder, r as Group, s as Text } from "./nodes.js";
-import { a as evaluate } from "./scene.js";
-import { buildFontRegistry, evaluateAt, parseCmap, untracked, validateFonts } from "@glissade/core";
+import { I as isEstimatingMeasurer, J as collapseReplacer, P as estimatingMeasurer, 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 { 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. */
 function commandView(cmd, resources) {
@@ -383,6 +384,7 @@ function validateScene(scene, doc) {
 			code,
 			severity,
 			message,
+			source: "validateScene",
 			...extra?.node !== void 0 ? { node: extra.node } : {},
 			...extra?.track !== void 0 ? { track: extra.track } : {}
 		});
@@ -475,4 +477,438 @@ function instanceProps(node) {
 	});
 }
 //#endregion
-export { DIAGNOSTIC_SCHEMA_VERSION, DL_SNAPSHOT_VERSION, DlSnapshotError, auditCacheCold, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, diffDisplayLists, formatDisplayDiff, instanceProps, levenshtein, nearestId, parseDisplaySnapshot, resolveAt, serializeDisplayList, validateScene, validateSceneFonts };
+//#region src/critique.ts
+function growBounds(b, x, y) {
+	if (!b) return {
+		minX: x,
+		minY: y,
+		maxX: x,
+		maxY: y
+	};
+	if (x < b.minX) b.minX = x;
+	if (y < b.minY) b.minY = y;
+	if (x > b.maxX) b.maxX = x;
+	if (y > b.maxY) b.maxY = y;
+	return b;
+}
+/** Local-space rect → device-space box under `m`, growing `into`. */
+function accumulateRect(into, m, x0, y0, x1, y1) {
+	let b = into;
+	for (const [x, y] of [
+		[x0, y0],
+		[x1, y0],
+		[x0, y1],
+		[x1, y1]
+	]) b = growBounds(b, m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]);
+	return b;
+}
+/** Control-point bounding box of a path — curves/rotated ellipses stay inside. */
+function segsBounds(segs) {
+	let b = null;
+	const pt = (x, y) => {
+		b = growBounds(b, x, y);
+	};
+	for (const seg of segs) switch (seg[0]) {
+		case "M":
+		case "L":
+			pt(seg[1], seg[2]);
+			break;
+		case "C":
+			pt(seg[1], seg[2]);
+			pt(seg[3], seg[4]);
+			pt(seg[5], seg[6]);
+			break;
+		case "Q":
+			pt(seg[1], seg[2]);
+			pt(seg[3], seg[4]);
+			break;
+		case "E": {
+			const r = Math.max(seg[3], seg[4]);
+			pt(seg[1] - r, seg[2] - r);
+			pt(seg[1] + r, seg[2] + r);
+			break;
+		}
+	}
+	return b;
+}
+function pathResourceBounds(resources, id) {
+	const res = resources[id];
+	return res && res.kind === "path" ? segsBounds(res.segs) : null;
+}
+/** True when two boxes overlap the open frame [0,0,w,h] (bbox ∩ frame ≠ ∅). */
+function intersectsFrame(b, w, h) {
+	return b.maxX > 0 && b.minX < w && b.maxY > 0 && b.minY < h;
+}
+/** True when `b` is FULLY outside the frame (off one edge entirely). */
+function fullyOutsideFrame(b, w, h) {
+	return b.maxX <= 0 || b.minX >= w || b.maxY <= 0 || b.minY >= h;
+}
+/** True when `outer` fully contains `inner` (bbox containment). */
+function contains(outer, inner) {
+	return outer.minX <= inner.minX && outer.minY <= inner.minY && outer.maxX >= inner.maxX && outer.maxY >= inner.maxY;
+}
+/**
+* Walk one DisplayList (+ its id stream) maintaining a transform stack and a group
+* stack, unioning each command's device-space bbox per node id. Solid-opaque fills
+* under a fully-opaque group stack are recorded as occluders. COPIES the golden-
+* tested save/restore/transform/pushGroup/popGroup discipline from raster2d.
+*/
+function walkFrame(list, ids, measurer) {
+	const nodes = /* @__PURE__ */ new Map();
+	const occluders = [];
+	let mat = IDENTITY;
+	const matStack = [];
+	let nonOpaqueGroupDepth = 0;
+	const groupOpaque = [];
+	const attribute = (id, box, order) => {
+		if (id === void 0 || box === null) return;
+		const existing = nodes.get(id);
+		if (existing) {
+			existing.bounds = accumulateRect(existing.bounds, IDENTITY, box.minX, box.minY, box.maxX, box.maxY);
+			if (order > existing.maxOrder) existing.maxOrder = order;
+		} else nodes.set(id, {
+			bounds: { ...box },
+			maxOrder: order,
+			texts: []
+		});
+	};
+	const commands = list.commands;
+	for (let ci = 0; ci < commands.length; ci++) {
+		const cmd = commands[ci];
+		const id = ids[ci];
+		switch (cmd.op) {
+			case "save":
+				matStack.push(mat);
+				break;
+			case "restore":
+				mat = matStack.pop() ?? mat;
+				break;
+			case "transform":
+				mat = multiply(mat, cmd.m);
+				break;
+			case "clip": break;
+			case "fillPath": {
+				const pb = pathResourceBounds(list.resources, cmd.path);
+				if (!pb) break;
+				const box = accumulateRect(null, mat, pb.minX, pb.minY, pb.maxX, pb.maxY);
+				attribute(id, box, ci);
+				if (box && nonOpaqueGroupDepth === 0 && isOpaqueSolid(cmd.paint)) occluders.push({
+					bounds: box,
+					order: ci,
+					id
+				});
+				break;
+			}
+			case "strokePath": {
+				const pb = pathResourceBounds(list.resources, cmd.path);
+				if (!pb) break;
+				const o = cmd.stroke.width * ((cmd.stroke.join ?? "miter") === "miter" ? 5 : 1);
+				attribute(id, accumulateRect(null, mat, pb.minX - o, pb.minY - o, pb.maxX + o, pb.maxY + o), ci);
+				break;
+			}
+			case "fillText": {
+				let width = 0;
+				try {
+					width = measurer.measureText(cmd.text, cmd.font).width;
+				} catch {
+					width = cmd.text.length * cmd.font.size * .6;
+				}
+				const align = cmd.align ?? "left";
+				const x0 = align === "center" ? cmd.x - width / 2 : align === "right" ? cmd.x - width : cmd.x;
+				const m = cmd.font.size;
+				attribute(id, accumulateRect(null, mat, x0 - m, cmd.y - 1.5 * m, x0 + width + m, cmd.y + .75 * m), ci);
+				if (id !== void 0) nodes.get(id).texts.push({
+					text: cmd.text,
+					font: cmd.font
+				});
+				break;
+			}
+			case "drawImage": {
+				const { x, y, w: dw, h: dh } = cmd.dst;
+				attribute(id, accumulateRect(null, mat, x, y, x + dw, y + dh), ci);
+				break;
+			}
+			case "pushGroup": {
+				const opaque = cmd.opacity >= 1 && cmd.blend === "source-over" && cmd.filters.length === 0 && cmd.matte === void 0;
+				groupOpaque.push(opaque);
+				if (!opaque) nonOpaqueGroupDepth++;
+				break;
+			}
+			case "popGroup":
+				if (groupOpaque.pop() === false) nonOpaqueGroupDepth--;
+				break;
+		}
+	}
+	return {
+		nodes,
+		occluders
+	};
+}
+/** Is a paint a SOLID opaque color (alpha ≥ ~0.98)? Conservative: gradient/mesh
+*  and any un-parseable color count as NOT opaque (false-negatives are fine, a
+*  false cover is not). */
+function isOpaqueSolid(paint) {
+	if (!paint || paint.kind !== "color") return false;
+	try {
+		return parseColor(paint.color).a >= .98;
+	} catch {
+		return false;
+	}
+}
+/**
+* Rendered-geometric diagnostics for `(scene, timeline)`. Runs `validateScene`
+* first; short-circuits the rendered pass on any static error. Otherwise binds the
+* scene, samples a fixed integer-frame grid, and emits OFF_CANVAS / TEXT_OVERFLOW
+* / OCCLUSION where a span check fires. PURE READ — never changes evaluate() or a
+* render path; canonically-sorted (frame, then code, then node-id) output.
+*/
+function critique(scene, timeline, opts = {}) {
+	const staticRes = validateScene(scene, timeline);
+	const staticDiags = staticRes.diagnostics;
+	if (staticRes.hasErrors) return {
+		schemaVersion: 1,
+		hasErrors: true,
+		diagnostics: sortDiagnostics(staticDiags.slice()),
+		renderedSkipped: true,
+		renderedSkipReason: "fix static errors first — the scene can’t bind, so rendered geometry would be garbage.",
+		sampledFrames: 0
+	};
+	bindScene(scene, timeline);
+	const { w, h } = scene.size;
+	const measurer = scene.textMeasurer;
+	const estimating = isEstimatingMeasurer(measurer);
+	const fps = opts.fps ?? timeline.fps ?? 60;
+	const duration = compileTimeline(timeline).duration;
+	const lastFrame = Math.max(0, Math.floor(duration * fps));
+	const agg = /* @__PURE__ */ new Map();
+	const ensure = (id) => {
+		let a = agg.get(id);
+		if (!a) {
+			a = {
+				onStage: 0,
+				offCanvas: 0,
+				occluded: 0,
+				lastFrame: -1,
+				lastT: 0,
+				lastBounds: {
+					minX: 0,
+					minY: 0,
+					maxX: 0,
+					maxY: 0
+				},
+				occluderId: void 0,
+				occluderBounds: null,
+				lastTextFrameT: 0,
+				lastTexts: []
+			};
+			agg.set(id, a);
+		}
+		return a;
+	};
+	let sampledFrames = 0;
+	for (let i = 0; i <= lastFrame; i++) {
+		const t = i / fps;
+		const { displayList, ids } = emitWithIds(scene, timeline, t);
+		const frame = walkFrame(displayList, ids, measurer);
+		sampledFrames++;
+		for (const [id, fn] of frame.nodes) {
+			const a = ensure(id);
+			a.onStage++;
+			a.lastFrame = i;
+			a.lastT = t;
+			a.lastBounds = fn.bounds;
+			if (fn.texts.length > 0) {
+				a.lastTextFrameT = t;
+				a.lastTexts = fn.texts;
+			}
+			if (fullyOutsideFrame(fn.bounds, w, h)) a.offCanvas++;
+			if (intersectsFrame(fn.bounds, w, h)) {
+				let cover;
+				for (const occ of frame.occluders) if (occ.order > fn.maxOrder && contains(occ.bounds, fn.bounds)) {
+					cover = occ;
+					break;
+				}
+				if (cover) {
+					a.occluded++;
+					a.occluderId = cover.id;
+					a.occluderBounds = cover.bounds;
+				}
+			}
+		}
+	}
+	const rendered = [];
+	const offCanvasIds = /* @__PURE__ */ new Set();
+	for (const [id, a] of agg) if (a.onStage > 0 && a.offCanvas === a.onStage) offCanvasIds.add(id);
+	const reportedOffCanvas = /* @__PURE__ */ new Set();
+	for (const id of offCanvasIds) {
+		if (hasFlaggedAncestor(scene, id, offCanvasIds)) continue;
+		reportedOffCanvas.add(id);
+		const a = agg.get(id);
+		rendered.push(offCanvasDiagnostic(scene, id, a, w, h));
+	}
+	for (const [id, a] of agg) {
+		if (a.lastTexts.length === 0) continue;
+		const node = scene.nodes.get(id);
+		if (!node || node.describeType !== "Text") continue;
+		const width = numberAt(scene, `${id}/width`, a.lastTextFrameT);
+		if (width === void 0 || width <= 0) continue;
+		let widest = 0;
+		for (const run of a.lastTexts) {
+			let mw = 0;
+			try {
+				mw = measurer.measureText(run.text, run.font).width;
+			} catch {
+				mw = 0;
+			}
+			if (mw > widest) widest = mw;
+		}
+		const over = widest - width;
+		if (over <= .5) continue;
+		rendered.push(textOverflowDiagnostic(id, widest, width, over, estimating));
+	}
+	for (const [id, a] of agg) {
+		if (a.onStage === 0 || a.occluded !== a.onStage) continue;
+		if (reportedOffCanvas.has(id) || offCanvasIds.has(id)) continue;
+		const node = scene.nodes.get(id);
+		if (!node || node instanceof Group) continue;
+		rendered.push(occlusionDiagnostic(scene, id, a));
+	}
+	return {
+		schemaVersion: 1,
+		hasErrors: false,
+		diagnostics: sortDiagnostics([...staticDiags, ...rendered]),
+		renderedSkipped: false,
+		sampledFrames
+	};
+}
+function offCanvasDiagnostic(scene, id, a, w, h) {
+	const b = a.lastBounds;
+	const bw = b.maxX - b.minX;
+	const bh = b.maxY - b.minY;
+	let dir = "off-frame";
+	let need = "";
+	const pos = vec2At(scene, `${id}/position`, a.lastT);
+	const posStr = pos ? ` position [${round(pos[0])}, ${round(pos[1])}]` : "";
+	if (b.maxX <= 0) {
+		dir = `off the LEFT by ${round(-b.maxX)}px`;
+		need = `; a center-anchored box needs x ≥ ~${round(bw / 2)} to sit on-frame`;
+	} else if (b.minX >= w) {
+		dir = `off the RIGHT by ${round(b.minX - w)}px`;
+		need = `; a center-anchored box needs x ≤ ~${round(w - bw / 2)} to sit on-frame`;
+	} else if (b.maxY <= 0) {
+		dir = `off the TOP by ${round(-b.maxY)}px`;
+		need = `; a center-anchored box needs y ≥ ~${round(bh / 2)} to sit on-frame`;
+	} else if (b.minY >= h) {
+		dir = `off the BOTTOM by ${round(b.minY - h)}px`;
+		need = `; a center-anchored box needs y ≤ ~${round(h - bh / 2)} to sit on-frame`;
+	}
+	return {
+		schemaVersion: 1,
+		code: "OFF_CANVAS",
+		severity: "warning",
+		source: "critique",
+		node: id,
+		message: `node '${id}' renders fully outside the ${w}×${h} frame (bbox x:[${round(b.minX)},${round(b.maxX)}] y:[${round(b.minY)},${round(b.maxY)}], ${dir}) for its whole on-stage lifetime.${posStr}. Adjust its position/anchor to bring the box on-frame${need}.`,
+		detail: {
+			frame: a.lastFrame,
+			bounds: {
+				minX: round(b.minX),
+				minY: round(b.minY),
+				maxX: round(b.maxX),
+				maxY: round(b.maxY)
+			},
+			size: {
+				w,
+				h
+			}
+		}
+	};
+}
+function textOverflowDiagnostic(id, measured, threshold, over, estimating) {
+	const base = `text of node '${id}' overflows its box by ${round(over)}px (needs ${round(measured)}px, box width ${round(threshold)}px). Reduce fontSize, widen width, or wrap it with fitText({ maxW: ${round(threshold)} }).`;
+	return {
+		schemaVersion: 1,
+		code: "TEXT_OVERFLOW",
+		severity: estimating ? "info" : "warning",
+		source: "critique",
+		node: id,
+		message: estimating ? `${base} (metrics ESTIMATED — no real text measurer injected; verify with the real backend measurer.)` : base,
+		detail: {
+			measured: round(measured),
+			threshold: round(threshold),
+			overflowPx: round(over),
+			estimated: estimating
+		}
+	};
+}
+function occlusionDiagnostic(scene, id, a) {
+	const occ = a.occluderId !== void 0 ? `node '${a.occluderId}'` : "an opaque layer painted above it";
+	const pos = vec2At(scene, `${id}/position`, a.lastT);
+	return {
+		schemaVersion: 1,
+		code: "OCCLUSION",
+		severity: "warning",
+		source: "critique",
+		node: id,
+		message: `node '${id}'${pos ? ` (position [${round(pos[0])}, ${round(pos[1])}])` : ""} is fully covered by ${occ} (0 visible px) for its whole on-stage lifetime. ${a.occluderId !== void 0 ? `raise '${id}' above '${a.occluderId}' (higher zIndex / paint order) OR move it outside '${a.occluderId}'’s bounds` : "raise its zIndex above the covering layer OR move it out from under the cover"}.`,
+		detail: {
+			frame: a.lastFrame,
+			...a.occluderId !== void 0 ? { occluder: a.occluderId } : {},
+			...a.occluderBounds ? { occluderBounds: {
+				minX: round(a.occluderBounds.minX),
+				minY: round(a.occluderBounds.minY),
+				maxX: round(a.occluderBounds.maxX),
+				maxY: round(a.occluderBounds.maxY)
+			} } : {}
+		}
+	};
+}
+/** Walk `id`'s ided ancestor chain; true if any ancestor is in `flagged`. */
+function hasFlaggedAncestor(scene, id, flagged) {
+	let p = scene.nodes.get(id)?.parent ?? null;
+	while (p) {
+		if (p.id !== void 0 && flagged.has(p.id)) return true;
+		p = p.parent;
+	}
+	return false;
+}
+function numberAt(scene, target, t) {
+	const v = resolveAt(scene, target, t);
+	return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function vec2At(scene, target, t) {
+	const v = resolveAt(scene, target, t);
+	return Array.isArray(v) && v.length >= 2 && typeof v[0] === "number" && typeof v[1] === "number" ? [v[0], v[1]] : void 0;
+}
+function round(n) {
+	return Math.round(n * 100) / 100;
+}
+/**
+* CANONICAL SORT — by frame (detail.frame, undefined last), then code, then
+* node-id. An unordered diagnostic array is golden-unstable; this is the HARD emit
+* requirement (assert sort-invariance: shuffle-then-sort ≡ emitted order). Stable
+* for equal keys (the static-then-rendered concat order is deterministic).
+*/
+function sortDiagnostics(diags) {
+	const frameOf = (d) => {
+		const f = d.detail?.frame;
+		return typeof f === "number" ? f : Number.POSITIVE_INFINITY;
+	};
+	return diags.map((d, i) => [d, i]).sort((A, B) => {
+		const [a, ai] = A;
+		const [b, bi] = B;
+		const fa = frameOf(a);
+		const fb = frameOf(b);
+		if (fa !== fb) return fa - fb;
+		if (a.code !== b.code) return a.code < b.code ? -1 : 1;
+		const na = a.node ?? "";
+		const nb = b.node ?? "";
+		if (na !== nb) return na < nb ? -1 : 1;
+		const ta = a.track ?? "";
+		const tb = b.track ?? "";
+		if (ta !== tb) return ta < tb ? -1 : 1;
+		return ai - bi;
+	}).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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.59.0-pre.1",
+  "version": "0.60.0-pre.0",
   "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.59.0-pre.1"
+    "@glissade/core": "0.60.0-pre.0"
   },
   "repository": {
     "type": "git",