@glissade/cli 0.37.0-pre.0 → 0.37.0

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/repin.js

@@ -80,6 +80,7 @@ function diffTiming(a, b) {
 			id: s.id,
 			start: s.start,
 			deltaStart: prev ? s.start - prev.start : 0,
+			deltaDuration: prev ? s.duration - prev.duration : 0,
 			added: !prev,
 			removed: false
 		});
@@ -89,6 +90,7 @@ function diffTiming(a, b) {
 		id,
 		start: s.start,
 		deltaStart: 0,
+		deltaDuration: 0,
 		added: false,
 		removed: true
 	});
@@ -96,14 +98,32 @@ function diffTiming(a, b) {
 }
 const EPS = 1e-4;
 const sign = (n) => `${n >= 0 ? "+" : ""}${n.toFixed(2)}s`;
-/** One-line cause for a frame at time `t`, from the timing shifts. */
+/** 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 && active.added) return `${active.id}: new segment`;
-	if (active && Math.abs(active.deltaStart) > EPS) return `${active.id} moved ${sign(active.deltaStart)}: re-narration`;
-	const upstream = before.filter((s) => Math.abs(s.deltaStart) > EPS).pop();
-	if (upstream) return `downstream of ${upstream.id} (${sign(upstream.deltaStart)}): re-narration`;
+	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);
@@ -226,6 +246,13 @@ function formatReport(name, opts, r) {
 	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")}`;
@@ -235,7 +262,8 @@ function formatReport(name, opts, r) {
 		}
 		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)";
-		lines.push(`  ${fno}  ${perc}  ${f.cause ? `— ${f.cause}  ` : ""}${tail}`);
+		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`);

package/package.json

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