@glissade/cli 0.13.0 → 0.14.0-pre.0

package/dist/captions.js

@@ -21,8 +21,18 @@ function parseCaptionsMode(raw) {
 	if (raw === "sidecar" || raw === "off") return raw;
 	throw new Error(`--captions must be burn, sidecar, or off (got '${raw}')`);
 }
-/** `<module>.narration.timing.json`, when the scene has been narrated. */
-function timingPathFor(modulePath) {
+/**
+* `<module>.narration.timing.json`, when the scene has been narrated. With a
+* `locale`, PREFER the locale-tagged sibling `<module>.<locale>.narration.timing.json`
+* (0.14 localization core) and fall back to the base sibling when it is absent —
+* so a locale that reuses the base narration still renders. No `locale` (the
+* base path) resolves the base sibling, byte-identical to today.
+*/
+function timingPathFor(modulePath, locale) {
+	if (locale !== void 0 && locale !== "") {
+		const localeCandidate = modulePath.replace(/\.[jt]sx?$/, "") + `.${locale}.narration.timing.json`;
+		if (existsSync(localeCandidate)) return localeCandidate;
+	}
 	const candidate = modulePath.replace(/\.[jt]sx?$/, "") + ".narration.timing.json";
 	return existsSync(candidate) ? candidate : null;
 }

package/dist/cli.js

@@ -110,6 +110,8 @@ render options:
                    (YouTube needs the 1st chapter at 0:00 — auto-anchored — and each chapter >= 10s; author cue ts accordingly)
   --chapters-kind <k[,k]>  cue kinds that become VTT chapters (default: chapter); cues.json keeps all kinds
   --strict         fail on an unregistered font family or an uncovered glyph (§3.6; default: warn)
+  --locale <code>  resolve the scene against messages.<code>.json (node-id text + free-standing t() keys) and prefer
+                   the <base>.<code>.narration.timing.json sibling (0.14). No --locale resolves the BASE files
 
 diff options (DisplayList diff vs a committed baseline — exits non-zero on any divergence):
   --at <t>         time in SECONDS to evaluate the scene at (required)
@@ -458,6 +460,7 @@ async function main() {
 			...flags.has("lossless-intermediate") ? { losslessIntermediate: true } : {},
 			...flags.has("allow-gpu-shards") ? { allowGpuShards: true } : {},
 			...cache !== void 0 ? { cache } : {},
+			...flags.has("locale") && flags.get("locale") ? { locale: flags.get("locale") } : {},
 			captions: parseCaptionsModeOrFail(flags.get("captions")),
 			narration: flags.get("narration") === "off" ? "off" : "auto",
 			music: flags.get("music") === "off" ? "off" : "auto",

package/dist/index.d.ts

@@ -200,6 +200,13 @@ interface RenderOptions {
     mode: CacheMode;
     maxSize?: number;
   };
+  /**
+   * --locale <code> (0.14 localization core): resolve the scene against a
+   * per-locale message table (`messages.<code>.json`) and prefer the
+   * locale-tagged narration sibling (`<base>.<code>.narration.timing.json`).
+   * Omitted (the base path) resolves the BASE files → byte-identical to today.
+   */
+  locale?: string;
   onProgress?: (frame: number, total: number) => void;
 }
 declare class SceneModuleError extends Error {
@@ -211,7 +218,7 @@ declare class SceneModuleError extends Error {
  * ranges are rejected, since a frame index is an integer.
  */
 
-declare function loadSceneModule(modulePath: string): Promise<SceneModule>;
+declare function loadSceneModule(modulePath: string, locale?: string): Promise<SceneModule>;
 declare function ffmpegAvailable(): boolean;
 declare function render(opts: RenderOptions): Promise<{
   frames: number;
@@ -223,7 +230,7 @@ declare function render(opts: RenderOptions): Promise<{
  * render/shard path) and `buildMixWav` (the measure-loudness path), so the mix
  * 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[]>;
+declare function collectAudioClips(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx' | 'locale'>, 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

package/dist/locale.js

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region src/locale.ts
+/**
+* gs render --locale <code> (0.14 localization core): resolve the per-locale
+* message table + the locale-tagged narration timing sibling for a scene module.
+*
+* The render-time half of @glissade/core/i18n. The base (no --locale) path
+* resolves the BASE files (`messages.json` is NOT consulted, the base narration
+* sibling is used) → byte-identical to today. Every locale is opt-in.
+*/
+/**
+* The per-locale message table filename, resolved RELATIVE to the scene module
+* directory: `messages.<locale>.json`. DEFAULT convention; one-line change.
+*/
+function messagesFileFor(modulePath, locale) {
+	return join(dirname(modulePath), `messages.${locale}.json`);
+}
+/**
+* Load the message table for a locale, or `undefined` when no `messages.<locale>.json`
+* exists (a locale with only node-id / narration text and no free-standing t()
+* keys is valid). The base path never calls this.
+*/
+function loadMessageTable(modulePath, locale) {
+	const file = messagesFileFor(modulePath, locale);
+	if (!existsSync(file)) return void 0;
+	return JSON.parse(readFileSync(file, "utf8"));
+}
+//#endregion
+export { loadMessageTable };

package/dist/render.js

@@ -9,6 +9,59 @@ import { createJiti } from "jiti";
 import { buildFontRegistry } from "@glissade/core";
 import { evaluate, validateSceneFonts, withDeterminismGuards } from "@glissade/scene";
 import { SkiaBackend } from "@glissade/backend-skia";
+//#region src/assetValidation.ts
+/**
+* Walk a scene's node tree and collect every Image/Video asset reference. Pure
+* (no playhead) — the asset id a node references is structural, not a function
+* of time. `assetId` may be `undefined` at runtime (a JS caller that passed a
+* `src` URL instead of an `assetId` — the common codegen mistake), even though
+* scene's type says `string`; surfaced as-is.
+*/
+function collectAssetReferences(root) {
+	const out = [];
+	const visit = (node) => {
+		const kind = node.constructor.assetKind;
+		if (kind !== void 0) out.push({
+			assetId: node.assetId,
+			kind,
+			nodeId: node.id
+		});
+		if (node.children) for (const child of node.children) visit(child);
+	};
+	visit(root);
+	return out;
+}
+/**
+* An Image/Video node references an asset id that isn't declared in
+* `timeline.assets`. Distinct from ColdAssetError (a declared-but-not-warmed
+* asset) — this is an AUTHORING mistake caught before evaluation, and the
+* message names the most common cause: passing a `src` URL instead of an
+* `assetId` + a `timeline.assets` entry.
+*/
+var UnknownAssetError = class extends Error {
+	assetId;
+	declared;
+	constructor(ref, declared) {
+		const id = ref.assetId;
+		const at = ref.nodeId !== void 0 ? ` on ${ref.kind} node '${ref.nodeId}'` : ` on an ${ref.kind} node`;
+		const declaredList = declared.length > 0 ? declared.join(", ") : "(none)";
+		super(`assetId ${id === void 0 ? "<undefined>" : `'${id}'`}${at} is not declared in timeline.assets (declared: ${declaredList}) — an Image/Video needs an \`assetId\` plus a \`timeline.assets\` entry { kind, url }, not a \`src\` URL; remote URLs are not fetched at render (§2.5 offline determinism)`);
+		this.name = "UnknownAssetError";
+		this.assetId = id;
+		this.declared = declared;
+	}
+};
+/**
+* Pre-validate Image/Video asset references against the declared timeline asset
+* ids. Throws an UnknownAssetError naming the real mistake when a referenced id
+* is undefined or absent from `declaredIds`. A no-op when every reference is
+* declared.
+*/
+function validateAssetReferences(refs, declaredIds) {
+	const declared = new Set(declaredIds);
+	for (const ref of refs) if (ref.assetId === void 0 || !declared.has(ref.assetId)) throw new UnknownAssetError(ref, [...declared]);
+}
+//#endregion
 //#region src/render.ts
 /**
 * gs render (DESIGN.md §5.1d, §5.7): load a scene module, evaluate each frame,
@@ -46,7 +99,12 @@ function parseFrameRange(flag) {
 	if (b < a) throw new Error(`--range end (${b}) is before start (${a})`);
 	return [a, b];
 }
-async function loadSceneModule(modulePath) {
+async function loadSceneModule(modulePath, locale) {
+	const { setMessageTable } = await import("@glissade/core/i18n");
+	if (locale !== void 0 && locale !== "") {
+		const { loadMessageTable } = await import("./locale.js");
+		setMessageTable(loadMessageTable(modulePath, locale));
+	} else setMessageTable(void 0);
 	const abs = isAbsolute(modulePath) ? modulePath : resolve(process.cwd(), modulePath);
 	const loaded = await createJiti(pathToFileURL(process.cwd() + "/").href).import(pathToFileURL(abs).href, { default: true });
 	if (typeof loaded?.createScene !== "function" || loaded?.timeline === void 0) throw new SceneModuleError(modulePath, "default export is not a SceneModule");
@@ -56,7 +114,7 @@ function ffmpegAvailable() {
 	return spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0;
 }
 async function render(opts) {
-	const mod = await loadSceneModule(opts.modulePath);
+	const mod = await loadSceneModule(opts.modulePath, opts.locale);
 	const scene = mod.createScene();
 	const { resolveRenderDoc } = await import("./machines.js").then((n) => n.n);
 	let doc = resolveRenderDoc(mod, scene, {
@@ -64,6 +122,14 @@ async function render(opts) {
 		...opts.state !== void 0 ? { state: opts.state } : {},
 		...opts.force !== void 0 ? { force: opts.force } : {}
 	});
+	if (opts.locale !== void 0 && opts.locale !== "") {
+		const { loadMessageTable } = await import("./locale.js");
+		const table = loadMessageTable(opts.modulePath, opts.locale);
+		if (table) {
+			const { localize } = await import("@glissade/core/i18n");
+			doc = localize(doc, table, { locale: opts.locale });
+		}
+	}
 	const fps = opts.fps ?? doc.fps ?? 60;
 	const captionsMode = opts.captions ?? "burn";
 	const { hideCaptionsDoc, timingPathFor, writeCaptionSidecars } = await import("./captions.js").then((n) => n.t);
@@ -113,6 +179,7 @@ async function render(opts) {
 		const { loadYogaLayoutEngine } = await import("@glissade/scene/layout");
 		await loadYogaLayoutEngine();
 	}
+	validateAssetReferences(collectAssetReferences(scene.root), Object.keys(doc.assets ?? {}));
 	const videoSources = [];
 	const { resolveAssetPath: resolveAsset } = await import("./audioMix.js").then((n) => n.i);
 	const { createHash } = await import("node:crypto");
@@ -139,6 +206,8 @@ async function render(opts) {
 			}
 		}
 	}
+	const { GlobalFonts: GlobalFontsForValidation } = await import("@napi-rs/canvas");
+	const osFamilies = new Set(GlobalFontsForValidation.families.map((f) => f.family.toLowerCase()));
 	await validateSceneFonts(scene, doc, async (url) => {
 		try {
 			const buf = await readFile(resolveAsset(url, opts.modulePath));
@@ -146,7 +215,10 @@ async function render(opts) {
 		} catch {
 			return;
 		}
-	}, { mode: opts.strictFonts ? "strict" : "dev" });
+	}, {
+		mode: opts.strictFonts ? "strict" : "dev",
+		osFamilies
+	});
 	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");
 		const imgPath = resolveAsset(ref.url, opts.modulePath);
@@ -208,7 +280,7 @@ async function render(opts) {
 	for (const source of videoSources) source.close();
 	const emitSidecars = (target) => {
 		if (captionsMode === "off") return;
-		const timingPath = timingPathFor(opts.modulePath);
+		const timingPath = timingPathFor(opts.modulePath, opts.locale);
 		if (!timingPath) {
 			if (captionsMode === "sidecar") process.stderr.write("note: --captions sidecar: no narration timing manifest found; run gs narrate first\n");
 			return;
@@ -305,7 +377,7 @@ async function collectAudioClips(opts, timelineClips) {
 	const audioClips = [...timelineClips];
 	const { bedAlreadyReferenced, buildMusicClip, buildNarrationClips, musicPathFor } = await import("./music.js");
 	if ((opts.narration ?? "auto") === "auto") {
-		const narrationPath = timingPathFor(opts.modulePath);
+		const narrationPath = timingPathFor(opts.modulePath, opts.locale);
 		if (narrationPath) {
 			const voice = buildNarrationClips(narrationPath);
 			if (voice) if (voice.clips.some((c) => bedAlreadyReferenced(audioClips, c.asset.url, opts.modulePath))) process.stderr.write("note: narration already in the timeline audio — auto-mix skipped\n");
@@ -318,7 +390,7 @@ async function collectAudioClips(opts, timelineClips) {
 	if ((opts.music ?? "auto") === "auto") {
 		const musicPath = musicPathFor(opts.modulePath);
 		if (musicPath) {
-			const bed = buildMusicClip(musicPath, timingPathFor(opts.modulePath));
+			const bed = buildMusicClip(musicPath, timingPathFor(opts.modulePath, opts.locale));
 			if (bed) if (bedAlreadyReferenced(audioClips, bed.clip.asset.url, opts.modulePath)) process.stderr.write("note: music bed already in the timeline audio — auto-mix skipped\n");
 			else {
 				audioClips.push(bed.clip);

package/package.json

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