@glissade/cli 0.61.0-pre.0 → 0.61.0-pre.1

package/dist/semanticParity.js

@@ -186,6 +186,7 @@ function parseWarn(msg) {
 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);
@@ -267,19 +268,63 @@ function edgeDistance(x, y, b) {
 	const dy = Math.max(b.minY - y, 0, y - b.maxY);
 	return Math.hypot(dx, dy);
 }
-/** Walk `id`'s ided ancestor chain; return the nearest ancestor a DROP warn names
-*  (a render-only wrapper — camera/shake/motionBlur/echo — whose drop explains this
-*  descendant's divergence), so the residual coalesces to ONE finding at that drop
-*  instead of N unexplained leaves. Deterministic (the tree is fixed). */
-function nearestWarnedAncestor(scene, id, warnByNode) {
-	let p = scene.nodes.get(id)?.parent ?? null;
-	while (p) {
-		if (p.id !== void 0 && warnByNode.has(p.id)) return {
-			id: p.id,
-			warn: warnByNode.get(p.id)
-		};
-		p = p.parent;
-	}
+/** 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;
@@ -378,6 +423,7 @@ async function semanticParityCommand(opts) {
 			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
@@ -394,19 +440,29 @@ async function semanticParityCommand(opts) {
 		}
 	}
 	const findings = [];
-	const warnedNodesEmitted = /* @__PURE__ */ new Set();
+	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 mergeAttribution = (key, acc, warn, real) => {
+	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;
@@ -417,34 +473,44 @@ async function semanticParityCommand(opts) {
 		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)) mergeAttribution(id, acc, warnByNode.get(id), true);
-	else {
-		const anc = nearestWarnedAncestor(refScene, id, warnByNode);
-		if (anc) mergeAttribution(anc.id, acc, anc.warn, true);
-		else mergeAttribution(id, acc, void 0, acc.coverage >= COVERAGE_MIN);
+	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 [id, at] of attributed) {
+	for (const [, at] of attributed) {
 		if (!at.real) continue;
 		anyResidual = true;
-		const mean = round(at.worst);
+		const coalesced = [...at.coalesced].sort();
 		if (at.warn) {
-			warnedNodesEmitted.add(id);
-			findings.push(dropFinding(at.warn, id, at.region, at.frame, mean, at.role));
+			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 = refScene.nodes.get(id);
-			if (node?.hasAnchor === true && (node.anchor[0] !== .5 || node.anchor[1] !== .5)) findings.push(anchorFinding(id, node.anchor, at.region, at.frame, mean, at.role));
-			else findings.push(unexplained(id, at.region, at.frame, mean, at.role));
+			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 (warn.node !== void 0 && warnedNodesEmitted.has(warn.node)) continue;
-		findings.push(dropFinding(warn, warn.node, null, frames[0] ?? 0, null, null));
-		if (warn.node !== void 0) warnedNodesEmitted.add(warn.node);
+		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);
@@ -480,7 +546,7 @@ async function semanticParityCommand(opts) {
 		report: formatReport(result, opts)
 	};
 }
-function dropFinding(warn, node, region, frame, ssim, role) {
+function dropFinding(warn, node, region, frame, ssim, role, coalesced = []) {
 	return {
 		schemaVersion: DIAGNOSTIC_SCHEMA_VERSION,
 		code: warn.approximate ? "LOTTIE_APPROXIMATE" : "LOTTIE_DROP",
@@ -498,7 +564,30 @@ function dropFinding(warn, node, region, frame, ssim, role) {
 			...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
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.61.0-pre.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.61.0-pre.0",
-    "@glissade/core": "0.61.0-pre.0",
-    "@glissade/interact": "0.61.0-pre.0",
-    "@glissade/lottie": "0.61.0-pre.0",
-    "@glissade/narrate": "0.61.0-pre.0",
-    "@glissade/player": "0.61.0-pre.0",
-    "@glissade/scene": "0.61.0-pre.0",
-    "@glissade/sfx": "0.61.0-pre.0",
-    "@glissade/svg": "0.61.0-pre.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",