@glissade/cli 0.48.0-pre.2 → 0.49.0-pre.0

package/dist/cli.js

@@ -99,6 +99,7 @@ const USAGE = `usage:
   gs types [--out <file.ts>] [--from <api.json>] [--check] [--global]   codegen a type-checked track() SDK from the describe() manifest: only registered animatable paths + their value types compile, so a typo'd path or wrong value-type id is a COMPILE error (import track from the generated file). --check fails if --out is stale. Zero-runtime (types + a re-typed re-export of the real track). --global (alias --iife) instead emits a SELF-CONTAINED ambient window.glissade .d.ts for the no-build <script src> author (typed IIFE surface — a typo'd window.glissade member is a compile error)
   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>]   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. (dom = Phase B, not yet shipped)
   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
 
@@ -210,7 +211,7 @@ async function main() {
 		process.stdout.write(`${describe().version}\n`);
 		return;
 	}
-	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "export" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate" && command !== "repin" && command !== "master" && command !== "localize" && command !== "types") {
+	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "export" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate" && command !== "repin" && command !== "parity" && command !== "master" && command !== "localize" && command !== "types") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -430,6 +431,55 @@ async function main() {
 		}
 		return;
 	}
+	if (command === "parity") {
+		const { positional: pp, flags: pf } = parseArgs(rest);
+		const sceneModule = pp[0];
+		if (!sceneModule) fail(`gs parity needs <scene-module>\n${USAGE}`);
+		const nums = (raw) => raw === void 0 ? void 0 : raw.split(",").map((s) => {
+			const n = Number(s.trim());
+			if (!Number.isInteger(n) || n < 0) fail(`parity: '${s}' is not a frame number (expected comma-separated non-negative integers)`);
+			return n;
+		});
+		const dim = (flagName) => {
+			const raw = pf.get(flagName);
+			if (raw === void 0 || raw === "") return void 0;
+			const n = Number(raw);
+			if (!Number.isFinite(n) || n <= 0) fail(`parity: --${flagName} must be a positive number, got '${raw}'`);
+			return n;
+		};
+		const minRaw = pf.get("min");
+		let min;
+		if (minRaw !== void 0) {
+			min = Number(minRaw);
+			if (!(min >= -1 && min <= 1)) fail(`parity: --min must be an SSIM floor in [-1, 1], got '${minRaw}'`);
+		}
+		const { parityCommand, parseBackends, ParityBackendError } = await import("./parity.js");
+		let backends;
+		try {
+			backends = parseBackends(pf.get("backends"));
+		} catch (err) {
+			fail(err instanceof ParityBackendError ? err.message : err instanceof Error ? err.message : String(err));
+		}
+		const width = dim("width");
+		const height = dim("height");
+		try {
+			const result = await parityCommand({
+				modulePath: sceneModule,
+				backends,
+				...nums(pf.get("frames")) ? { frames: nums(pf.get("frames")) } : {},
+				...pf.get("fps") ? { fps: parseFpsOrFail(pf.get("fps")) } : {},
+				...width !== void 0 ? { width } : {},
+				...height !== void 0 ? { height } : {},
+				...pf.get("heatmap") ? { heatmapDir: pf.get("heatmap") } : {},
+				...min !== void 0 ? { min } : {}
+			});
+			process.stdout.write(`${result.report}\n`);
+			if (!result.ok) process.exit(1);
+		} catch (err) {
+			fail(err instanceof ParityBackendError ? err.message : err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	if (command === "localize") {
 		const { positional: lp, flags: lf } = parseArgs(rest);
 		const sceneModule = lp[0];

package/dist/parity.js

@@ -0,0 +1,177 @@
+import { o as loadSceneModule } from "./render.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { evaluate } from "@glissade/scene";
+import { SkiaBackend, heatmapRgba, ssimMap } from "@glissade/backend-skia";
+import { exportLottie, importLottie } from "@glissade/lottie";
+//#region src/parity.ts
+/**
+* `gs parity` (Phase A) — the cross-backend perceptual reviewer.
+*
+* Renders ONE scene across backends and reports, per frame, how far each backend
+* strays from the Skia reference: mean SSIM, the worst 8×8 tile (WHERE it drifts),
+* and an optional thermal heat-map PNG. It answers "does my Lottie export still
+* look like the real render?" as a NUMBER, per frame, headlessly.
+*
+* Phase A ships two legs, both in-process, ZERO browser deps:
+*   • `skia`   — the direct headless render (the reference every leg is diffed
+*                against): createScene → SkiaBackend.render(evaluate(...)) → readPixels.
+*   • `lottie` — the export↔import round-trip: exportLottie(mod) → importLottie(doc)
+*                .toSceneModule() → render the re-imported module on Skia → readPixels.
+*                This measures the Lottie bijection the same way the round-trip gate does.
+*
+* SSIM is the perceptual metric (`ssimMap` from the shipped @glissade/backend-skia),
+* NOT byte-equality — browser/exporter parity is perceptual by contract (DESIGN §3.4).
+* A `--min` floor (default 0.98) gates the run: any frame below it fails (non-zero exit).
+*
+* The `dom` leg (a DOM-backend rasterizer via Playwright) is Phase B — it is NOT
+* accepted here and fails loud rather than silently skipping a requested backend.
+*/
+/** Default sampled frames + fps — matches the round-trip / golden suites' cadence. */
+const DEFAULT_PARITY_FRAMES = [
+	0,
+	30,
+	60,
+	90,
+	119
+];
+/** 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). */
+const PHASE_A_BACKENDS = new Set(["skia", "lottie"]);
+/** Raised for an unknown or not-yet-shipped backend — the CLI turns it into a loud fail(). */
+var ParityBackendError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ParityBackendError";
+	}
+};
+/** Parse + validate a `--backends` list. dom fails loud (Phase B); unknown fails loud. */
+function parseBackends(raw) {
+	if (raw === void 0 || raw.trim() === "") return ["skia", "lottie"];
+	const list = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	if (list.length === 0) return ["skia", "lottie"];
+	for (const b of list) {
+		if (b === "dom") throw new ParityBackendError("the dom parity leg needs Playwright + chromium-headless-shell — Phase B, not yet shipped (Phase A backends: skia, lottie)");
+		if (!PHASE_A_BACKENDS.has(b)) throw new ParityBackendError(`unknown parity backend '${b}' (Phase A backends: skia, lottie)`);
+	}
+	return list;
+}
+/** skia = the direct headless render (repin's render→pixels shape) — the reference. */
+function skiaSource(mod, w, h) {
+	return async (t) => {
+		const scene = mod.createScene();
+		const backend = new SkiaBackend(w, h);
+		scene.setTextMeasurer(backend);
+		backend.render(evaluate(scene, mod.timeline, t));
+		return backend.readPixels();
+	};
+}
+/**
+* lottie = the export↔import round-trip rendered on Skia (roundtrip.test's renderPixels
+* shape). The document is exported/imported ONCE (it's time-independent); each frame
+* evaluates the re-imported module — so the leg measures the Lottie bijection per frame.
+*/
+function lottieSource(mod, w, h, fps) {
+	return skiaSource(importLottie(exportLottie(mod, {
+		width: w,
+		height: h,
+		fps
+	})).toSceneModule(), w, h);
+}
+function makeSource(backend, mod, w, h, fps) {
+	switch (backend) {
+		case "skia": return skiaSource(mod, w, h);
+		case "lottie": return lottieSource(mod, w, h, fps);
+		default: throw new ParityBackendError(`unknown parity backend '${backend}'`);
+	}
+}
+async function parityCommand(opts) {
+	const compared = (opts.backends ?? ["skia", "lottie"]).filter((b) => b !== REFERENCE_BACKEND);
+	if (compared.length === 0) throw new ParityBackendError(`gs parity needs at least one non-reference backend to compare against skia (e.g. --backends skia,lottie)`);
+	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 name = opts.name ?? basename(opts.modulePath).replace(/\.[jt]sx?$/, "");
+	const reference = skiaSource(mod, w, h);
+	const sources = new Map(compared.map((b) => [b, makeSource(b, mod, w, h, fps)]));
+	if (opts.heatmapDir && !existsSync(opts.heatmapDir)) mkdirSync(opts.heatmapDir, { recursive: true });
+	const results = [];
+	let belowFloor = 0;
+	let worstMean = Infinity;
+	let worstAt = null;
+	for (const frame of frames) {
+		const t = frame / fps;
+		const refRgba = await reference(t);
+		const pairs = [];
+		for (const backend of compared) {
+			const map = ssimMap(refRgba, await sources.get(backend)(t), w, h);
+			const below = map.mean < floor;
+			if (below) belowFloor++;
+			if (map.mean < worstMean) {
+				worstMean = map.mean;
+				worstAt = {
+					frame,
+					backend
+				};
+			}
+			const pair = {
+				backend,
+				mean: map.mean,
+				min: map.min,
+				minTile: map.minTile,
+				belowFloor: below
+			};
+			if (opts.heatmapDir) {
+				const hb = new SkiaBackend(w, h);
+				hb.putPixels(heatmapRgba(map, w, h));
+				const hp = join(opts.heatmapDir, `${name}-${backend}-f${String(frame).padStart(4, "0")}.heat.png`);
+				writeFileSync(hp, hb.encodePng());
+				pair.heatmap = hp;
+			}
+			pairs.push(pair);
+		}
+		results.push({
+			frame,
+			t,
+			pairs
+		});
+	}
+	const result = {
+		frames: results,
+		backends: compared,
+		width: w,
+		height: h,
+		floor,
+		worstMean,
+		worstAt,
+		belowFloor,
+		ok: belowFloor === 0
+	};
+	return {
+		...result,
+		report: formatReport(name, result)
+	};
+}
+function formatReport(name, r) {
+	const lines = [];
+	lines.push(`gs parity '${name}' — ${REFERENCE_BACKEND} reference vs ${r.backends.join(", ")} — ${r.frames.length} frame${r.frames.length === 1 ? "" : "s"} @ ${r.width}×${r.height}, floor ${r.floor}`);
+	for (const f of r.frames) {
+		const fno = `f${String(f.frame).padStart(4, "0")}`;
+		for (const p of f.pairs) {
+			const tile = `@ tile ${p.minTile.tx},${p.minTile.ty}`;
+			const mark = p.belowFloor ? "  ⚠ BELOW FLOOR" : "";
+			const heat = p.heatmap ? `  → ${p.heatmap}` : "";
+			lines.push(`  ${fno}  ${p.backend.padEnd(6)} ssim ${p.mean.toFixed(4)} (min ${p.min.toFixed(3)} ${tile})${mark}${heat}`);
+		}
+	}
+	if (r.worstAt) lines.push(`  worst: f${String(r.worstAt.frame).padStart(4, "0")} ${r.worstAt.backend} ssim ${r.worstMean.toFixed(4)}`);
+	lines.push(r.ok ? `  PASS — every frame ≥ floor ${r.floor}` : `  FAIL — ${r.belowFloor} comparison${r.belowFloor === 1 ? "" : "s"} below floor ${r.floor}`);
+	return lines.join("\n");
+}
+//#endregion
+export { ParityBackendError, parityCommand, parseBackends };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.48.0-pre.2",
+  "version": "0.49.0-pre.0",
   "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.48.0-pre.2",
-    "@glissade/core": "0.48.0-pre.2",
-    "@glissade/interact": "0.48.0-pre.2",
-    "@glissade/lottie": "0.48.0-pre.2",
-    "@glissade/narrate": "0.48.0-pre.2",
-    "@glissade/player": "0.48.0-pre.2",
-    "@glissade/scene": "0.48.0-pre.2",
-    "@glissade/sfx": "0.48.0-pre.2",
-    "@glissade/svg": "0.48.0-pre.2"
+    "@glissade/backend-skia": "0.49.0-pre.0",
+    "@glissade/core": "0.49.0-pre.0",
+    "@glissade/interact": "0.49.0-pre.0",
+    "@glissade/lottie": "0.49.0-pre.0",
+    "@glissade/narrate": "0.49.0-pre.0",
+    "@glissade/player": "0.49.0-pre.0",
+    "@glissade/scene": "0.49.0-pre.0",
+    "@glissade/sfx": "0.49.0-pre.0",
+    "@glissade/svg": "0.49.0-pre.0"
   },
   "repository": {
     "type": "git",