@glissade/cli 0.36.0 → 0.37.0-pre.1

package/README.md

@@ -2,7 +2,7 @@
 
 `gs` — headless rendering and the dev/capture loop. `gs render` evaluates every frame, rasterizes on Skia (no browser anywhere), writes a PNG sequence or muxes mp4/webm via FFmpeg with sample-accurate audio. v2: `gs dev --record` serves a scene with its state machines mounted and writes input-trace sidecars; `gs render --trace/--state` are the deterministic export routes for interactive scenes.
 
-The full command set: `render`, `dev`, `import` (Lottie `.json` / `.svg`), `build`, `mcp` (an MCP server over the engine), `describe`, `migrate`, `narrate`, `sfx`, `prepare`, `measure-loudness`, `fonts`, `cache`, `diff`, and `verify-determinism`.
+The full command set: `render`, `dev`, `import` (Lottie `.json` / `.svg`), `build`, `mcp` (an MCP server over the engine), `describe`, `migrate`, `repin` (narration-aware golden reviewer), `narrate`, `sfx`, `prepare`, `measure-loudness`, `fonts`, `cache`, `diff`, and `verify-determinism`. Run `gs` with no arguments for the full usage.
 
 ```sh
 npm i -D @glissade/cli
@@ -14,6 +14,25 @@ gs dev scene.ts --record        # capture a take
 gs render scene.ts --trace scene.button.take1.trace.json --out take.mp4
 ```
 
+## Reviewing goldens (`gs repin`)
+
+When a re-narration re-flows a project's beats, every downstream golden goes
+stale at once. `gs repin` renders the current scene vs the committed golden PNGs
+and, per changed frame, reports a perceptual SSIM delta (mean + worst tile) plus a
+one-line **cause** — it diffs the `*.narration.timing.json` sibling against a git
+ref to attribute the edit site and trace the pushed beats back to it. Default is a
+dry run; `--write` re-pins, and `--floor <ssim>` refuses a bigger-than-expected
+drop until `--force` — the confidence gate before you bless a batch re-pin.
+
+```sh
+gs repin scene.ts --golden test/golden                       # dry-run: what changed & why
+gs repin scene.ts --golden test/golden --write --floor 0.98  # re-pin, guarded
+```
+
+The SSIM machinery is also exported from `@glissade/backend-skia`
+(`ssim` / `ssimMap` / `heatmapRgba`) for your own golden tooling. Full guide:
+[Reviewing goldens](https://github.com/tyevco/glissade/blob/main/docs/golden-review.md).
+
 ## Part of glissade
 
 *(glide & slide)* — programmatic motion graphics for TypeScript: realtime-first in any web page, deterministic headless video export from the same code, a visual studio over the same document. No generator functions.

package/dist/captions.js

@@ -78,4 +78,4 @@ function writeCaptionSidecars(timingPath, outPath) {
 	};
 }
 //#endregion
-export { parseCaptionsMode as n, captions_exports as t };
+export { parseCaptionsMode as n, timingPathFor as r, captions_exports as t };

package/dist/cli.js

@@ -87,6 +87,7 @@ const USAGE = `usage:
   gs build [filter...] [--config <glissade.config.ts>] [--explain]   content-graph DAG runner: narrate→sfx→loudness→render per scene, runs ONLY the stale subtree
   gs describe [--out <api.json>] [--examples]   snapshot THIS engine's describe() API manifest (stdout, or --out to a file) — the input to gs migrate
   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 --version   print the engine version
 
 render options:
@@ -183,7 +184,7 @@ async function main() {
 		process.stdout.write(`${describe().version}\n`);
 		return;
 	}
-	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" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate") {
+	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" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate" && command !== "repin") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -289,6 +290,45 @@ async function main() {
 		if (mf.has("check") && report.summary.breaking > 0) process.exit(1);
 		return;
 	}
+	if (command === "repin") {
+		const { positional: rp, flags: rf } = parseArgs(rest);
+		const sceneModule = rp[0];
+		if (!sceneModule) fail(`gs repin needs <scene-module>\n${USAGE}`);
+		const goldenDir = rf.get("golden");
+		if (!goldenDir) fail(`gs repin needs --golden <dir> (the committed golden PNG directory)\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(`repin: '${s}' is not a frame number (expected comma-separated non-negative integers)`);
+			return n;
+		});
+		const floorRaw = rf.get("floor");
+		let floor;
+		if (floorRaw !== void 0) {
+			floor = Number(floorRaw);
+			if (!(floor >= -1 && floor <= 1)) fail(`repin: --floor must be an SSIM in [-1, 1], got '${floorRaw}'`);
+		}
+		const { repinCommand } = await import("./repin.js").then((n) => n.i);
+		try {
+			const result = await repinCommand({
+				modulePath: sceneModule,
+				goldenDir,
+				...rf.get("name") ? { name: rf.get("name") } : {},
+				...nums(rf.get("frames")) ? { frames: nums(rf.get("frames")) } : {},
+				...rf.get("fps") ? { fps: parseFpsOrFail(rf.get("fps")) } : {},
+				...rf.get("since") ? { since: rf.get("since") } : {},
+				...rf.has("write") ? { write: true } : {},
+				...nums(rf.get("only")) ? { only: nums(rf.get("only")) } : {},
+				...rf.get("heatmap") ? { heatmapDir: rf.get("heatmap") } : {},
+				...floor !== void 0 ? { floor } : {},
+				...rf.has("force") ? { force: true } : {}
+			});
+			process.stdout.write(`${result.report}\n`);
+			if (result.blocked > 0 || !rf.has("write") && result.changed > 0) 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}`);

package/dist/index.d.ts

@@ -742,6 +742,62 @@ declare function diffCommand(opts: DiffOptions): Promise<DiffResult>;
 /** Snapshot a scene's DisplayList at `t` to a `.dl.json` string (the baseline writer). */
 declare function snapshotAt(modulePath: string, t: number): Promise<string>;
 //#endregion
+//#region src/repin.d.ts
+/** The default golden frame set + fps — matches the Skia golden harness. */
+declare const DEFAULT_FRAMES: number[];
+declare const DEFAULT_FPS = 60;
+interface RepinOptions {
+  modulePath: string;
+  /** directory holding the committed golden PNGs. */
+  goldenDir: string;
+  /** golden filename prefix (`<name>-f0030.png`); default = the module basename. */
+  name?: string;
+  /** frame numbers to review; default DEFAULT_FRAMES. */
+  frames?: number[];
+  /** frames-per-second for `t = frame / fps`; default 60. */
+  fps?: number;
+  /** git ref to diff the narration timing sibling against for the cause line; default 'HEAD'. */
+  since?: string;
+  /** actually overwrite changed/new goldens (default: dry-run report). */
+  write?: boolean;
+  /** when writing, restrict to these frames (per-frame confirm). */
+  only?: number[];
+  /** write per-frame SSIM heat-map PNGs here for visual review. */
+  heatmapDir?: string;
+  /** refuse to write a frame whose mean SSIM fell below this (unless force). */
+  floor?: number;
+  /** override the floor guard. */
+  force?: boolean;
+}
+type RepinStatus = 'identical' | 'changed' | 'new' | 'missing';
+interface RepinFrame {
+  frame: number;
+  t: number;
+  status: RepinStatus;
+  /** mean SSIM vs the golden (changed frames only). */
+  ssim?: number;
+  /** worst-tile SSIM (changed frames only). */
+  minSsim?: number;
+  /** the narration cause line, when a timing shift explains the change. */
+  cause?: string;
+  /** true when this frame's golden PNG was (re)written. */
+  wrote: boolean;
+  /** true when a write was refused because the drop fell below --floor. */
+  blocked?: boolean;
+  /** path of the heat-map PNG, when --heatmap was given. */
+  heatmap?: string;
+}
+interface RepinResult {
+  frames: RepinFrame[];
+  changed: number;
+  wrote: number;
+  blocked: number;
+  /** true when the timing sibling was resolved AND diffed against `since`. */
+  causeSource: string | null;
+  report: string;
+}
+declare function repinCommand(opts: RepinOptions): Promise<RepinResult>;
+//#endregion
 //#region src/narrationLint.d.ts
 type LintRule = 'reading-speed' | 'anchor-budget' | 'caption-fit' | 'beat-drift' | 'silence';
 interface Diagnostic {
@@ -905,4 +961,4 @@ declare function cacheVerifyCommand(opts: CacheVerifyOptions): Promise<CacheVeri
 /** The @glissade/cli package version (the glissade VERSION for the cache key). */
 declare function glissadeVersion(): string;
 //#endregion
-export { AudioMixError, type AudioMixPlan, type CacheKeyContext, type CacheMode, type CacheVerifyOptions, type CacheVerifyResult, type CaptionProbe, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, type DevOptions, type DevServer, type Diagnostic, type DiffOptions, type DiffResult, type EncoderChoice, FfmpegVideoFrameSource, FrameCache, FrameCacheError, type FrameCacheOptions, type ImportCommandResult, type ImportOptions, LOUDNESS_SCHEMA_VERSION, type LintOptions, type LintRule, LocaleArgsError, LoudnessError, type LoudnessMeasurement, MachineExportError, type MachineRenderFlags, type MeasureLoudnessOptions, type MeasureLoudnessResult, type NarrationLintOptions, type NarrationLintResult, NoEncoderError, PUBLISH_PROFILES, type PublishProfile, type RenderOptions, type RenderShardedArgs, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };
+export { AudioMixError, type AudioMixPlan, type CacheKeyContext, type CacheMode, type CacheVerifyOptions, type CacheVerifyResult, type CaptionProbe, DEFAULT_CACHE_MAX_SIZE, DEFAULT_FPS, DEFAULT_FRAMES, DEFAULT_PROFILE_ID, type DevOptions, type DevServer, type Diagnostic, type DiffOptions, type DiffResult, type EncoderChoice, FfmpegVideoFrameSource, FrameCache, FrameCacheError, type FrameCacheOptions, type ImportCommandResult, type ImportOptions, LOUDNESS_SCHEMA_VERSION, type LintOptions, type LintRule, LocaleArgsError, LoudnessError, type LoudnessMeasurement, MachineExportError, type MachineRenderFlags, type MeasureLoudnessOptions, type MeasureLoudnessResult, type NarrationLintOptions, type NarrationLintResult, NoEncoderError, PUBLISH_PROFILES, type PublishProfile, type RenderOptions, type RenderShardedArgs, type RepinFrame, type RepinOptions, type RepinResult, type RepinStatus, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, repinCommand, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };

package/dist/index.js

@@ -9,7 +9,8 @@ import { r as resolveRenderDoc, t as MachineExportError } from "./machines.js";
 import { t as dev } from "./dev.js";
 import { t as importCommand } from "./import.js";
 import { i as snapshotAt, r as evaluateAt, t as diffCommand } from "./diff.js";
+import { n as DEFAULT_FRAMES, r as repinCommand, t as DEFAULT_FPS } from "./repin.js";
 import { a as fixDiff, c as lintNarration, n as lintTimingPathFor, o as formatTable, r as narrationLintCommand, s as hasErrors, t as buildCaptionProbe } from "./narrationLintCommand.js";
 import { a as clearFrameCache, c as parseCacheMaxSize, i as capsId, l as probeEntryHeader, n as FrameCache, o as frameCacheKey, r as FrameCacheError, t as DEFAULT_CACHE_MAX_SIZE } from "./frameCache.js";
 import { t as cacheVerifyCommand } from "./cacheVerify.js";
-export { AudioMixError, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, FfmpegVideoFrameSource, FrameCache, FrameCacheError, LOUDNESS_SCHEMA_VERSION, LocaleArgsError, LoudnessError, MachineExportError, NoEncoderError, PUBLISH_PROFILES, SceneModuleError, ShardError, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };
+export { AudioMixError, DEFAULT_CACHE_MAX_SIZE, DEFAULT_FPS, DEFAULT_FRAMES, DEFAULT_PROFILE_ID, FfmpegVideoFrameSource, FrameCache, FrameCacheError, LOUDNESS_SCHEMA_VERSION, LocaleArgsError, LoudnessError, MachineExportError, NoEncoderError, PUBLISH_PROFILES, SceneModuleError, ShardError, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, repinCommand, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };

package/dist/repin.js

@@ -0,0 +1,273 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { o as loadSceneModule } from "./render.js";
+import { r as timingPathFor } from "./captions.js";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { evaluate } from "@glissade/scene";
+import { SkiaBackend, heatmapRgba, ssimMap } from "@glissade/backend-skia";
+import { createCanvas, loadImage } from "@napi-rs/canvas";
+//#region src/repin.ts
+/**
+* `gs repin` (0.37) — the narration-aware golden reviewer.
+*
+* The lived pain: one re-narration re-flows every beat, so all of a project's
+* goldens go stale at once and you re-pin them blind with `vitest -u`. `gs repin`
+* renders the CURRENT scene frame-by-frame against the committed golden PNGs and,
+* for every frame that changed, reports:
+*
+*   • a perceptual delta (mean SSIM + the worst 8×8 tile — WHERE it changed), and
+*   • a one-line CAUSE, by diffing the scene's `*.narration.timing.json` sibling
+*     against a git ref (default HEAD): "seg-4 moved +0.21s: re-narration".
+*
+* Then it re-pins only the frames you allow. Default is a DRY RUN (report only);
+* `--write` overwrites the changed goldens. A `--floor <ssim>` guard REFUSES to
+* write any frame whose perceptual drop is bigger than you'd expect from a
+* re-narration (an actual regression sneaking into a re-pin) unless `--force`.
+*
+* Byte-equality stays the golden contract (same as the harness): a frame is
+* "identical" only when the PNG bytes match; SSIM is used solely to EXPLAIN and
+* to GATE a divergence, never to accept one silently.
+*/
+var repin_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_FPS: () => 60,
+	DEFAULT_FRAMES: () => DEFAULT_FRAMES,
+	causeFor: () => causeFor,
+	diffTiming: () => diffTiming,
+	repinCommand: () => repinCommand
+});
+/** The default golden frame set + fps — matches the Skia golden harness. */
+const DEFAULT_FRAMES = [
+	0,
+	30,
+	60,
+	90,
+	120,
+	150,
+	179
+];
+const DEFAULT_FPS = 60;
+/** Read `<ref>:<path>` from git as text; null when not a repo / not tracked. */
+function gitShow(ref, absPath) {
+	try {
+		const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd: dirname(absPath),
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).toString().trim();
+		return execFileSync("git", ["show", `${ref}:${relative(root, absPath)}`], {
+			cwd: root,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).toString("utf8");
+	} catch {
+		return null;
+	}
+}
+/** Segment-by-id delta between two narration timings (older `a` → current `b`). */
+function diffTiming(a, b) {
+	const old = new Map(a.segments.map((s) => [s.id, s]));
+	const shifts = [];
+	for (const s of b.segments) {
+		const prev = old.get(s.id);
+		shifts.push({
+			id: s.id,
+			start: s.start,
+			deltaStart: prev ? s.start - prev.start : 0,
+			deltaDuration: prev ? s.duration - prev.duration : 0,
+			added: !prev,
+			removed: false
+		});
+		old.delete(s.id);
+	}
+	for (const [id, s] of old) shifts.push({
+		id,
+		start: s.start,
+		deltaStart: 0,
+		deltaDuration: 0,
+		added: false,
+		removed: true
+	});
+	return shifts.sort((x, y) => x.start - y.start);
+}
+const EPS = 1e-4;
+const sign = (n) => `${n >= 0 ? "+" : ""}${n.toFixed(2)}s`;
+/** Is this shift a re-narration ROOT — a segment whose own content changed
+*  (duration moved) or that was newly added, i.e. an EDIT SITE that pushes
+*  everything downstream of it? */
+function isRoot(s) {
+	return s.added || Math.abs(s.deltaDuration) > EPS;
+}
+/**
+* One-line cause for a frame at time `t`. A re-narration that re-records one line
+* changes that segment's DURATION (not its start) and pushes every later segment's
+* start by the same amount — so attribution has two jobs:
+*   • name the EDIT SITE by its duration change (its start doesn't move), and
+*   • trace a purely-shifted downstream beat back to the ROOT that pushed it,
+*     rather than letting it claim its own (derived) shift.
+*/
+function causeFor(t, shifts) {
+	const before = shifts.filter((s) => s.start <= t + EPS && !s.removed);
+	const active = before[before.length - 1];
+	if (!active) return void 0;
+	if (active.added) return `${active.id}: new segment`;
+	if (Math.abs(active.deltaDuration) > EPS) return `${active.id} re-narrated (${sign(active.deltaDuration)} duration): re-narration`;
+	const root = before.slice(0, -1).reverse().find(isRoot);
+	if (Math.abs(active.deltaStart) > EPS) {
+		if (root) return `downstream of ${root.id} (${sign(active.deltaStart)}): re-narration`;
+		return `${active.id} moved ${sign(active.deltaStart)}: re-narration`;
+	}
+	if (root) return `downstream of ${root.id} (${sign(root.deltaDuration)}): re-narration`;
+}
+async function decodePng(buf) {
+	const img = await loadImage(buf);
+	const w = img.width;
+	const h = img.height;
+	const ctx = createCanvas(w, h).getContext("2d");
+	ctx.drawImage(img, 0, 0);
+	return {
+		rgba: ctx.getImageData(0, 0, w, h).data,
+		w,
+		h
+	};
+}
+function goldenPathFor(dir, name, frame) {
+	return join(dir, `${name}-f${String(frame).padStart(4, "0")}.png`);
+}
+async function repinCommand(opts) {
+	const fps = opts.fps ?? 60;
+	const frames = opts.frames ?? DEFAULT_FRAMES;
+	const name = opts.name ?? basename(opts.modulePath).replace(/\.[jt]sx?$/, "");
+	const onlySet = opts.only ? new Set(opts.only) : null;
+	const mod = await loadSceneModule(opts.modulePath);
+	let shifts = [];
+	let causeSource = null;
+	const timingPath = timingPathFor(opts.modulePath);
+	if (timingPath) {
+		const older = gitShow(opts.since ?? "HEAD", resolve(timingPath));
+		if (older) try {
+			shifts = diffTiming(JSON.parse(older), JSON.parse(readFileSync(timingPath, "utf8")));
+			causeSource = timingPath;
+		} catch {}
+	}
+	if (opts.heatmapDir && !existsSync(opts.heatmapDir)) mkdirSync(opts.heatmapDir, { recursive: true });
+	const results = [];
+	for (const frame of frames) {
+		const t = frame / fps;
+		const scene = mod.createScene();
+		const backend = new SkiaBackend(scene.size.w, scene.size.h);
+		scene.setTextMeasurer(backend);
+		backend.render(evaluate(scene, mod.timeline, t));
+		const curPng = backend.encodePng();
+		const curRgba = await backend.readPixels();
+		const goldenPath = goldenPathFor(opts.goldenDir, name, frame);
+		const canWrite = opts.write === true && (!onlySet || onlySet.has(frame));
+		if (!existsSync(goldenPath)) {
+			let wrote = false;
+			if (canWrite) {
+				mkdirSync(dirname(goldenPath), { recursive: true });
+				writeFileSync(goldenPath, curPng);
+				wrote = true;
+			}
+			results.push({
+				frame,
+				t,
+				status: "new",
+				wrote
+			});
+			continue;
+		}
+		const goldPng = readFileSync(goldenPath);
+		if (curPng.equals(goldPng)) {
+			results.push({
+				frame,
+				t,
+				status: "identical",
+				wrote: false
+			});
+			continue;
+		}
+		const rec = {
+			frame,
+			t,
+			status: "changed",
+			wrote: false
+		};
+		const { rgba: goldRgba, w, h } = await decodePng(goldPng);
+		if (w === scene.size.w && h === scene.size.h) {
+			const map = ssimMap(goldRgba, curRgba, w, h);
+			rec.ssim = map.mean;
+			rec.minSsim = map.min;
+			if (opts.heatmapDir) {
+				const hb = new SkiaBackend(w, h);
+				hb.putPixels(heatmapRgba(map, w, h));
+				const hp = join(opts.heatmapDir, `${name}-f${String(frame).padStart(4, "0")}.heat.png`);
+				writeFileSync(hp, hb.encodePng());
+				rec.heatmap = hp;
+			}
+		}
+		const cause = causeFor(t, shifts);
+		if (cause) rec.cause = cause;
+		const belowFloor = opts.floor !== void 0 && rec.ssim !== void 0 && rec.ssim < opts.floor;
+		if (canWrite) if (belowFloor && !opts.force) rec.blocked = true;
+		else {
+			writeFileSync(goldenPath, curPng);
+			rec.wrote = true;
+		}
+		results.push(rec);
+	}
+	const changed = results.filter((r) => r.status === "changed" || r.status === "new").length;
+	const wrote = results.filter((r) => r.wrote).length;
+	const blocked = results.filter((r) => r.blocked).length;
+	return {
+		frames: results,
+		changed,
+		wrote,
+		blocked,
+		causeSource,
+		report: formatReport(name, opts, {
+			frames: results,
+			changed,
+			wrote,
+			blocked,
+			causeSource
+		})
+	};
+}
+function formatReport(name, opts, r) {
+	const lines = [];
+	const mode = opts.write ? opts.only ? "write (--only)" : "write" : "dry-run";
+	lines.push(`gs repin '${name}' — ${r.frames.length} frames, ${r.changed} changed [${mode}]`);
+	if (r.causeSource) lines.push(`  cause ← ${r.causeSource} vs ${opts.since ?? "HEAD"}`);
+	else lines.push(`  (no narration timing sibling diffed — perceptual delta only)`);
+	let worstFrame = -1;
+	let worstSsim = Infinity;
+	for (const f of r.frames) if (f.status === "changed" && f.ssim !== void 0 && f.ssim < worstSsim) {
+		worstSsim = f.ssim;
+		worstFrame = f.frame;
+	}
+	const marked = r.changed > 1 && worstFrame >= 0;
+	for (const f of r.frames) {
+		if (f.status === "identical") continue;
+		const fno = `f${String(f.frame).padStart(4, "0")}`;
+		if (f.status === "new") {
+			lines.push(`  ${fno}  NEW        ${f.wrote ? "→ written" : "(dry-run)"}`);
+			continue;
+		}
+		const perc = f.ssim !== void 0 ? `ssim ${f.ssim.toFixed(4)} (min ${f.minSsim.toFixed(3)})` : `dimensions changed`;
+		const tail = f.blocked ? "⚠ BELOW FLOOR — refused (use --force)" : f.wrote ? "→ re-pinned" : "(dry-run)";
+		const editMark = marked && f.frame === worstFrame ? "◀ likely edit-site (lowest SSIM)  " : "";
+		lines.push(`  ${fno}  ${perc}  ${f.cause ? `— ${f.cause}  ` : ""}${editMark}${tail}`);
+	}
+	if (!opts.write && r.changed > 0) lines.push(`  ${r.changed} stale — re-run with --write to re-pin${opts.floor !== void 0 ? ` (floor ${opts.floor})` : ""}`);
+	if (r.blocked > 0) lines.push(`  ${r.blocked} refused below floor — inspect the heat-map, then --force if intended`);
+	return lines.join("\n");
+}
+//#endregion
+export { repin_exports as i, DEFAULT_FRAMES as n, repinCommand as r, DEFAULT_FPS as t };

package/package.json

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