@glissade/cli 0.11.0 → 0.12.0-pre.0

package/dist/render.js

@@ -1,3 +1,4 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
 import { spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -14,6 +15,17 @@ import { SkiaBackend } from "@glissade/backend-skia";
 * rasterize on Skia, write a PNG sequence — and mux to mp4/webm via FFmpeg
 * when requested and available. No browser anywhere.
 */
+var render_exports = /* @__PURE__ */ __exportAll({
+	SceneModuleError: () => SceneModuleError,
+	buildMixWav: () => buildMixWav,
+	collectAudioClips: () => collectAudioClips,
+	ffmpegAvailable: () => ffmpegAvailable,
+	loadSceneModule: () => loadSceneModule,
+	parseFrameRange: () => parseFrameRange,
+	planFinalAudio: () => planFinalAudio,
+	render: () => render,
+	resolveLoudnessGainDb: () => resolveLoudnessGainDb
+});
 var SceneModuleError = class extends Error {
 	constructor(modulePath, detail) {
 		super(`${modulePath}: ${detail}\nA scene module default-exports { createScene(): Scene, timeline: Timeline } (SceneModule).`);
@@ -101,11 +113,23 @@ async function render(opts) {
 		await loadYogaLayoutEngine();
 	}
 	const videoSources = [];
-	const { resolveAssetPath: resolveAsset } = await import("./audioMix.js").then((n) => n.r);
+	const { resolveAssetPath: resolveAsset } = await import("./audioMix.js").then((n) => n.i);
 	const fontRegistry = buildFontRegistry(doc.assets);
 	if (fontRegistry.faces().length > 0) {
 		const { GlobalFonts } = await import("@napi-rs/canvas");
-		for (const face of fontRegistry.faces()) GlobalFonts.registerFromPath(resolveAsset(face.url, opts.modulePath), face.family);
+		let ingest;
+		for (const face of fontRegistry.faces()) {
+			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);
+				const result = await ingest.ingestFont({
+					family: face.family,
+					src
+				});
+				GlobalFonts.register(Buffer.from(result.bytes), face.family);
+			} else GlobalFonts.registerFromPath(path, face.family);
+		}
 	}
 	await validateSceneFonts(scene, doc, async (url) => {
 		try {
@@ -126,12 +150,48 @@ async function render(opts) {
 		backend.setVideoAsset(assetId, source);
 		videoSources.push(source);
 	}
+	let frameCache;
+	let keyCtx;
+	if (opts.cache && opts.cache.mode !== "off") {
+		const { FrameCache, capsId } = await import("./frameCache.js").then((n) => n.s);
+		const { glissadeVersion } = await import("./version.js").then((n) => n.n);
+		frameCache = new FrameCache({
+			dir: opts.cache.dir,
+			mode: opts.cache.mode,
+			...opts.cache.maxSize !== void 0 ? { maxSize: opts.cache.maxSize } : {}
+		});
+		keyCtx = {
+			version: glissadeVersion(),
+			capsId: capsId(backend.caps)
+		};
+	}
 	for (let f = firstFrame; f <= lastFrame; f++) {
-		backend.render(withDeterminismGuards("throw", () => evaluate(scene, doc, f / fps)));
-		writeFileSync(singleFile ? resolve(opts.out) : join(framesDir, `frame-${String(f).padStart(5, "0")}.png`), backend.encodePng());
+		const dl = withDeterminismGuards("throw", () => evaluate(scene, doc, f / fps));
+		let pngBytes;
+		if (frameCache && keyCtx) {
+			const { frameCacheKey } = await import("./frameCache.js").then((n) => n.s);
+			const key = frameCacheKey(dl, keyCtx);
+			const cached = frameCache.get(key);
+			if (cached) {
+				backend.putPixels(cached);
+				pngBytes = backend.encodePng();
+			} else {
+				backend.render(dl);
+				pngBytes = backend.encodePng();
+				frameCache.put(key, scene.size.w, scene.size.h, await backend.readPixels());
+			}
+		} else {
+			backend.render(dl);
+			pngBytes = backend.encodePng();
+		}
+		writeFileSync(singleFile ? resolve(opts.out) : join(framesDir, `frame-${String(f).padStart(5, "0")}.png`), pngBytes);
 		opts.onProgress?.(f - firstFrame + 1, total);
 	}
 	backend.dispose();
+	if (frameCache) {
+		const s = frameCache.getStats();
+		process.stderr.write(`cache (${opts.cache.mode}): ${s.hits} hit${s.hits === 1 ? "" : "s"}, ${s.misses} miss${s.misses === 1 ? "" : "es"}` + (s.stored ? `, ${s.stored} stored` : "") + (s.evicted ? `, ${s.evicted} evicted (LRU cap ${frameCache.maxSize} B)` : "") + ` → ${opts.cache.dir}\n`);
+	}
 	for (const source of videoSources) source.close();
 	const emitSidecars = (target) => {
 		if (captionsMode === "off") return;
@@ -222,13 +282,12 @@ async function render(opts) {
 	};
 }
 /**
-* Collect timeline + auto-mixed (narration/music/sfx) audio clips and plan the
-* FFmpeg audio graph, returning the `-i`/`-filter_complex`/`-map` argument
-* fragments. Shared by the linear `render()` path and the sharded orchestrator
-* (which mixes audio once, over the concatenated video). Returns empty args when
-* there is nothing to mix.
+* Collect the timeline + auto-mixed (narration/music/sfx) audio clips for a
+* scene — the shared front half of the mix used by both `planFinalAudio` (the
+* render/shard path) and `buildMixWav` (the measure-loudness path), so the mix
+* CONTENT measured at commit-time is byte-for-byte the mix rendered later.
 */
-async function planFinalAudio(opts, timelineClips, duration, container) {
+async function collectAudioClips(opts, timelineClips) {
 	const { timingPathFor } = await import("./captions.js").then((n) => n.t);
 	const audioClips = [...timelineClips];
 	const { bedAlreadyReferenced, buildMusicClip, buildNarrationClips, musicPathFor } = await import("./music.js");
@@ -266,7 +325,39 @@ async function planFinalAudio(opts, timelineClips, duration, container) {
 			}
 		}
 	}
-	const { planAudioMix } = await import("./audioMix.js").then((n) => n.r);
+	return audioClips;
+}
+/**
+* Resolve the committed publish gain (dB) for a render: read `<scene>.loudness.json`
+* (when present and `loudness !== 'off'`), recompute the mixHash over the current
+* mix inputs, and HARD-THROW on a mismatch — a re-narrate/re-sfx must invalidate
+* the measurement loudly rather than silently mis-normalize. Returns null when no
+* measurement is committed or loudness is off (no gain applied).
+*/
+async function resolveLoudnessGainDb(opts) {
+	if ((opts.loudness ?? "auto") === "off") return null;
+	const { readLoudness, computeMixHash, loudnessPathFor } = await import("./loudness.js").then((n) => n.c);
+	const measurement = readLoudness(opts.modulePath);
+	if (!measurement) return null;
+	const actual = computeMixHash(opts.modulePath);
+	if (actual !== measurement.mixHash) throw new Error(`loudness: ${loudnessPathFor(opts.modulePath)} is stale — the mix inputs changed since it was measured (committed mixHash ${measurement.mixHash.slice(0, 23)}…, current ${actual.slice(0, 23)}…). Re-run \`gs measure-loudness ${opts.modulePath}\` (or pass --loudness off to render without normalization).`);
+	return measurement.gain;
+}
+/**
+* Collect audio clips + auto-mixed siblings and plan the FFmpeg audio graph,
+* returning the `-i`/`-filter_complex`/`-map` argument fragments. Shared by the
+* linear `render()` path and the sharded orchestrator (which mixes audio once,
+* over the concatenated video). Returns empty args when there is nothing to mix.
+*
+* When a committed `<scene>.loudness.json` applies, its publish gain is appended
+* as a PURE `volume=<gain>dB` scalar on the FINAL mix node — a single scalar in
+* the existing graph, NOT a second pass. The scalar gain is bit-deterministic
+* (verified) and golden-hashable; the only non-deterministic stages (mix-to-PCM,
+* measure-time ebur128) are quarantined to commit/measure-time per §5.3.
+*/
+async function planFinalAudio(opts, timelineClips, duration, container) {
+	const audioClips = await collectAudioClips(opts, timelineClips);
+	const { planAudioMix, applyMixGainDb } = await import("./audioMix.js").then((n) => n.i);
 	const { pickEncoder } = await import("./encoders.js").then((n) => n.r);
 	const mix = planAudioMix(audioClips, opts.modulePath, duration);
 	if (mix?.hasEasedGain) process.stderr.write("note: eased gain keys are approximated linearly in the FFmpeg mix\n");
@@ -274,12 +365,15 @@ async function planFinalAudio(opts, timelineClips, duration, container) {
 		audioInputs: [],
 		audioArgs: []
 	};
+	const gainDb = await resolveLoudnessGainDb(opts);
+	const filterComplex = gainDb !== null ? applyMixGainDb(mix.filterComplex, gainDb) : mix.filterComplex;
+	if (gainDb !== null) process.stderr.write(`note: applying committed publish loudness gain ${gainDb.toFixed(2)} dB (single-pass scalar)\n`);
 	const audioEnc = pickEncoder("audio", container);
 	return {
 		audioInputs: mix.inputs.flatMap((p) => ["-i", p]),
 		audioArgs: [
 			"-filter_complex",
-			mix.filterComplex,
+			filterComplex,
 			"-map",
 			"0:v",
 			"-map",
@@ -290,5 +384,51 @@ async function planFinalAudio(opts, timelineClips, duration, container) {
 		]
 	};
 }
+/**
+* Build the FINAL mixed audio to a WAV file — the measure-loudness input. Uses
+* the SAME `collectAudioClips` + `planAudioMix` as the render path (no loudness
+* gain — measurement is of the un-gained mix), so the measured content is exactly
+* what render will later mix. Returns false when the scene has no audio.
+*/
+async function buildMixWav(opts, wavOut) {
+	if (!ffmpegAvailable()) throw new Error("gs measure-loudness needs FFmpeg on PATH and none was found.");
+	const mod = await loadSceneModule(opts.modulePath);
+	const scene = mod.createScene();
+	const { compileTimeline } = await import("@glissade/core");
+	const compiled = compileTimeline(mod.timeline);
+	const duration = compiled.duration;
+	const audioClips = await collectAudioClips(opts, [...compiled.audio]);
+	const { planAudioMix } = await import("./audioMix.js").then((n) => n.i);
+	const mix = planAudioMix(audioClips, opts.modulePath, duration);
+	if (!mix) return false;
+	const result = spawnSync("ffmpeg", [
+		"-y",
+		"-hide_banner",
+		"-nostats",
+		"-f",
+		"lavfi",
+		"-i",
+		"anullsrc=channel_layout=stereo:sample_rate=48000",
+		...mix.inputs.flatMap((p) => ["-i", p]),
+		"-filter_complex",
+		mix.filterComplex,
+		"-map",
+		"[aout]",
+		"-c:a",
+		"pcm_s16le",
+		"-ar",
+		"48000",
+		"-t",
+		String(duration),
+		wavOut
+	], { stdio: [
+		"ignore",
+		"ignore",
+		"pipe"
+	] });
+	if (result.status !== 0) throw new Error(`ffmpeg mix-to-WAV failed (exit ${result.status}):\n${result.stderr?.toString().slice(-2e3)}`);
+	scene.size;
+	return true;
+}
 //#endregion
-export { planFinalAudio as a, parseFrameRange as i, ffmpegAvailable as n, render as o, loadSceneModule as r, SceneModuleError as t };
+export { loadSceneModule as a, render as c, ffmpegAvailable as i, render_exports as l, buildMixWav as n, parseFrameRange as o, collectAudioClips as r, planFinalAudio as s, SceneModuleError as t, resolveLoudnessGainDb as u };

package/dist/rolldown-runtime.js

@@ -1,3 +1,4 @@
+import "node:module";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {

package/dist/shards.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
-import { a as planFinalAudio } from "./render.js";
+import { s as planFinalAudio } from "./render.js";
 import { a as pickEncoder } from "./encoders.js";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";

package/dist/verifyDeterminism.js

@@ -0,0 +1,302 @@
+import { t as SceneModuleError } from "./render.js";
+import { a as splitFrameRange } from "./shards.js";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+import { createDisplayListBuilder, diffDisplayLists, evaluate, formatDisplayDiff, serializeDisplayList, withDeterminismGuards } from "@glissade/scene";
+import { createHash } from "node:crypto";
+//#region src/verifyDeterminism.ts
+/**
+* gs verify-determinism (DESIGN.md §5.5/§5.6 §7): the cross-shard / cross-machine
+* divergence LOCATOR. It is the VERIFIER of the determinism tenet — it never
+* perturbs the contract: it evaluates under the SAME `withDeterminismGuards('throw')`
+* as `gs render`, hashes the SAME raw RGBA the FFmpeg pipe consumes, and reuses the
+* SHIPPED DisplayList serializer for the per-node sub-hashes. It renders no new
+* pixels through a path the goldens don't already pin.
+*
+* The authoritative byte check is the per-frame `sha256(RGBA)` over the raw
+* `backend.readPixels()` (NOT `encodePng` — sidestepping any PNG-encoder
+* nondeterminism). The per-node sub-hashes LOCALIZE where a frame diverged; they
+* are a locator, not the authority — a node whose isolated emit() depends on the
+* parent CTM may sub-hash differently in isolation than it draws in context.
+*
+* HONEST SCOPE (§5.5 item 6): the byte-equality guarantee is Skia↔Skia ONLY
+* (cross-machine / cross-shard, same pinned toolchain). Browser↔Skia is perceptual
+* (SSIM), never byte-identity — so comparing a non-Skia manifest by byte-hash is a
+* CATEGORY ERROR and is REJECTED with a clear error. The manifest stamps `backend`
+* so an `--against` cross-backend compare is caught.
+*/
+/**
+* Load a scene module with a FRESH module cache (`moduleCache: false`), so each
+* call re-runs the module's top level from scratch — exactly what a separate `gs`
+* shard process does. This is the faithful in-process model of cross-process
+* sharding: it resets any module-level state (the §5.5-item-5 cross-frame
+* accumulation a render shard child wouldn't share), so a stateful impurity
+* actually diverges here instead of being masked by a shared module instance.
+*/
+async function freshLoadSceneModule(modulePath) {
+	const abs = isAbsolute(modulePath) ? modulePath : resolve(process.cwd(), modulePath);
+	const loaded = await createJiti(pathToFileURL(process.cwd() + "/").href, { moduleCache: false }).import(pathToFileURL(abs).href, { default: true });
+	if (typeof loaded?.createScene !== "function" || loaded?.timeline === void 0) throw new SceneModuleError(modulePath, "default export is not a SceneModule");
+	return loaded;
+}
+var VerifyDeterminismError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "VerifyDeterminismError";
+	}
+};
+/** sha256 hex of arbitrary bytes / string (the committed-byte-hash precedent — node:crypto, no BLAKE3). */
+function sha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+/**
+* Per-node DisplayList sub-hashes for one frame: each node's emit() in ISOLATION,
+* serialized through the SHIPPED `serializeDisplayList` (the byte-preserving
+* collapse serializer that backs `.dl.json` + the cacheKey), then sha256'd. This
+* mirrors `auditCacheCold`'s per-node emit — the divergence locator.
+*/
+function nodeSubHashes(scene, ctx) {
+	const out = {};
+	for (const [id, node] of scene.nodes) {
+		const b = createDisplayListBuilder(scene.size);
+		node.emit(b, ctx);
+		out[id] = sha256(serializeDisplayList(b.finish()));
+	}
+	return out;
+}
+/**
+* Build a frames manifest for an inclusive frame range. Each frame is evaluated
+* under `withDeterminismGuards('throw')` (EXACTLY as render.ts does — any
+* clock/random/timer call in scene code throws HERE during verification),
+* rasterized on Skia, and the raw RGBA from `readPixels()` is sha256'd.
+*
+* Asset loading (fonts/images/video) is intentionally out of scope: this is a
+* geometry/raster determinism probe over the pure DisplayList path. A scene with
+* external assets still verifies its drawn output; unregistered fonts fall back
+* deterministically (the same as the linear render path with no registration).
+*/
+async function buildManifest(mod, first, last, fpsOverride) {
+	const { SkiaBackend } = await import("@glissade/backend-skia");
+	const scene = mod.createScene();
+	const doc = mod.timeline;
+	const fps = fpsOverride ?? doc.fps ?? 60;
+	const backend = new SkiaBackend(scene.size.w, scene.size.h);
+	scene.setTextMeasurer(backend);
+	const frames = [];
+	for (let f = first; f <= last; f++) {
+		const t = f / fps;
+		const dl = withDeterminismGuards("throw", () => evaluate(scene, doc, t));
+		backend.render(dl);
+		const rgba = await backend.readPixels();
+		const ctx = {
+			time: t,
+			frame: doc.fps !== void 0 ? Math.round(t * doc.fps) : Math.round(t * fps),
+			measurer: scene.textMeasurer
+		};
+		frames.push({
+			frame: f,
+			hash: sha256(new Uint8Array(rgba.buffer, rgba.byteOffset, rgba.byteLength)),
+			nodes: nodeSubHashes(scene, ctx)
+		});
+	}
+	backend.dispose();
+	const groups = [];
+	for (const [id, node] of scene.nodes) if (Array.isArray(node.children)) groups.push(id);
+	return {
+		manifestVersion: 1,
+		backend: "skia",
+		size: scene.size,
+		fps,
+		groups,
+		frames
+	};
+}
+function serializeManifest(m) {
+	return JSON.stringify(m, null, 2);
+}
+function parseManifest(json) {
+	const doc = JSON.parse(json);
+	if (doc.manifestVersion !== 1) throw new VerifyDeterminismError(`unsupported manifestVersion ${String(doc.manifestVersion)}; this build reads 1`);
+	if (doc.backend === void 0 || !doc.size || doc.fps === void 0 || !Array.isArray(doc.frames) || !Array.isArray(doc.groups)) throw new VerifyDeterminismError("malformed frames.manifest (need backend, size, fps, groups[], frames[])");
+	return doc;
+}
+/**
+* Compare two manifests frame-by-frame. The full-frame RGBA hash is authoritative;
+* the per-node sub-hashes localize WHERE a divergent frame differs. Stops at the
+* FIRST divergent frame (the bisect target).
+*/
+function compareManifests(a, b) {
+	if (a.backend !== b.backend) throw new VerifyDeterminismError(`cross-backend byte-compare rejected: '${a.backend}' vs '${b.backend}'. Byte-equality is a Skia↔Skia (cross-machine/shard) guarantee only; browser↔Skia is perceptual (SSIM) parity, never byte-identity (§5.5 item 6).`);
+	const byFrameB = new Map(b.frames.map((e) => [e.frame, e]));
+	let compared = 0;
+	for (const ea of a.frames) {
+		const eb = byFrameB.get(ea.frame);
+		if (!eb) continue;
+		compared++;
+		if (ea.hash === eb.hash) continue;
+		const groups = new Set(a.groups);
+		let node;
+		let groupFallback;
+		for (const [id, ha] of Object.entries(ea.nodes)) {
+			if (eb.nodes[id] === ha) continue;
+			if (groups.has(id)) {
+				groupFallback ??= id;
+				continue;
+			}
+			node = id;
+			break;
+		}
+		node ??= groupFallback;
+		return {
+			ok: false,
+			compared,
+			divergence: {
+				frame: ea.frame,
+				hash: {
+					a: ea.hash,
+					b: eb.hash
+				},
+				...node !== void 0 ? { node } : {}
+			}
+		};
+	}
+	return {
+		ok: true,
+		compared
+	};
+}
+/**
+* Replay a fresh scene through frames `[from..frame]` to reach the SAME module
+* state the divergent render had at `frame`, then return the divergent NODE's
+* isolated DisplayList at `frame`. Replaying the leading frames is what makes a
+* cross-frame-state impurity reproduce here: the linear side replays from the
+* range start, the shard side replays from the shard's sub-range start, so a
+* counter/accumulator reaches different values exactly as it did in the manifests.
+*/
+function replayNodeEmit(mod, from, frame, fps, node) {
+	const scene = mod.createScene();
+	const target = scene.nodes.get(node);
+	if (!target) return void 0;
+	const docFps = mod.timeline.fps;
+	return withDeterminismGuards("throw", () => {
+		for (let f = from; f <= frame; f++) evaluate(scene, mod.timeline, f / fps);
+		const t = frame / fps;
+		const ctx = {
+			time: t,
+			frame: docFps !== void 0 ? Math.round(t * docFps) : Math.round(t * fps),
+			measurer: scene.textMeasurer
+		};
+		const b = createDisplayListBuilder(scene.size);
+		target.emit(b, ctx);
+		return b.finish();
+	});
+}
+/** Produce the command-level drill (`diffDisplayLists` + `formatDisplayDiff`) of the divergent node. */
+async function runBisect(plan) {
+	const modA = await freshLoadSceneModule(plan.modulePath);
+	const modB = await freshLoadSceneModule(plan.modulePath);
+	const dlA = replayNodeEmit(modA, plan.fromA, plan.frame, plan.fps, plan.node);
+	const dlB = replayNodeEmit(modB, plan.fromB, plan.frame, plan.fps, plan.node);
+	if (!dlA || !dlB) return `node '${plan.node}' is not present in both scenes — cannot drill`;
+	return formatDisplayDiff(diffDisplayLists(dlA, dlB));
+}
+/**
+* Resolve the inclusive frame range to verify. Mirrors render.ts: an explicit
+* --range wins; otherwise the whole timeline [0, ceil(duration*fps)-1].
+*/
+async function resolveRange(mod, opts) {
+	const fps = opts.fps ?? mod.timeline.fps ?? 60;
+	if (opts.frameRange) {
+		const [a, b] = opts.frameRange;
+		return {
+			first: a,
+			last: Math.max(a, b),
+			fps
+		};
+	}
+	const { compileTimeline } = await import("@glissade/core");
+	const duration = compileTimeline(mod.timeline).duration;
+	return {
+		first: 0,
+		last: Math.max(0, Math.ceil(duration * fps) - 1),
+		fps
+	};
+}
+async function verifyDeterminismCommand(opts) {
+	const mod = await freshLoadSceneModule(opts.modulePath);
+	const { first, last, fps } = await resolveRange(mod, opts);
+	if (opts.emit !== void 0) {
+		const manifest = await buildManifest(mod, first, last, fps);
+		const { writeFileSync } = await import("node:fs");
+		writeFileSync(opts.emit, serializeManifest(manifest));
+		return {
+			ok: true,
+			frames: manifest.frames.length,
+			report: `wrote ${manifest.frames.length}-frame manifest (frames ${first}..${last}) → ${opts.emit}`
+		};
+	}
+	const linear = await buildManifest(mod, first, last, fps);
+	if (opts.against !== void 0) {
+		const baseline = parseManifest(readFileSync(opts.against, "utf8"));
+		if (baseline.backend !== linear.backend) throw new VerifyDeterminismError(`cross-backend byte-compare rejected: baseline '${opts.against}' is backend '${baseline.backend}', this render is '${linear.backend}'. Byte-equality is a Skia↔Skia (cross-machine/shard) guarantee only; browser↔Skia is perceptual (SSIM) parity, never byte-identity (§5.5 item 6). Use SSIM parity for cross-backend.`);
+		return finalize(compareManifests(baseline, linear), opts, `linear render vs baseline ${opts.against}`, void 0);
+	}
+	if (opts.shards !== void 0 && opts.shards > 1) {
+		const ranges = splitFrameRange(first, last, opts.shards);
+		const shardFrames = [];
+		for (const r of ranges) {
+			const sub = await buildManifest(await freshLoadSceneModule(opts.modulePath), r.first, r.last, fps);
+			shardFrames.push(...sub.frames);
+		}
+		const cmp = compareManifests(linear, {
+			...linear,
+			frames: shardFrames
+		});
+		const bisectFor = (d) => {
+			if (d.node === void 0) return void 0;
+			const shard = ranges.find((r) => d.frame >= r.first && d.frame <= r.last);
+			return {
+				modulePath: opts.modulePath,
+				node: d.node,
+				frame: d.frame,
+				fps,
+				fromA: first,
+				fromB: shard?.first ?? first
+			};
+		};
+		return finalize(cmp, opts, `linear vs ${ranges.length}-shard render (frames ${first}..${last})`, bisectFor);
+	}
+	return {
+		ok: true,
+		frames: linear.frames.length,
+		report: `built a ${linear.frames.length}-frame manifest (frames ${first}..${last}) under determinism guards — no clock/random violation. Pass --shards N or --against <manifest> to byte-compare.`
+	};
+}
+/** Shared tail: build the report + optional --bisect drill for a comparison result. */
+async function finalize(cmp, opts, label, bisectFor) {
+	if (cmp.ok) return {
+		ok: true,
+		frames: cmp.compared,
+		report: `byte-identical: ${cmp.compared} frames match (${label})`
+	};
+	const d = cmp.divergence;
+	let report = `DIVERGENCE (${label})\n  frame ${d.frame}: RGBA sha256 ${d.hash.a.slice(0, 16)}… != ${d.hash.b.slice(0, 16)}…\n` + (d.node !== void 0 ? `  first divergent node: '${d.node}' (sub-hash locator)` : "  no per-node sub-hash differs (a parent-CTM / composite effect localized the frame hash only)");
+	if (opts.bisect && d.node !== void 0) {
+		const plan = bisectFor?.(d);
+		if (plan) {
+			const drill = await runBisect(plan);
+			d.bisect = drill;
+			report += `\n  --bisect drill (node '${d.node}' @ frame ${d.frame}):\n${drill.replace(/^/gm, "    ")}`;
+		} else report += `\n  --bisect: no command-level drill available (an --against baseline carries hashes, not a scene)`;
+	}
+	return {
+		ok: false,
+		frames: cmp.compared,
+		divergence: d,
+		report
+	};
+}
+//#endregion
+export { verifyDeterminismCommand };

package/dist/version.js

@@ -0,0 +1,26 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { createRequire } from "node:module";
+//#region src/version.ts
+/**
+* The glissade VERSION string folded into the persistent frame-cache key
+* (DESIGN.md §3.5, 0.12). Lockstep `0.x` versioning means the @glissade/cli
+* package version bumps with EVERY release, so any Raster2D-composite or
+* Skia-toolchain change ships under a new version — making bump-on-version the
+* cheapest CORRECT cache invalidation. Read once from the package manifest (the
+* single source of truth) rather than hard-coded so it can never drift from the
+* published version.
+*/
+var version_exports = /* @__PURE__ */ __exportAll({ glissadeVersion: () => glissadeVersion });
+let cached;
+/** The @glissade/cli package version (the glissade VERSION for the cache key). */
+function glissadeVersion() {
+	if (cached !== void 0) return cached;
+	try {
+		cached = createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
+	} catch {
+		cached = "0.0.0";
+	}
+	return cached;
+}
+//#endregion
+export { version_exports as n, glissadeVersion as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.11.0",
+  "version": "0.12.0-pre.0",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "engines": {
@@ -23,15 +23,15 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "^0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.11.0",
-    "@glissade/core": "0.11.0",
-    "@glissade/interact": "0.11.0",
-    "@glissade/lottie": "0.11.0",
-    "@glissade/svg": "0.11.0",
-    "@glissade/narrate": "0.11.0",
-    "@glissade/player": "0.11.0",
-    "@glissade/scene": "0.11.0",
-    "@glissade/sfx": "0.11.0"
+    "@glissade/backend-skia": "0.12.0-pre.0",
+    "@glissade/core": "0.12.0-pre.0",
+    "@glissade/interact": "0.12.0-pre.0",
+    "@glissade/lottie": "0.12.0-pre.0",
+    "@glissade/svg": "0.12.0-pre.0",
+    "@glissade/narrate": "0.12.0-pre.0",
+    "@glissade/player": "0.12.0-pre.0",
+    "@glissade/scene": "0.12.0-pre.0",
+    "@glissade/sfx": "0.12.0-pre.0"
   },
   "repository": {
     "type": "git",