@glissade/cli 0.9.1 → 0.10.0-pre.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as render, i as parseFrameRange } from "./render.js";
+import { i as parseFrameRange, o as render } from "./render.js";
 import { n as parseCaptionsMode } from "./captions.js";
 //#region src/cli.ts
 /**
@@ -53,6 +53,11 @@ render options:
   --range <a..b>   integer FRAME indices to render, inclusive (default: whole timeline)
   --frame <n>      render a single frame; --out foo.png writes that one file, --out <dir> writes a PNG into it
   --format png-seq force a PNG sequence even when --out looks like a video
+  --workers <n>    shard the frame range across n separate render processes, then concat (§5.6; video out only).
+                   byte-identical to a single-worker render at the frame level
+  --lossless-intermediate  render shards as FFV1 + one final encode — the guaranteed byte-correct join
+                   (auto-enabled when the encoder can't honor precise boundary keyframes, e.g. mpeg4/openh264)
+  --allow-gpu-shards  permit sharding a scene with GPU/shader nodes (output is not reproducible across shards; §3.7)
   --trace <file>   replay an InputTrace and bake it (machine scenes, §A.6)
   --state <name>   render one machine state's timeline linearly
   --force          downgrade a trace hash mismatch to a warning
@@ -178,7 +183,12 @@ async function main() {
 	}
 	const formatFlag = flags.get("format");
 	if (formatFlag !== void 0 && formatFlag !== "png-seq") fail(`--format must be 'png-seq', got '${formatFlag}'`);
-	if (flags.has("workers")) process.stderr.write("note: --workers is accepted but parallel sharding is not yet implemented; rendering single-threaded\n");
+	let workers;
+	const workersFlag = flags.get("workers");
+	if (workersFlag !== void 0) {
+		if (!/^\d+$/.test(workersFlag) || Number(workersFlag) < 1) fail(`--workers must be a positive integer, got '${workersFlag}'`);
+		workers = Number(workersFlag);
+	}
 	if (flags.has("watch")) process.stderr.write("note: --watch is not yet implemented in this release; rendering once\n");
 	const fpsFlag = flags.get("fps");
 	const started = performance.now();
@@ -196,6 +206,9 @@ async function main() {
 			...flags.has("state") ? { state: flags.get("state") } : {},
 			...flags.has("force") ? { force: true } : {},
 			...flags.has("strict") ? { strictFonts: true } : {},
+			...workers !== void 0 ? { workers } : {},
+			...flags.has("lossless-intermediate") ? { losslessIntermediate: true } : {},
+			...flags.has("allow-gpu-shards") ? { allowGpuShards: true } : {},
 			captions: parseCaptionsModeOrFail(flags.get("captions")),
 			narration: flags.get("narration") === "off" ? "off" : "auto",
 			music: flags.get("music") === "off" ? "off" : "auto",

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AudioClip, Key, Timeline } from "@glissade/core";
+import { AudioClip, CompiledTimeline, Key, Timeline } from "@glissade/core";
 import { Scene, SceneModule, VideoFrameSource } from "@glissade/scene";
 import { Image } from "@napi-rs/canvas";
 
@@ -36,6 +36,30 @@ interface RenderOptions {
   chapterKinds?: ReadonlySet<string>;
   /** --strict: font validation throws on an unregistered family / missing glyph (§3.6). Default dev-warn. */
   strictFonts?: 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
+   * a single frame or N <= 1. Only meaningful for a video `out`.
+   */
+  workers?: number;
+  /**
+   * --lossless-intermediate (§5.6, §8.1): render shards as FFV1 (lossless) and do a
+   * single final encode after the concat — the guaranteed byte-correct join path.
+   * Forced on automatically when the picked encoder can't honor precise boundary
+   * keyframes (mpeg4 / openh264).
+   */
+  losslessIntermediate?: boolean;
+  /**
+   * --allow-gpu-shards (§5.6): sharded GPU/shader output isn't reproducible across
+   * processes/machines, so a scene containing a ShaderEffect refuses to shard unless
+   * this is set.
+   */
+  allowGpuShards?: boolean;
+  /**
+   * Internal (shard children): render video-only — skip the audio mix and the
+   * caption/cue sidecars, which the orchestrator emits once over the joined result.
+   */
+  videoOnly?: boolean;
   onProgress?: (frame: number, total: number) => void;
 }
 declare class SceneModuleError extends Error {
@@ -53,6 +77,62 @@ declare function render(opts: RenderOptions): Promise<{
   frames: number;
   out: string;
 }>;
+/**
+ * Collect timeline + auto-mixed (narration/music/sfx) audio clips and plan the
+ * FFmpeg audio graph, returning the `-i`/`-filter_complex`/`-map` argument
+ * fragments. Shared by the linear `render()` path and the sharded orchestrator
+ * (which mixes audio once, over the concatenated video). Returns empty args when
+ * there is nothing to mix.
+ */
+declare function planFinalAudio(opts: RenderOptions, timelineClips: AudioClip[], duration: number, container: 'mp4' | 'webm'): Promise<{
+  audioInputs: string[];
+  audioArgs: string[];
+}>;
+//#endregion
+//#region src/shards.d.ts
+declare class ShardError extends Error {
+  constructor(message: string);
+}
+interface ShardRange {
+  /** inclusive first frame */
+  first: number;
+  /** inclusive last frame */
+  last: number;
+}
+/**
+ * Split inclusive `[first, last]` into up to `workers` contiguous sub-ranges,
+ * front-loading the remainder so earlier shards are at most one frame larger.
+ * Never returns more ranges than there are frames.
+ */
+declare function splitFrameRange(first: number, last: number, workers: number): ShardRange[];
+/** Does this scene contain a GPU/shader node (outside the §3.7 determinism guarantee)? */
+declare function sceneHasGpuNodes(scene: Scene): boolean;
+interface RenderShardedArgs {
+  opts: RenderOptions;
+  scene: Scene;
+  compiled: CompiledTimeline;
+  fps: number;
+  duration: number;
+  firstFrame: number;
+  lastFrame: number;
+  container: 'mp4' | 'webm';
+  workers: number;
+  timingPathFor: (modulePath: string) => string | null;
+  writeCaptionSidecars: (timingPath: string, target: string) => {
+    srt: string;
+    vtt: string;
+  };
+  writeCueSidecars: (target: string, markers: CompiledTimeline['markers'], duration: number, chapters: boolean, chapterKinds?: ReadonlySet<string>) => string[];
+}
+/**
+ * Orchestrate a sharded render. Returns the same `{ frames, out }` shape as the
+ * linear `render()`. Throws on a GPU scene without --allow-gpu-shards, or on any
+ * child / ffmpeg failure.
+ */
+declare function renderSharded(a: RenderShardedArgs): Promise<{
+  frames: number;
+  out: string;
+}>;
 //#endregion
 //#region src/videoSource.d.ts
 declare class VideoProbeError extends Error {
@@ -184,4 +264,4 @@ interface ImportCommandResult {
 }
 declare function importCommand(opts: ImportOptions): Promise<ImportCommandResult>;
 //#endregion
-export { AudioMixError, type AudioMixPlan, type DevOptions, type DevServer, type EncoderChoice, FfmpegVideoFrameSource, type ImportCommandResult, type ImportOptions, MachineExportError, type MachineRenderFlags, NoEncoderError, type RenderOptions, SceneModuleError, type VideoInfo, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, importCommand, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, probeVideo, render, resolveAssetPath, resolveRenderDoc };
+export { AudioMixError, type AudioMixPlan, type DevOptions, type DevServer, type EncoderChoice, FfmpegVideoFrameSource, type ImportCommandResult, type ImportOptions, MachineExportError, type MachineRenderFlags, NoEncoderError, type RenderOptions, type RenderShardedArgs, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, importCommand, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, planFinalAudio, probeVideo, render, renderSharded, resolveAssetPath, resolveRenderDoc, sceneHasGpuNodes, splitFrameRange };

package/dist/index.js

@@ -1,8 +1,9 @@
-import { a as render, n as ffmpegAvailable, r as loadSceneModule, t as SceneModuleError } from "./render.js";
+import { a as planFinalAudio, n as ffmpegAvailable, o as render, r as loadSceneModule, t as SceneModuleError } from "./render.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";
 import { n as VideoProbeError, r as probeVideo, t as FfmpegVideoFrameSource } from "./videoSource.js";
 import { a as planAudioMix, i as gainExpression, n as atempoChain, o as resolveAssetPath, t as AudioMixError } from "./audioMix.js";
-import { a as pickEncoder, i as parseEncoderList, n as availableEncoders, t as NoEncoderError } from "./encoders.js";
 import { r as resolveRenderDoc, t as MachineExportError } from "./machines.js";
 import { t as dev } from "./dev.js";
 import { t as importCommand } from "./import.js";
-export { AudioMixError, FfmpegVideoFrameSource, MachineExportError, NoEncoderError, SceneModuleError, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, importCommand, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, probeVideo, render, resolveAssetPath, resolveRenderDoc };
+export { AudioMixError, FfmpegVideoFrameSource, MachineExportError, NoEncoderError, SceneModuleError, ShardError, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, importCommand, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, planFinalAudio, probeVideo, render, renderSharded, resolveAssetPath, resolveRenderDoc, sceneHasGpuNodes, splitFrameRange };

package/dist/render.js

@@ -74,6 +74,24 @@ async function render(opts) {
 	const isVideo = opts.format !== "png-seq" && /\.(mp4|webm)$/i.test(opts.out);
 	const singleFile = !isVideo && total === 1 && /\.png$/i.test(opts.out);
 	if (isVideo && !ffmpegAvailable()) throw new Error(`'${opts.out}' needs FFmpeg on PATH and none was found. Render a PNG sequence instead (--out <directory>) or install ffmpeg.`);
+	const workers = opts.videoOnly ? 1 : Math.max(1, Math.floor(opts.workers ?? 1));
+	if (workers > 1 && isVideo && total > 1) {
+		const { renderSharded } = await import("./shards.js").then((n) => n.i);
+		return renderSharded({
+			opts,
+			scene,
+			compiled,
+			fps,
+			duration,
+			firstFrame,
+			lastFrame,
+			container: /\.webm$/i.test(opts.out) ? "webm" : "mp4",
+			workers,
+			timingPathFor,
+			writeCaptionSidecars,
+			writeCueSidecars
+		});
+	}
 	const framesDir = isVideo ? mkdtempSync(join(tmpdir(), "glissade-frames-")) : singleFile ? dirname(resolve(opts.out)) : resolve(opts.out);
 	mkdirSync(framesDir, { recursive: true });
 	const backend = new SkiaBackend(scene.size.w, scene.size.h);
@@ -144,8 +162,10 @@ async function render(opts) {
 	}
 	const outAbs = resolve(opts.out);
 	mkdirSync(dirname(outAbs), { recursive: true });
-	emitSidecars(outAbs);
-	emitCues(outAbs);
+	if (!opts.videoOnly) {
+		emitSidecars(outAbs);
+		emitCues(outAbs);
+	}
 	const isWebm = /\.webm$/i.test(outAbs);
 	const container = isWebm ? "webm" : "mp4";
 	const { pickEncoder } = await import("./encoders.js").then((n) => n.r);
@@ -173,60 +193,10 @@ async function render(opts) {
 			"+faststart"
 		]
 	];
-	const audioClips = [...compiled.audio];
-	{
-		const { bedAlreadyReferenced, buildMusicClip, buildNarrationClips, musicPathFor } = await import("./music.js");
-		if ((opts.narration ?? "auto") === "auto") {
-			const narrationPath = timingPathFor(opts.modulePath);
-			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");
-				else {
-					audioClips.push(...voice.clips);
-					process.stderr.write(`note: auto-mixing ${voice.note}\n`);
-				}
-			}
-		}
-		if ((opts.music ?? "auto") === "auto") {
-			const musicPath = musicPathFor(opts.modulePath);
-			if (musicPath) {
-				const bed = buildMusicClip(musicPath, timingPathFor(opts.modulePath));
-				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);
-					process.stderr.write(`note: auto-mixing ${bed.note}\n`);
-				}
-			}
-		}
-		if ((opts.sfx ?? "auto") === "auto") {
-			const { buildSfxClipsFromTiming, sfxTimingPathFor } = await import("./sfx.js");
-			const sfxPath = sfxTimingPathFor(opts.modulePath);
-			if (sfxPath) {
-				const fx = buildSfxClipsFromTiming(sfxPath);
-				if (fx) if (fx.clips.some((c) => bedAlreadyReferenced(audioClips, c.asset.url, opts.modulePath))) process.stderr.write("note: sfx already in the timeline audio — auto-mix skipped\n");
-				else {
-					audioClips.push(...fx.clips);
-					process.stderr.write(`note: auto-mixing ${fx.note}\n`);
-				}
-			}
-		}
-	}
-	const { planAudioMix } = await import("./audioMix.js").then((n) => n.r);
-	const mix = planAudioMix(audioClips, opts.modulePath, duration);
-	if (mix?.hasEasedGain) process.stderr.write("note: eased gain keys are approximated linearly in the FFmpeg mix\n");
-	const audioInputs = mix ? mix.inputs.flatMap((p) => ["-i", p]) : [];
-	const audioEnc = mix ? pickEncoder("audio", container) : null;
-	const audioArgs = mix && audioEnc ? [
-		"-filter_complex",
-		mix.filterComplex,
-		"-map",
-		"0:v",
-		"-map",
-		"[aout]",
-		"-c:a",
-		audioEnc.name,
-		...container === "mp4" ? ["-b:a", "192k"] : []
-	] : [];
+	const { audioInputs, audioArgs } = opts.videoOnly ? {
+		audioInputs: [],
+		audioArgs: []
+	} : await planFinalAudio(opts, [...compiled.audio], duration, container);
 	const result = spawnSync("ffmpeg", [
 		"-y",
 		"-framerate",
@@ -256,5 +226,74 @@ async function render(opts) {
 		out: outAbs
 	};
 }
+/**
+* Collect timeline + auto-mixed (narration/music/sfx) audio clips and plan the
+* FFmpeg audio graph, returning the `-i`/`-filter_complex`/`-map` argument
+* fragments. Shared by the linear `render()` path and the sharded orchestrator
+* (which mixes audio once, over the concatenated video). Returns empty args when
+* there is nothing to mix.
+*/
+async function planFinalAudio(opts, timelineClips, duration, container) {
+	const { timingPathFor } = await import("./captions.js").then((n) => n.t);
+	const audioClips = [...timelineClips];
+	const { bedAlreadyReferenced, buildMusicClip, buildNarrationClips, musicPathFor } = await import("./music.js");
+	if ((opts.narration ?? "auto") === "auto") {
+		const narrationPath = timingPathFor(opts.modulePath);
+		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");
+			else {
+				audioClips.push(...voice.clips);
+				process.stderr.write(`note: auto-mixing ${voice.note}\n`);
+			}
+		}
+	}
+	if ((opts.music ?? "auto") === "auto") {
+		const musicPath = musicPathFor(opts.modulePath);
+		if (musicPath) {
+			const bed = buildMusicClip(musicPath, timingPathFor(opts.modulePath));
+			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);
+				process.stderr.write(`note: auto-mixing ${bed.note}\n`);
+			}
+		}
+	}
+	if ((opts.sfx ?? "auto") === "auto") {
+		const { buildSfxClipsFromTiming, sfxTimingPathFor } = await import("./sfx.js");
+		const sfxPath = sfxTimingPathFor(opts.modulePath);
+		if (sfxPath) {
+			const fx = buildSfxClipsFromTiming(sfxPath);
+			if (fx) if (fx.clips.some((c) => bedAlreadyReferenced(audioClips, c.asset.url, opts.modulePath))) process.stderr.write("note: sfx already in the timeline audio — auto-mix skipped\n");
+			else {
+				audioClips.push(...fx.clips);
+				process.stderr.write(`note: auto-mixing ${fx.note}\n`);
+			}
+		}
+	}
+	const { planAudioMix } = await import("./audioMix.js").then((n) => n.r);
+	const { pickEncoder } = await import("./encoders.js").then((n) => n.r);
+	const mix = planAudioMix(audioClips, opts.modulePath, duration);
+	if (mix?.hasEasedGain) process.stderr.write("note: eased gain keys are approximated linearly in the FFmpeg mix\n");
+	if (!mix) return {
+		audioInputs: [],
+		audioArgs: []
+	};
+	const audioEnc = pickEncoder("audio", container);
+	return {
+		audioInputs: mix.inputs.flatMap((p) => ["-i", p]),
+		audioArgs: [
+			"-filter_complex",
+			mix.filterComplex,
+			"-map",
+			"0:v",
+			"-map",
+			"[aout]",
+			"-c:a",
+			audioEnc.name,
+			...container === "mp4" ? ["-b:a", "192k"] : []
+		]
+	};
+}
 //#endregion
-export { render as a, parseFrameRange as i, ffmpegAvailable as n, loadSceneModule as r, SceneModuleError as t };
+export { planFinalAudio as a, parseFrameRange as i, ffmpegAvailable as n, render as o, loadSceneModule as r, SceneModuleError as t };

package/dist/shards.js

@@ -0,0 +1,280 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { a 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";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ShaderEffect } from "@glissade/scene";
+//#region src/shards.ts
+/**
+* Sharded export (DESIGN.md §5.6, §8.1 item 1): `gs render --workers N` splits
+* the frame range into N contiguous sub-ranges, renders each in a SEPARATE `gs`
+* child process (NOT worker_threads — @napi-rs/canvas / GlobalFonts hold unsafe
+* process-global state), then joins the shard videos with the FFmpeg concat
+* demuxer. Determinism is frame-level: every shard re-runs the scene module from
+* scratch (re-deriving any module-level `bake()` for its prefix), so an N-worker
+* render of a range is byte-identical to a single-worker render of the same range
+* at the PNG level; the join is pure engineering above the purity guarantee.
+*
+* Two join strategies (the §8.1 decision):
+*   - default: per-shard encode with a forced keyframe at each range start +
+*     identical encoder settings, concat-demuxer copy.
+*   - --lossless-intermediate: FFV1 shards + a single final encode. Forced on
+*     automatically when the picked encoder can't honor precise boundary
+*     keyframes (mpeg4 / openh264) — a concat-copy of imprecise-GOP codecs drops
+*     or dupes boundary frames, so it would not be byte-faithful.
+*
+* GPU/shader scenes are outside the cross-process reproducibility guarantee
+* (§3.7), so a scene containing a ShaderEffect refuses to shard without
+* --allow-gpu-shards.
+*/
+var shards_exports = /* @__PURE__ */ __exportAll({
+	ShardError: () => ShardError,
+	renderSharded: () => renderSharded,
+	sceneHasGpuNodes: () => sceneHasGpuNodes,
+	splitFrameRange: () => splitFrameRange
+});
+/** Encoders that can't place a keyframe exactly on a forced boundary → not concat-copy-safe. */
+const IMPRECISE_KEYFRAME_ENCODERS = new Set(["mpeg4", "libopenh264"]);
+/** Per-encoder quality flags — must match render.ts's linear path byte-for-byte. */
+const VIDEO_QUALITY = {
+	"libx264": ["-crf", "18"],
+	"libvpx-vp9": [
+		"-b:v",
+		"0",
+		"-crf",
+		"32"
+	],
+	"libvpx": ["-b:v", "2M"],
+	"libopenh264": ["-b:v", "4M"],
+	"mpeg4": ["-q:v", "3"]
+};
+var ShardError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ShardError";
+	}
+};
+/**
+* Split inclusive `[first, last]` into up to `workers` contiguous sub-ranges,
+* front-loading the remainder so earlier shards are at most one frame larger.
+* Never returns more ranges than there are frames.
+*/
+function splitFrameRange(first, last, workers) {
+	const totalFrames = last - first + 1;
+	const n = Math.min(Math.max(1, Math.floor(workers)), totalFrames);
+	const base = Math.floor(totalFrames / n);
+	const extra = totalFrames % n;
+	const ranges = [];
+	let cursor = first;
+	for (let i = 0; i < n; i++) {
+		const len = base + (i < extra ? 1 : 0);
+		ranges.push({
+			first: cursor,
+			last: cursor + len - 1
+		});
+		cursor += len;
+	}
+	return ranges;
+}
+/** Does this scene contain a GPU/shader node (outside the §3.7 determinism guarantee)? */
+function sceneHasGpuNodes(scene) {
+	for (const node of scene.nodes.values()) if (node instanceof ShaderEffect) return true;
+	return false;
+}
+/**
+* Resolve the built `gs` CLI entry. In production this module is `dist/shards.js`,
+* so the sibling `dist/cli.js` is the entry. Under test/source the sibling
+* `cli.js` doesn't exist, so fall back to the package's built `dist/cli.js`.
+*/
+function cliEntry() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const sibling = resolve(here, "cli.js");
+	if (existsSync(sibling)) return sibling;
+	const dist = resolve(here, "..", "dist", "cli.js");
+	if (existsSync(dist)) return dist;
+	return sibling;
+}
+/**
+* Orchestrate a sharded render. Returns the same `{ frames, out }` shape as the
+* linear `render()`. Throws on a GPU scene without --allow-gpu-shards, or on any
+* child / ffmpeg failure.
+*/
+async function renderSharded(a) {
+	const { opts, scene, compiled, fps, duration, firstFrame, lastFrame, container } = a;
+	if (sceneHasGpuNodes(scene) && !opts.allowGpuShards) throw new ShardError("this scene contains a GPU/shader node, whose output is not reproducible across shard processes (§3.7). Re-run with --allow-gpu-shards to override, or render single-threaded (drop --workers).");
+	const ranges = splitFrameRange(firstFrame, lastFrame, a.workers);
+	const total = lastFrame - firstFrame + 1;
+	const outAbs = resolve(opts.out);
+	mkdirSync(dirname(outAbs), { recursive: true });
+	const finalEnc = pickEncoder("video", container);
+	if (finalEnc.note) process.stderr.write(`note: ${finalEnc.note}\n`);
+	let lossless = opts.losslessIntermediate === true;
+	if (!lossless && IMPRECISE_KEYFRAME_ENCODERS.has(finalEnc.name)) {
+		lossless = true;
+		process.stderr.write(`note: '${finalEnc.name}' can't honor precise shard-boundary keyframes; falling back to --lossless-intermediate (FFV1 shards + one final encode) for a byte-faithful join
+`);
+	}
+	const work = mkdtempSync(join(tmpdir(), "glissade-shards-"));
+	const shardVideos = [];
+	let done = 0;
+	try {
+		process.stderr.write(`sharding ${total} frames across ${ranges.length} worker${ranges.length === 1 ? "" : "s"}${lossless ? " (lossless intermediate)" : ""}\n`);
+		for (let i = 0; i < ranges.length; i++) {
+			const { first, last } = ranges[i];
+			const shardFrames = join(work, `shard-${String(i).padStart(3, "0")}-frames`);
+			mkdirSync(shardFrames, { recursive: true });
+			const childArgs = [
+				cliEntry(),
+				"render",
+				opts.modulePath,
+				"--out",
+				shardFrames,
+				"--range",
+				`${first}..${last}`,
+				"--format",
+				"png-seq",
+				"--fps",
+				String(fps),
+				"--narration",
+				"off",
+				"--music",
+				"off",
+				"--sfx",
+				"off",
+				...opts.captions ? ["--captions", opts.captions] : [],
+				...opts.trace !== void 0 ? ["--trace", opts.trace] : [],
+				...opts.state !== void 0 ? ["--state", opts.state] : [],
+				...opts.force ? ["--force"] : [],
+				...opts.strictFonts ? ["--strict"] : []
+			];
+			const child = spawnSync(process.execPath, childArgs, { stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			] });
+			if (child.status !== 0) throw new ShardError(`shard ${i} (frames ${first}..${last}) failed (exit ${child.status}):\n${child.stderr?.toString().slice(-2e3) ?? ""}`);
+			const ext = container === "webm" && !lossless ? "webm" : "mkv";
+			const shardVideo = join(work, `shard-${String(i).padStart(3, "0")}.${ext}`);
+			const codecArgs = lossless ? [
+				"-c:v",
+				"ffv1",
+				"-level",
+				"3"
+			] : [
+				"-c:v",
+				finalEnc.name,
+				...VIDEO_QUALITY[finalEnc.name] ?? [],
+				"-force_key_frames",
+				"0",
+				...container === "webm" ? [] : ["-pix_fmt", "yuv420p"]
+			];
+			const enc = spawnSync("ffmpeg", [
+				"-y",
+				"-framerate",
+				String(fps),
+				"-start_number",
+				String(first),
+				"-i",
+				join(shardFrames, "frame-%05d.png"),
+				...codecArgs,
+				shardVideo
+			], { stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			] });
+			if (enc.status !== 0) throw new ShardError(`shard ${i} encode failed (exit ${enc.status}):\n${enc.stderr?.toString().slice(-2e3)}`);
+			rmSync(shardFrames, {
+				recursive: true,
+				force: true
+			});
+			shardVideos.push(shardVideo);
+			done += last - first + 1;
+			opts.onProgress?.(done, total);
+		}
+		const listFile = join(work, "concat.txt");
+		writeFileSync(listFile, shardVideos.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+		const { audioInputs, audioArgs } = await planFinalAudio(opts, [...compiled.audio], duration, container);
+		let joinArgs;
+		if (lossless) {
+			const videoEnc = finalEnc;
+			joinArgs = [
+				"-y",
+				"-f",
+				"concat",
+				"-safe",
+				"0",
+				"-i",
+				listFile,
+				...audioInputs,
+				...audioArgs,
+				"-c:v",
+				videoEnc.name,
+				...VIDEO_QUALITY[videoEnc.name] ?? [],
+				...container === "webm" ? [] : [
+					"-pix_fmt",
+					"yuv420p",
+					"-movflags",
+					"+faststart"
+				],
+				outAbs
+			];
+		} else if (audioArgs.length) joinArgs = [
+			"-y",
+			"-f",
+			"concat",
+			"-safe",
+			"0",
+			"-i",
+			listFile,
+			...audioInputs,
+			"-c:v",
+			"copy",
+			...audioArgs,
+			...container === "webm" ? [] : ["-movflags", "+faststart"],
+			outAbs
+		];
+		else joinArgs = [
+			"-y",
+			"-f",
+			"concat",
+			"-safe",
+			"0",
+			"-i",
+			listFile,
+			"-c",
+			"copy",
+			...container === "webm" ? [] : ["-movflags", "+faststart"],
+			outAbs
+		];
+		const join_ = spawnSync("ffmpeg", joinArgs, { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		if (join_.status !== 0) throw new ShardError(`shard join failed (exit ${join_.status}):\n${join_.stderr?.toString().slice(-2e3)}`);
+	} finally {
+		rmSync(work, {
+			recursive: true,
+			force: true
+		});
+	}
+	if ((opts.captions ?? "burn") !== "off") {
+		const timingPath = a.timingPathFor(opts.modulePath);
+		if (timingPath) {
+			const { srt, vtt } = a.writeCaptionSidecars(timingPath, outAbs);
+			process.stderr.write(`captions: ${srt}, ${vtt}\n`);
+		} else if (opts.captions === "sidecar") process.stderr.write("note: --captions sidecar: no narration timing manifest found; run gs narrate first\n");
+	}
+	const cueFiles = a.writeCueSidecars(outAbs, compiled.markers, duration, opts.chapters === "vtt", opts.chapterKinds);
+	if (cueFiles.length) process.stderr.write(`cues: ${cueFiles.join(", ")}\n`);
+	return {
+		frames: total,
+		out: outAbs
+	};
+}
+//#endregion
+export { splitFrameRange as a, shards_exports as i, renderSharded as n, sceneHasGpuNodes as r, ShardError as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.9.1",
+  "version": "0.10.0-pre.0",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,15 +20,15 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "^0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.9.1",
-    "@glissade/core": "0.9.1",
-    "@glissade/interact": "0.9.1",
-    "@glissade/lottie": "0.9.1",
-    "@glissade/svg": "0.9.1",
-    "@glissade/narrate": "0.9.1",
-    "@glissade/player": "0.9.1",
-    "@glissade/scene": "0.9.1",
-    "@glissade/sfx": "0.9.1"
+    "@glissade/backend-skia": "0.10.0-pre.0",
+    "@glissade/core": "0.10.0-pre.0",
+    "@glissade/interact": "0.10.0-pre.0",
+    "@glissade/lottie": "0.10.0-pre.0",
+    "@glissade/svg": "0.10.0-pre.0",
+    "@glissade/narrate": "0.10.0-pre.0",
+    "@glissade/player": "0.10.0-pre.0",
+    "@glissade/scene": "0.10.0-pre.0",
+    "@glissade/sfx": "0.10.0-pre.0"
   },
   "repository": {
     "type": "git",