@glissade/cli 0.49.0-pre.1 → 0.50.0-pre.0

package/dist/cli.js

@@ -29,7 +29,8 @@ const KNOWN_BOOLEAN_FLAGS = new Set([
 	"lottie",
 	"lint",
 	"global",
-	"iife"
+	"iife",
+	"update-baseline"
 ]);
 function parseArgs(argv) {
 	const positional = [];
@@ -99,7 +100,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 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 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
 
@@ -453,6 +454,15 @@ async function main() {
 			min = Number(minRaw);
 			if (!(min >= -1 && min <= 1)) fail(`parity: --min must be an SSIM floor in [-1, 1], got '${minRaw}'`);
 		}
+		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}`);
+		const tolRaw = pf.get("tolerance");
+		let tolerance;
+		if (tolRaw !== void 0) {
+			tolerance = Number(tolRaw);
+			if (!(tolerance >= 0) || !Number.isFinite(tolerance)) fail(`parity: --tolerance must be a non-negative number, got '${tolRaw}'`);
+		}
 		const { parityCommand, parseBackends, ParityBackendError } = await import("./parity.js");
 		let backends;
 		try {
@@ -471,10 +481,15 @@ async function main() {
 				...width !== void 0 ? { width } : {},
 				...height !== void 0 ? { height } : {},
 				...pf.get("heatmap") ? { heatmapDir: pf.get("heatmap") } : {},
-				...min !== void 0 ? { min } : {}
+				...min !== void 0 ? { min } : {},
+				...baselinePath !== void 0 ? { baselinePath } : {},
+				...updateBaseline ? { updateBaseline: true } : {},
+				...tolerance !== void 0 ? { tolerance } : {}
 			});
 			process.stdout.write(`${result.report}\n`);
-			if (!result.ok) process.exit(1);
+			if (updateBaseline) {} else if (baselinePath !== void 0) {
+				if (result.gateOk !== true) process.exit(1);
+			} else if (!result.ok) process.exit(1);
 		} catch (err) {
 			fail(err instanceof ParityBackendError ? err.message : err instanceof Error ? err.message : String(err));
 		}

package/dist/parity.js

@@ -1,9 +1,124 @@
 import { d as prepareSkiaRenderEnv, o as loadSceneModule } from "./render.js";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { evaluate, withDeterminismGuards } from "@glissade/scene";
 import { SkiaBackend, heatmapRgba, ssimMap } from "@glissade/backend-skia";
 import { exportLottie, importLottie } from "@glissade/lottie";
+//#region src/parityBaseline.ts
+/**
+* `gs parity` known-drop regression-gate — the committed per-scene baseline.
+*
+* `gs parity` (Phase A) is RED-BY-DESIGN: documented scope-outs (non-center-anchor
+* transforms, gradient/mesh fills, variable-font axes, text-wrap, media) legitimately
+* fall below the 0.98 SSIM floor and fail the strict `--min` path. That makes the
+* command a fidelity READOUT, not a regression gate you can wire into CI.
+*
+* This module turns it into a real gate: a committed baseline pins each scope-out's
+* EXPECTED SSIM drop per (frame, backend); the run compares actual vs expected and
+* alerts only on DEVIATION — a new/worse drop is a REGRESSION (fail), while a
+* documented drop that matches its pin PASSES even though it's below the floor.
+*
+* Mirrors `gs repin`'s golden/baseline model (write vs compare split): a default
+* conventional path (`parityBaselinePathFor`, like `goldenPathFor`), a loud header
+* validation (the baseline is pinned at a specific w×h/fps/reference), and a
+* four-way classify (`compareToBaseline`, like repin's `RepinStatus`).
+*
+* Pure of the render pipeline — plain JSON I/O over `node:fs`. `parity.ts` owns the
+* render; this owns the baseline. (Dependency runs one way: parity.ts → here.)
+*/
+/** Raised for a malformed / mismatched baseline — the CLI turns it into a loud fail(). */
+var ParityBaselineError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ParityBaselineError";
+	}
+};
+function isRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function readExpectation(where, raw) {
+	if (!isRecord(raw)) throw new ParityBaselineError(`parity baseline: ${where} is not an object`);
+	if (typeof raw.mean !== "number" || !Number.isFinite(raw.mean)) throw new ParityBaselineError(`parity baseline: ${where} is missing a numeric 'mean'`);
+	const exp = { mean: raw.mean };
+	if (raw.min !== void 0) {
+		if (typeof raw.min !== "number" || !Number.isFinite(raw.min)) throw new ParityBaselineError(`parity baseline: ${where}.min is not a number`);
+		exp.min = raw.min;
+	}
+	if (raw.minTile !== void 0) {
+		const mt = raw.minTile;
+		if (!isRecord(mt) || typeof mt.tx !== "number" || typeof mt.ty !== "number") throw new ParityBaselineError(`parity baseline: ${where}.minTile is not {tx,ty}`);
+		exp.minTile = {
+			tx: mt.tx,
+			ty: mt.ty
+		};
+	}
+	return exp;
+}
+/** Read + structurally validate a baseline file. Any malformation fails LOUD. */
+function loadParityBaseline(path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new ParityBaselineError(`could not read parity baseline '${path}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!isRecord(parsed)) throw new ParityBaselineError(`parity baseline '${path}' is not a JSON object`);
+	const { name, width, height, fps, reference, frames } = parsed;
+	if (typeof name !== "string") throw new ParityBaselineError(`parity baseline '${path}': missing string 'name'`);
+	if (typeof width !== "number" || width <= 0) throw new ParityBaselineError(`parity baseline '${path}': missing positive 'width'`);
+	if (typeof height !== "number" || height <= 0) throw new ParityBaselineError(`parity baseline '${path}': missing positive 'height'`);
+	if (typeof fps !== "number" || fps <= 0) throw new ParityBaselineError(`parity baseline '${path}': missing positive 'fps'`);
+	if (typeof reference !== "string") throw new ParityBaselineError(`parity baseline '${path}': missing string 'reference'`);
+	if (!isRecord(frames)) throw new ParityBaselineError(`parity baseline '${path}': missing 'frames' object`);
+	const outFrames = {};
+	for (const [frame, backends] of Object.entries(frames)) {
+		if (!isRecord(backends)) throw new ParityBaselineError(`parity baseline '${path}': frame '${frame}' is not an object`);
+		const perBackend = {};
+		for (const [backend, exp] of Object.entries(backends)) perBackend[backend] = readExpectation(`frame '${frame}' backend '${backend}'`, exp);
+		outFrames[frame] = perBackend;
+	}
+	return {
+		name,
+		width,
+		height,
+		fps,
+		reference,
+		frames: outFrames
+	};
+}
+/** Write a baseline (pretty JSON), creating the parent dir — mirrors repin's --write emit. */
+function saveParityBaseline(path, baseline) {
+	const dir = dirname(path);
+	if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true });
+	writeFileSync(path, `${JSON.stringify(baseline, null, 2)}\n`);
+}
+/**
+* Assert the baseline was pinned at the SAME config as the live run. A mismatch
+* means the numbers aren't comparable (a 480×480 pin vs a 240×240 run) → LOUD fail
+* rather than a meaningless gate verdict.
+*/
+function assertBaselineHeader(b, live) {
+	const mm = [];
+	if (b.width !== live.width) mm.push(`width ${b.width} ≠ ${live.width}`);
+	if (b.height !== live.height) mm.push(`height ${b.height} ≠ ${live.height}`);
+	if (b.fps !== live.fps) mm.push(`fps ${b.fps} ≠ ${live.fps}`);
+	if (b.reference !== live.reference) mm.push(`reference '${b.reference}' ≠ '${live.reference}'`);
+	if (mm.length > 0) throw new ParityBaselineError(`parity baseline pinned at a different config: ${mm.join(", ")} — re-pin with --update-baseline`);
+}
+/**
+* Classify one live comparison against its pin.
+*   • no pin (unpinned frame/backend) → 'new'      → FAIL (must be accepted via --update-baseline)
+*   • mean ≥ expected − tol           → 'ok'       → PASS (even below the 0.98 floor — the point)
+*   • mean < expected − tol           → 'regressed'→ FAIL (a new/worse drop)
+*   • mean > expected + tol           → 'improved' → PASS but FLAG (re-pin tighter)
+*/
+function compareToBaseline(actualMean, expected, tolerance) {
+	if (expected === void 0) return "new";
+	if (actualMean < expected.mean - tolerance) return "regressed";
+	if (actualMean > expected.mean + tolerance) return "improved";
+	return "ok";
+}
+//#endregion
 //#region src/parity.ts
 /**
 * `gs parity` (Phase A) — the cross-backend perceptual reviewer.
@@ -116,6 +231,18 @@ async function parityCommand(opts) {
 	const frames = opts.frames ?? DEFAULT_PARITY_FRAMES;
 	const floor = opts.min ?? .98;
 	const name = opts.name ?? basename(opts.modulePath).replace(/\.[jt]sx?$/, "");
+	const tolerance = opts.tolerance ?? 1e-4;
+	const gating = opts.baselinePath !== void 0 && opts.updateBaseline !== true;
+	let baseline;
+	if (gating) {
+		baseline = loadParityBaseline(opts.baselinePath);
+		assertBaselineHeader(baseline, {
+			width: w,
+			height: h,
+			fps,
+			reference: REFERENCE_BACKEND
+		});
+	}
 	const reference = await skiaSource(mod, w, h, opts.modulePath);
 	const sources = /* @__PURE__ */ new Map();
 	for (const b of compared) sources.set(b, await makeSource(b, mod, w, h, fps, opts.modulePath));
@@ -124,6 +251,9 @@ async function parityCommand(opts) {
 	let belowFloor = 0;
 	let worstMean = Infinity;
 	let worstAt = null;
+	let regressed = 0;
+	let newComparisons = 0;
+	let improved = 0;
 	for (const frame of frames) {
 		const t = frame / fps;
 		const refRgba = await reference(t);
@@ -153,6 +283,18 @@ async function parityCommand(opts) {
 				writeFileSync(hp, hb.encodePng());
 				pair.heatmap = hp;
 			}
+			if (baseline) {
+				const expected = baseline.frames[String(frame)]?.[backend];
+				const status = compareToBaseline(map.mean, expected, tolerance);
+				pair.status = status;
+				if (expected !== void 0) {
+					pair.expected = expected.mean;
+					pair.delta = map.mean - expected.mean;
+				}
+				if (status === "regressed") regressed++;
+				else if (status === "new") newComparisons++;
+				else if (status === "improved") improved++;
+			}
 			pairs.push(pair);
 		}
 		results.push({
@@ -172,12 +314,85 @@ async function parityCommand(opts) {
 		belowFloor,
 		ok: belowFloor === 0
 	};
+	if (opts.updateBaseline === true) {
+		if (opts.baselinePath === void 0) throw new ParityBaselineError("gs parity --update-baseline needs --baseline <file> to write to");
+		const emitted = buildBaseline(name, w, h, fps, results);
+		let prior;
+		if (existsSync(opts.baselinePath)) try {
+			prior = loadParityBaseline(opts.baselinePath);
+		} catch {}
+		let added = 0;
+		let repinned = 0;
+		for (const [frame, backends] of Object.entries(emitted.frames)) for (const backend of Object.keys(backends)) {
+			const before = prior?.frames[frame]?.[backend];
+			if (before === void 0) added++;
+			else if (Math.abs(before.mean - backends[backend].mean) > tolerance) repinned++;
+		}
+		saveParityBaseline(opts.baselinePath, emitted);
+		const updated = {
+			...result,
+			improved,
+			baselineWritten: opts.baselinePath,
+			baselineAdded: added
+		};
+		return {
+			...updated,
+			regressed: repinned,
+			report: formatReport(name, updated, { repinned })
+		};
+	}
+	if (gating) {
+		const gated = {
+			...result,
+			regressed,
+			newComparisons,
+			improved,
+			gateOk: regressed === 0 && newComparisons === 0
+		};
+		return {
+			...gated,
+			report: formatReport(name, gated)
+		};
+	}
 	return {
 		...result,
 		report: formatReport(name, result)
 	};
 }
-function formatReport(name, r) {
+/** Build a baseline document from the live frames (used by --update-baseline). */
+function buildBaseline(name, w, h, fps, frames) {
+	const out = {};
+	for (const f of frames) {
+		const perBackend = {};
+		for (const p of f.pairs) perBackend[p.backend] = {
+			mean: p.mean,
+			min: p.min,
+			minTile: {
+				tx: p.minTile.tx,
+				ty: p.minTile.ty
+			}
+		};
+		out[String(f.frame)] = perBackend;
+	}
+	return {
+		name,
+		width: w,
+		height: h,
+		fps,
+		reference: REFERENCE_BACKEND,
+		frames: out
+	};
+}
+/** gate/update status → the report mark appended to a pair line. */
+const GATE_MARK = {
+	ok: "  ✓ expected-drop",
+	regressed: "  ⚠ REGRESSION",
+	new: "  ＋ NEW",
+	improved: "  ▲ improved"
+};
+function formatReport(name, r, extra) {
+	const update = r.baselineWritten !== void 0;
+	const gate = !update && r.gateOk !== void 0;
 	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) {
@@ -186,10 +401,23 @@ function formatReport(name, r) {
 			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}`);
+			let gateSuffix = "";
+			if (gate && p.status !== void 0) gateSuffix = `${p.expected !== void 0 ? ` exp ${p.expected.toFixed(4)} Δ${p.delta >= 0 ? "+" : ""}${p.delta.toFixed(4)}` : ""}${GATE_MARK[p.status]}`;
+			lines.push(`  ${fno}  ${p.backend.padEnd(6)} ssim ${p.mean.toFixed(4)} (min ${p.min.toFixed(3)} ${tile})${gateSuffix}${mark}${heat}`);
 		}
 	}
 	if (r.worstAt) lines.push(`  worst: f${String(r.worstAt.frame).padStart(4, "0")} ${r.worstAt.backend} ssim ${r.worstMean.toFixed(4)}`);
+	if (update) {
+		lines.push(`  wrote baseline → ${r.baselineWritten}`);
+		lines.push(`  ${r.baselineAdded ?? 0} added, ${extra?.repinned ?? 0} re-pinned (moved > tol), ${r.improved ?? 0} improved`);
+		return lines.join("\n");
+	}
+	if (gate) {
+		const parts = [`${r.regressed ?? 0} regressed`, `${r.newComparisons ?? 0} new`];
+		if ((r.improved ?? 0) > 0) parts.push(`${r.improved} improved`);
+		lines.push(r.gateOk ? `  PASS — every comparison matched its expected drop (${parts.join(", ")})` : `  FAIL — ${parts.join(", ")} vs the baseline`);
+		return lines.join("\n");
+	}
 	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");
 }

package/package.json

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