@glissade/cli 0.14.0 → 0.15.0-pre.1

package/dist/cacheVerify.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
-import { a as loadSceneModule } from "./render.js";
+import { o as loadSceneModule } from "./render.js";
 import { i as capsId, n as FrameCache, o as frameCacheKey } from "./frameCache.js";
 import { t as glissadeVersion } from "./version.js";
 import { mkdtempSync, rmSync } from "node:fs";

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as render, o as parseFrameRange } from "./render.js";
+import { c as parseFrameRange, d as render, f as renderLocales, l as parseLocalesList, t as LocaleArgsError } from "./render.js";
 import { n as parseCaptionsMode } from "./captions.js";
 //#region src/args.ts
 /**
@@ -73,7 +73,7 @@ const USAGE = `usage:
   gs narration-lint <scene-module|script.narration.timing.json> [--json] [--fix] [--max-cps <n>]
   gs sfx <scene-module|script.sfx.json> [--verbose]
   gs prepare <scene-module>  [--provider <id>] [--align <id>] [--force]
-  gs measure-loudness <scene-module> [--profile <youtube|shorts|podcast|broadcast|ebu>]
+  gs measure-loudness <scene-module> [--profile <youtube|shorts|podcast|broadcast|ebu>] [--locale <code>]
   gs fonts audit <scene-module>   list registered families, formats, and missing-glyph runs (§3.6)
   gs cache verify <scene-module> [--range a..b] [--sample <n>]   assert cache hits == cold renders (§3.5)
 
@@ -115,6 +115,11 @@ render options:
                    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
+  --locales <a,b>  (0.15) fan out: render the scene ONCE PER comma-separated locale, each over the --locale <code>
+                   path, to a DISTINCT per-locale output. A video/png --out gets a locale segment before the
+                   extension (out/ep.mp4 → out/ep.<locale>.mp4); a directory --out gets a per-locale subdir
+                   (out/ → out/<locale>/). Mutually exclusive with --locale. A locale with NO resolvable assets
+                   aborts the whole fan-out with the same UnknownLocaleError --locale throws (never silently skipped)
 
 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)
@@ -142,6 +147,9 @@ measure-loudness options (the explicit publish-loudness measure step; commits *.
   --profile <id>   youtube (default) | shorts (both -14 LUFS) | podcast (-16) | broadcast/ebu (-23); all cap at -1 dBTP
                    measures the final mix (ebur128) and commits a deterministic peak-clamped gain; render applies it
                    as a pure scalar. Needs ffmpeg. Brickwall limiter deferred — peaky un-normalized profiles warn.
+  --locale <code>  (0.15) measure the per-locale mix (the localized narration sibling) and commit
+                   <stem>.<locale>.loudness.json. A localized 'gs render --locale <code>' REQUIRES this per-locale
+                   file (the base measurement can't gate the per-locale mix). No --locale measures the base mix.
 
 narrate options (the explicit TTS prepare step; render itself stays offline):
   --provider <id>  fake | espeak | piper | kokoro | openai (default: the script's provider, else espeak)
@@ -289,12 +297,14 @@ async function main() {
 	if (command === "measure-loudness") {
 		const { measureLoudnessCommand } = await import("./loudness.js").then((n) => n.c);
 		try {
+			const mlLocale = flags.get("locale");
 			const result = await measureLoudnessCommand({
 				modulePath,
 				...flags.has("profile") ? { profile: flags.get("profile") } : {},
 				...flags.get("narration") === "off" ? { narration: "off" } : {},
 				...flags.get("music") === "off" ? { music: "off" } : {},
-				...flags.get("sfx") === "off" ? { sfx: "off" } : {}
+				...flags.get("sfx") === "off" ? { sfx: "off" } : {},
+				...mlLocale !== void 0 && mlLocale !== "" ? { locale: mlLocale } : {}
 			});
 			const m = result.measurement;
 			process.stderr.write(`gs measure-loudness: profile '${m.profileId}' — in ${m.inputI} LUFS / ${m.inputTp} dBTP → gain ${m.gain >= 0 ? "+" : ""}${m.gain} dB (out ~${(m.inputI + m.gain).toFixed(2)} LUFS / ~${(m.inputTp + m.gain).toFixed(2)} dBTP) → ${result.loudnessPath}\n`);
@@ -443,10 +453,19 @@ async function main() {
 		};
 	}
 	if (flags.has("watch")) process.stderr.write("note: --watch is not yet implemented in this release; rendering once\n");
+	let locales;
+	if (flags.has("locales") && flags.get("locales")) {
+		if (flags.has("locale") && flags.get("locale")) fail("--locale and --locales are mutually exclusive — pass one (--locale renders a single locale; --locales fans out over many)");
+		try {
+			locales = parseLocalesList(flags.get("locales"));
+		} catch (err) {
+			fail(err instanceof LocaleArgsError ? err.message : err instanceof Error ? err.message : String(err));
+		}
+	}
 	const fpsFlag = flags.get("fps");
 	const started = performance.now();
 	try {
-		const result = await render({
+		const sharedOpts = {
 			modulePath,
 			out: flags.get("out") ?? "out",
 			...fpsFlag ? { fps: parseInt(fpsFlag, 10) } : {},
@@ -464,7 +483,6 @@ 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",
@@ -475,10 +493,21 @@ async function main() {
 					if (n % 30 === 0 || n === total) process.stderr.write(`\rrendering ${n}/${total} frames`);
 				} else if (n % 300 === 0 || n === total) process.stderr.write(`rendering ${n}/${total} frames\n`);
 			}
-		});
-		const secs = ((performance.now() - started) / 1e3).toFixed(2);
+		};
 		const cr = process.stderr.isTTY ? "\r" : "";
-		process.stderr.write(`${cr}rendered ${result.frames} frames in ${secs}s → ${result.out}\n`);
+		if (locales) {
+			const fan = await renderLocales(sharedOpts, locales);
+			const secs = ((performance.now() - started) / 1e3).toFixed(2);
+			for (const { locale, result } of fan) process.stderr.write(`${cr}rendered [${locale}] ${result.frames} frames → ${result.out}\n`);
+			process.stderr.write(`done: ${fan.length} locale${fan.length === 1 ? "" : "s"} in ${secs}s\n`);
+		} else {
+			const result = await render({
+				...sharedOpts,
+				...flags.has("locale") && flags.get("locale") ? { locale: flags.get("locale") } : {}
+			});
+			const secs = ((performance.now() - started) / 1e3).toFixed(2);
+			process.stderr.write(`${cr}rendered ${result.frames} frames in ${secs}s → ${result.out}\n`);
+		}
 	} catch (err) {
 		fail(err instanceof Error ? err.message : String(err));
 	}

package/dist/diff.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
-import { a as loadSceneModule } from "./render.js";
+import { o as loadSceneModule } from "./render.js";
 import { readFileSync } from "node:fs";
 import { diffDisplayLists, evaluate, formatDisplayDiff, parseDisplaySnapshot, serializeDisplayList } from "@glissade/scene";
 //#region src/diff.ts

package/dist/fonts.js

@@ -1,4 +1,4 @@
-import { a as loadSceneModule } from "./render.js";
+import { o as loadSceneModule } from "./render.js";
 import { readFile } from "node:fs/promises";
 import { buildFontRegistry } from "@glissade/core";
 import { collectTextUsages } from "@glissade/scene";

package/dist/index.d.ts

@@ -226,8 +226,63 @@ interface RenderOptions {
  * 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.
+ *
+ * 0.15 FIX 5 (osFamilies brand-warn gap): when an OS family name COLLIDES with a
+ * family glissade actually registered from `doc.assets`, the OS-catalog fold must
+ * NOT re-add it as an "OS-only" exemption — a registered family is a declared
+ * brand font that must stay subject to glyph-coverage validation, not be waved
+ * through as a system family. We therefore skip any osCatalog entry that collides
+ * with a registered family (the `registered` seed already carries it, and core's
+ * `validateFonts` runs coverage for registered families regardless of exemption).
+ * The exemption is for GENUINELY-OS-only families, never registered ones that
+ * happen to share a name.
  */
 
+declare class LocaleArgsError extends Error {
+  constructor(detail: string);
+}
+/**
+ * Parse the `--locales <a,b,c>` comma-separated list into a de-duplicated,
+ * order-preserving array of locale codes. Empty / whitespace-only entries are
+ * dropped; an all-empty list is rejected (a `--locales` with nothing to render
+ * is a user error, not a silent no-op).
+ */
+declare function parseLocalesList(raw: string): string[];
+/**
+ * Derive the per-locale output path from the base `out` and a locale code.
+ *
+ * Convention: a video/PNG FILE path (`out/episode.mp4`, `out/still.png`) gets a
+ * locale segment inserted before the extension → `out/episode.<locale>.mp4`. Any
+ * other `out` (a PNG-sequence DIRECTORY, the default `out`) gets a per-locale
+ * SUBDIR → `out/<locale>` (so `out/en/frame-00000.png`, `out/zh/frame-00000.png`).
+ * `--format png-seq` forces the directory convention even for a video-looking
+ * name, matching how `render()` itself treats `out` under that flag.
+ */
+declare function localeOutPath(out: string, locale: string, format?: 'png-seq'): string;
+/**
+ * §0.15 `--locales` fan-out: render the scene once per locale, writing one
+ * artifact per locale to a distinct per-locale path (`localeOutPath`). Each
+ * per-locale render IS the 0.14 single-`--locale` render — so `--locales en,zh`
+ * ≡ `--locale en` then `--locale zh` with distinct outputs.
+ *
+ * Fails LOUDLY: a locale in the list with no resolvable assets throws the 0.14
+ * `UnknownLocaleError` (naming the bad locale) from inside `render()`, aborting
+ * the whole fan-out — locales already rendered keep their artifacts, but the
+ * process exits non-zero so a missing-asset locale is never silently skipped.
+ *
+ * 0.15 FIX 2: a per-locale loudness dead-end (no `<stem>.<locale>.loudness.json`
+ * committed) also aborts the batch — but a bare error mid-fan-out reads like a
+ * generic crash, so each per-locale failure is wrapped to NAME the failing locale.
+ * It still fails loudly (never swallowed): the wrapped message stays actionable.
+ */
+declare function renderLocales(opts: Omit<RenderOptions, 'locale'>, locales: readonly string[]): Promise<{
+  locale: string;
+  result: {
+    frames: number;
+    out: string;
+  };
+}[]>;
+/** A scene module's default export is not a valid `SceneModule`. */
 declare class SceneModuleError extends Error {
   constructor(modulePath: string, detail: string);
 }
@@ -276,8 +331,16 @@ declare function collectAudioClips(opts: Pick<RenderOptions, 'modulePath' | 'nar
  * `.wav`/music stem invalidates the measurement here too (the §5.3 stale-gain
  * gate). `timelineClips` defaults to the scene's compiled timeline audio when
  * omitted, so a bare `{ modulePath }` call still gates correctly.
+ *
+ * 0.15 FIX 2 (localized loudness): a localized render (`--locale zh`) mixes the
+ * per-locale narration → a DIFFERENT mixHash than the base measurement. So when a
+ * locale is set it reads the per-locale file `<stem>.<locale>.loudness.json` FIRST.
+ * When that per-locale file is MISSING it throws an ACTIONABLE per-locale error
+ * (naming the file + the `gs measure-loudness … --locale` to run) instead of the
+ * generic stale-mixHash message — there is otherwise no supported way to commit a
+ * per-locale measurement, so a base file would always read as stale and dead-end.
  */
-declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness' | 'narration' | 'music' | 'sfx'>, timelineClips?: AudioClip[]): Promise<number | null>;
+declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness' | 'narration' | 'music' | 'sfx' | 'locale'>, timelineClips?: AudioClip[]): Promise<number | null>;
 /**
  * Collect audio clips + auto-mixed siblings and plan the FFmpeg audio graph,
  * returning the `-i`/`-filter_complex`/`-map` argument fragments. Shared by the
@@ -303,7 +366,7 @@ declare function planFinalAudio(opts: RenderOptions, timelineClips: AudioClip[],
  * gain — measurement is of the un-gained mix), so the measured content is exactly
  * what render will later mix. Returns false when the scene has no audio.
  */
-declare function buildMixWav(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx'>, wavOut: string): Promise<boolean>;
+declare function buildMixWav(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx' | 'locale'>, wavOut: string): Promise<boolean>;
 //#endregion
 //#region src/loudness.d.ts
 /**
@@ -412,10 +475,18 @@ declare function peakClampBinds(profile: PublishProfile, inputI: number, inputTp
  * hash. The scene module path itself is excluded.
  */
 declare function computeMixHash(modulePath: string, extraInputs?: readonly string[]): string;
-/** `<module>.loudness.json` for a scene module. */
-declare function loudnessPathFor(modulePath: string): string;
+/**
+ * The committed loudness measurement path for a scene module.
+ *
+ * Base (no locale): `<stem>.loudness.json` — UNCHANGED. With a locale set (0.15
+ * FIX 2): `<stem>.<locale>.loudness.json`. A localized render mixes the per-locale
+ * narration (e.g. the zh wavs) → a DIFFERENT mixHash than the base, so it needs its
+ * OWN committed measurement; one base file can't gate a localized render (it would
+ * always read as a stale mixHash, with no supported way to commit a per-locale one).
+ */
+declare function loudnessPathFor(modulePath: string, locale?: string): string;
 /** Read + validate a committed measurement, or null when none is committed. */
-declare function readLoudness(modulePath: string): LoudnessMeasurement | null;
+declare function readLoudness(modulePath: string, locale?: string): LoudnessMeasurement | null;
 /**
  * Parse the JSON block ffmpeg's `loudnorm=print_format=json` prints to stderr.
  * It carries `input_i` / `input_tp` / `input_lra` (the measured loudness),
@@ -445,6 +516,13 @@ interface MeasureLoudnessOptions {
   narration?: 'auto' | 'off';
   music?: 'auto' | 'off';
   sfx?: 'auto' | 'off';
+  /**
+   * locale code (0.15 FIX 2). When set, measure the per-locale mix (the localized
+   * narration sibling) and commit `<stem>.<locale>.loudness.json` instead of the
+   * base file. Mirrors `gs render --locale`, so the measured content matches what
+   * a localized render mixes.
+   */
+  locale?: string;
 }
 interface MeasureLoudnessResult {
   measurement: LoudnessMeasurement;
@@ -833,4 +911,4 @@ declare function cacheVerifyCommand(opts: CacheVerifyOptions): Promise<CacheVeri
 /** The @glissade/cli package version (the glissade VERSION for the cache key). */
 declare function glissadeVersion(): string;
 //#endregion
-export { AudioMixError, type AudioMixPlan, type CacheKeyContext, type CacheMode, type CacheVerifyOptions, type CacheVerifyResult, type CaptionProbe, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, type DevOptions, type DevServer, type Diagnostic, type DiffOptions, type DiffResult, type EncoderChoice, FfmpegVideoFrameSource, FrameCache, FrameCacheError, type FrameCacheOptions, type ImportCommandResult, type ImportOptions, LOUDNESS_SCHEMA_VERSION, type LintOptions, type LintRule, LoudnessError, type LoudnessMeasurement, MachineExportError, type MachineRenderFlags, type MeasureLoudnessOptions, type MeasureLoudnessResult, type NarrationLintOptions, type NarrationLintResult, NoEncoderError, PUBLISH_PROFILES, type PublishProfile, type RenderOptions, type RenderShardedArgs, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };
+export { AudioMixError, type AudioMixPlan, type CacheKeyContext, type CacheMode, type CacheVerifyOptions, type CacheVerifyResult, type CaptionProbe, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, type DevOptions, type DevServer, type Diagnostic, type DiffOptions, type DiffResult, type EncoderChoice, FfmpegVideoFrameSource, FrameCache, FrameCacheError, type FrameCacheOptions, type ImportCommandResult, type ImportOptions, LOUDNESS_SCHEMA_VERSION, type LintOptions, type LintRule, LocaleArgsError, LoudnessError, type LoudnessMeasurement, MachineExportError, type MachineRenderFlags, type MeasureLoudnessOptions, type MeasureLoudnessResult, type NarrationLintOptions, type NarrationLintResult, NoEncoderError, PUBLISH_PROFILES, type PublishProfile, type RenderOptions, type RenderShardedArgs, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as loadSceneModule, c as render, i as ffmpegAvailable, n as buildMixWav, r as collectAudioClips, s as planFinalAudio, t as SceneModuleError, u as resolveLoudnessGainDb } from "./render.js";
+import { a as ffmpegAvailable, d as render, f as renderLocales, i as collectAudioClips, l as parseLocalesList, m as resolveLoudnessGainDb, n as SceneModuleError, o as loadSceneModule, r as buildMixWav, s as localeOutPath, t as LocaleArgsError, u as planFinalAudio } from "./render.js";
 import { a as computeGainDb, d as parseLoudnormJson, f as peakClampBinds, i as PUBLISH_PROFILES, l as measureFile, m as resolveProfile, n as LOUDNESS_SCHEMA_VERSION, o as computeMixHash, p as readLoudness, r as LoudnessError, s as loudnessPathFor, t as DEFAULT_PROFILE_ID, u as measureLoudnessCommand } from "./loudness.js";
 import { a as pickEncoder, i as parseEncoderList, n as availableEncoders, t as NoEncoderError } from "./encoders.js";
 import { a as splitFrameRange, n as renderSharded, r as sceneHasGpuNodes, t as ShardError } from "./shards.js";
@@ -12,4 +12,4 @@ import { a as fixDiff, c as lintNarration, n as lintTimingPathFor, o as formatTa
 import { a as clearFrameCache, c as parseCacheMaxSize, i as capsId, l as probeEntryHeader, n as FrameCache, o as frameCacheKey, r as FrameCacheError, t as DEFAULT_CACHE_MAX_SIZE } from "./frameCache.js";
 import { t as glissadeVersion } from "./version.js";
 import { t as cacheVerifyCommand } from "./cacheVerify.js";
-export { AudioMixError, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, FfmpegVideoFrameSource, FrameCache, FrameCacheError, LOUDNESS_SCHEMA_VERSION, LoudnessError, MachineExportError, NoEncoderError, PUBLISH_PROFILES, SceneModuleError, ShardError, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };
+export { AudioMixError, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, FfmpegVideoFrameSource, FrameCache, FrameCacheError, LOUDNESS_SCHEMA_VERSION, LocaleArgsError, LoudnessError, MachineExportError, NoEncoderError, PUBLISH_PROFILES, SceneModuleError, ShardError, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };

package/dist/loudness.js

@@ -146,13 +146,22 @@ function computeMixHash(modulePath, extraInputs = []) {
 	}
 	return `sha256:${h.digest("hex")}`;
 }
-/** `<module>.loudness.json` for a scene module. */
-function loudnessPathFor(modulePath) {
-	return modulePath.replace(/\.[jt]sx?$/, "") + ".loudness.json";
+/**
+* The committed loudness measurement path for a scene module.
+*
+* Base (no locale): `<stem>.loudness.json` — UNCHANGED. With a locale set (0.15
+* FIX 2): `<stem>.<locale>.loudness.json`. A localized render mixes the per-locale
+* narration (e.g. the zh wavs) → a DIFFERENT mixHash than the base, so it needs its
+* OWN committed measurement; one base file can't gate a localized render (it would
+* always read as a stale mixHash, with no supported way to commit a per-locale one).
+*/
+function loudnessPathFor(modulePath, locale) {
+	const stem = modulePath.replace(/\.[jt]sx?$/, "");
+	return locale !== void 0 && locale !== "" ? `${stem}.${locale}.loudness.json` : `${stem}.loudness.json`;
 }
 /** Read + validate a committed measurement, or null when none is committed. */
-function readLoudness(modulePath) {
-	const path = loudnessPathFor(modulePath);
+function readLoudness(modulePath, locale) {
+	const path = loudnessPathFor(modulePath, locale);
 	if (!existsSync(path)) return null;
 	const raw = JSON.parse(readFileSync(path, "utf8"));
 	if (raw.loudnessVersion !== 1) throw new LoudnessError(`${path}: unsupported loudnessVersion ${String(raw.loudnessVersion)} (expected 1); re-run gs measure-loudness`);
@@ -214,7 +223,7 @@ function measureFile(audioPath) {
 */
 async function measureLoudnessCommand(opts) {
 	const profile = resolveProfile(opts.profile ?? "youtube");
-	const { buildMixWav } = await import("./render.js").then((n) => n.l);
+	const { buildMixWav } = await import("./render.js").then((n) => n.p);
 	const tmp = mkdtempSync(join(tmpdir(), "glissade-loudness-"));
 	try {
 		const wavPath = join(tmp, "mix.wav");
@@ -222,17 +231,19 @@ async function measureLoudnessCommand(opts) {
 			modulePath: opts.modulePath,
 			narration: opts.narration ?? "auto",
 			music: opts.music ?? "auto",
-			sfx: opts.sfx ?? "auto"
+			sfx: opts.sfx ?? "auto",
+			...opts.locale !== void 0 && opts.locale !== "" ? { locale: opts.locale } : {}
 		}, wavPath)) throw new LoudnessError(`${opts.modulePath} has no audio to measure (no timeline audio and no narration/music/sfx manifests)`);
 		const { inputI, inputTp, inputLra } = measureFile(wavPath);
 		const gain = computeGainDb(profile, inputI, inputTp);
 		const clampBound = peakClampBinds(profile, inputI, inputTp);
-		const { collectMixAudioInputs } = await import("./render.js").then((n) => n.l);
+		const { collectMixAudioInputs } = await import("./render.js").then((n) => n.p);
 		const extraInputs = await collectMixAudioInputs({
 			modulePath: opts.modulePath,
 			narration: opts.narration ?? "auto",
 			music: opts.music ?? "auto",
-			sfx: opts.sfx ?? "auto"
+			sfx: opts.sfx ?? "auto",
+			...opts.locale !== void 0 && opts.locale !== "" ? { locale: opts.locale } : {}
 		});
 		const mixHash = computeMixHash(opts.modulePath, extraInputs);
 		const measurement = {
@@ -244,7 +255,7 @@ async function measureLoudnessCommand(opts) {
 			gain: floorGain2(gain),
 			mixHash
 		};
-		const loudnessPath = loudnessPathFor(opts.modulePath);
+		const loudnessPath = loudnessPathFor(opts.modulePath, opts.locale);
 		writeFileSync(loudnessPath, JSON.stringify(measurement, null, 2) + "\n");
 		return {
 			measurement,

package/dist/narrationLintCommand.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
-import { a as loadSceneModule } from "./render.js";
+import { o as loadSceneModule } from "./render.js";
 import { existsSync, readFileSync } from "node:fs";
 import { splitCaption } from "@glissade/narrate";
 //#region src/narrationLint.ts

package/dist/prepare.js

@@ -1,4 +1,4 @@
-import { a as loadSceneModule } from "./render.js";
+import { o as loadSceneModule } from "./render.js";
 import { narrateCommand } from "./narrate.js";
 import { prepareSfx, sfxScriptPathFor } from "./sfx.js";
 import { existsSync } from "node:fs";

package/dist/render.js

@@ -69,6 +69,7 @@ function validateAssetReferences(refs, declaredIds) {
 * when requested and available. No browser anywhere.
 */
 var render_exports = /* @__PURE__ */ __exportAll({
+	LocaleArgsError: () => LocaleArgsError,
 	SceneModuleError: () => SceneModuleError,
 	buildFontExemptSet: () => buildFontExemptSet,
 	buildMixWav: () => buildMixWav,
@@ -76,9 +77,12 @@ var render_exports = /* @__PURE__ */ __exportAll({
 	collectMixAudioInputs: () => collectMixAudioInputs,
 	ffmpegAvailable: () => ffmpegAvailable,
 	loadSceneModule: () => loadSceneModule,
+	localeOutPath: () => localeOutPath,
 	parseFrameRange: () => parseFrameRange,
+	parseLocalesList: () => parseLocalesList,
 	planFinalAudio: () => planFinalAudio,
 	render: () => render,
+	renderLocales: () => renderLocales,
 	resolveLoudnessGainDb: () => resolveLoudnessGainDb
 });
 /**
@@ -90,12 +94,103 @@ var render_exports = /* @__PURE__ */ __exportAll({
 * 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.
+*
+* 0.15 FIX 5 (osFamilies brand-warn gap): when an OS family name COLLIDES with a
+* family glissade actually registered from `doc.assets`, the OS-catalog fold must
+* NOT re-add it as an "OS-only" exemption — a registered family is a declared
+* brand font that must stay subject to glyph-coverage validation, not be waved
+* through as a system family. We therefore skip any osCatalog entry that collides
+* with a registered family (the `registered` seed already carries it, and core's
+* `validateFonts` runs coverage for registered families regardless of exemption).
+* The exemption is for GENUINELY-OS-only families, never registered ones that
+* happen to share a name.
 */
 function buildFontExemptSet(registered, opts) {
 	const exempt = new Set(registered);
-	if (opts.allowSystemFonts && !opts.strict) for (const f of opts.osCatalog) exempt.add(f);
+	if (opts.allowSystemFonts && !opts.strict) {
+		for (const f of opts.osCatalog) if (!registered.has(f)) exempt.add(f);
+	}
 	return exempt;
 }
+var LocaleArgsError = class extends Error {
+	constructor(detail) {
+		super(detail);
+		this.name = "LocaleArgsError";
+	}
+};
+/**
+* Parse the `--locales <a,b,c>` comma-separated list into a de-duplicated,
+* order-preserving array of locale codes. Empty / whitespace-only entries are
+* dropped; an all-empty list is rejected (a `--locales` with nothing to render
+* is a user error, not a silent no-op).
+*/
+function parseLocalesList(raw) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const part of raw.split(",")) {
+		const code = part.trim();
+		if (code === "" || seen.has(code)) continue;
+		seen.add(code);
+		out.push(code);
+	}
+	if (out.length === 0) throw new LocaleArgsError(`--locales is empty — pass a comma-separated list, e.g. --locales en,zh`);
+	return out;
+}
+/**
+* Derive the per-locale output path from the base `out` and a locale code.
+*
+* Convention: a video/PNG FILE path (`out/episode.mp4`, `out/still.png`) gets a
+* locale segment inserted before the extension → `out/episode.<locale>.mp4`. Any
+* other `out` (a PNG-sequence DIRECTORY, the default `out`) gets a per-locale
+* SUBDIR → `out/<locale>` (so `out/en/frame-00000.png`, `out/zh/frame-00000.png`).
+* `--format png-seq` forces the directory convention even for a video-looking
+* name, matching how `render()` itself treats `out` under that flag.
+*/
+function localeOutPath(out, locale, format) {
+	const isVideoName = format !== "png-seq" && /\.(mp4|webm)$/i.test(out);
+	const isPngFile = format !== "png-seq" && /\.png$/i.test(out);
+	if (isVideoName || isPngFile) return out.replace(/(\.[^.]+)$/, `.${locale}$1`);
+	return join(out, locale);
+}
+/**
+* §0.15 `--locales` fan-out: render the scene once per locale, writing one
+* artifact per locale to a distinct per-locale path (`localeOutPath`). Each
+* per-locale render IS the 0.14 single-`--locale` render — so `--locales en,zh`
+* ≡ `--locale en` then `--locale zh` with distinct outputs.
+*
+* Fails LOUDLY: a locale in the list with no resolvable assets throws the 0.14
+* `UnknownLocaleError` (naming the bad locale) from inside `render()`, aborting
+* the whole fan-out — locales already rendered keep their artifacts, but the
+* process exits non-zero so a missing-asset locale is never silently skipped.
+*
+* 0.15 FIX 2: a per-locale loudness dead-end (no `<stem>.<locale>.loudness.json`
+* committed) also aborts the batch — but a bare error mid-fan-out reads like a
+* generic crash, so each per-locale failure is wrapped to NAME the failing locale.
+* It still fails loudly (never swallowed): the wrapped message stays actionable.
+*/
+async function renderLocales(opts, locales) {
+	const results = [];
+	for (const locale of locales) {
+		let result;
+		try {
+			result = await render({
+				...opts,
+				out: localeOutPath(opts.out, locale, opts.format),
+				locale
+			});
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			if (err instanceof Error && msg.includes(`'${locale}'`)) throw err;
+			throw new Error(`--locales: locale '${locale}' failed — ${msg}`, { cause: err });
+		}
+		results.push({
+			locale,
+			result
+		});
+	}
+	return results;
+}
+/** A scene module's default export is not a valid `SceneModule`. */
 var SceneModuleError = class extends Error {
 	constructor(modulePath, detail) {
 		super(`${modulePath}: ${detail}\nA scene module default-exports { createScene(): Scene, timeline: Timeline } (SceneModule).`);
@@ -455,23 +550,26 @@ async function collectAudioClips(opts, timelineClips) {
 * clips — the narration/music/sfx siblings still resolve from `modulePath`.
 */
 async function collectMixAudioInputs(opts, timelineClips) {
-	let tl = timelineClips;
-	if (tl === void 0) try {
-		const mod = await loadSceneModule(opts.modulePath);
-		const { compileTimeline } = await import("@glissade/core");
-		tl = [...compileTimeline(mod.timeline).audio];
-	} catch {
-		tl = [];
-	}
-	const clips = await collectAudioClips(opts, tl);
-	const { resolveAssetPath } = await import("./audioMix.js").then((n) => n.i);
-	const paths = /* @__PURE__ */ new Set();
-	for (const c of clips) try {
-		paths.add(resolveAssetPath(c.asset.url, opts.modulePath));
-	} catch {
-		paths.add(c.asset.url);
-	}
-	return [...paths].sort();
+	const { preservingMessageTable } = await import("@glissade/core/i18n");
+	return preservingMessageTable(async () => {
+		let tl = timelineClips;
+		if (tl === void 0) try {
+			const mod = await loadSceneModule(opts.modulePath, opts.locale);
+			const { compileTimeline } = await import("@glissade/core");
+			tl = [...compileTimeline(mod.timeline).audio];
+		} catch {
+			tl = [];
+		}
+		const clips = await collectAudioClips(opts, tl);
+		const { resolveAssetPath } = await import("./audioMix.js").then((n) => n.i);
+		const paths = /* @__PURE__ */ new Set();
+		for (const c of clips) try {
+			paths.add(resolveAssetPath(c.asset.url, opts.modulePath));
+		} catch {
+			paths.add(c.asset.url);
+		}
+		return [...paths].sort();
+	});
 }
 /**
 * Resolve the committed publish gain (dB) for a render: read `<scene>.loudness.json`
@@ -485,15 +583,34 @@ async function collectMixAudioInputs(opts, timelineClips) {
 * `.wav`/music stem invalidates the measurement here too (the §5.3 stale-gain
 * gate). `timelineClips` defaults to the scene's compiled timeline audio when
 * omitted, so a bare `{ modulePath }` call still gates correctly.
+*
+* 0.15 FIX 2 (localized loudness): a localized render (`--locale zh`) mixes the
+* per-locale narration → a DIFFERENT mixHash than the base measurement. So when a
+* locale is set it reads the per-locale file `<stem>.<locale>.loudness.json` FIRST.
+* When that per-locale file is MISSING it throws an ACTIONABLE per-locale error
+* (naming the file + the `gs measure-loudness … --locale` to run) instead of the
+* generic stale-mixHash message — there is otherwise no supported way to commit a
+* per-locale measurement, so a base file would always read as stale and dead-end.
 */
 async function resolveLoudnessGainDb(opts, timelineClips) {
 	if ((opts.loudness ?? "auto") === "off") return null;
 	const { readLoudness, computeMixHash, loudnessPathFor } = await import("./loudness.js").then((n) => n.c);
-	const measurement = readLoudness(opts.modulePath);
-	if (!measurement) return null;
+	const hasLocale = opts.locale !== void 0 && opts.locale !== "";
+	const measurement = readLoudness(opts.modulePath, opts.locale);
+	if (!measurement) {
+		if (hasLocale && readLoudness(opts.modulePath) !== null) {
+			const perLocale = loudnessPathFor(opts.modulePath, opts.locale);
+			throw new Error(`loudness: no ${perLocale} for locale '${opts.locale}' — a localized render mixes the per-locale narration, which has a different loudness than the base mix, so it needs its OWN measurement. Run \`gs measure-loudness ${opts.modulePath} --locale ${opts.locale}\` to commit it (or pass --loudness off to render this locale without normalization).`);
+		}
+		return null;
+	}
 	const extraInputs = await collectMixAudioInputs(opts, timelineClips);
 	const actual = computeMixHash(opts.modulePath, extraInputs);
-	if (actual !== measurement.mixHash) throw new Error(`loudness: ${loudnessPathFor(opts.modulePath)} is stale — the mix inputs changed since it was measured (committed mixHash ${measurement.mixHash.slice(0, 23)}…, current ${actual.slice(0, 23)}…). Re-run \`gs measure-loudness ${opts.modulePath}\` (or pass --loudness off to render without normalization).`);
+	if (actual !== measurement.mixHash) {
+		const path = loudnessPathFor(opts.modulePath, opts.locale);
+		const reRun = hasLocale ? `gs measure-loudness ${opts.modulePath} --locale ${opts.locale}` : `gs measure-loudness ${opts.modulePath}`;
+		throw new Error(`loudness: ${path} is stale — the mix inputs changed since it was measured (committed mixHash ${measurement.mixHash.slice(0, 23)}…, current ${actual.slice(0, 23)}…). Re-run \`${reRun}\` (or pass --loudness off to render without normalization).`);
+	}
 	return measurement.gain;
 }
 /**
@@ -548,43 +665,46 @@ async function planFinalAudio(opts, timelineClips, duration, container) {
 */
 async function buildMixWav(opts, wavOut) {
 	if (!ffmpegAvailable()) throw new Error("gs measure-loudness needs FFmpeg on PATH and none was found.");
-	const mod = await loadSceneModule(opts.modulePath);
-	const scene = mod.createScene();
-	const { compileTimeline } = await import("@glissade/core");
-	const compiled = compileTimeline(mod.timeline);
-	const duration = compiled.duration;
-	const audioClips = await collectAudioClips(opts, [...compiled.audio]);
-	const { planAudioMix } = await import("./audioMix.js").then((n) => n.i);
-	const mix = planAudioMix(audioClips, opts.modulePath, duration);
-	if (!mix) return false;
-	const result = spawnSync("ffmpeg", [
-		"-y",
-		"-hide_banner",
-		"-nostats",
-		"-f",
-		"lavfi",
-		"-i",
-		"anullsrc=channel_layout=stereo:sample_rate=48000",
-		...mix.inputs.flatMap((p) => ["-i", p]),
-		"-filter_complex",
-		mix.filterComplex,
-		"-map",
-		"[aout]",
-		"-c:a",
-		"pcm_s16le",
-		"-ar",
-		"48000",
-		"-t",
-		String(duration),
-		wavOut
-	], { stdio: [
-		"ignore",
-		"ignore",
-		"pipe"
-	] });
-	if (result.status !== 0) throw new Error(`ffmpeg mix-to-WAV failed (exit ${result.status}):\n${result.stderr?.toString().slice(-2e3)}`);
-	scene.size;
-	return true;
+	const { preservingMessageTable } = await import("@glissade/core/i18n");
+	return preservingMessageTable(async () => {
+		const mod = await loadSceneModule(opts.modulePath, opts.locale);
+		const scene = mod.createScene();
+		const { compileTimeline } = await import("@glissade/core");
+		const compiled = compileTimeline(mod.timeline);
+		const duration = compiled.duration;
+		const audioClips = await collectAudioClips(opts, [...compiled.audio]);
+		const { planAudioMix } = await import("./audioMix.js").then((n) => n.i);
+		const mix = planAudioMix(audioClips, opts.modulePath, duration);
+		if (!mix) return false;
+		const result = spawnSync("ffmpeg", [
+			"-y",
+			"-hide_banner",
+			"-nostats",
+			"-f",
+			"lavfi",
+			"-i",
+			"anullsrc=channel_layout=stereo:sample_rate=48000",
+			...mix.inputs.flatMap((p) => ["-i", p]),
+			"-filter_complex",
+			mix.filterComplex,
+			"-map",
+			"[aout]",
+			"-c:a",
+			"pcm_s16le",
+			"-ar",
+			"48000",
+			"-t",
+			String(duration),
+			wavOut
+		], { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		if (result.status !== 0) throw new Error(`ffmpeg mix-to-WAV failed (exit ${result.status}):\n${result.stderr?.toString().slice(-2e3)}`);
+		scene.size;
+		return true;
+	});
 }
 //#endregion
-export { loadSceneModule as a, render as c, ffmpegAvailable as i, render_exports as l, buildMixWav as n, parseFrameRange as o, collectAudioClips as r, planFinalAudio as s, SceneModuleError as t, resolveLoudnessGainDb as u };
+export { ffmpegAvailable as a, parseFrameRange as c, render as d, renderLocales as f, collectAudioClips as i, parseLocalesList as l, resolveLoudnessGainDb as m, SceneModuleError as n, loadSceneModule as o, render_exports as p, buildMixWav as r, localeOutPath as s, LocaleArgsError as t, planFinalAudio as u };

package/dist/shards.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
-import { s as planFinalAudio } from "./render.js";
+import { u as planFinalAudio } from "./render.js";
 import { a as pickEncoder } from "./encoders.js";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";

package/dist/verifyDeterminism.js

@@ -1,4 +1,4 @@
-import { t as SceneModuleError } from "./render.js";
+import { n as SceneModuleError } from "./render.js";
 import { a as splitFrameRange } from "./shards.js";
 import { readFileSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";

package/package.json

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