@glissade/cli 0.41.1 → 0.42.0-pre.1

package/dist/cli.js

@@ -22,7 +22,9 @@ const KNOWN_BOOLEAN_FLAGS = new Set([
 	"verbose",
 	"allow-degraded",
 	"bisect",
-	"watch"
+	"watch",
+	"write",
+	"keep-voice"
 ]);
 function parseArgs(argv) {
 	const positional = [];
@@ -90,6 +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] [--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:
@@ -191,7 +194,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" && command !== "repin" && command !== "master") {
+	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" && command !== "master" && command !== "localize") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -352,6 +355,28 @@ async function main() {
 		}
 		return;
 	}
+	if (command === "localize") {
+		const { positional: lp, flags: lf } = parseArgs(rest);
+		const sceneModule = lp[0];
+		if (!sceneModule) fail(`gs localize needs <scene-module>\n${USAGE}`);
+		const to = lf.get("to");
+		if (!to) fail(`gs localize needs --to <locale> (e.g. --to zh)\n${USAGE}`);
+		const { localizeCommand, formatLocalizeReport } = await import("./localize.js");
+		try {
+			const report = await localizeCommand(sceneModule, {
+				to,
+				...lf.get("from") ? { from: lf.get("from") } : {},
+				...lf.has("write") ? { write: 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 (report.preflight.issues.length > 0 && (!lf.has("write") || lf.has("strict"))) 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

@@ -2,6 +2,7 @@ import { AudioClip, CompiledTimeline, Key, Timeline } from "@glissade/core";
 import { DisplayList, Scene, SceneModule, VideoFrameSource } from "@glissade/scene";
 import { NarrationTiming } from "@glissade/narrate";
 import { Image } from "@napi-rs/canvas";
+import * as _glissade_core_i18n0 from "@glissade/core/i18n";
 
 //#region src/frameCache.d.ts
 
@@ -497,7 +498,7 @@ declare class SceneModuleError extends Error {
  * ranges are rejected, since a frame index is an integer.
  */
 
-declare function loadSceneModule(modulePath: string, locale?: string): Promise<SceneModule>;
+declare function loadSceneModule(modulePath: string, locale?: string, messageTableOverride?: _glissade_core_i18n0.MessageTable): Promise<SceneModule>;
 declare function ffmpegAvailable(): boolean;
 declare function render(opts: RenderOptions): Promise<{
   frames: number;

package/dist/localize.js

@@ -0,0 +1,273 @@
+import { isPause } from "@glissade/narrate";
+import { LocalizationError, ParityError, localize, requireParity } from "@glissade/core/i18n";
+//#region src/localize.ts
+/**
+* `gs localize` (0.42) — the fork/translate/parity orchestrator. Forking a
+* narration into a new locale by hand is where drift creeps in: you clone the
+* script, re-author the timing, hand-write `messages.<locale>.json`, and only
+* discover a missing beat id or an orphaned message when something THROWS deep in
+* a render — after a minute of TTS. `gs localize <base> --to <locale>` does the
+* mechanical fork up front and runs the SAME parity + localize checks the render
+* path runs, BEFORE any synthesis: it clones the segment/pause structure keeping
+* every beat id (so `.start('seg-x')` anchors survive), stubs a translatable
+* `messages.<locale>.json` from the scene's `t()` ids, and reports every drift.
+*
+* This module is the PURE engine (fork + stub + preflight report). The CLI
+* command (file IO, harvesting `t()` ids by loading the scene, `--write`) wraps it.
+* Nothing here synthesizes audio, touches the render path, or calls `evaluate()`.
+*/
+var LocalizeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LocalizeError";
+	}
+};
+/**
+* Fork an authored narration script for a new locale: a structural clone that
+* PRESERVES every segment/pause id (the beat ids `.start()`/`.end()` anchors and
+* SFX/visual cues resolve against — they MUST survive so the translated locale
+* stays anchor-compatible) and carries the source text through as a translate-me
+* placeholder. Pure: the input is never mutated. The `voice` is dropped so the
+* locale picks its own (an English voice on translated text is a mistake) unless
+* `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 };
+		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 = {
+		...base,
+		segments
+	};
+	if (!opts.keepVoice) delete forked.voice;
+	return forked;
+}
+/**
+* Derive an authored-script skeleton from a COMMITTED timing manifest — the fork
+* source when the base project kept only `<base>.narration.timing.json` (no
+* authored `<base>.narration.json`). Maps each timed segment/pause back to its
+* script element, preserving ids and text; drops the resolved timing (start/
+* duration/file/words) which a re-narration of the new locale regenerates.
+*/
+function scriptFromTiming(timing) {
+	const pauses = timing.pauses ?? [];
+	const els = [...timing.segments.map((s) => ({
+		start: s.start,
+		el: {
+			id: s.id,
+			text: s.text
+		}
+	})), ...pauses.map((p) => ({
+		start: p.start,
+		el: {
+			id: p.id,
+			pause: p.duration,
+			...p.bed ? { bed: p.bed } : {}
+		}
+	}))];
+	els.sort((a, b) => a.start - b.start);
+	return {
+		narrationVersion: 1,
+		...timing.captionSplit ? { captionSplit: timing.captionSplit } : {},
+		...timing.captionMode ? { captionMode: timing.captionMode } : {},
+		...timing.budgets ? { budgets: timing.budgets } : {},
+		segments: els.map((e) => e.el)
+	};
+}
+/**
+* Build a translatable `messages.<locale>.json` stub for a set of `t()` ids. Each
+* id maps to the base-locale string as a translate-from placeholder (so the
+* translator sees the source), or `''` when no base value exists. Existing target
+* translations are CARRIED OVER (a re-localize never blanks work already done —
+* the translation-memory seed). Keys are sorted for a deterministic, diff-stable
+* file. Pure.
+*/
+function stubMessageTable(ids, opts = {}) {
+	const out = {};
+	for (const id of [...new Set(ids)].sort()) out[id] = opts.existing?.[id] ?? opts.base?.[id] ?? "";
+	return out;
+}
+/**
+* Run the SAME checks the render path runs — `requireParity` across the base and
+* new-locale id manifests, and a dry `localize()` of the scene document with the
+* stub table — but as a NON-throwing report, so every drift surfaces at once
+* before a minute of TTS instead of one-at-a-time at render. Pure over its loaded
+* inputs (it catches the `ParityError`/`LocalizationError` the primitives throw).
+*/
+function runLocalizePreflight(args) {
+	const issues = [];
+	try {
+		requireParity(args.baseManifest, args.localeManifest);
+	} catch (e) {
+		if (e instanceof ParityError) issues.push({
+			kind: "parity",
+			message: e.message
+		});
+		else throw e;
+	}
+	try {
+		localize(args.doc, args.stubTable, {
+			locale: args.locale,
+			...args.consumedIds ? { consumedIds: args.consumedIds } : {}
+		});
+	} catch (e) {
+		if (e instanceof LocalizationError) issues.push({
+			kind: "localize",
+			message: e.message
+		});
+		else throw e;
+	}
+	const untranslated = Object.values(args.stubTable).filter((v) => v === "").length;
+	return {
+		locale: args.locale,
+		ids: [...args.localeManifest.ids].sort(),
+		untranslated,
+		issues,
+		ok: issues.length === 0
+	};
+}
+const nodeIdOf = (target) => {
+	const i = target.indexOf("/");
+	return i < 0 ? target : target.slice(0, i);
+};
+const moduleStemOf = (modulePath) => modulePath.replace(/\.[jt]sx?$/, "");
+/** beat ids (segments + pauses, in order) of an authored script — the anchor id set. */
+const scriptBeatIds = (script) => script.segments.map((e) => e.id);
+/**
+* Harvest the message-table keys a scene actually uses: every `t()` id (recorded
+* by loading the scene under a table that treats every id as known — a Proxy whose
+* `has` is always true, so no `t()` throws — then reading `getConsumedMessageIds`)
+* plus every `type:'string'` track's node-id (the `localize()` keys). This is the
+* one impure step (loading the module runs its side effects), quarantined here.
+*/
+async function harvestMessageIds(modulePath) {
+	const recording = new Proxy({}, {
+		has: () => true,
+		get: (_t, prop) => typeof prop === "string" ? prop : void 0
+	});
+	const { getConsumedMessageIds } = await import("@glissade/core/i18n");
+	const { loadSceneModule } = await import("./render.js").then((n) => n.p);
+	const mod = await loadSceneModule(modulePath, void 0, recording);
+	mod.createScene();
+	const tIds = new Set(getConsumedMessageIds());
+	const ids = new Set(tIds);
+	const doc = mod.timeline;
+	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,
+		doc
+	};
+}
+/**
+* Fork a scene's narration into a new locale + stub its message table, running the
+* render path's parity + localize checks first. Dry-run by default (reports what it
+* WOULD write); `--write` emits `<base>.<locale>.narration.json` +
+* `messages.<locale>.json`. Never synthesizes audio or calls `evaluate()`.
+*/
+async function localizeCommand(modulePath, opts) {
+	const { readFileSync, writeFileSync, existsSync } = await import("node:fs");
+	const { scriptPathFor } = await import("@glissade/narrate/providers");
+	const { messagesFileFor, loadMessageTable } = await import("./locale.js");
+	const { timingPathFor } = await import("./captions.js").then((n) => n.t);
+	const to = opts.to;
+	if (!/^[a-z]{2}(-[A-Za-z0-9]+)*$/.test(to)) throw new LocalizeError(`--to '${to}' is not a locale code (expected e.g. 'zh', 'pt-BR')`);
+	const { ids: messageIds, tIds, doc } = await harvestMessageIds(modulePath);
+	const scriptPath = scriptPathFor(modulePath);
+	const baseTimingPath = timingPathFor(modulePath);
+	let baseScript;
+	let narrationSource = "none";
+	if (existsSync(scriptPath)) {
+		baseScript = JSON.parse(readFileSync(scriptPath, "utf8"));
+		narrationSource = "script";
+	} else if (baseTimingPath && existsSync(baseTimingPath)) {
+		baseScript = scriptFromTiming(JSON.parse(readFileSync(baseTimingPath, "utf8")));
+		narrationSource = "timing";
+	}
+	const narrationPath = moduleStemOf(modulePath) + `.${to}.narration.json`;
+	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);
+	const stubTable = stubMessageTable(messageIds, {
+		...base ? { base } : {},
+		...existingTable ? { existing: existingTable } : {}
+	});
+	const preflight = runLocalizePreflight({
+		locale: to,
+		baseManifest: {
+			locale: opts.from ?? "base",
+			ids: beatIds
+		},
+		localeManifest: {
+			locale: to,
+			ids: localeBeatIds
+		},
+		doc,
+		stubTable,
+		consumedIds: tIds
+	});
+	const wrote = [];
+	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);
+		}
+		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
+	};
+}
+/** Human-readable report (migrate.ts style). */
+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)`}` + (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.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
+export { formatLocalizeReport, localizeCommand };

package/dist/render.js

@@ -334,9 +334,10 @@ function warnOnVersionSkew(scenePath) {
 	if (coreVer === void 0 || coreVer === cliVer) return;
 	process.stderr.write(`warning: @glissade version skew — gs (@glissade/cli@${cliVer}) is rendering a scene that resolves @glissade/core@${coreVer}.\n  glissade is LOCKSTEP: subpath features register per-package-instance (the /expr sampler, Yoga layout), so under a skew a\n  correctly-imported '@glissade/core/expr' or 'layout' can still fail with "need import" / "no LayoutEngine registered".\n  Align every @glissade/* dependency to ${cliVer} (e.g. npm i @glissade/core@${cliVer} @glissade/scene@${cliVer}).\n`);
 }
-async function loadSceneModule(modulePath, locale) {
+async function loadSceneModule(modulePath, locale, messageTableOverride) {
 	const { setMessageTable } = await import("@glissade/core/i18n");
-	if (locale !== void 0 && locale !== "") {
+	if (messageTableOverride !== void 0) setMessageTable(messageTableOverride);
+	else if (locale !== void 0 && locale !== "") {
 		const { loadMessageTable } = await import("./locale.js");
 		setMessageTable(loadMessageTable(modulePath, locale));
 	} else setMessageTable(void 0);

package/package.json

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