@glissade/cli 0.42.0-pre.0 → 0.42.0

package/dist/cli.js

@@ -92,7 +92,7 @@ const USAGE = `usage:
   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 localize <scene-module> --to <locale> [--from <locale>] [--write] [--keep-voice] [--json]   fork a narration into a new locale (clone segment/pause structure, PRESERVING beat ids so .start() anchors survive) + stub messages.<locale>.json from the scene's t() ids, running the render path's parity + localize checks BEFORE any TTS. Default dry-run (exits non-zero on drift); --write emits <base>.<locale>.narration.json + messages.<locale>.json
+  gs localize <scene-module> --to <locale> [--from <locale>] [--write] [--strict] [--keep-voice] [--json]   fork a narration into a new locale (clone segment/pause structure, PRESERVING beat ids so .start() anchors survive) + stub messages.<locale>.json from the scene's t() ids, running the render path's parity + localize checks BEFORE any TTS. Default dry-run (exits non-zero on drift); --write emits <base>.<locale>.narration.json + messages.<locale>.json (re-localize CARRIES existing translations over — never clobbers); --strict refuses to write on a preflight failure
   gs --version   print the engine version
 
 render options:
@@ -367,10 +367,11 @@ async function main() {
 				to,
 				...lf.get("from") ? { from: lf.get("from") } : {},
 				...lf.has("write") ? { write: true } : {},
-				...lf.has("keep-voice") ? { keepVoice: true } : {}
+				...lf.has("keep-voice") ? { keepVoice: true } : {},
+				...lf.has("strict") ? { strict: true } : {}
 			});
 			process.stdout.write(lf.has("json") ? `${JSON.stringify(report, null, 2)}\n` : `${formatLocalizeReport(report)}\n`);
-			if (!lf.has("write") && report.preflight.issues.length > 0) process.exit(1);
+			if (report.preflight.issues.length > 0 && (!lf.has("write") || lf.has("strict"))) process.exit(1);
 		} catch (err) {
 			fail(err instanceof Error ? err.message : String(err));
 		}

package/dist/localize.js

@@ -32,10 +32,17 @@ var LocalizeError = class extends Error {
 * `keepVoice` is set.
 */
 function forkNarrationScript(base, opts = {}) {
+	const existingText = /* @__PURE__ */ new Map();
+	for (const el of opts.existing?.segments ?? []) if (!isPause(el) && el.text !== "") existingText.set(el.id, el.text);
 	const segments = base.segments.map((el) => {
 		if (isPause(el)) return { ...el };
-		if (opts.keepVoice) return { ...el };
-		const { voice: _voice, ...rest } = el;
+		const carried = existingText.get(el.id);
+		const withText = carried !== void 0 && carried !== el.text ? {
+			...el,
+			text: carried
+		} : { ...el };
+		if (opts.keepVoice) return withText;
+		const { voice: _voice, ...rest } = withText;
 		return rest;
 	});
 	const forked = {
@@ -155,7 +162,11 @@ async function harvestMessageIds(modulePath) {
 	const tIds = new Set(getConsumedMessageIds());
 	const ids = new Set(tIds);
 	const doc = mod.timeline;
-	for (const tr of doc.tracks ?? []) if (tr.type === "string") ids.add(nodeIdOf(tr.target));
+	for (const tr of doc.tracks ?? []) {
+		if (tr.type !== "string") continue;
+		if (new Set((tr.keys ?? []).map((k) => k.value)).size > 1) continue;
+		ids.add(nodeIdOf(tr.target));
+	}
 	return {
 		ids: [...ids],
 		tIds,
@@ -187,11 +198,15 @@ async function localizeCommand(modulePath, opts) {
 		baseScript = scriptFromTiming(JSON.parse(readFileSync(baseTimingPath, "utf8")));
 		narrationSource = "timing";
 	}
-	const forked = baseScript ? forkNarrationScript(baseScript, { keepVoice: opts.keepVoice ?? false }) : void 0;
-	const beatIds = baseScript ? scriptBeatIds(baseScript) : [];
 	const narrationPath = moduleStemOf(modulePath) + `.${to}.narration.json`;
-	let localeBeatIds = beatIds;
-	if (existsSync(narrationPath)) localeBeatIds = scriptBeatIds(JSON.parse(readFileSync(narrationPath, "utf8")));
+	const existingLocale = baseScript && existsSync(narrationPath) ? JSON.parse(readFileSync(narrationPath, "utf8")) : void 0;
+	const forked = baseScript ? forkNarrationScript(baseScript, {
+		keepVoice: opts.keepVoice ?? false,
+		...existingLocale ? { existing: existingLocale } : {}
+	}) : void 0;
+	const beatIds = baseScript ? scriptBeatIds(baseScript) : [];
+	const localeBeatIds = existingLocale ? scriptBeatIds(existingLocale) : beatIds;
+	const carriedSegments = baseScript && forked ? forked.segments.filter((el, i) => !isPause(el) && el.text !== baseScript.segments[i].text).length : 0;
 	const base = opts.from ? loadMessageTable(modulePath, opts.from) : void 0;
 	const messagesPath = messagesFileFor(modulePath, to);
 	const existingTable = existsSync(messagesPath) ? JSON.parse(readFileSync(messagesPath, "utf8")) : loadMessageTable(modulePath, to);
@@ -214,20 +229,25 @@ async function localizeCommand(modulePath, opts) {
 		consumedIds: tIds
 	});
 	const wrote = [];
-	if (opts.write) {
+	const refusedWrite = !!(opts.write && opts.strict && !preflight.ok);
+	if (opts.write && !refusedWrite) {
 		if (forked) {
 			writeFileSync(narrationPath, JSON.stringify(forked, null, 2) + "\n");
 			wrote.push(narrationPath);
 		}
-		writeFileSync(messagesPath, JSON.stringify(stubTable, null, 2) + "\n");
-		wrote.push(messagesPath);
+		if (messageIds.length > 0) {
+			writeFileSync(messagesPath, JSON.stringify(stubTable, null, 2) + "\n");
+			wrote.push(messagesPath);
+		}
 	}
 	return {
 		locale: to,
 		messageIds: messageIds.sort(),
 		beatIds,
+		carriedSegments,
 		preflight,
 		wrote,
+		refusedWrite,
 		narrationPath,
 		messagesPath,
 		narrationSource
@@ -237,15 +257,16 @@ async function localizeCommand(modulePath, opts) {
 function formatLocalizeReport(r) {
 	const lines = [];
 	lines.push(`gs localize → ${r.locale}`);
-	lines.push(`  narration: ${r.narrationSource === "none" ? "none found" : `${r.beatIds.length} beat(s) from the ${r.narrationSource} (ids preserved)`}`);
-	lines.push(`  messages:  ${r.messageIds.length} id(s) harvested, ${r.preflight.untranslated} still untranslated`);
+	lines.push(`  narration: ${r.narrationSource === "none" ? "none found" : `${r.beatIds.length} beat(s) from the ${r.narrationSource} (ids preserved)`}` + (r.carriedSegments > 0 ? `; ${r.carriedSegments} translation(s) carried over` : ""));
+	lines.push(r.messageIds.length === 0 ? "  messages:  none localizable (no t() ids / no single-cue string tracks) — narration only" : `  messages:  ${r.messageIds.length} id(s) harvested, ${r.preflight.untranslated} still untranslated`);
 	if (r.preflight.issues.length === 0) lines.push("  preflight: ✓ parity + localize clean (safe to translate + narrate)");
 	else {
 		lines.push(`  preflight: ✗ ${r.preflight.issues.length} issue(s) — fix before narrating:`);
 		for (const i of r.preflight.issues) lines.push(`    [${i.kind}] ${i.message.replace(/\n/g, "\n      ")}`);
 	}
-	if (r.wrote.length) lines.push(`  wrote: ${r.wrote.join(", ")}`);
-	else lines.push(`  (dry run — re-run with --write to emit ${r.narrationPath} + ${r.messagesPath})`);
+	if (r.refusedWrite) lines.push("  --strict: refused to write (preflight failed); fix the drift above, then re-run");
+	else if (r.wrote.length) lines.push(`  wrote: ${r.wrote.join(", ")}`);
+	else lines.push(`  (dry run — re-run with --write to emit ${r.narrationPath}${r.messageIds.length ? ` + ${r.messagesPath}` : ""})`);
 	return lines.join("\n");
 }
 //#endregion

package/package.json

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