@glissade/cli 0.12.0-pre.0 → 0.12.0

package/dist/cacheVerify.js

@@ -76,7 +76,8 @@ async function cacheVerifyCommand(opts) {
 	const sample = Math.max(1, Math.floor(opts.sample ?? 1));
 	const ctx = opts.keyContextOverride ?? {
 		version: glissadeVersion(),
-		capsId: capsId(backend.caps)
+		capsId: capsId(backend.caps),
+		assetsDigest: ""
 	};
 	const keyer = opts.keyerOverride ?? frameCacheKey;
 	const dir = mkdtempSync(join(tmpdir(), "gscache-verify-"));

package/dist/frameCache.js

@@ -21,15 +21,22 @@ import { deflateSync, inflateSync } from "node:zlib";
 * THE failure mode is SILENT corruption: a stale tile served from an INCOMPLETE
 * key. So the key MUST fold EVERY byte-affecting input (§ key completeness):
 *   1. the frame's DisplayList-snapshot bytes (`serializeDisplayList` — the shipped
-*      byte-preserving collapse serializer; resources already inlined to content,
-*      and the post-evaluate DisplayList already encodes resolved device
-*      transforms, so this captures geometry/paint/transform for a whole frame),
+*      byte-preserving collapse serializer; the post-evaluate DisplayList encodes
+*      resolved device transforms, so this captures geometry/paint/transform for a
+*      whole frame). CAVEAT: image/video/font draws carry only the asset *id* (not
+*      pixels/glyphs), so the DisplayList alone does NOT see an in-place edit of
+*      `logo.png`/`clip.mp4`/`font.ttf` — component (4) closes that hole,
 *   2. the glissade VERSION (any Raster2D-composite / Skia-toolchain change
 *      invalidates every frame — bump-on-version is the cheapest correct
 *      invalidation; text/font tiles are thereby scoped to the pinned toolchain),
-*   3. the BackendCaps id (filters / shaders / maxTextureSize).
-* `version` and `capsId` have no source inside `scene`, so they are INJECTED via a
-* `CacheKeyContext` from the CLI — NEVER read from disk.
+*   3. the BackendCaps id (filters / shaders / maxTextureSize),
+*   4. the ASSET-CONTENT digest: a single sha256 over the sorted (assetId →
+*      sha256(bytes)) map of every referenced image/video/font. Editing an asset's
+*      BYTES in place (same id/url/family) changes this digest → the key changes →
+*      no stale pixels are served. It over-invalidates a frame that doesn't use a
+*      changed asset (whole-run scope), which is CORRECT-safe — never stale.
+* `version`, `capsId`, and `assetsDigest` have no source inside `scene`, so they are
+* INJECTED via a `CacheKeyContext` from the CLI — NEVER read from disk.
 *
 * HIT == MISS: the HIT path reuses the SAME composite/encode routine as a MISS.
 * The miss path renders, reads raw RGBA, stores it; the hit path loads the stored
@@ -53,6 +60,7 @@ var frameCache_exports = /* @__PURE__ */ __exportAll({
 	FrameCacheError: () => FrameCacheError,
 	capsId: () => capsId,
 	clearFrameCache: () => clearFrameCache,
+	combineAssetDigests: () => combineAssetDigests,
 	frameCacheKey: () => frameCacheKey,
 	parseCacheMaxSize: () => parseCacheMaxSize,
 	probeEntryHeader: () => probeEntryHeader
@@ -70,14 +78,33 @@ var FrameCacheError = class extends Error {
 };
 /**
 * Stable, content-addressed key for ONE whole frame. Folds EVERY byte-affecting
-* input: the DisplayList-snapshot bytes (geometry/paint/transform, resources
-* inlined to content), the glissade version, and the backend caps id. An
-* incomplete key here IS the only failure mode (a stale frame served for changed
-* content), so the NEGATIVE gate test asserts that dropping any component makes
-* `gs cache verify` fail.
+* input: the DisplayList-snapshot bytes (geometry/paint/transform — but only the
+* asset *id* for image/video/font draws), the glissade version, the backend caps
+* id, AND the asset-content digest (the BYTES behind those ids). An incomplete key
+* here IS the only failure mode (a stale frame served for changed content), so the
+* NEGATIVE gate test asserts that dropping any component makes `gs cache verify`
+* fail.
 */
 function frameCacheKey(dl, ctx) {
-	return createHash("sha256").update(serializeDisplayList(dl)).update("\0").update(ctx.version).update("\0").update(ctx.capsId).digest("hex");
+	return createHash("sha256").update(serializeDisplayList(dl)).update("\0").update(ctx.version).update("\0").update(ctx.capsId).update(" ").update(ctx.assetsDigest).digest("hex");
+}
+/**
+* Combine per-asset byte digests into ONE stable digest for the key context. Sorts
+* by assetId so the order assets loaded in never affects the key, then folds each
+* `id\0byteSha256\0` pair. An empty map → '' (no binary assets → no extra
+* invalidation, byte-identical key to a pre-asset-digest scene). Each byteDigest is
+* the caller's sha256 of the asset's raw bytes.
+*/
+function combineAssetDigests(byId) {
+	if (byId.size === 0) return "";
+	const h = createHash("sha256");
+	for (const id of [...byId.keys()].sort()) {
+		h.update(id);
+		h.update("\0");
+		h.update(byId.get(id));
+		h.update("\0");
+	}
+	return h.digest("hex");
 }
 /** A canonical BackendCaps id (filters sorted, shaders, maxTextureSize) — the §3 caps fold. */
 function capsId(caps) {

package/dist/index.d.ts

@@ -19,6 +19,14 @@ interface CacheKeyContext {
   version: string;
   /** BackendCaps id (filters/shaders/maxTextureSize) — folds the rasterizer's capabilities. */
   capsId: string;
+  /**
+   * A digest of the BYTES of every referenced image/video/font asset (a single
+   * sha256 over the sorted assetId→byteDigest map; see `assetsDigest`). The
+   * DisplayList carries only the asset *id*, NOT pixels, so without this an
+   * in-place edit of an asset (same id/url) would collide the key and serve stale
+   * pixels. Empty string when the scene references no binary assets.
+   */
+  assetsDigest: string;
 }
 interface FrameCacheOptions {
   dir: string;
@@ -33,13 +41,22 @@ declare class FrameCacheError extends Error {
 }
 /**
  * Stable, content-addressed key for ONE whole frame. Folds EVERY byte-affecting
- * input: the DisplayList-snapshot bytes (geometry/paint/transform, resources
- * inlined to content), the glissade version, and the backend caps id. An
- * incomplete key here IS the only failure mode (a stale frame served for changed
- * content), so the NEGATIVE gate test asserts that dropping any component makes
- * `gs cache verify` fail.
+ * input: the DisplayList-snapshot bytes (geometry/paint/transform — but only the
+ * asset *id* for image/video/font draws), the glissade version, the backend caps
+ * id, AND the asset-content digest (the BYTES behind those ids). An incomplete key
+ * here IS the only failure mode (a stale frame served for changed content), so the
+ * NEGATIVE gate test asserts that dropping any component makes `gs cache verify`
+ * fail.
  */
 declare function frameCacheKey(dl: DisplayList, ctx: CacheKeyContext): string;
+/**
+ * Combine per-asset byte digests into ONE stable digest for the key context. Sorts
+ * by assetId so the order assets loaded in never affects the key, then folds each
+ * `id\0byteSha256\0` pair. An empty map → '' (no binary assets → no extra
+ * invalidation, byte-identical key to a pre-asset-digest scene). Each byteDigest is
+ * the caller's sha256 of the asset's raw bytes.
+ */
+
 /** A canonical BackendCaps id (filters sorted, shaders, maxTextureSize) — the §3 caps fold. */
 declare function capsId(caps: {
   filters: ReadonlySet<string>;
@@ -207,14 +224,34 @@ declare function render(opts: RenderOptions): Promise<{
  * CONTENT measured at commit-time is byte-for-byte the mix rendered later.
  */
 declare function collectAudioClips(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx'>, timelineClips: AudioClip[]): Promise<AudioClip[]>;
+/**
+ * Resolve the ACTUAL audio files that feed the final mix (timeline clips +
+ * auto-mixed narration/music/sfx), as absolute paths. This is what the mixHash
+ * must hash the BYTES of: editing a timeline `.wav` or a music stem in place leaves
+ * the timing manifests unchanged, so without folding these bytes a stale publish
+ * gain would be applied silently. Reuses `collectAudioClips` (the same gather the
+ * mix itself uses), then resolves each clip asset URL. De-duplicated + sorted so
+ * measure-time and render-time agree regardless of clip order. `timelineClips` is
+ * the scene's compiled timeline audio; when omitted it is compiled from the module
+ * (so measure-time and the bare-gate path see the SAME timeline clips render does).
+ * A module that can't load (e.g. a unit-test stub path) falls back to no timeline
+ * clips — the narration/music/sfx siblings still resolve from `modulePath`.
+ */
+
 /**
  * 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).
+ *
+ * The mixHash folds the BYTES of the actual mix audio inputs (timeline clips +
+ * narration/music/sfx) — not just the timing manifests — so an in-place edit of a
+ * `.wav`/music stem invalidates the measurement here too (the §5.3 stale-gain
+ * gate). `timelineClips` defaults to the scene's compiled timeline audio when
+ * omitted, so a bare `{ modulePath }` call still gates correctly.
  */
-declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness'>): Promise<number | null>;
+declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness' | 'narration' | 'music' | 'sfx'>, timelineClips?: AudioClip[]): Promise<number | null>;
 /**
  * Collect audio clips + auto-mixed siblings and plan the FFmpeg audio graph,
  * returning the `-i`/`-filter_complex`/`-map` argument fragments. Shared by the
@@ -226,6 +263,9 @@ declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' |
  * 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.
+ *
+ * (Note: `collectMixAudioInputs` resolves auto-mixed narration/music/sfx siblings
+ * from `modulePath`, so a `timelineClips: []` default still gates those.)
  */
 declare function planFinalAudio(opts: RenderOptions, timelineClips: AudioClip[], duration: number, container: 'mp4' | 'webm'): Promise<{
   audioInputs: string[];
@@ -334,13 +374,16 @@ declare function computeGainDb(profile: PublishProfile, inputI: number, inputTp:
  */
 declare function peakClampBinds(profile: PublishProfile, inputI: number, inputTp: number): boolean;
 /**
- * Hash the CONTENT of the mix's input manifests so a re-narrate / re-sfx / music
- * change invalidates a committed measurement. We hash the files' BYTES (not
- * mtime): the narration/music/sfx timing manifests and any wired timeline audio
- * sidecars. Missing siblings are recorded by name with a sentinel so adding one
- * later also changes the hash. The scene module path itself is excluded — the
- * mix is a function of the manifests, and timeline `audio` clips flow through the
- * narration/music/sfx manifests or the explicitly-passed extra inputs.
+ * Hash the CONTENT of the mix's inputs so a re-narrate / re-sfx / music change OR
+ * an in-place edit of an audio file invalidates a committed measurement. We hash
+ * the files' BYTES (not mtime): the narration/music/sfx timing manifests AND every
+ * path in `extraInputs` — the resolved mix AUDIO files (timeline clips + the music
+ * stem + narration cache audio), supplied by `collectMixAudioInputs` at both the
+ * measure and render call sites so the two agree. Hashing only the timing manifests
+ * would miss an edited `.wav`/stem (same manifest, changed bytes) and apply a stale
+ * publish gain silently — so `extraInputs` MUST be passed on the gate path. Missing
+ * files are recorded by name with a sentinel so adding one later also changes the
+ * hash. The scene module path itself is excluded.
  */
 declare function computeMixHash(modulePath: string, extraInputs?: readonly string[]): string;
 /** `<module>.loudness.json` for a scene module. */

package/dist/loudness.js

@@ -117,13 +117,16 @@ function peakClampBinds(profile, inputI, inputTp) {
 	return profile.truePeakDb - inputTp < profile.targetLufs - inputI;
 }
 /**
-* Hash the CONTENT of the mix's input manifests so a re-narrate / re-sfx / music
-* change invalidates a committed measurement. We hash the files' BYTES (not
-* mtime): the narration/music/sfx timing manifests and any wired timeline audio
-* sidecars. Missing siblings are recorded by name with a sentinel so adding one
-* later also changes the hash. The scene module path itself is excluded — the
-* mix is a function of the manifests, and timeline `audio` clips flow through the
-* narration/music/sfx manifests or the explicitly-passed extra inputs.
+* Hash the CONTENT of the mix's inputs so a re-narrate / re-sfx / music change OR
+* an in-place edit of an audio file invalidates a committed measurement. We hash
+* the files' BYTES (not mtime): the narration/music/sfx timing manifests AND every
+* path in `extraInputs` — the resolved mix AUDIO files (timeline clips + the music
+* stem + narration cache audio), supplied by `collectMixAudioInputs` at both the
+* measure and render call sites so the two agree. Hashing only the timing manifests
+* would miss an edited `.wav`/stem (same manifest, changed bytes) and apply a stale
+* publish gain silently — so `extraInputs` MUST be passed on the gate path. Missing
+* files are recorded by name with a sentinel so adding one later also changes the
+* hash. The scene module path itself is excluded.
 */
 function computeMixHash(modulePath, extraInputs = []) {
 	const base = modulePath.replace(/\.[jt]sx?$/, "");
@@ -223,7 +226,14 @@ async function measureLoudnessCommand(opts) {
 		const { inputI, inputTp, inputLra } = measureFile(wavPath);
 		const gain = computeGainDb(profile, inputI, inputTp);
 		const clampBound = peakClampBinds(profile, inputI, inputTp);
-		const mixHash = computeMixHash(opts.modulePath);
+		const { collectMixAudioInputs } = await import("./render.js").then((n) => n.l);
+		const extraInputs = await collectMixAudioInputs({
+			modulePath: opts.modulePath,
+			narration: opts.narration ?? "auto",
+			music: opts.music ?? "auto",
+			sfx: opts.sfx ?? "auto"
+		});
+		const mixHash = computeMixHash(opts.modulePath, extraInputs);
 		const measurement = {
 			loudnessVersion: 1,
 			profileId: profile.id,

package/dist/render.js

@@ -19,6 +19,7 @@ var render_exports = /* @__PURE__ */ __exportAll({
 	SceneModuleError: () => SceneModuleError,
 	buildMixWav: () => buildMixWav,
 	collectAudioClips: () => collectAudioClips,
+	collectMixAudioInputs: () => collectMixAudioInputs,
 	ffmpegAvailable: () => ffmpegAvailable,
 	loadSceneModule: () => loadSceneModule,
 	parseFrameRange: () => parseFrameRange,
@@ -114,6 +115,9 @@ async function render(opts) {
 	}
 	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 fontRegistry = buildFontRegistry(doc.assets);
 	if (fontRegistry.faces().length > 0) {
 		const { GlobalFonts } = await import("@napi-rs/canvas");
@@ -123,12 +127,16 @@ async function render(opts) {
 			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 GlobalFonts.registerFromPath(path, face.family);
+			} else {
+				assetDigests.set(`font:${face.family}:${face.url}`, digestBytes(await readFile(path)));
+				GlobalFonts.registerFromPath(path, face.family);
+			}
 		}
 	}
 	await validateSceneFonts(scene, doc, async (url) => {
@@ -141,11 +149,15 @@ async function render(opts) {
 	}, { mode: opts.strictFonts ? "strict" : "dev" });
 	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");
-		backend.setImageAsset(assetId, await loadImage(resolveAsset(ref.url, opts.modulePath)));
+		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 source = new FfmpegVideoFrameSource(resolveAsset(ref.url, opts.modulePath));
+		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);
@@ -153,7 +165,7 @@ async function render(opts) {
 	let frameCache;
 	let keyCtx;
 	if (opts.cache && opts.cache.mode !== "off") {
-		const { FrameCache, capsId } = await import("./frameCache.js").then((n) => n.s);
+		const { FrameCache, capsId, combineAssetDigests } = 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,
@@ -162,7 +174,8 @@ async function render(opts) {
 		});
 		keyCtx = {
 			version: glissadeVersion(),
-			capsId: capsId(backend.caps)
+			capsId: capsId(backend.caps),
+			assetsDigest: combineAssetDigests(assetDigests)
 		};
 	}
 	for (let f = firstFrame; f <= lastFrame; f++) {
@@ -328,18 +341,57 @@ async function collectAudioClips(opts, timelineClips) {
 	return audioClips;
 }
 /**
+* Resolve the ACTUAL audio files that feed the final mix (timeline clips +
+* auto-mixed narration/music/sfx), as absolute paths. This is what the mixHash
+* must hash the BYTES of: editing a timeline `.wav` or a music stem in place leaves
+* the timing manifests unchanged, so without folding these bytes a stale publish
+* gain would be applied silently. Reuses `collectAudioClips` (the same gather the
+* mix itself uses), then resolves each clip asset URL. De-duplicated + sorted so
+* measure-time and render-time agree regardless of clip order. `timelineClips` is
+* the scene's compiled timeline audio; when omitted it is compiled from the module
+* (so measure-time and the bare-gate path see the SAME timeline clips render does).
+* A module that can't load (e.g. a unit-test stub path) falls back to no timeline
+* clips — the narration/music/sfx siblings still resolve from `modulePath`.
+*/
+async function collectMixAudioInputs(opts, timelineClips) {
+	let tl = timelineClips;
+	if (tl === void 0) try {
+		const mod = await loadSceneModule(opts.modulePath);
+		const { compileTimeline } = await import("@glissade/core");
+		tl = [...compileTimeline(mod.timeline).audio];
+	} catch {
+		tl = [];
+	}
+	const clips = await collectAudioClips(opts, tl);
+	const { resolveAssetPath } = await import("./audioMix.js").then((n) => n.i);
+	const paths = /* @__PURE__ */ new Set();
+	for (const c of clips) try {
+		paths.add(resolveAssetPath(c.asset.url, opts.modulePath));
+	} catch {
+		paths.add(c.asset.url);
+	}
+	return [...paths].sort();
+}
+/**
 * 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).
+*
+* The mixHash folds the BYTES of the actual mix audio inputs (timeline clips +
+* narration/music/sfx) — not just the timing manifests — so an in-place edit of a
+* `.wav`/music stem invalidates the measurement here too (the §5.3 stale-gain
+* gate). `timelineClips` defaults to the scene's compiled timeline audio when
+* omitted, so a bare `{ modulePath }` call still gates correctly.
 */
-async function resolveLoudnessGainDb(opts) {
+async function resolveLoudnessGainDb(opts, timelineClips) {
 	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);
+	const extraInputs = await collectMixAudioInputs(opts, timelineClips);
+	const actual = computeMixHash(opts.modulePath, extraInputs);
 	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;
 }
@@ -354,6 +406,9 @@ async function resolveLoudnessGainDb(opts) {
 * 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.
+*
+* (Note: `collectMixAudioInputs` resolves auto-mixed narration/music/sfx siblings
+* from `modulePath`, so a `timelineClips: []` default still gates those.)
 */
 async function planFinalAudio(opts, timelineClips, duration, container) {
 	const audioClips = await collectAudioClips(opts, timelineClips);
@@ -365,7 +420,7 @@ async function planFinalAudio(opts, timelineClips, duration, container) {
 		audioInputs: [],
 		audioArgs: []
 	};
-	const gainDb = await resolveLoudnessGainDb(opts);
+	const gainDb = await resolveLoudnessGainDb(opts, timelineClips);
 	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);

package/dist/verifyDeterminism.js

@@ -131,9 +131,13 @@ 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;
+	let absent = 0;
 	for (const ea of a.frames) {
 		const eb = byFrameB.get(ea.frame);
-		if (!eb) continue;
+		if (!eb) {
+			absent++;
+			continue;
+		}
 		compared++;
 		if (ea.hash === eb.hash) continue;
 		const groups = new Set(a.groups);
@@ -162,6 +166,16 @@ function compareManifests(a, b) {
 			}
 		};
 	}
+	if (compared === 0) return {
+		ok: false,
+		compared,
+		reason: `0 frames compared (baseline/render range disjoint): the baseline has ${a.frames.length} frame(s), none present in the render set of ${b.frames.length}`
+	};
+	if (absent > 0) return {
+		ok: true,
+		compared,
+		reason: `warning: ${absent} baseline frame(s) absent from the render set were not compared (compared ${compared})`
+	};
 	return {
 		ok: true,
 		compared
@@ -276,10 +290,18 @@ async function verifyDeterminismCommand(opts) {
 }
 /** 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,
+	if (cmp.ok) {
+		const tail = cmp.reason !== void 0 ? `\n  ${cmp.reason}` : "";
+		return {
+			ok: true,
+			frames: cmp.compared,
+			report: `byte-identical: ${cmp.compared} frames match (${label})${tail}`
+		};
+	}
+	if (cmp.divergence === void 0) return {
+		ok: false,
 		frames: cmp.compared,
-		report: `byte-identical: ${cmp.compared} frames match (${label})`
+		report: `VERIFY FAILED (${label})\n  ${cmp.reason ?? "0 frames compared"}`
 	};
 	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)");

package/package.json

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