@glissade/cli 0.11.0-pre.1 → 0.12.0-pre.0

package/dist/audioMix.js

@@ -10,6 +10,7 @@ import { audioOffsetSamples } from "@glissade/core";
 */
 var audioMix_exports = /* @__PURE__ */ __exportAll({
 	AudioMixError: () => AudioMixError,
+	applyMixGainDb: () => applyMixGainDb,
 	atempoChain: () => atempoChain,
 	gainExpression: () => gainExpression,
 	planAudioMix: () => planAudioMix,
@@ -60,6 +61,20 @@ function atempoChain(rate) {
 	if (Math.abs(r - 1) > 1e-9 || chain.length === 0) chain.push(`atempo=${r}`);
 	return chain;
 }
+/**
+* Append a PURE scalar publish-loudness gain to a mix's `-filter_complex`: the
+* graph's final `[aout]` label is renamed and a `volume=<gain>dB` node feeds the
+* new `[aout]`. This is a single multiply on the FINAL mix node — NOT a second
+* ffmpeg pass — and is bit-deterministic (verified) + golden-hashable. A gain of
+* exactly 0 dB is a no-op (returned unchanged) so an at-target source preserves
+* the prior, un-gained bytes.
+*/
+function applyMixGainDb(filterComplex, gainDb) {
+	if (gainDb === 0) return filterComplex;
+	const at = filterComplex.lastIndexOf("[aout]");
+	if (at < 0) throw new AudioMixError("mix filter graph has no [aout] to apply the loudness gain to");
+	return `${filterComplex.slice(0, at) + "[apreg]" + filterComplex.slice(at + 6)};[apreg]volume=${gainDb}dB[aout]`;
+}
 /** Build the FFmpeg mix plan for clips that intersect [0, duration]. */
 function planAudioMix(clips, modulePath, duration) {
 	const active = clips.filter((c) => c.at < duration);
@@ -93,4 +108,4 @@ function planAudioMix(clips, modulePath, duration) {
 	};
 }
 //#endregion
-export { planAudioMix as a, gainExpression as i, atempoChain as n, resolveAssetPath as o, audioMix_exports as r, AudioMixError as t };
+export { gainExpression as a, audioMix_exports as i, applyMixGainDb as n, planAudioMix as o, atempoChain as r, resolveAssetPath as s, AudioMixError as t };

package/dist/cacheVerify.js

@@ -0,0 +1,133 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { a as loadSceneModule } from "./render.js";
+import { i as capsId, n as FrameCache, o as frameCacheKey } from "./frameCache.js";
+import { t as glissadeVersion } from "./version.js";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { evaluate, withDeterminismGuards } from "@glissade/scene";
+import { SkiaBackend } from "@glissade/backend-skia";
+import { createHash } from "node:crypto";
+//#region src/cacheVerify.ts
+/**
+* gs cache verify — THE verify gate for the persistent `.gscache` (DESIGN.md §3.5,
+* 0.12). The frame cache's single failure mode is SILENT corruption (a stale tile
+* served from an incomplete key), so this gate is MANDATORY: it renders the scene
+* through the cache (read-only — serving HITS) and again with the cache OFF, then
+* asserts the per-frame `encodePng` bytes are EQUAL frame-for-frame. A mismatch
+* means a hit is NOT byte-identical to a cold render — the cache is unsafe.
+*
+* This EXTENDS verify-determinism's committed-byte-hash machinery (`sha256` over
+* the rasterized frame bytes — the same `node:crypto` precedent) across the DISK
+* boundary: instead of linear-vs-shard, it is cache-hit-vs-cache-off.
+*
+* A sampled fraction is fine for speed, and the sample is LOGGED (no silent caps):
+* the report names exactly which frames were compared.
+*
+* Companion NEGATIVE gate: see `cacheVerify.test.ts`, which injects a deliberately
+* INCOMPLETE key (drops the version / a transform-bearing component) and asserts
+* this comparison FAILS — proving the gate actually catches the only failure mode.
+*/
+var cacheVerify_exports = /* @__PURE__ */ __exportAll({ cacheVerifyCommand: () => cacheVerifyCommand });
+/** sha256 hex of the encoded PNG bytes — the authoritative cross-the-disk-boundary check. */
+function sha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+/**
+* Render one frame with a given backend, returning its encodePng bytes. When
+* `cache` is provided, a HIT loads stored RGBA via `putPixels` and encodes through
+* the IDENTICAL path; a MISS renders, encodes, and (in read-write) stores. The
+* keyer/ctx are injectable for the NEGATIVE gate.
+*/
+async function renderFrameBytes(backend, scene, doc, f, fps, cache, ctx, keyer) {
+	const dl = withDeterminismGuards("throw", () => evaluate(scene, doc, f / fps));
+	if (cache && cache.mode !== "off") {
+		const key = keyer(dl, ctx);
+		const hit = cache.get(key);
+		if (hit) {
+			backend.putPixels(hit);
+			return backend.encodePng();
+		}
+		backend.render(dl);
+		const png = backend.encodePng();
+		cache.put(key, scene.size.w, scene.size.h, await backend.readPixels());
+		return png;
+	}
+	backend.render(dl);
+	return backend.encodePng();
+}
+/**
+* The verify gate. Renders the range through a read-WRITE cache once (to WARM it),
+* then compares — for each SAMPLED frame — a read-ONLY render (serving the warmed
+* hits) against a cache-OFF render, by encodePng sha256. Equal frame-for-frame is
+* the contract; the first mismatch fails the gate.
+*/
+async function cacheVerifyCommand(opts) {
+	const mod = await loadSceneModule(opts.modulePath);
+	const scene = mod.createScene();
+	const doc = mod.timeline;
+	const fps = opts.fps ?? doc.fps ?? 60;
+	const backend = new SkiaBackend(scene.size.w, scene.size.h);
+	scene.setTextMeasurer(backend);
+	const { compileTimeline } = await import("@glissade/core");
+	const duration = compileTimeline(doc).duration;
+	const [first, last] = opts.frameRange ?? [0, Math.max(0, Math.ceil(duration * fps) - 1)];
+	const totalFrames = last - first + 1;
+	const sample = Math.max(1, Math.floor(opts.sample ?? 1));
+	const ctx = opts.keyContextOverride ?? {
+		version: glissadeVersion(),
+		capsId: capsId(backend.caps)
+	};
+	const keyer = opts.keyerOverride ?? frameCacheKey;
+	const dir = mkdtempSync(join(tmpdir(), "gscache-verify-"));
+	try {
+		const warm = new FrameCache({
+			dir,
+			mode: "read-write"
+		});
+		for (let f = first; f <= last; f++) await renderFrameBytes(backend, scene, doc, f, fps, warm, ctx, keyer);
+		const readOnly = new FrameCache({
+			dir,
+			mode: "read-only"
+		});
+		const comparedFrames = [];
+		let mismatch;
+		for (let f = first; f <= last; f += sample) {
+			comparedFrames.push(f);
+			const cachedBytes = await renderFrameBytes(backend, scene, doc, f, fps, readOnly, ctx, keyer);
+			const coldBytes = await renderFrameBytes(backend, scene, doc, f, fps, void 0, ctx, keyer);
+			const a = sha256(cachedBytes);
+			const b = sha256(coldBytes);
+			if (a !== b) {
+				mismatch = {
+					frame: f,
+					cached: a,
+					cold: b
+				};
+				break;
+			}
+		}
+		backend.dispose();
+		const sampledNote = sample === 1 ? `all ${totalFrames} frames` : `${comparedFrames.length} of ${totalFrames} frames (1-of-${sample} sample): [${comparedFrames.join(", ")}]`;
+		if (mismatch) return {
+			ok: false,
+			comparedFrames,
+			totalFrames,
+			mismatch,
+			report: `CACHE VERIFY FAILED — a hit is NOT byte-identical to a cold render.\n  frame ${mismatch.frame}: cached-hit PNG sha256 ${mismatch.cached.slice(0, 16)}… != cache-off ${mismatch.cold.slice(0, 16)}…\n  the cache key is INCOMPLETE (it served a stale frame for changed content) — DO NOT SHIP.\n  sampled: ${sampledNote}`
+		};
+		return {
+			ok: true,
+			comparedFrames,
+			totalFrames,
+			report: `cache verify OK: cache hits are byte-identical to cold renders.\n  compared (encodePng sha256, hit vs cache-off): ${sampledNote}`
+		};
+	} finally {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+export { cacheVerify_exports as n, cacheVerifyCommand as t };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as parseFrameRange, o as render } from "./render.js";
+import { c as render, o as parseFrameRange } from "./render.js";
 import { n as parseCaptionsMode } from "./captions.js";
 //#region src/cli.ts
 /**
@@ -41,11 +41,17 @@ function parseArgs(argv) {
 }
 const USAGE = `usage:
   gs render <scene-module> [options]
+  gs diff <scene-module> --at <t> --against <baseline.dl.json|.png>
+  gs verify-determinism <scene-module> [--shards <n>] [--against <frames.manifest>] [--range a..b] [--bisect] [--emit <p>]
   gs dev <scene-module> [--record] [--port <n>]
   gs import <lottie.json|asset.svg> [--out <dir>] [--allow-degraded]
   gs narrate <scene-module|script.narration.json> [--provider <id>] [--align <id>] [--force]
+  gs narration-lint <scene-module|script.narration.timing.json> [--json] [--fix] [--max-cps <n>]
   gs sfx <scene-module|script.sfx.json> [--verbose]
   gs prepare <scene-module>  [--provider <id>] [--align <id>] [--force]
+  gs measure-loudness <scene-module> [--profile <youtube|shorts|podcast|broadcast|ebu>]
+  gs fonts audit <scene-module>   list registered families, formats, and missing-glyph runs (§3.6)
+  gs cache verify <scene-module> [--range a..b] [--sample <n>]   assert cache hits == cold renders (§3.5)
 
 render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
@@ -60,6 +66,14 @@ render options:
   --lossless-intermediate  render shards as FFV1 + one final encode — the guaranteed byte-correct join
                    (auto-enabled when the encoder can't honor precise boundary keyframes, e.g. mpeg4/openh264)
   --allow-gpu-shards  permit sharding a scene with GPU/shader nodes (output is not reproducible across shards; §3.7)
+  --cache [<dir>]  persistent whole-frame raster cache in <dir> (default .gscache; §3.5). OFF by default — opting in
+                   never changes output, only speed. A hit serves a stored frame byte-identical to a cold render.
+                   WINS: repeated renders + the UNCHANGED-PREFIX of a single-segment edit. Does NOT win a re-narrate —
+                   that shifts every frame's timing, so every DisplayList changes and every frame MISSES. Shards share
+                   one .gscache. Verify safety with 'gs cache verify'.
+  --cache-mode <m> read-write (default with --cache) | read-only (serve hits, never write) | off (bypass = baseline)
+  --cache-max-size <bytes|2GB>  LRU size cap; oldest entries evicted when exceeded (default 2GB). Whole-frame RGBA is
+                   ~MBs/frame (tens of GB/episode) — the cap keeps .gscache from eating the disk
   --trace <file>   replay an InputTrace and bake it (machine scenes, §A.6)
   --state <name>   render one machine state's timeline linearly
   --force          downgrade a trace hash mismatch to a warning
@@ -67,11 +81,27 @@ render options:
   --narration <m>  auto (default): mix the voice from a sibling *.narration.timing.json | off
   --music <m>      auto (default): mix a sibling *.music.timing.json bed, ducked under narration | off
   --sfx <m>        auto (default): mix effect hits from a sibling *.sfx.timing.json | off
+  --loudness <m>   auto (default): apply a committed *.loudness.json publish gain (pure scalar; gs measure-loudness)
+                   | off. A stale mixHash (mix inputs changed since measure) HARD-THROWS — re-run gs measure-loudness
   --chapters <m>   vtt: also write WebVTT chapters from cue markers (cues.json is always written when cues exist)
                    (YouTube needs the 1st chapter at 0:00 — auto-anchored — and each chapter >= 10s; author cue ts accordingly)
   --chapters-kind <k[,k]>  cue kinds that become VTT chapters (default: chapter); cues.json keeps all kinds
   --strict         fail on an unregistered font family or an uncovered glyph (§3.6; default: warn)
 
+diff options (DisplayList diff vs a committed baseline — exits non-zero on any divergence):
+  --at <t>         time in SECONDS to evaluate the scene at (required)
+  --against <p>    baseline to compare to: <name>.dl.json (command-level structural diff)
+                   or <name>.png (raw encodePng byte-compare only — no pixel-diff)
+  --snapshot <p>   instead of diffing, write the scene's .dl.json snapshot at --at to <p>
+
+verify-determinism options (the cross-shard/backend byte-divergence LOCATOR — exits non-zero on any divergence):
+  --shards <n>     diff a linear render vs an n-shard render of the same range (byte-identical is the contract)
+  --against <p>    diff against a committed / other-machine frames.manifest (REJECTS a cross-backend byte-compare)
+  --range <a..b>   integer FRAME indices to verify, inclusive (default: whole timeline)
+  --bisect         drill the first divergence to the exact (frame, node, op) via the command-level diff
+  --emit <p>       instead of comparing, write the linear frames.manifest baseline to <p>
+                   (byte-equality is Skia↔Skia / cross-machine only — browser↔Skia is perceptual SSIM, not bytes)
+
 dev options:
   --record         add a Record button; writes .trace.json sidecars next to the module
   --port <n>       listen port (default: any free port)
@@ -80,18 +110,80 @@ import options (.json = Lottie; .svg = static SVG → a scene that defers to @gl
   --out <dir>          output directory for the generated scene module (default: .)
   --allow-degraded     (Lottie only) downgrade degradable rejections (expressions, merge-paths modes != 1) to warnings
 
+measure-loudness options (the explicit publish-loudness measure step; commits *.loudness.json):
+  --profile <id>   youtube (default) | shorts (both -14 LUFS) | podcast (-16) | broadcast/ebu (-23); all cap at -1 dBTP
+                   measures the final mix (ebur128) and commits a deterministic peak-clamped gain; render applies it
+                   as a pure scalar. Needs ffmpeg. Brickwall limiter deferred — peaky un-normalized profiles warn.
+
 narrate options (the explicit TTS prepare step; render itself stays offline):
   --provider <id>  fake | espeak | piper | kokoro | openai (default: the script's provider, else espeak)
                    (kokoro = Apache-2.0 offline neural voice; add 'kokoro-js' to your project; pnpm: allow its native build scripts)
   --align <id>     heuristic (default) | vosk | none — word timings for providers that emit none
   --force          ignore the cache and re-synthesize every segment
+
+narration-lint options (lint the committed *.narration.timing.json + the real caption geometry; exits non-zero on a Tier-1 issue):
+  --max-cps <n>    reading-speed ceiling in chars-per-second (default: 17)
+  --max-lines <n>  caption maxLines for the fit rule (default: 2, captionNode's own default)
+  --json           machine-readable diagnostics ({ hasErrors, diagnostics })
+  --no-warnings    omit Tier-2 (warn-only) diagnostics
+  --fix            print a git-apply-able budget-bump diff for the SCRIPT (never writes a committed artifact)
 `;
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
-	if (command !== "render" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "sfx" && command !== "prepare") {
+	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
+	if (command === "fonts") {
+		const { positional: fp } = parseArgs(rest);
+		const sub = fp[0];
+		const sceneModule = fp[1];
+		if (sub !== "audit") fail(`unknown 'fonts' subcommand '${sub ?? ""}' (expected: audit)\n${USAGE}`);
+		if (!sceneModule) fail(`fonts audit needs <scene-module>\n${USAGE}`);
+		const { fontsAuditCommand } = await import("./fonts.js");
+		const { resolveAssetPath } = await import("./audioMix.js").then((n) => n.i);
+		try {
+			const { text } = await fontsAuditCommand({
+				modulePath: sceneModule,
+				resolvePath: (url) => resolveAssetPath(url, sceneModule)
+			});
+			process.stdout.write(`${text}\n`);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
+	if (command === "cache") {
+		const { positional: cp, flags: cf } = parseArgs(rest);
+		const sub = cp[0];
+		const sceneModule = cp[1];
+		if (sub !== "verify") fail(`unknown 'cache' subcommand '${sub ?? ""}' (expected: verify)\n${USAGE}`);
+		if (!sceneModule) fail(`cache verify needs <scene-module>\n${USAGE}`);
+		let cvRange;
+		const cvRangeFlag = cf.get("range");
+		if (cvRangeFlag) try {
+			cvRange = parseFrameRange(cvRangeFlag);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		const sampleFlag = cf.get("sample");
+		if (sampleFlag !== void 0 && (!/^\d+$/.test(sampleFlag) || Number(sampleFlag) < 1)) fail(`--sample must be a positive integer (1-of-N frame sampling), got '${sampleFlag}'`);
+		const cvFpsFlag = cf.get("fps");
+		const { cacheVerifyCommand } = await import("./cacheVerify.js").then((n) => n.n);
+		try {
+			const result = await cacheVerifyCommand({
+				modulePath: sceneModule,
+				...cvRange ? { frameRange: cvRange } : {},
+				...sampleFlag !== void 0 ? { sample: Number(sampleFlag) } : {},
+				...cvFpsFlag ? { fps: parseInt(cvFpsFlag, 10) } : {}
+			});
+			process.stdout.write(`${result.report}\n`);
+			if (!result.ok) process.exit(1);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	const { positional, flags } = parseArgs(rest);
 	const modulePath = positional[0];
 	if (!modulePath) fail(`missing ${command === "import" ? "<lottie.json|asset.svg>" : "<scene-module>"}\n${USAGE}`);
@@ -115,6 +207,28 @@ async function main() {
 		}
 		return;
 	}
+	if (command === "narration-lint") {
+		const { narrationLintCommand } = await import("./narrationLintCommand.js").then((n) => n.i);
+		const maxCpsFlag = flags.get("max-cps");
+		if (maxCpsFlag !== void 0 && (maxCpsFlag === "" || !Number.isFinite(Number(maxCpsFlag)))) fail(`--max-cps must be a number, got '${maxCpsFlag}'`);
+		const maxLinesFlag = flags.get("max-lines");
+		if (maxLinesFlag !== void 0 && !/^\d+$/.test(maxLinesFlag)) fail(`--max-lines must be a non-negative integer, got '${maxLinesFlag}'`);
+		try {
+			const result = await narrationLintCommand({
+				input: modulePath,
+				...maxCpsFlag !== void 0 ? { maxCps: Number(maxCpsFlag) } : {},
+				...maxLinesFlag !== void 0 ? { maxLines: Number(maxLinesFlag) } : {},
+				...flags.has("json") ? { json: true } : {},
+				...flags.has("fix") ? { fix: true } : {},
+				...flags.has("no-warnings") ? { noWarnings: true } : {}
+			});
+			process.stdout.write(result.output);
+			if (result.hasErrors) process.exit(1);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	if (command === "prepare") {
 		const { prepareCommand } = await import("./prepare.js");
 		try {
@@ -144,6 +258,90 @@ async function main() {
 		}
 		return;
 	}
+	if (command === "measure-loudness") {
+		const { measureLoudnessCommand } = await import("./loudness.js").then((n) => n.c);
+		try {
+			const result = await measureLoudnessCommand({
+				modulePath,
+				...flags.has("profile") ? { profile: flags.get("profile") } : {},
+				...flags.get("narration") === "off" ? { narration: "off" } : {},
+				...flags.get("music") === "off" ? { music: "off" } : {},
+				...flags.get("sfx") === "off" ? { sfx: "off" } : {}
+			});
+			const m = result.measurement;
+			process.stderr.write(`gs measure-loudness: profile '${m.profileId}' — in ${m.inputI} LUFS / ${m.inputTp} dBTP → gain ${m.gain >= 0 ? "+" : ""}${m.gain} dB (out ~${(m.inputI + m.gain).toFixed(2)} LUFS / ~${(m.inputTp + m.gain).toFixed(2)} dBTP) → ${result.loudnessPath}\n`);
+			if (result.warning) process.stderr.write(`gs measure-loudness: warning: ${result.warning}\n`);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
+	if (command === "diff") {
+		const atRaw = flags.get("at");
+		if (atRaw === void 0 || atRaw === "") fail(`diff needs --at <seconds>\n${USAGE}`);
+		const at = Number(atRaw);
+		if (!Number.isFinite(at)) fail(`--at must be a number of seconds, got '${atRaw}'`);
+		const snapshotOut = flags.get("snapshot");
+		if (snapshotOut !== void 0 && snapshotOut !== "") {
+			const { snapshotAt } = await import("./diff.js").then((n) => n.n);
+			try {
+				const { writeFileSync } = await import("node:fs");
+				writeFileSync(snapshotOut, await snapshotAt(modulePath, at));
+				process.stderr.write(`gs diff: wrote snapshot @ ${at}s → ${snapshotOut}\n`);
+			} catch (err) {
+				fail(err instanceof Error ? err.message : String(err));
+			}
+			return;
+		}
+		const against = flags.get("against");
+		if (against === void 0 || against === "") fail(`diff needs --against <baseline.dl.json|.png>\n${USAGE}`);
+		const { diffCommand } = await import("./diff.js").then((n) => n.n);
+		try {
+			const result = await diffCommand({
+				modulePath,
+				at,
+				against
+			});
+			process.stdout.write(`${result.report}\n`);
+			if (!result.equal) process.exit(1);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
+	if (command === "verify-determinism") {
+		let frameRange;
+		const rangeFlag = flags.get("range");
+		if (rangeFlag) try {
+			frameRange = parseFrameRange(rangeFlag);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		const shardsFlag = flags.get("shards");
+		let shards;
+		if (shardsFlag !== void 0) {
+			if (!/^\d+$/.test(shardsFlag) || Number(shardsFlag) < 1) fail(`--shards must be a positive integer, got '${shardsFlag}'`);
+			shards = Number(shardsFlag);
+		}
+		const fpsFlag = flags.get("fps");
+		const { verifyDeterminismCommand } = await import("./verifyDeterminism.js");
+		try {
+			const result = await verifyDeterminismCommand({
+				modulePath,
+				...shards !== void 0 ? { shards } : {},
+				...flags.has("against") ? { against: flags.get("against") } : {},
+				...frameRange ? { frameRange } : {},
+				...flags.has("bisect") ? { bisect: true } : {},
+				...flags.has("emit") ? { emit: flags.get("emit") } : {},
+				...fpsFlag ? { fps: parseInt(fpsFlag, 10) } : {}
+			});
+			process.stdout.write(`${result.report}\n`);
+			if (!result.ok) process.exit(1);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	if (command === "import") {
 		const { importCommand } = await import("./import.js").then((n) => n.n);
 		try {
@@ -191,6 +389,31 @@ async function main() {
 		if (!/^\d+$/.test(workersFlag) || Number(workersFlag) < 1) fail(`--workers must be a positive integer, got '${workersFlag}'`);
 		workers = Number(workersFlag);
 	}
+	let cache;
+	if (flags.has("cache")) {
+		const dir = flags.get("cache") || ".gscache";
+		const modeFlag = flags.get("cache-mode");
+		let mode = "read-write";
+		if (modeFlag !== void 0) {
+			if (modeFlag !== "read-write" && modeFlag !== "read-only" && modeFlag !== "off") fail(`--cache-mode must be read-write|read-only|off, got '${modeFlag}'`);
+			mode = modeFlag;
+		}
+		let maxSize;
+		const maxSizeFlag = flags.get("cache-max-size");
+		if (maxSizeFlag !== void 0 && maxSizeFlag !== "") {
+			const { parseCacheMaxSize } = await import("./frameCache.js").then((n) => n.s);
+			try {
+				maxSize = parseCacheMaxSize(maxSizeFlag);
+			} catch (err) {
+				fail(err instanceof Error ? err.message : String(err));
+			}
+		}
+		cache = {
+			dir,
+			mode,
+			...maxSize !== void 0 ? { maxSize } : {}
+		};
+	}
 	if (flags.has("watch")) process.stderr.write("note: --watch is not yet implemented in this release; rendering once\n");
 	const fpsFlag = flags.get("fps");
 	const started = performance.now();
@@ -211,10 +434,12 @@ async function main() {
 			...workers !== void 0 ? { workers } : {},
 			...flags.has("lossless-intermediate") ? { losslessIntermediate: true } : {},
 			...flags.has("allow-gpu-shards") ? { allowGpuShards: true } : {},
+			...cache !== void 0 ? { cache } : {},
 			captions: parseCaptionsModeOrFail(flags.get("captions")),
 			narration: flags.get("narration") === "off" ? "off" : "auto",
 			music: flags.get("music") === "off" ? "off" : "auto",
 			sfx: flags.get("sfx") === "off" ? "off" : "auto",
+			loudness: flags.get("loudness") === "off" ? "off" : "auto",
 			onProgress: (n, total) => {
 				if (process.stderr.isTTY) {
 					if (n % 30 === 0 || n === total) process.stderr.write(`\rrendering ${n}/${total} frames`);

package/dist/diff.js

@@ -0,0 +1,66 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { a as loadSceneModule } from "./render.js";
+import { readFileSync } from "node:fs";
+import { diffDisplayLists, evaluate, formatDisplayDiff, parseDisplaySnapshot, serializeDisplayList } from "@glissade/scene";
+//#region src/diff.ts
+/**
+* gs diff (DESIGN.md §3.3): turn an opaque golden-hash mismatch into a
+* command-level explanation. Evaluate a scene at `--at <t>` to its pure
+* DisplayList, then compare against a committed baseline:
+*
+*   --against <baseline.dl.json>  → structural, index-aligned command diff
+*                                   (parse → diffDisplayLists → command tree)
+*   --against <baseline.png>      → raw encodePng byte-compare ONLY (no pixel
+*                                   diff algorithm, no new raster path)
+*
+* Operates entirely on the already-pure IR (no audio). Exits non-zero on any
+* divergence so it slots into CI / a golden-update workflow.
+*/
+var diff_exports = /* @__PURE__ */ __exportAll({
+	diffCommand: () => diffCommand,
+	evaluateAt: () => evaluateAt,
+	snapshotAt: () => snapshotAt
+});
+/** Evaluate the scene module at `t` to its DisplayList (single-frame, no audio). */
+async function evaluateAt(modulePath, t) {
+	const mod = await loadSceneModule(modulePath);
+	return evaluate(mod.createScene(), mod.timeline, t);
+}
+async function diffCommand(opts) {
+	if (opts.against.endsWith(".png")) return diffAgainstPng(opts);
+	if (opts.against.endsWith(".dl.json")) return diffAgainstSnapshot(opts);
+	throw new Error(`--against must be a .dl.json or .png baseline, got '${opts.against}'`);
+}
+async function diffAgainstSnapshot(opts) {
+	const mod = await loadSceneModule(opts.modulePath);
+	const actual = evaluate(mod.createScene(), mod.timeline, opts.at);
+	const diff = diffDisplayLists(parseDisplaySnapshot(readFileSync(opts.against, "utf8")), actual);
+	return {
+		equal: diff.equal,
+		report: diff.equal ? `match: ${actual.commands.length} commands identical to ${opts.against}` : `${opts.against} (baseline) -> scene @ ${opts.at}s\n${formatDisplayDiff(diff)}`,
+		actual
+	};
+}
+async function diffAgainstPng(opts) {
+	const { SkiaBackend } = await import("@glissade/backend-skia");
+	const mod = await loadSceneModule(opts.modulePath);
+	const scene = mod.createScene();
+	const backend = new SkiaBackend(scene.size.w, scene.size.h);
+	scene.setTextMeasurer(backend);
+	const actual = evaluate(scene, mod.timeline, opts.at);
+	backend.render(actual);
+	const actualPng = backend.encodePng();
+	const baselinePng = readFileSync(opts.against);
+	const equal = actualPng.equals(baselinePng);
+	return {
+		equal,
+		report: equal ? `match: rendered PNG is byte-identical to ${opts.against}` : `PNG mismatch vs ${opts.against}: baseline ${baselinePng.length}B, rendered ${actualPng.length}B\n(byte-compare only; run with --against a .dl.json baseline for a command-level diff)`,
+		actual
+	};
+}
+/** Snapshot a scene's DisplayList at `t` to a `.dl.json` string (the baseline writer). */
+async function snapshotAt(modulePath, t) {
+	return serializeDisplayList(await evaluateAt(modulePath, t));
+}
+//#endregion
+export { snapshotAt as i, diff_exports as n, evaluateAt as r, diffCommand as t };

package/dist/fonts.js

@@ -0,0 +1,122 @@
+import { a as loadSceneModule } from "./render.js";
+import { readFile } from "node:fs/promises";
+import { buildFontRegistry } from "@glissade/core";
+import { collectTextUsages } from "@glissade/scene";
+//#region src/fonts.ts
+/**
+* gs fonts audit (DESIGN.md §3.6) — the font front-door report. Loads a scene
+* module, builds the FontRegistry from its timeline assets, ingests each face
+* (sniff format → woff2 decode → static instance, via @glissade/core/font-ingest),
+* and prints per family: the declared faces, the on-disk format, the cmap
+* coverage size, and any missing-glyph RUNS for the text the scene actually
+* renders ("héllo 👋 renders emoji in Chrome, tofu in Skia").
+*
+* Read-only and offline: no rasterization, no network. The same ingest path the
+* render/prepare steps use, so the audit reflects exactly what would ship.
+*/
+function codePointsOf(text) {
+	const out = [];
+	for (const ch of text) {
+		const cp = ch.codePointAt(0);
+		if (cp !== void 0) out.push(cp);
+	}
+	return out;
+}
+/** Collapse a sorted, de-duped code-point list into [start,end] inclusive runs. */
+function toRuns(cps) {
+	const sorted = [...new Set(cps)].sort((a, b) => a - b);
+	const runs = [];
+	for (const cp of sorted) {
+		const last = runs[runs.length - 1];
+		if (last && cp === last.end + 1) last.end = cp;
+		else runs.push({
+			start: cp,
+			end: cp
+		});
+	}
+	return runs;
+}
+function hex(cp) {
+	return "U+" + cp.toString(16).toUpperCase().padStart(4, "0");
+}
+/**
+* Build the audit report for a scene module. `resolvePath` maps an asset url to
+* an absolute path to read (the CLI resolves relative to the scene module).
+*/
+async function auditSceneFonts(modulePath, resolvePath) {
+	const mod = await loadSceneModule(modulePath);
+	const scene = mod.createScene();
+	const doc = mod.timeline;
+	const registry = buildFontRegistry(doc.assets);
+	const ingest = await import("@glissade/core/font-ingest");
+	const faceCoverage = /* @__PURE__ */ new Map();
+	const families = [];
+	for (const family of [...new Set(registry.faces().map((f) => f.family))].sort()) {
+		const faceReports = [];
+		for (const face of registry.faces().filter((f) => f.family === family)) {
+			let format = "missing";
+			let coverage = -1;
+			try {
+				const src = await readFile(resolvePath(face.url));
+				const result = await ingest.ingestFont({
+					family: face.family,
+					src
+				});
+				format = result.sourceFormat;
+				coverage = result.coverage.size;
+				faceCoverage.set(`${family}|${face.url}`, result.coverage);
+			} catch {}
+			faceReports.push({
+				family: face.family,
+				url: face.url,
+				weight: face.weight,
+				style: face.style,
+				format,
+				coverage
+			});
+		}
+		const missing = /* @__PURE__ */ new Set();
+		const usages = collectTextUsages(scene).filter((u) => u.family === family);
+		if (usages.length > 0) {
+			const covered = /* @__PURE__ */ new Set();
+			for (const face of registry.faces().filter((f) => f.family === family)) {
+				const cov = faceCoverage.get(`${family}|${face.url}`);
+				if (cov) for (const cp of cov) covered.add(cp);
+			}
+			for (const u of usages) for (const cp of codePointsOf(u.text)) if (!covered.has(cp)) missing.add(cp);
+		}
+		families.push({
+			family,
+			faces: faceReports,
+			missingRuns: toRuns([...missing])
+		});
+	}
+	return { families };
+}
+/** Render the audit report as the human-readable text `gs fonts audit` prints. */
+function formatFontAudit(report) {
+	if (report.families.length === 0) return "no font families registered in this scene";
+	const lines = [];
+	for (const fam of report.families) {
+		lines.push(`${fam.family}`);
+		for (const f of fam.faces) {
+			const cov = f.coverage >= 0 ? `${f.coverage} glyphs` : "unreadable";
+			lines.push(`  - ${f.weight}/${f.style}  ${f.format.padEnd(10)}  ${cov}  (${f.url})`);
+		}
+		if (fam.missingRuns.length > 0) {
+			const runs = fam.missingRuns.map((r) => r.start === r.end ? hex(r.start) : `${hex(r.start)}–${hex(r.end)}`).join(", ");
+			lines.push(`  ! missing glyphs for used text: ${runs}`);
+		}
+	}
+	return lines.join("\n");
+}
+/** The `gs fonts audit <scene-module>` entry point. Returns the report + text. */
+async function fontsAuditCommand(args) {
+	const report = await auditSceneFonts(args.modulePath, args.resolvePath);
+	return {
+		report,
+		text: formatFontAudit(report)
+	};
+}
+//#endregion
+export { fontsAuditCommand };