@glissade/scene 0.59.0 → 0.60.0-pre.1

package/dist/describe.d.ts

@@ -153,8 +153,16 @@ interface DescribedHelper {
 interface SurfaceEntry {
   /** The export name — also the `window.glissade.<name>` global on the IIFE. */
   name: string;
-  /** `'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). */
-  kind: 'value' | 'type';
+  /**
+   * `'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'`.
+   */
+  kind: 'value' | 'type' | 'diagnostic';
   /** `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.59.0";
+const RAW_VERSION = "0.60.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
@@ -182,6 +182,34 @@ const SURFACE_EXTRA = [
 /** Value exports that are runtime OBJECTS (not callable): the easing registry. */
 const SURFACE_VALUE_OBJECTS = ["easings"];
 /**
+* The 0.60 machine-readable AUTHORING-DIAGNOSTIC functions on `window.glissade`
+* (the `@glissade/scene/diagnostics` subpath, IIFE-re-exported off the base embed):
+* `critique` (rendered geometry), `validateScene` (static structure), `resolveAt`
+* (the truthful read primitive), `instanceProps` (instance-bound state). Marked
+* `kind: 'diagnostic'` so a consumer can PARTITION the surface — build-a-scene
+* tooling filters them OUT, render-critique/perception tooling filters them IN —
+* instead of them being invisible (previously exempt-internal, discoverable only by
+* reading the bundle). `arity` = the documented required positional-arg count.
+*/
+const SURFACE_DIAGNOSTICS = [
+	{
+		name: "critique",
+		arity: 2
+	},
+	{
+		name: "validateScene",
+		arity: 2
+	},
+	{
+		name: "resolveAt",
+		arity: 3
+	},
+	{
+		name: "instanceProps",
+		arity: 1
+	}
+];
+/**
 * 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
@@ -235,6 +263,13 @@ function buildSurface() {
 		iife: true,
 		form: "object"
 	});
+	for (const d of SURFACE_DIAGNOSTICS) out.push({
+		name: d.name,
+		kind: "diagnostic",
+		iife: true,
+		form: "function",
+		arity: d.arity
+	});
 	for (const name of SURFACE_TYPE_ONLY) out.push({
 		name,
 		kind: "type",

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,57 @@ 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;
+  /**
+   * Author-declared INTENTIONALLY off-stage node ids — the OFF_CANVAS opt-out.
+   * A node is exempt from OFF_CANVAS iff its id is in this list OR ANY of its
+   * ancestors' ids is (SUBTREE match): list the parked GROUP id
+   * (`'sd1-drawer'`) and its whole subtree — current children AND any it later
+   * gains — is suppressed, while sibling groups stay fully checked. This lets an
+   * author silence the true-positive-but-intentional off-stage art (wing-parked
+   * drawers, hidden placeholder cards) without muting OFF_CANVAS wholesale. A
+   * PURE emission filter — determinism-neutral (it never changes the sampled
+   * geometry, only which off-frame nodes are reported). Same param-seam shape as
+   * a future `safeAreas`; a per-node `offstage:true` marker is a planned
+   * fast-follow, not this mechanism.
+   */
+  offstage?: readonly string[];
+}
+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, 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 { 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,448 @@ 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 offstageSet = new Set(opts.offstage ?? []);
+	const isOffstage = (id) => offstageSet.size > 0 && (offstageSet.has(id) || hasFlaggedAncestor(scene, id, offstageSet));
+	const offCanvasIds = /* @__PURE__ */ new Set();
+	for (const [id, a] of agg) if (a.onStage > 0 && a.offCanvas === a.onStage && !isOffstage(id)) 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 instanceof Text)) continue;
+		const width = numberAt(scene, `${id}/width`, a.lastTextFrameT);
+		if (width !== void 0 && width > 0) {
+			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) rendered.push(textOverflowDiagnostic(id, "width", widest, width, over, estimating));
+		}
+		const boxH = node.box?.h;
+		if (boxH !== void 0 && boxH > 0) {
+			const fontSize = a.lastTexts[0].font.size;
+			const blockH = quantize(fontSize * node.lineHeight) * a.lastTexts.length;
+			const overH = blockH - boxH;
+			if (overH > .5) rendered.push(textOverflowDiagnostic(id, "height", blockH, boxH, overH, 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, dimension, measured, threshold, over, estimating) {
+	const base = dimension === "width" ? `text of node '${id}' overflows its box WIDTH 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)} }).` : `text of node '${id}' overflows its box HEIGHT by ${round(over)}px (wrapped block ${round(measured)}px tall, box height ${round(threshold)}px). Reduce fontSize, increase the box height, or shorten the text.`;
+	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: {
+			dimension,
+			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",
+  "version": "0.60.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.59.0"
+    "@glissade/core": "0.60.0-pre.1"
   },
   "repository": {
     "type": "git",