@glissade/cli 0.13.0 → 0.14.0-pre.1

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

@@ -17,6 +17,7 @@ const KNOWN_BOOLEAN_FLAGS = new Set([
 	"no-warnings",
 	"lossless-intermediate",
 	"allow-gpu-shards",
+	"allow-system-fonts",
 	"verbose",
 	"allow-degraded",
 	"bisect",
@@ -110,6 +111,10 @@ 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)
+  --allow-system-fonts  exempt true-OS-installed families from the unregistered-family check (host-dependent;
+                   off by default, IGNORED under --strict so the strict verdict stays host-independent; §3.6)
+  --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)
@@ -454,10 +459,12 @@ async function main() {
 			...flags.has("state") ? { state: flags.get("state") } : {},
 			...flags.has("force") ? { force: true } : {},
 			...flags.has("strict") ? { strictFonts: true } : {},
+			...flags.has("allow-system-fonts") ? { allowSystemFonts: true } : {},
 			...workers !== void 0 ? { workers } : {},
 			...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

@@ -168,6 +168,14 @@ interface RenderOptions {
   chapterKinds?: ReadonlySet<string>;
   /** --strict: font validation throws on an unregistered family / missing glyph (§3.6). Default dev-warn. */
   strictFonts?: boolean;
+  /**
+   * --allow-system-fonts (§3.6, 0.14 FIX 6): exempt true-OS-installed families
+   * (the host `GlobalFonts.families` catalog) from the unregistered-family check.
+   * OFF by default — the exempt set is otherwise just the families glissade
+   * registered from `doc.assets`, so the verdict is host-independent. IGNORED
+   * under --strict (strict stays host-independent regardless of this flag).
+   */
+  allowSystemFonts?: boolean;
   /**
    * --workers N (§5.6): split the frame range into N contiguous sub-ranges, render
    * each in a separate `gs` child process, and join the shard videos. Ignored for
@@ -200,8 +208,26 @@ 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;
 }
+/**
+ * Build the case-folded set of families EXEMPT from the §3.6 unregistered-family
+ * check (FIX 6, 0.14). Seeded from the families glissade actually registered out
+ * of `doc.assets` (`registered`, already lower-cased) — NEVER the true-OS
+ * `GlobalFonts.families` catalog, which is host-dependent (3 families on a clean
+ * Linux CI box, hundreds on a dev macOS) and would make the --strict PASS/FAIL
+ * verdict depend on the host. The true-OS `osCatalog` is folded in ONLY when
+ * `allowSystemFonts` is set AND `strict` is false — so --strict stays host-
+ * independent regardless of the flag. Pure: no I/O, no host queries.
+ */
+
 declare class SceneModuleError extends Error {
   constructor(modulePath: string, detail: string);
 }
@@ -211,7 +237,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 +249,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,67 @@
+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.
+*/
+/** Strip a scene module's `.ts`/`.tsx`/`.js`/`.jsx` extension → the file stem. */
+function moduleStem(modulePath) {
+	return modulePath.replace(/\.[jt]sx?$/, "");
+}
+/**
+* The locale-tagged NARRATION timing sibling suffix. A `--locale xx` render
+* prefers `<base>.xx.narration.timing.json` over the base
+* `<base>.narration.timing.json`. DEFAULT convention — the maintainer is
+* confirming the exact suffix with the ai-training consumer; changing it is a
+* one-line edit HERE. `%s` is the locale code.
+*/
+const LOCALE_NARRATION_SUFFIX = ".%s.narration.timing.json";
+/**
+* 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"));
+}
+/**
+* The locale-tagged narration timing sibling path for a module, or `undefined`
+* when no `locale` is requested. The render path prefers this sibling when it
+* exists, falling back to the base sibling otherwise (so a locale that reuses
+* the base narration still renders).
+*/
+function localeNarrationPathFor(modulePath, locale) {
+	return moduleStem(modulePath) + LOCALE_NARRATION_SUFFIX.replace("%s", locale);
+}
+/**
+* A declared `--locale <code>` resolved to NEITHER a `messages.<code>.json` nor a
+* `<base>.<code>.narration.timing.json` sibling — the locale has no assets at
+* all, so a render would silently fall back to the BASE artifact (wrong-language
+* output, exit 0, no warning). Render hard-throws this instead.
+*
+* (A narration-only locale legitimately has no messages file, and a
+* messages-only locale legitimately reuses the base narration — so this fires
+* only when BOTH are absent.)
+*/
+var UnknownLocaleError = class extends Error {
+	constructor(locale, messagesPath, narrationPath) {
+		super(`--locale '${locale}': no locale assets found — neither a message table nor a narration sibling resolves. Looked for '${messagesPath}' and '${narrationPath}'. Add one of those files, or drop --locale to render the base language.`);
+		this.name = "UnknownLocaleError";
+	}
+};
+//#endregion
+export { UnknownLocaleError, loadMessageTable, localeNarrationPathFor, messagesFileFor };

package/dist/render.js

@@ -1,14 +1,67 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { readFile } from "node:fs/promises";
 import { createJiti } from "jiti";
 import { buildFontRegistry } from "@glissade/core";
-import { evaluate, validateSceneFonts, withDeterminismGuards } from "@glissade/scene";
+import { collectLocalizedTextUsages, 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,
@@ -17,6 +70,7 @@ import { SkiaBackend } from "@glissade/backend-skia";
 */
 var render_exports = /* @__PURE__ */ __exportAll({
 	SceneModuleError: () => SceneModuleError,
+	buildFontExemptSet: () => buildFontExemptSet,
 	buildMixWav: () => buildMixWav,
 	collectAudioClips: () => collectAudioClips,
 	collectMixAudioInputs: () => collectMixAudioInputs,
@@ -27,6 +81,21 @@ var render_exports = /* @__PURE__ */ __exportAll({
 	render: () => render,
 	resolveLoudnessGainDb: () => resolveLoudnessGainDb
 });
+/**
+* Build the case-folded set of families EXEMPT from the §3.6 unregistered-family
+* check (FIX 6, 0.14). Seeded from the families glissade actually registered out
+* of `doc.assets` (`registered`, already lower-cased) — NEVER the true-OS
+* `GlobalFonts.families` catalog, which is host-dependent (3 families on a clean
+* Linux CI box, hundreds on a dev macOS) and would make the --strict PASS/FAIL
+* verdict depend on the host. The true-OS `osCatalog` is folded in ONLY when
+* `allowSystemFonts` is set AND `strict` is false — so --strict stays host-
+* independent regardless of the flag. Pure: no I/O, no host queries.
+*/
+function buildFontExemptSet(registered, opts) {
+	const exempt = new Set(registered);
+	if (opts.allowSystemFonts && !opts.strict) for (const f of opts.osCatalog) exempt.add(f);
+	return exempt;
+}
 var SceneModuleError = class extends Error {
 	constructor(modulePath, detail) {
 		super(`${modulePath}: ${detail}\nA scene module default-exports { createScene(): Scene, timeline: Timeline } (SceneModule).`);
@@ -46,7 +115,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 +130,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 +138,19 @@ 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, messagesFileFor, localeNarrationPathFor, UnknownLocaleError } = await import("./locale.js");
+		const table = loadMessageTable(opts.modulePath, opts.locale);
+		const narrationPath = localeNarrationPathFor(opts.modulePath, opts.locale);
+		if (!table && !existsSync(narrationPath)) throw new UnknownLocaleError(opts.locale, messagesFileFor(opts.modulePath, opts.locale), narrationPath);
+		if (table) {
+			const { localize, getConsumedMessageIds } = await import("@glissade/core/i18n");
+			doc = localize(doc, table, {
+				locale: opts.locale,
+				consumedIds: getConsumedMessageIds()
+			});
+		}
+	}
 	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,16 +200,19 @@ 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");
 	const assetDigests = /* @__PURE__ */ new Map();
 	const digestBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");
+	const registeredFamilies = /* @__PURE__ */ new Set();
 	const fontRegistry = buildFontRegistry(doc.assets);
 	if (fontRegistry.faces().length > 0) {
 		const { GlobalFonts } = await import("@napi-rs/canvas");
 		let ingest;
 		for (const face of fontRegistry.faces()) {
+			registeredFamilies.add(face.family.toLowerCase());
 			const path = resolveAsset(face.url, opts.modulePath);
 			if (/\.woff2?$/i.test(face.url)) {
 				ingest ??= await import("@glissade/core/font-ingest");
@@ -139,6 +229,13 @@ async function render(opts) {
 			}
 		}
 	}
+	const osCatalog = !!opts.allowSystemFonts && !opts.strictFonts ? new Set((await import("@napi-rs/canvas")).GlobalFonts.families.map((f) => f.family.toLowerCase())) : /* @__PURE__ */ new Set();
+	const osFamilies = buildFontExemptSet(registeredFamilies, {
+		allowSystemFonts: !!opts.allowSystemFonts,
+		strict: !!opts.strictFonts,
+		osCatalog
+	});
+	const localizedUsages = opts.locale !== void 0 && opts.locale !== "" ? collectLocalizedTextUsages(scene, doc) : [];
 	await validateSceneFonts(scene, doc, async (url) => {
 		try {
 			const buf = await readFile(resolveAsset(url, opts.modulePath));
@@ -146,7 +243,11 @@ async function render(opts) {
 		} catch {
 			return;
 		}
-	}, { mode: opts.strictFonts ? "strict" : "dev" });
+	}, {
+		mode: opts.strictFonts ? "strict" : "dev",
+		osFamilies,
+		extraUsages: localizedUsages
+	});
 	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 +309,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 +406,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 +419,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/dist/shards.js

@@ -149,7 +149,8 @@ async function renderSharded(a) {
 				...opts.trace !== void 0 ? ["--trace", opts.trace] : [],
 				...opts.state !== void 0 ? ["--state", opts.state] : [],
 				...opts.force ? ["--force"] : [],
-				...opts.strictFonts ? ["--strict"] : []
+				...opts.strictFonts ? ["--strict"] : [],
+				...opts.allowSystemFonts ? ["--allow-system-fonts"] : []
 			];
 			const child = spawnSync(process.execPath, childArgs, { stdio: [
 				"ignore",

package/package.json

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