@glissade/cli 0.48.0 → 0.49.0-pre.1

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as parseFrameRange, d as render, f as renderLocales, l as parseLocalesList, t as LocaleArgsError } from "./render.js";
+import { c as parseFrameRange, f as render, l as parseLocalesList, p as renderLocales, t as LocaleArgsError } from "./render.js";
 import { n as parseCaptionsMode } from "./captions.js";
 //#region src/args.ts
 /**
@@ -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/index.d.ts

@@ -1,6 +1,7 @@
 import { A as peakClampBinds, C as PublishProfile, D as measureFile, E as loudnessPathFor, M as resolveProfile, O as measureLoudnessCommand, S as PUBLISH_PROFILES, T as computeMixHash, _ as LOUDNESS_SCHEMA_VERSION, a as MasterMemberResult, b as MeasureLoudnessOptions, d as masterAfChain, f as masterCommand, g as DEFAULT_PROFILE_ID, h as CommittedLimiter, i as MasterLimiter, j as readLoudness, k as parseLoudnormJson, l as MemberMeasure, m as planMaster, n as MasterConfig, o as MasterPlan, p as normalizeMasterConfig, r as MasterError, s as MasterResult, t as DEFAULT_MAX_GR_DB, u as MemberPlan, v as LoudnessError, w as computeGainDb, x as MeasureLoudnessResult, y as LoudnessMeasurement } from "./master.js";
 import { AudioClip, CompiledTimeline, Key, Timeline } from "@glissade/core";
 import { DisplayList, Scene, SceneModule, VideoFrameSource } from "@glissade/scene";
+import { SkiaBackend } from "@glissade/backend-skia";
 import { NarrationTiming } from "@glissade/narrate";
 import { Image } from "@napi-rs/canvas";
 import * as _glissade_core_i18n0 from "@glissade/core/i18n";
@@ -130,6 +131,37 @@ declare function probeEntryHeader(file: string): {
 /** Remove the whole `.gscache` dir (a `gs cache clear` convenience / test cleanup). */
 declare function clearFrameCache(dir: string): void;
 //#endregion
+//#region src/videoSource.d.ts
+declare class VideoProbeError extends Error {
+  constructor(path: string, detail: string);
+}
+interface VideoInfo {
+  fps: number;
+  duration: number;
+  width: number;
+  height: number;
+}
+declare function probeVideo(path: string): VideoInfo;
+/**
+ * v1 strategy: warm() extracts the full requested media range once at the
+ * source's own fps; getFrameSync indexes the extracted sequence. Disk-bound,
+ * trivially correct; the streaming-pipe variant is a later optimization.
+ */
+declare class FfmpegVideoFrameSource implements VideoFrameSource {
+  readonly fps: number;
+  readonly duration: number;
+  private readonly path;
+  private framesDir;
+  private warmedFrom;
+  private warmedTo;
+  private readonly cache;
+  constructor(path: string, info?: VideoInfo);
+  private frameIndex;
+  warm(fromT: number, toT: number): Promise<void>;
+  getFrameSync(mediaT: number): Image;
+  close(): void;
+}
+//#endregion
 //#region src/render.d.ts
 interface RenderOptions {
   modulePath: string;
@@ -307,6 +339,10 @@ declare class SceneModuleError extends Error {
 
 declare function loadSceneModule(modulePath: string, locale?: string, messageTableOverride?: _glissade_core_i18n0.MessageTable): Promise<SceneModule>;
 declare function ffmpegAvailable(): boolean;
+/** What `prepareSkiaRenderEnv` needs to make a Skia render FAITHFUL (fonts+axes,
+ *  Yoga, assets) — the setup that `gs render` and any parity/preview render must
+ *  share so a headless render is byte-faithful to `gs render` by construction. */
+
 declare function render(opts: RenderOptions): Promise<{
   frames: number;
   out: string;
@@ -424,37 +460,6 @@ declare function renderSharded(a: RenderShardedArgs): Promise<{
 }>;
 /** The FFV1 lossless intermediate retained beside a `--incremental` output for the next splice. */
 //#endregion
-//#region src/videoSource.d.ts
-declare class VideoProbeError extends Error {
-  constructor(path: string, detail: string);
-}
-interface VideoInfo {
-  fps: number;
-  duration: number;
-  width: number;
-  height: number;
-}
-declare function probeVideo(path: string): VideoInfo;
-/**
- * v1 strategy: warm() extracts the full requested media range once at the
- * source's own fps; getFrameSync indexes the extracted sequence. Disk-bound,
- * trivially correct; the streaming-pipe variant is a later optimization.
- */
-declare class FfmpegVideoFrameSource implements VideoFrameSource {
-  readonly fps: number;
-  readonly duration: number;
-  private readonly path;
-  private framesDir;
-  private warmedFrom;
-  private warmedTo;
-  private readonly cache;
-  constructor(path: string, info?: VideoInfo);
-  private frameIndex;
-  warm(fromT: number, toT: number): Promise<void>;
-  getFrameSync(mediaT: number): Image;
-  close(): void;
-}
-//#endregion
 //#region src/audioMix.d.ts
 declare class AudioMixError extends Error {
   constructor(detail: string);

package/dist/index.js

@@ -1,5 +1,5 @@
 import { t as glissadeVersion } from "./version.js";
-import { a as ffmpegAvailable, d as render, f as renderLocales, i as collectAudioClips, l as parseLocalesList, m as resolveLoudnessGainDb, n as SceneModuleError, o as loadSceneModule, r as buildMixWav, s as localeOutPath, t as LocaleArgsError, u as planFinalAudio } from "./render.js";
+import { a as ffmpegAvailable, f as render, h as resolveLoudnessGainDb, i as collectAudioClips, l as parseLocalesList, n as SceneModuleError, o as loadSceneModule, p as renderLocales, r as buildMixWav, s as localeOutPath, t as LocaleArgsError, u as planFinalAudio } from "./render.js";
 import { a as computeGainDb, d as parseLoudnormJson, f as peakClampBinds, i as PUBLISH_PROFILES, l as measureFile, m as resolveProfile, n as LOUDNESS_SCHEMA_VERSION, o as computeMixHash, p as readLoudness, r as LoudnessError, s as loudnessPathFor, t as DEFAULT_PROFILE_ID, u as measureLoudnessCommand } from "./loudness.js";
 import { i as masterCommand, n as MasterError, o as normalizeMasterConfig, r as masterAfChain, s as planMaster, t as DEFAULT_MAX_GR_DB } from "./master.js";
 import { a as pickEncoder, i as parseEncoderList, n as availableEncoders, t as NoEncoderError } from "./encoders.js";

package/dist/localize.js

@@ -156,7 +156,7 @@ async function harvestMessageIds(modulePath) {
 		get: (_t, prop) => typeof prop === "string" ? prop : void 0
 	});
 	const { getConsumedMessageIds } = await import("@glissade/core/i18n");
-	const { loadSceneModule } = await import("./render.js").then((n) => n.p);
+	const { loadSceneModule } = await import("./render.js").then((n) => n.m);
 	const mod = await loadSceneModule(modulePath, void 0, recording);
 	mod.createScene();
 	const tIds = new Set(getConsumedMessageIds());

package/dist/loudness.js

@@ -225,7 +225,7 @@ function measureFile(audioPath) {
 */
 async function measureLoudnessCommand(opts) {
 	const profile = resolveProfile(opts.profile ?? "youtube");
-	const { buildMixWav } = await import("./render.js").then((n) => n.p);
+	const { buildMixWav } = await import("./render.js").then((n) => n.m);
 	const tmp = mkdtempSync(join(tmpdir(), "glissade-loudness-"));
 	try {
 		const wavPath = join(tmp, "mix.wav");
@@ -239,7 +239,7 @@ async function measureLoudnessCommand(opts) {
 		const { inputI, inputTp, inputLra } = measureFile(wavPath);
 		const gain = computeGainDb(profile, inputI, inputTp);
 		const clampBound = peakClampBinds(profile, inputI, inputTp);
-		const { collectMixAudioInputs } = await import("./render.js").then((n) => n.p);
+		const { collectMixAudioInputs } = await import("./render.js").then((n) => n.m);
 		const extraInputs = await collectMixAudioInputs({
 			modulePath: opts.modulePath,
 			narration: opts.narration ?? "auto",

package/dist/master.js

@@ -132,7 +132,7 @@ async function runMaster(members, opts = {}, onLog) {
 	const consistency = opts.consistency ?? "shared-target";
 	const limiter = opts.limiter || null;
 	const log = onLog ?? (() => {});
-	const { buildMixWav, collectMixAudioInputs } = await import("./render.js").then((n) => n.p);
+	const { buildMixWav, collectMixAudioInputs } = await import("./render.js").then((n) => n.m);
 	if (members.length === 0) throw new MasterError("master: no members to master");
 	const ceilingDb = limiter?.ceilingDb ?? profile.truePeakDb;
 	const committedLimiter = limiter ? {

package/dist/parity.js

@@ -0,0 +1,197 @@
+import { d as prepareSkiaRenderEnv, o as loadSceneModule } from "./render.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, 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/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 — the reference every leg is diffed against.
+* CRITICAL: it renders through the SAME environment as `gs render`
+* (`prepareSkiaRenderEnv`: font faces incl. variable-font axes registered, Yoga
+* for flexbox, assets decoded) and wraps `evaluate` in the determinism guard. Without
+* this the reference would render a variable-font scene at DEFAULT weight (the face
+* never registered) and match a fontAxes-dropping Lottie leg at a FALSE SSIM 1.0 —
+* a fidelity gate silently reporting perfect on a real interchange loss.
+*
+* The scene + backend are built ONCE and reused across frames (evaluate is pure of
+* time — the ONE contract — exactly as `gs render`'s frame loop reuses them).
+*/
+async function skiaSource(mod, w, h, modulePath) {
+	const scene = mod.createScene();
+	const backend = new SkiaBackend(w, h);
+	await prepareSkiaRenderEnv({
+		scene,
+		doc: mod.timeline,
+		backend,
+		modulePath
+	});
+	return async (t) => {
+		const dl = withDeterminismGuards("throw", () => evaluate(scene, mod.timeline, t));
+		backend.render(dl);
+		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); the re-imported
+* module renders through the SAME faithful environment as the reference (so its render is
+* honest too). Asset URLs resolve against the ORIGINAL module path. This leg measures the
+* Lottie bijection per frame — e.g. the dropped `fontAxes` surfaces as a real SSIM drop.
+*/
+async function lottieSource(mod, w, h, fps, modulePath) {
+	return skiaSource(importLottie(exportLottie(mod, {
+		width: w,
+		height: h,
+		fps
+	})).toSceneModule(), w, h, modulePath);
+}
+function makeSource(backend, mod, w, h, fps, modulePath) {
+	switch (backend) {
+		case "skia": return skiaSource(mod, w, h, modulePath);
+		case "lottie": return lottieSource(mod, w, h, fps, modulePath);
+		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 = 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));
+	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/dist/render.js

@@ -166,6 +166,7 @@ var render_exports = /* @__PURE__ */ __exportAll({
 	parseFrameRange: () => parseFrameRange,
 	parseLocalesList: () => parseLocalesList,
 	planFinalAudio: () => planFinalAudio,
+	prepareSkiaRenderEnv: () => prepareSkiaRenderEnv,
 	render: () => render,
 	renderLocales: () => renderLocales,
 	resolveLoudnessGainDb: () => resolveLoudnessGainDb
@@ -358,6 +359,95 @@ async function loadSceneModule(modulePath, locale, messageTableOverride) {
 function ffmpegAvailable() {
 	return spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0;
 }
+/**
+* Prepare the Skia render environment so `evaluate(scene, doc, t)` → `backend.render`
+* is FAITHFUL: line-break measurer, Yoga (flexbox scenes), font faces registered
+* under their families (variable-font axes included, so `fontAxes` reaches the
+* glyphs), font validation, and image/video asset decode bound to the backend.
+*
+* This is the SINGLE SOURCE OF TRUTH for render setup — `gs render` AND `gs parity`
+* both call it, so a parity render cannot silently diverge from a real render (e.g.
+* report a false-perfect SSIM on a variable-font scene by rendering BOTH legs at the
+* default weight because neither registered the face). Extracted verbatim from the
+* `render()` body; the ordering (yoga → asset-validate → font-register → validate →
+* asset-decode) is preserved so `gs render` stays byte-identical.
+*/
+async function prepareSkiaRenderEnv(o) {
+	const { scene, doc, backend, modulePath } = o;
+	scene.setTextMeasurer(backend);
+	if ([...scene.nodes.values()].some((n) => n.constructor.isLayoutNode === true)) {
+		const { loadYogaLayoutEngine } = await import("@glissade/scene/layout");
+		await loadYogaLayoutEngine();
+	}
+	validateAssetReferences(collectAssetReferences(scene.root), Object.keys(doc.assets ?? {}));
+	const videoSources = [];
+	const { resolveAssetPath: resolveAsset } = await import("./audioMix.js").then((n) => n.i);
+	const { createHash } = await import("node:crypto");
+	const assetDigests = /* @__PURE__ */ new Map();
+	const digestBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");
+	const registeredFamilies = /* @__PURE__ */ new Set();
+	const fontRegistry = buildFontRegistry(doc.assets);
+	if (fontRegistry.faces().length > 0) {
+		const { GlobalFonts } = await import("@napi-rs/canvas");
+		let ingest;
+		for (const face of fontRegistry.faces()) {
+			registeredFamilies.add(face.family.toLowerCase());
+			const path = resolveAsset(face.url, modulePath);
+			if (/\.woff2?$/i.test(face.url)) {
+				ingest ??= await import("@glissade/core/font-ingest");
+				const src = await readFile(path);
+				assetDigests.set(`font:${face.family}:${face.url}`, digestBytes(src));
+				const result = await ingest.ingestFont({
+					family: face.family,
+					src
+				});
+				GlobalFonts.register(Buffer.from(result.bytes), face.family);
+			} else {
+				assetDigests.set(`font:${face.family}:${face.url}`, digestBytes(await readFile(path)));
+				GlobalFonts.registerFromPath(path, face.family);
+			}
+		}
+	}
+	const osCatalog = !!o.allowSystemFonts && !o.strictFonts ? new Set((await import("@napi-rs/canvas")).GlobalFonts.families.map((f) => f.family.toLowerCase())) : /* @__PURE__ */ new Set();
+	const osFamilies = buildFontExemptSet(registeredFamilies, {
+		allowSystemFonts: !!o.allowSystemFonts,
+		strict: !!o.strictFonts,
+		osCatalog
+	});
+	const localizedUsages = o.locale !== void 0 && o.locale !== "" ? collectLocalizedTextUsages(scene, doc) : [];
+	await validateSceneFonts(scene, doc, async (url) => {
+		try {
+			const buf = await readFile(resolveAsset(url, modulePath));
+			return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+		} catch {
+			return;
+		}
+	}, {
+		mode: o.strictFonts ? "strict" : "dev",
+		osFamilies,
+		extraUsages: localizedUsages
+	});
+	for (const [assetId, ref] of Object.entries(doc.assets ?? {})) if (ref.kind === "font") {} else if (ref.kind === "image") {
+		const { loadImage } = await import("@napi-rs/canvas");
+		const imgPath = resolveAsset(ref.url, modulePath);
+		assetDigests.set(`image:${assetId}`, digestBytes(await readFile(imgPath)));
+		backend.setImageAsset(assetId, await loadImage(imgPath));
+	} else if (ref.kind === "video") {
+		if (!ffmpegAvailable()) throw new Error(`video asset '${assetId}' needs FFmpeg on PATH for frame extraction (§5.4)`);
+		const { FfmpegVideoFrameSource } = await import("./videoSource.js").then((n) => n.i);
+		const videoPath = resolveAsset(ref.url, modulePath);
+		assetDigests.set(`video:${assetId}`, digestBytes(await readFile(videoPath)));
+		const source = new FfmpegVideoFrameSource(videoPath);
+		await source.warm(0, source.duration);
+		backend.setVideoAsset(assetId, source);
+		videoSources.push(source);
+	}
+	return {
+		assetDigests,
+		videoSources,
+		registeredFamilies
+	};
+}
 async function render(opts) {
 	const mod = await loadSceneModule(opts.modulePath, opts.locale);
 	const scene = mod.createScene();
@@ -427,74 +517,15 @@ async function render(opts) {
 	const framesDir = isVideo ? mkdtempSync(join(tmpdir(), "glissade-frames-")) : singleFile ? dirname(resolve(opts.out)) : resolve(opts.out);
 	mkdirSync(framesDir, { recursive: true });
 	const backend = new SkiaBackend(scene.size.w, scene.size.h);
-	scene.setTextMeasurer(backend);
-	if ([...scene.nodes.values()].some((n) => n.constructor.isLayoutNode === true)) {
-		const { loadYogaLayoutEngine } = await import("@glissade/scene/layout");
-		await loadYogaLayoutEngine();
-	}
-	validateAssetReferences(collectAssetReferences(scene.root), Object.keys(doc.assets ?? {}));
-	const videoSources = [];
-	const { resolveAssetPath: resolveAsset } = await import("./audioMix.js").then((n) => n.i);
-	const { createHash } = await import("node:crypto");
-	const assetDigests = /* @__PURE__ */ new Map();
-	const digestBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");
-	const registeredFamilies = /* @__PURE__ */ new Set();
-	const fontRegistry = buildFontRegistry(doc.assets);
-	if (fontRegistry.faces().length > 0) {
-		const { GlobalFonts } = await import("@napi-rs/canvas");
-		let ingest;
-		for (const face of fontRegistry.faces()) {
-			registeredFamilies.add(face.family.toLowerCase());
-			const path = resolveAsset(face.url, opts.modulePath);
-			if (/\.woff2?$/i.test(face.url)) {
-				ingest ??= await import("@glissade/core/font-ingest");
-				const src = await readFile(path);
-				assetDigests.set(`font:${face.family}:${face.url}`, digestBytes(src));
-				const result = await ingest.ingestFont({
-					family: face.family,
-					src
-				});
-				GlobalFonts.register(Buffer.from(result.bytes), face.family);
-			} else {
-				assetDigests.set(`font:${face.family}:${face.url}`, digestBytes(await readFile(path)));
-				GlobalFonts.registerFromPath(path, face.family);
-			}
-		}
-	}
-	const osCatalog = !!opts.allowSystemFonts && !opts.strictFonts ? new Set((await import("@napi-rs/canvas")).GlobalFonts.families.map((f) => f.family.toLowerCase())) : /* @__PURE__ */ new Set();
-	const osFamilies = buildFontExemptSet(registeredFamilies, {
-		allowSystemFonts: !!opts.allowSystemFonts,
-		strict: !!opts.strictFonts,
-		osCatalog
-	});
-	const localizedUsages = opts.locale !== void 0 && opts.locale !== "" ? collectLocalizedTextUsages(scene, doc) : [];
-	await validateSceneFonts(scene, doc, async (url) => {
-		try {
-			const buf = await readFile(resolveAsset(url, opts.modulePath));
-			return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
-		} catch {
-			return;
-		}
-	}, {
-		mode: opts.strictFonts ? "strict" : "dev",
-		osFamilies,
-		extraUsages: localizedUsages
+	const { assetDigests, videoSources } = await prepareSkiaRenderEnv({
+		scene,
+		doc,
+		backend,
+		modulePath: opts.modulePath,
+		...opts.strictFonts !== void 0 ? { strictFonts: opts.strictFonts } : {},
+		...opts.allowSystemFonts !== void 0 ? { allowSystemFonts: opts.allowSystemFonts } : {},
+		...opts.locale !== void 0 ? { locale: opts.locale } : {}
 	});
-	for (const [assetId, ref] of Object.entries(doc.assets ?? {})) if (ref.kind === "font") {} else if (ref.kind === "image") {
-		const { loadImage } = await import("@napi-rs/canvas");
-		const imgPath = resolveAsset(ref.url, opts.modulePath);
-		assetDigests.set(`image:${assetId}`, digestBytes(await readFile(imgPath)));
-		backend.setImageAsset(assetId, await loadImage(imgPath));
-	} else if (ref.kind === "video") {
-		if (!ffmpegAvailable()) throw new Error(`video asset '${assetId}' needs FFmpeg on PATH for frame extraction (§5.4)`);
-		const { FfmpegVideoFrameSource } = await import("./videoSource.js").then((n) => n.i);
-		const videoPath = resolveAsset(ref.url, opts.modulePath);
-		assetDigests.set(`video:${assetId}`, digestBytes(await readFile(videoPath)));
-		const source = new FfmpegVideoFrameSource(videoPath);
-		await source.warm(0, source.duration);
-		backend.setVideoAsset(assetId, source);
-		videoSources.push(source);
-	}
 	let frameCache;
 	let keyCtx;
 	const cacheOn = !!(opts.cache && opts.cache.mode !== "off");
@@ -995,4 +1026,4 @@ async function buildMixWav(opts, wavOut) {
 	});
 }
 //#endregion
-export { readRenderManifest as _, ffmpegAvailable as a, parseFrameRange as c, render as d, renderLocales as f, frameKeyDigest as g, changedFrameRanges as h, collectAudioClips as i, parseLocalesList as l, resolveLoudnessGainDb as m, SceneModuleError as n, loadSceneModule as o, render_exports as p, buildMixWav as r, localeOutPath as s, LocaleArgsError as t, planFinalAudio as u, writeRenderManifest as v };
+export { frameKeyDigest as _, ffmpegAvailable as a, parseFrameRange as c, prepareSkiaRenderEnv as d, render as f, changedFrameRanges as g, resolveLoudnessGainDb as h, collectAudioClips as i, parseLocalesList as l, render_exports as m, SceneModuleError as n, loadSceneModule as o, renderLocales as p, buildMixWav as r, localeOutPath as s, LocaleArgsError as t, planFinalAudio as u, readRenderManifest as v, writeRenderManifest as y };

package/dist/shards.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
-import { _ as readRenderManifest, g as frameKeyDigest, h as changedFrameRanges, u as planFinalAudio, v as writeRenderManifest } from "./render.js";
+import { _ as frameKeyDigest, g as changedFrameRanges, u as planFinalAudio, v as readRenderManifest, y as writeRenderManifest } from "./render.js";
 import { a as pickEncoder } from "./encoders.js";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";

package/package.json

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