@glissade/cli 0.60.0 → 0.61.0-pre.1

package/dist/cli.js

@@ -30,7 +30,9 @@ const KNOWN_BOOLEAN_FLAGS = new Set([
 	"lint",
 	"global",
 	"iife",
-	"update-baseline"
+	"update-baseline",
+	"semantic",
+	"all"
 ]);
 function parseArgs(argv) {
 	const positional = [];
@@ -102,6 +104,7 @@ const USAGE = `usage:
   gs migrate <baseline-api.json> [--json] [--check]   diff a saved API manifest against the current engine: moved imports / removed / added / changed, with a suggested fix per breaking item (advisory; --check exits non-zero on any breaking change for CI gating)
   gs repin <scene-module> --golden <dir> [--name <p>] [--frames a,b,..] [--fps <n>] [--since <ref>] [--write] [--only a,b] [--heatmap <dir>] [--floor <ssim>] [--force]   narration-aware golden reviewer: render current vs committed goldens, report perceptual delta + the re-narration cause, re-pin only frames you allow (default dry-run; --floor refuses a bigger-than-expected drop)
   gs parity <scene-module> [--backends skia,lottie] [--frames a,b,..] [--fps <n>] [--width <n>] [--height <n>] [--heatmap <dir>] [--min <ssim>] [--baseline <file>] [--update-baseline] [--tolerance <eps>]   cross-backend perceptual review: render ONE scene across backends and report per-frame SSIM vs the Skia reference + the worst 8×8 tile (skia = reference, lottie = export↔import round-trip). --heatmap writes a thermal PNG per frame; --min is the SSIM floor (default 0.98) — a below-floor frame exits non-zero. --baseline turns it into a KNOWN-DROP regression gate: compare each mean vs a committed per-scene baseline of EXPECTED drops and fail ONLY on a deviation (a new/worse drop), so documented scope-outs that legitimately fail the floor PASS while a real regression FAILs; --update-baseline (re)writes that baseline from the live run; --tolerance is the expected-SSIM band (default 1e-4). --baseline takes precedence over --min. (dom = Phase B, not yet shipped)
+  gs parity <scene-module> --semantic [--all] [--frames a,b,..] [--fps <n>] [--width <n>] [--height <n>] [--min <ssim>] [--baseline <file>] [--update-baseline] [--json]   the STRUCTURED Skia↔Lottie round-trip drop-diff: fuse the exporter's own warn-list (which element dropped + why) with the SSIM residual localized to each node's rendered bbox → source:'parity' diagnostics (LOTTIE_DROP/APPROXIMATE = warn-explained expected drops masked from the default view; ANCHOR_RECENTER = report-only; UNEXPLAINED_RESIDUAL = a residual with NO matching warn, the only thing in the default error-only view). --all shows every finding; --baseline pins the expected-drop keys (a NEW expected drop still flags); --update-baseline re-pins
   gs localize <scene-module> --to <locale> [--from <locale>] [--write] [--strict] [--keep-voice] [--json]   fork a narration into a new locale (clone segment/pause structure, PRESERVING beat ids so .start() anchors survive) + stub messages.<locale>.json from the scene's t() ids, running the render path's parity + localize checks BEFORE any TTS. Default dry-run (exits non-zero on drift); --write emits <base>.<locale>.narration.json + messages.<locale>.json (re-localize CARRIES existing translations over — never clobbers); --strict refuses to write on a preflight failure
   gs --version   print the engine version
 
@@ -455,6 +458,43 @@ async function main() {
 			min = Number(minRaw);
 			if (!(min >= -1 && min <= 1)) fail(`parity: --min must be an SSIM floor in [-1, 1], got '${minRaw}'`);
 		}
+		if (pf.has("semantic")) {
+			const { semanticParityCommand } = await import("./semanticParity.js");
+			const { existsSync, readFileSync, writeFileSync } = await import("node:fs");
+			const sBaselinePath = pf.get("baseline");
+			const sUpdate = pf.has("update-baseline");
+			let sBaseline;
+			if (sBaselinePath !== void 0 && !sUpdate && existsSync(sBaselinePath)) try {
+				const raw = JSON.parse(readFileSync(sBaselinePath, "utf8"));
+				sBaseline = Array.isArray(raw) ? raw : raw.keys ?? [];
+			} catch (err) {
+				fail(`parity --semantic: could not read baseline '${sBaselinePath}': ${err instanceof Error ? err.message : String(err)}`);
+			}
+			try {
+				const result = await semanticParityCommand({
+					modulePath: sceneModule,
+					...nums(pf.get("frames")) ? { frames: nums(pf.get("frames")) } : {},
+					...pf.get("fps") ? { fps: parseFpsOrFail(pf.get("fps")) } : {},
+					...dim("width") !== void 0 ? { width: dim("width") } : {},
+					...dim("height") !== void 0 ? { height: dim("height") } : {},
+					...min !== void 0 ? { min } : {},
+					...pf.has("all") ? { all: true } : {},
+					...sBaseline !== void 0 ? { baseline: sBaseline } : {},
+					...pf.has("json") ? { json: true } : {}
+				});
+				if (sUpdate && sBaselinePath !== void 0) {
+					const keys = result.findings.filter((f) => f.detail?.expected === true).map((f) => `${f.node ?? ""}|${f.code}|${String(f.detail?.property ?? "")}`);
+					writeFileSync(sBaselinePath, `${JSON.stringify([...new Set(keys)].sort(), null, 2)}\n`);
+					process.stdout.write(`gs parity --semantic: wrote ${keys.length} expected-drop key(s) → ${sBaselinePath}\n`);
+					return;
+				}
+				process.stdout.write(pf.has("json") ? `${JSON.stringify(result, null, 2)}\n` : `${result.report}\n`);
+				if (result.hasErrors || sBaseline !== void 0 && result.newExpected.length > 0) process.exit(1);
+			} catch (err) {
+				fail(err instanceof Error ? err.message : String(err));
+			}
+			return;
+		}
 		const baselinePath = pf.get("baseline");
 		const updateBaseline = pf.has("update-baseline");
 		if (updateBaseline && baselinePath === void 0) fail(`parity: --update-baseline needs --baseline <file> (the baseline path to write to)\n${USAGE}`);

package/dist/describeLint.js

@@ -218,7 +218,7 @@ function describeLint(manifest, surface, opts = {}) {
 	const callables = /* @__PURE__ */ new Set();
 	for (const name of Object.keys(manifest.nodes)) callables.add(name);
 	for (const h of manifest.helpers) callables.add(h.name);
-	for (const e of manifest.surface ?? []) if ((e.kind === "value" || e.kind === "diagnostic") && (e.form === "constructor" || e.form === "function")) callables.add(e.name);
+	for (const e of manifest.surface ?? []) if ((e.kind === "value" || e.kind === "diagnostic" || e.kind === "tool") && (e.form === "constructor" || e.form === "function")) callables.add(e.name);
 	for (const name of [...callables].sort()) {
 		if (exempt.has(name) || isFn(name)) continue;
 		out.push(present(name) ? {

package/dist/parity.js

@@ -150,6 +150,7 @@ const DEFAULT_PARITY_FRAMES = [
 	90,
 	119
 ];
+const DEFAULT_PARITY_FLOOR = .98;
 /** The reference backend every other leg is diffed against. */
 const REFERENCE_BACKEND = "skia";
 /** Backends accepted in Phase A (skia = reference; lottie = export↔import round-trip). */
@@ -437,4 +438,4 @@ function formatReport(name, r, extra) {
 	return lines.join("\n");
 }
 //#endregion
-export { ParityBackendError, parityCommand, parseBackends };
+export { DEFAULT_PARITY_FLOOR, DEFAULT_PARITY_FRAMES, ParityBackendError, parityCommand, parseBackends };

package/dist/semanticParity.js

@@ -0,0 +1,648 @@
+import { d as prepareSkiaRenderEnv, o as loadSceneModule } from "./render.js";
+import { DEFAULT_PARITY_FRAMES } from "./parity.js";
+import { evaluate, withDeterminismGuards } from "@glissade/scene";
+import { DIAGNOSTIC_SCHEMA_VERSION, sortDiagnostics } from "@glissade/scene/diagnostics";
+import { SkiaBackend, ssimMap } from "@glissade/backend-skia";
+import { exportLottie, importLottie } from "@glissade/lottie";
+import { emitWithIds } from "@glissade/scene/identity";
+//#region src/semanticParity.ts
+/**
+* `gs parity --semantic` — the structured Skia↔Lottie round-trip DROP-DIFF.
+*
+* It FUSES the exporter's own warn-list (WHICH element dropped + WHY) with the SSIM
+* residual localized to that node's rendered bbox (WHERE it drifts + how much),
+* emitting ONE auto-correlated `source:'parity'` diagnostic per finding — the
+* hand-correlated PARITY_BASELINE table become a GENERATED, self-verifying artifact.
+*
+* Reuses the SHIPPED machinery, nothing new on the render path:
+*   • the export↔import round-trip (@glissade/lottie) — exportLottie→importLottie→render.
+*   • the export warn-capture — exportLottie's `onWarn` sink IS the intentional-drop
+*     declaration (every render-only drop already warns; we just capture the list).
+*   • the 8×8-tile SSIM harness (`ssimMap` from @glissade/backend-skia, shipped 0.37).
+*   • `emitWithIds` (@glissade/scene/identity) for the reference DisplayList + node id
+*     stream → per-node composed-world bbox (the same walk critique() uses).
+*
+* DETERMINISTIC by construction: the residual→node attribution is a TOTAL ORDER
+* (contains → topmost paint → node-id), so shuffling tile iteration yields identical
+* attribution; output is canonically sorted via `sortDiagnostics`. Pure read — it
+* renders through the SAME faithful env as `gs render`/`gs parity` and never mutates
+* evaluate().
+*/
+const ID_MAT = [
+	1,
+	0,
+	0,
+	1,
+	0,
+	0
+];
+function mul(a, b) {
+	return [
+		a[0] * b[0] + a[2] * b[1],
+		a[1] * b[0] + a[3] * b[1],
+		a[0] * b[2] + a[2] * b[3],
+		a[1] * b[2] + a[3] * b[3],
+		a[0] * b[4] + a[2] * b[5] + a[4],
+		a[1] * b[4] + a[3] * b[5] + a[5]
+	];
+}
+function grow(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;
+}
+function rectBox(into, m, x0, y0, x1, y1) {
+	let b = into;
+	for (const [x, y] of [
+		[x0, y0],
+		[x1, y0],
+		[x0, y1],
+		[x1, y1]
+	]) b = grow(b, m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]);
+	return b;
+}
+/** Walk one DisplayList + id stream → per-node device-space bbox + paint order. A
+*  compact copy of critique's walkFrame (transform stack; path/text/image bounds). */
+function walkBounds(list, ids) {
+	const nodes = /* @__PURE__ */ new Map();
+	let mat = ID_MAT;
+	const stack = [];
+	const resources = list.resources;
+	const attribute = (id, box, order) => {
+		if (id === void 0 || box === null) return;
+		const ex = nodes.get(id);
+		if (ex) {
+			ex.bounds = rectBox(ex.bounds, ID_MAT, box.minX, box.minY, box.maxX, box.maxY);
+			if (order > ex.order) ex.order = order;
+		} else nodes.set(id, {
+			bounds: { ...box },
+			order
+		});
+	};
+	const segBounds = (segs) => {
+		let b = null;
+		for (const seg of segs) switch (seg[0]) {
+			case "M":
+			case "L":
+				b = grow(b, seg[1], seg[2]);
+				break;
+			case "C":
+				b = grow(b, seg[1], seg[2]);
+				b = grow(b, seg[3], seg[4]);
+				b = grow(b, seg[5], seg[6]);
+				break;
+			case "Q":
+				b = grow(b, seg[1], seg[2]);
+				b = grow(b, seg[3], seg[4]);
+				break;
+			case "E": {
+				const r = Math.max(seg[3], seg[4]);
+				b = grow(b, seg[1] - r, seg[2] - r);
+				b = grow(b, seg[1] + r, seg[2] + r);
+				break;
+			}
+		}
+		return b;
+	};
+	const pathBounds = (idx) => {
+		const res = resources[idx];
+		return res && res.kind === "path" ? segBounds(res.segs) : null;
+	};
+	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":
+				stack.push(mat);
+				break;
+			case "restore":
+				mat = stack.pop() ?? mat;
+				break;
+			case "transform":
+				mat = mul(mat, cmd.m);
+				break;
+			case "fillPath":
+			case "strokePath": {
+				const pb = pathBounds(cmd.path);
+				if (pb) attribute(id, rectBox(null, mat, pb.minX, pb.minY, pb.maxX, pb.maxY), ci);
+				break;
+			}
+			case "fillText": {
+				const font = cmd.font;
+				const width = String(cmd.text).length * font.size * .6;
+				const x = cmd.x;
+				const y = cmd.y;
+				const align = cmd.align ?? "left";
+				const x0 = align === "center" ? x - width / 2 : align === "right" ? x - width : x;
+				const m = font.size;
+				attribute(id, rectBox(null, mat, x0 - m, y - 1.5 * m, x0 + width + m, y + .75 * m), ci);
+				break;
+			}
+			case "drawImage": {
+				const dst = cmd.dst;
+				attribute(id, rectBox(null, mat, dst.x, dst.y, dst.x + dst.w, dst.y + dst.h), ci);
+				break;
+			}
+		}
+	}
+	return nodes;
+}
+/** Parse ONE exporter warn string into a structured drop. The exporter formats
+*  every warn as `<Type> '<id>': <cause>` (id optional) — see lottie/export.ts. */
+function parseWarn(msg) {
+	const node = /^\w+ '([^']+)'/.exec(msg)?.[1];
+	const approximate = /valign is approximated|relies on the player's own line reflow|sampled at .* fps|hard linear ramp|flattened to a static raster|double-composite/.test(msg);
+	let property = "unknown";
+	if (/motionBlur|analog-shutter/.test(msg)) property = "motion-blur";
+	else if (/echo trails/.test(msg)) property = "echo-trails";
+	else if (/camera shake|whole-frame camera shake/.test(msg)) property = "camera-shake";
+	else if (/shake\(\) jitter|closed-form jitter/.test(msg)) property = "shake";
+	else if (/mesh/.test(msg)) property = "mesh-animation";
+	else if (/variable-font axes|fontAxes|fontVariationSettings/.test(msg)) property = "variable-font-axes";
+	else if (/typewriter 'reveal'|'revealFraction'/.test(msg)) property = "reveal-fraction";
+	else if (/box valign/.test(msg)) property = "box-valign";
+	else if (/wrap 'width'|line reflow/.test(msg)) property = "wrap-width";
+	else if (/gradient interpolation/.test(msg)) property = "gradient-interpolation";
+	else if (/not exportable/.test(msg)) {
+		const kind = /^(\w+)/.exec(msg)?.[1]?.toLowerCase();
+		property = kind === "image" ? "image" : kind === "video" ? "video" : kind === "textcursor" ? "text-cursor" : kind ?? "drop";
+	}
+	return {
+		...node !== void 0 ? { node } : {},
+		property,
+		cause: msg,
+		approximate
+	};
+}
+const ORPHAN_RADIUS = 64;
+const COVERAGE_MIN = .34;
+const MIN_ORPHAN_TILES = 3;
+const BENIGN_MEAN_FLOOR = .92;
+/** How many 8×8 tiles a node's device bbox spans (≥1) — the coverage denominator. */
+function bboxTileArea(box, win) {
+	return Math.max(1, (box.maxX - box.minX) / win) * Math.max(1, (box.maxY - box.minY) / win);
+}
+/**
+* Attribute every residual tile (`ssim < floor`) of one frame's SSIM grid to a
+* node (or ORPHAN). PURE + total-order: each tile decides independently, so tile
+* iteration order never changes the result. Returns per-node residuals + the
+* orphan tiles' union.
+*/
+function attributeResiduals(map, bounds, floor) {
+	const perNode = /* @__PURE__ */ new Map();
+	let orphan = null;
+	const nodeList = [...bounds.entries()];
+	const add = (into, box, ssim) => {
+		if (!into) return {
+			region: { ...box },
+			worst: ssim,
+			sum: ssim,
+			count: 1
+		};
+		into.region.minX = Math.min(into.region.minX, box.minX);
+		into.region.minY = Math.min(into.region.minY, box.minY);
+		into.region.maxX = Math.max(into.region.maxX, box.maxX);
+		into.region.maxY = Math.max(into.region.maxY, box.maxY);
+		into.worst = Math.min(into.worst, ssim);
+		into.sum += ssim;
+		into.count += 1;
+		return into;
+	};
+	for (let ty = 0; ty < map.rows; ty++) for (let tx = 0; tx < map.cols; tx++) {
+		const s = map.tiles[ty * map.cols + tx];
+		if (s >= floor) continue;
+		const cx = tx * map.win + map.win / 2;
+		const cy = ty * map.win + map.win / 2;
+		const tileBox = {
+			minX: tx * map.win,
+			minY: ty * map.win,
+			maxX: (tx + 1) * map.win,
+			maxY: (ty + 1) * map.win
+		};
+		const owner = attributeTile(cx, cy, nodeList);
+		if (owner) perNode.set(owner, add(perNode.get(owner) ?? null, tileBox, s));
+		else orphan = add(orphan, tileBox, s);
+	}
+	return {
+		perNode,
+		orphan
+	};
+}
+/** The total order: containing nodes → TOPMOST paint → node-id; else nearest by
+*  edge distance (tie paint-order then id) within ORPHAN_RADIUS; else undefined. */
+function attributeTile(cx, cy, nodeList) {
+	let best;
+	for (const [id, nb] of nodeList) {
+		const b = nb.bounds;
+		if (cx >= b.minX && cx <= b.maxX && cy >= b.minY && cy <= b.maxY) {
+			if (!best || nb.order > best.order || nb.order === best.order && id < best.id) best = {
+				id,
+				order: nb.order
+			};
+		}
+	}
+	if (best) return best.id;
+	let near;
+	for (const [id, nb] of nodeList) {
+		const d = edgeDistance(cx, cy, nb.bounds);
+		if (d > ORPHAN_RADIUS) continue;
+		if (!near || d < near.dist || d === near.dist && (nb.order > near.order || nb.order === near.order && id < near.id)) near = {
+			id,
+			dist: d,
+			order: nb.order
+		};
+	}
+	return near?.id;
+}
+function edgeDistance(x, y, b) {
+	const dx = Math.max(b.minX - x, 0, x - b.maxX);
+	const dy = Math.max(b.minY - y, 0, y - b.maxY);
+	return Math.hypot(dx, dy);
+}
+/** id-less render-only warns → the scene `describeType`(s) that produce them, so a
+*  warn with no quoted id still resolves to its render-only node(s) structurally. */
+const FEATURE_TYPES = {
+	"motion-blur": ["MotionBlur"],
+	"echo-trails": ["Echo"],
+	"camera-shake": ["Camera"],
+	shake: ["Camera"],
+	followpath: ["FollowPath"],
+	orienttopath: ["OrientToPath"],
+	lookat: ["LookAt"],
+	"text-cursor": ["TextCursor"]
+};
+/** Collect a node's id-bearing subtree (itself + descendants). */
+function collectSubtreeIds(node, into) {
+	if (node.id !== void 0) into.add(node.id);
+	const children = node.children;
+	if (Array.isArray(children)) for (const c of children) collectSubtreeIds(c, into);
+}
+/**
+* Resolve each export warn to the set of scene node ids its drop STRUCTURALLY
+* explains: a WRAPPER (motionBlur/echo/camera) explains its whole SUBTREE; a DRIVER
+* (followPath/orientToPath/lookAt) explains its `.target`'s subtree (the target is a
+* SIBLING it mutates, which an ancestry walk would miss); a leaf (Image/Video/Text)
+* explains only ITSELF. This structural link — never bare geometric overlap — is what
+* keeps an INDEPENDENT residual that merely sits inside a drop's bbox UNEXPLAINED.
+*/
+function buildDropExtents(scene, warns) {
+	const byType = /* @__PURE__ */ new Map();
+	const indexTree = (node) => {
+		const t = node.describeType;
+		(byType.get(t) ?? byType.set(t, []).get(t)).push(node);
+		const children = node.children;
+		if (Array.isArray(children)) for (const c of children) indexTree(c);
+	};
+	indexTree(scene.root);
+	const out = [];
+	warns.forEach((warn, i) => {
+		const resolved = [];
+		if (warn.node !== void 0) {
+			const n = scene.nodes.get(warn.node);
+			if (n) resolved.push(n);
+		} else for (const type of FEATURE_TYPES[warn.property] ?? []) resolved.push(...byType.get(type) ?? []);
+		if (resolved.length === 0) return;
+		const ids = /* @__PURE__ */ new Set();
+		for (const n of resolved) {
+			collectSubtreeIds(n, ids);
+			const target = n.target;
+			if (target && typeof target === "object") collectSubtreeIds(target, ids);
+		}
+		out.push({
+			key: warn.node ?? `${warn.property}@${i}`,
+			...warn.node !== void 0 ? { node: warn.node } : {},
+			warn,
+			ids
+		});
+	});
+	return out;
+}
+function regionRole(region, w, h) {
+	const cx = (region.minX + region.maxX) / 2;
+	const cy = (region.minY + region.maxY) / 2;
+	if (cy >= h * .72) return {
+		role: "caption-safe-area",
+		weight: 3
+	};
+	if (cx >= w / 3 && cx <= 2 * w / 3 && cy >= h / 3 && cy <= 2 * h / 3) return {
+		role: "focal-center",
+		weight: 2
+	};
+	return {
+		role: "edge",
+		weight: 1
+	};
+}
+function round(n) {
+	return Math.round(n * 1e3) / 1e3;
+}
+function roundBox(b) {
+	return {
+		minX: Math.round(b.minX),
+		minY: Math.round(b.minY),
+		maxX: Math.round(b.maxX),
+		maxY: Math.round(b.maxY)
+	};
+}
+function boxesOverlap(a, b) {
+	return a.minX <= b.maxX && a.maxX >= b.minX && a.minY <= b.maxY && a.maxY >= b.minY;
+}
+async function semanticParityCommand(opts) {
+	const mod = opts.module ?? await loadSceneModule(opts.modulePath);
+	const size = mod.createScene().size;
+	const w = opts.width ?? size.w;
+	const h = opts.height ?? size.h;
+	const fps = opts.fps ?? mod.timeline.fps ?? 60;
+	const frames = opts.frames ?? DEFAULT_PARITY_FRAMES;
+	const floor = opts.min ?? .98;
+	const refScene = mod.createScene();
+	const refBackend = new SkiaBackend(w, h);
+	await prepareSkiaRenderEnv({
+		scene: refScene,
+		doc: mod.timeline,
+		backend: refBackend,
+		modulePath: opts.modulePath
+	});
+	const measurer = refBackend;
+	const encodePng = (rgba, rw, rh) => {
+		const b = new SkiaBackend(rw, rh);
+		b.putPixels(rgba);
+		return b.encodePng().toString("base64");
+	};
+	const warnings = [];
+	const rtMod = importLottie(exportLottie(mod, {
+		width: w,
+		height: h,
+		fps,
+		measurer,
+		onWarn: (m) => warnings.push(m),
+		encodePng
+	})).toSceneModule();
+	const rtScene = rtMod.createScene();
+	const rtBackend = new SkiaBackend(w, h);
+	const fontAssets = Object.fromEntries(Object.entries(mod.timeline.assets ?? {}).filter(([, a]) => a.kind === "font"));
+	await prepareSkiaRenderEnv({
+		scene: rtScene,
+		doc: {
+			...rtMod.timeline,
+			assets: {
+				...rtMod.timeline.assets ?? {},
+				...fontAssets
+			}
+		},
+		backend: rtBackend,
+		modulePath: opts.modulePath
+	});
+	const parsedWarns = warnings.map(parseWarn);
+	const nodeAcc = /* @__PURE__ */ new Map();
+	let orphanAcc = null;
+	let anyResidual = false;
+	for (const frame of frames) {
+		const t = frame / fps;
+		const { displayList, ids } = withDeterminismGuards("throw", () => emitWithIds(refScene, mod.timeline, t));
+		refBackend.render(displayList);
+		const refRgba = await refBackend.readPixels();
+		const rtDl = withDeterminismGuards("throw", () => evaluate(rtScene, rtMod.timeline, t));
+		rtBackend.render(rtDl);
+		const map = ssimMap(refRgba, await rtBackend.readPixels(), w, h);
+		const bounds = walkBounds(displayList, ids);
+		const { perNode, orphan } = attributeResiduals(map, bounds, floor);
+		for (const [id, res] of perNode) {
+			const nb = bounds.get(id);
+			const coverage = nb ? res.count / bboxTileArea(nb.bounds, map.win) : 1;
+			const ex = nodeAcc.get(id);
+			if (!ex || res.worst < ex.worst) nodeAcc.set(id, {
+				region: res.region,
+				worst: res.worst,
+				mean: res.sum / res.count,
+				frame,
+				role: regionRole(res.region, w, h),
+				coverage
+			});
+		}
+		if (orphan && orphan.count >= MIN_ORPHAN_TILES) {
+			anyResidual = true;
+			if (!orphanAcc || orphan.worst < orphanAcc.worst) orphanAcc = {
+				region: orphan.region,
+				worst: orphan.worst,
+				frame,
+				tiles: orphan.count
+			};
+		}
+	}
+	const findings = [];
+	const emittedCauses = /* @__PURE__ */ new Set();
+	const warnByNode = /* @__PURE__ */ new Map();
+	for (const pw of parsedWarns) if (pw.node !== void 0 && !warnByNode.has(pw.node)) warnByNode.set(pw.node, pw);
+	const dropExtents = buildDropExtents(refScene, parsedWarns);
+	const explainedBy = /* @__PURE__ */ new Map();
+	for (const ext of dropExtents) for (const id of ext.ids) {
+		const list = explainedBy.get(id);
+		if (list) list.push(ext);
+		else explainedBy.set(id, [ext]);
+	}
+	const attributed = /* @__PURE__ */ new Map();
+	const merge = (key, node, acc, warn, real, from) => {
+		const ex = attributed.get(key);
+		if (!ex) {
+			attributed.set(key, {
+				region: { ...acc.region },
+				worst: acc.worst,
+				mean: acc.mean,
+				frame: acc.frame,
+				role: acc.role,
+				...warn ? { warn } : {},
+				...node !== void 0 ? { node } : {},
+				coalesced: new Set(key === from ? [] : [from]),
+				real
+			});
+			return;
+		}
+		ex.region.minX = Math.min(ex.region.minX, acc.region.minX);
+		ex.region.minY = Math.min(ex.region.minY, acc.region.minY);
+		ex.region.maxX = Math.max(ex.region.maxX, acc.region.maxX);
+		ex.region.maxY = Math.max(ex.region.maxY, acc.region.maxY);
+		if (acc.worst < ex.worst) {
+			ex.worst = acc.worst;
+			ex.mean = acc.mean;
+			ex.frame = acc.frame;
+			ex.role = acc.role;
+		}
+		if (key !== from) ex.coalesced.add(from);
+		ex.real = ex.real || real;
+	};
+	for (const [id, acc] of nodeAcc) {
+		if (warnByNode.has(id)) {
+			merge(id, id, acc, warnByNode.get(id), true, id);
+			continue;
+		}
+		const exts = explainedBy.get(id);
+		if (exts && exts.length > 0) {
+			const ext = exts.reduce((a, b) => a.key <= b.key ? a : b);
+			merge(ext.key, ext.node, acc, ext.warn, true, id);
+			continue;
+		}
+		merge(id, id, acc, void 0, acc.coverage >= COVERAGE_MIN, id);
+	}
+	for (const [, at] of attributed) {
+		if (!at.real) continue;
+		anyResidual = true;
+		const coalesced = [...at.coalesced].sort();
+		if (at.warn) {
+			emittedCauses.add(at.warn.cause);
+			findings.push(dropFinding(at.warn, at.node, at.region, at.frame, round(at.worst), at.role, coalesced));
+		} else {
+			const node = at.node !== void 0 ? refScene.nodes.get(at.node) : void 0;
+			if (node?.hasAnchor === true && (node.anchor[0] !== .5 || node.anchor[1] !== .5)) findings.push(anchorFinding(at.node, node.anchor, at.region, at.frame, round(at.worst), at.role));
+			else if (at.mean >= BENIGN_MEAN_FLOOR) findings.push(compositingApprox(at.node, at.region, at.frame, round(at.mean), at.role));
+			else findings.push(unexplained(at.node, at.region, at.frame, round(at.worst), at.role));
+		}
+	}
+	for (const warn of parsedWarns) {
+		if (emittedCauses.has(warn.cause)) continue;
+		findings.push(dropFinding(warn, warn.node, null, frames[0] ?? 0, null, null, []));
+		emittedCauses.add(warn.cause);
+	}
+	if (orphanAcc) findings.push(unexplained(void 0, orphanAcc.region, orphanAcc.frame, round(orphanAcc.worst), regionRole(orphanAcc.region, w, h)));
+	const sorted = sortDiagnostics(findings);
+	const invRegionOverlaps = sorted.every((f) => {
+		if (f.detail?.expected !== true) return true;
+		const region = f.detail?.region;
+		return region === void 0 || boxesOverlap(region, region);
+	});
+	const everyResidualHasCause = !anyResidual || sorted.some((f) => f.detail?.region !== void 0);
+	const everyWarnHasFinding = parsedWarns.every((pw) => sorted.some((f) => f.detail?.cause === pw.cause));
+	const keyOf = (f) => `${f.node ?? ""}|${f.code}|${String(f.detail?.property ?? "")}`;
+	const baseline = new Set(opts.baseline ?? []);
+	const newExpected = opts.baseline ? sorted.filter((f) => f.detail?.expected === true && !baseline.has(keyOf(f))).map(keyOf) : [];
+	const result = {
+		schemaVersion: DIAGNOSTIC_SCHEMA_VERSION,
+		findings: sorted,
+		view: opts.all ? sorted : sorted.filter((f) => f.severity === "error" || opts.baseline !== void 0 && f.detail?.expected === true && newExpected.includes(keyOf(f))),
+		warnings,
+		hasErrors: sorted.some((f) => f.severity === "error"),
+		invariants: {
+			regionOverlapsResidual: invRegionOverlaps,
+			everyResidualHasCause,
+			everyWarnHasFinding
+		},
+		newExpected,
+		width: w,
+		height: h,
+		floor,
+		frames
+	};
+	return {
+		...result,
+		report: formatReport(result, opts)
+	};
+}
+function dropFinding(warn, node, region, frame, ssim, role, coalesced = []) {
+	return {
+		schemaVersion: DIAGNOSTIC_SCHEMA_VERSION,
+		code: warn.approximate ? "LOTTIE_APPROXIMATE" : "LOTTIE_DROP",
+		severity: warn.approximate ? "warning" : "info",
+		source: "parity",
+		...node !== void 0 ? { node } : {},
+		message: `${warn.property} on ${node ? `'${node}'` : "an unnamed node"} ${warn.approximate ? "exports DEGRADED" : "is DROPPED"} by Lottie export — ${warn.cause}`,
+		detail: {
+			property: warn.property,
+			cause: warn.cause,
+			frame,
+			expected: true,
+			...region ? { region: roundBox(region) } : {},
+			...ssim !== null ? { ssim } : {},
+			...role ? {
+				role: role.role,
+				roleWeight: role.weight
+			} : {},
+			...coalesced.length > 0 ? { coalesced } : {}
+		}
+	};
+}
+/** Class III: an UNWARNED but BENIGN sub-pixel compositing residual (Stack/sequence
+*  rounding) — tagged LOTTIE_APPROXIMATE (expected:true → masked from the default
+*  error view) so it doesn't alarm as an episode-breaking UNEXPLAINED. */
+function compositingApprox(node, region, frame, meanSsim, role) {
+	return {
+		schemaVersion: DIAGNOSTIC_SCHEMA_VERSION,
+		code: "LOTTIE_APPROXIMATE",
+		severity: "warning",
+		source: "parity",
+		...node !== void 0 ? { node } : {},
+		message: `${node ? `node '${node}'` : "a region"} shows a BENIGN sub-pixel compositing difference on the Lottie round-trip (mean ssim ${meanSsim}, no feature dropped) — a rounding/layer-order approximation, not a loss.`,
+		detail: {
+			property: "compositing-approx",
+			frame,
+			region: roundBox(region),
+			ssim: meanSsim,
+			expected: true,
+			role: role.role,
+			roleWeight: role.weight
+		}
+	};
+}
+function anchorFinding(id, anchor, region, frame, ssim, role) {
+	return {
+		schemaVersion: DIAGNOSTIC_SCHEMA_VERSION,
+		code: "ANCHOR_RECENTER",
+		severity: "warning",
+		source: "parity",
+		node: id,
+		message: `node '${id}' has a non-center anchor [${round(anchor[0])}, ${round(anchor[1])}] that Lottie export re-centers (MIS-export — wrong pixels, not absent). Report-only in 0.61 (the anchor-correct-export fix is 0.68).`,
+		detail: {
+			fromAnchor: [round(anchor[0]), round(anchor[1])],
+			toAnchor: "center",
+			frame,
+			region: roundBox(region),
+			ssim,
+			expected: false,
+			role: role.role,
+			roleWeight: role.weight
+		}
+	};
+}
+function unexplained(node, region, frame, ssim, role) {
+	return {
+		schemaVersion: DIAGNOSTIC_SCHEMA_VERSION,
+		code: "UNEXPLAINED_RESIDUAL",
+		severity: "error",
+		source: "parity",
+		...node !== void 0 ? { node } : {},
+		message: `${node ? `node '${node}'` : "a residual region"} diverges on the Lottie round-trip (ssim ${ssim}) with NO matching export warn — an UNEXPLAINED divergence (the episode-breaking class). Investigate: this loss is silent.`,
+		detail: {
+			frame,
+			region: roundBox(region),
+			ssim,
+			expected: false,
+			...role ? {
+				role: role.role,
+				roleWeight: role.weight
+			} : {}
+		}
+	};
+}
+function formatReport(r, opts) {
+	const lines = [];
+	lines.push(`gs parity --semantic — Skia↔Lottie round-trip @ ${r.width}×${r.height}, floor ${r.floor}, frames ${r.frames.join(",")} — ${r.findings.length} finding${r.findings.length === 1 ? "" : "s"}${opts.all ? "" : ` (${r.view.length} in default error-only view; --all for every finding)`}`);
+	for (const f of r.view) {
+		const where = f.node ? ` [${f.node}]` : "";
+		lines.push(`  ${f.severity.toUpperCase()} ${f.code}${where}: ${f.message}`);
+	}
+	const inv = r.invariants;
+	lines.push(`  invariants: region-overlaps-residual ${inv.regionOverlapsResidual ? "✓" : "✗"}, every-residual-has-cause ${inv.everyResidualHasCause ? "✓" : "✗"}, every-warn-has-finding ${inv.everyWarnHasFinding ? "✓" : "✗"}`);
+	if (opts.baseline !== void 0) lines.push(r.newExpected.length === 0 ? `  baseline: PASS — no NEW expected drop` : `  baseline: FAIL — ${r.newExpected.length} NEW expected drop(s) absent from the pin: ${r.newExpected.join(", ")}`);
+	lines.push(r.hasErrors ? `  FAIL — ${r.findings.filter((f) => f.severity === "error").length} UNEXPLAINED residual(s) (the never-silent alarm)` : `  PASS — every residual is a warn-explained (expected) drop`);
+	return lines.join("\n");
+}
+//#endregion
+export { semanticParityCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.60.0",
+  "version": "0.61.0-pre.1",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "engines": {
@@ -28,15 +28,15 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.60.0",
-    "@glissade/core": "0.60.0",
-    "@glissade/interact": "0.60.0",
-    "@glissade/lottie": "0.60.0",
-    "@glissade/narrate": "0.60.0",
-    "@glissade/player": "0.60.0",
-    "@glissade/scene": "0.60.0",
-    "@glissade/sfx": "0.60.0",
-    "@glissade/svg": "0.60.0"
+    "@glissade/backend-skia": "0.61.0-pre.1",
+    "@glissade/core": "0.61.0-pre.1",
+    "@glissade/interact": "0.61.0-pre.1",
+    "@glissade/lottie": "0.61.0-pre.1",
+    "@glissade/narrate": "0.61.0-pre.1",
+    "@glissade/player": "0.61.0-pre.1",
+    "@glissade/scene": "0.61.0-pre.1",
+    "@glissade/sfx": "0.61.0-pre.1",
+    "@glissade/svg": "0.61.0-pre.1"
   },
   "repository": {
     "type": "git",