@glissade/cli 0.40.0 → 0.41.0-pre.1

package/dist/cacheVerify.js

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

package/dist/cli.js

@@ -16,6 +16,7 @@ const KNOWN_BOOLEAN_FLAGS = new Set([
 	"fix",
 	"no-warnings",
 	"lossless-intermediate",
+	"incremental",
 	"allow-gpu-shards",
 	"allow-system-fonts",
 	"verbose",
@@ -104,6 +105,11 @@ render options:
   --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)
+  --incremental    dirty-beat: re-render ONLY the frames whose per-frame key changed since the last render, splicing
+                   the rest verbatim from a retained FFV1 intermediate (video out only). WINS the re-narrate / move-one-
+                   beat edit that MISSES the whole-frame cache: a timing shift changes every downstream frame's key, so
+                   the cache re-renders all of them — incremental re-renders only the changed run. A warm splice is
+                   byte-identical to a cold --incremental render. First run builds the intermediate; edits splice it
   --cache[=<dir>]  persistent whole-frame raster cache in <dir> (default .gscache; §3.5). OFF by default — opting in
                    never changes output, only speed. A hit serves a stored frame byte-identical to a cold render.
                    WINS: repeated renders + the UNCHANGED-PREFIX of a single-segment edit. Does NOT win a re-narrate —
@@ -616,6 +622,7 @@ async function main() {
 			...flags.has("allow-system-fonts") ? { allowSystemFonts: true } : {},
 			...workers !== void 0 ? { workers } : {},
 			...flags.has("lossless-intermediate") ? { losslessIntermediate: true } : {},
+			...flags.has("incremental") ? { incremental: true } : {},
 			...flags.has("allow-gpu-shards") ? { allowGpuShards: true } : {},
 			...cache !== void 0 ? { cache } : {},
 			captions: parseCaptionsModeOrFail(flags.get("captions")),

package/dist/index.d.ts

@@ -383,6 +383,17 @@ interface RenderOptions {
    * keyframes (mpeg4 / openh264).
    */
   losslessIntermediate?: boolean;
+  /**
+   * --incremental (§8.1, 0.41 dirty-beat): re-render ONLY the frames whose per-frame
+   * content key changed since the last render, splicing the unchanged runs verbatim
+   * out of a retained FFV1 lossless intermediate. Kills the full re-render an edit
+   * that shifts timing (move one beat) otherwise forces — every downstream frame's
+   * DisplayList shifts, defeating both the whole-frame cache and the remux fast path.
+   * Implies the lossless-intermediate pipeline (FFV1 → single final encode); a warm
+   * splice is byte-identical to a cold `--incremental` render by construction. Video
+   * output only; requires the per-frame key (folds the same context the cache uses).
+   */
+  incremental?: 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
@@ -723,6 +734,7 @@ declare function renderSharded(a: RenderShardedArgs): Promise<{
   frames: number;
   out: string;
 }>;
+/** The FFV1 lossless intermediate retained beside a `--incremental` output for the next splice. */
 //#endregion
 //#region src/videoSource.d.ts
 declare class VideoProbeError extends Error {

package/dist/index.js

@@ -1,5 +1,5 @@
-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 { t as glissadeVersion } from "./version.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 { i as masterCommand, n as MasterError, o as normalizeMasterConfig, r as masterAfChain, s as planMaster, t as DEFAULT_MAX_GR_DB } from "./master.js";
 import { a as pickEncoder, i as parseEncoderList, n as availableEncoders, t as NoEncoderError } from "./encoders.js";

package/dist/mcp.js

@@ -1,5 +1,5 @@
-import { o as loadSceneModule } from "./render.js";
 import { t as glissadeVersion } from "./version.js";
+import { o as loadSceneModule } from "./render.js";
 import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";

package/dist/render.js

@@ -1,4 +1,6 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
+import { t as glissadeVersion } from "./version.js";
+import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -36,6 +38,37 @@ function frameKeyDigest(keys) {
 	}
 	return h.digest("hex");
 }
+/**
+* 0.41 dirty-beat: the changed frames between a prior render's key vector and this
+* render's, as contiguous inclusive [start, end] index ranges (0-based within the
+* range). `null` when incremental is impossible — no prior vector, or the frame
+* COUNT differs (a duration change is a structural re-render, not a splice). An
+* empty array means NOTHING changed (the remux/copy path). A returned range set
+* names exactly the frames to re-render; every other frame is spliced verbatim
+* from the retained lossless intermediate, so the final output is byte-identical
+* to a full cold render (the determinism contract holds through the optimization).
+*/
+function changedFrameRanges(prev, now) {
+	if (prev === void 0 || prev.length !== now.length) return null;
+	const ranges = [];
+	let runStart = -1;
+	for (let i = 0; i < now.length; i++) {
+		const changed = prev[i] !== now[i];
+		if (changed && runStart < 0) runStart = i;
+		else if (!changed && runStart >= 0) {
+			ranges.push({
+				start: runStart,
+				end: i - 1
+			});
+			runStart = -1;
+		}
+	}
+	if (runStart >= 0) ranges.push({
+		start: runStart,
+		end: now.length - 1
+	});
+	return ranges;
+}
 const manifestPathFor = (videoPath) => `${videoPath}.gsrender.json`;
 /** Read the manifest beside a video output, or undefined if absent/unreadable/old-format. */
 function readRenderManifest(videoPath) {
@@ -262,6 +295,45 @@ function parseFrameRange(flag) {
 	if (b < a) throw new Error(`--range end (${b}) is before start (${a})`);
 	return [a, b];
 }
+/**
+* Resolve the `@glissade/core` version the SCENE will bind to (anchored at the
+* scene's own directory, so it's the copy in the user's project), by resolving
+* core's entry and walking up to its package root — `@glissade/core/package.json`
+* isn't an exported subpath, so it can't be required directly. Returns undefined
+* if it can't be resolved (an unusual layout) — the caller then skips the check.
+*/
+function resolveSceneCoreVersion(scenePath) {
+	try {
+		let dir = dirname(createRequire(pathToFileURL(scenePath)).resolve("@glissade/core"));
+		for (let i = 0; i < 8; i++) {
+			const pkgPath = join(dir, "package.json");
+			if (existsSync(pkgPath)) {
+				const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+				if (pkg.name === "@glissade/core") return pkg.version;
+			}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	} catch {}
+}
+/**
+* Warn (once, loudly) on a `@glissade/*` version SKEW between the running `gs`
+* (cli) and the `@glissade/core` the scene resolves. glissade is lockstep, and
+* the subpath side-effect registries (`/expr`'s sampler, Yoga `layout`) register
+* per-package-INSTANCE — so under a skew a correctly-imported `@glissade/core/expr`
+* or `layout` still fails with a misleading "expr tracks need import …" / "no
+* LayoutEngine registered". Naming the skew up front turns a confusing failure
+* into an actionable one. A warning, never a throw: legitimate edge layouts exist,
+* and the check must never break a render (video-canary 0.41 adopt finding).
+*/
+function warnOnVersionSkew(scenePath) {
+	const cliVer = glissadeVersion();
+	if (cliVer === "0.0.0") return;
+	const coreVer = resolveSceneCoreVersion(scenePath);
+	if (coreVer === void 0 || coreVer === cliVer) return;
+	process.stderr.write(`warning: @glissade version skew — gs (@glissade/cli@${cliVer}) is rendering a scene that resolves @glissade/core@${coreVer}.\n  glissade is LOCKSTEP: subpath features register per-package-instance (the /expr sampler, Yoga layout), so under a skew a\n  correctly-imported '@glissade/core/expr' or 'layout' can still fail with "need import" / "no LayoutEngine registered".\n  Align every @glissade/* dependency to ${cliVer} (e.g. npm i @glissade/core@${cliVer} @glissade/scene@${cliVer}).\n`);
+}
 async function loadSceneModule(modulePath, locale) {
 	const { setMessageTable } = await import("@glissade/core/i18n");
 	if (locale !== void 0 && locale !== "") {
@@ -269,13 +341,15 @@ async function loadSceneModule(modulePath, locale) {
 		setMessageTable(loadMessageTable(modulePath, locale));
 	} else setMessageTable(void 0);
 	const abs = isAbsolute(modulePath) ? modulePath : resolve(process.cwd(), modulePath);
-	if (![
+	const candidates = [
 		abs,
 		abs.replace(/\.js$/, ".ts"),
 		abs.replace(/\.ts$/, ".js"),
 		`${abs}.ts`,
 		`${abs}.js`
-	].some((c) => existsSync(c))) throw new SceneModuleError(modulePath, "scene module not found (check the path)");
+	];
+	if (!candidates.some((c) => existsSync(c))) throw new SceneModuleError(modulePath, "scene module not found (check the path)");
+	warnOnVersionSkew(candidates.find((c) => existsSync(c)) ?? abs);
 	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");
 	return loaded;
@@ -422,21 +496,24 @@ async function render(opts) {
 	}
 	let frameCache;
 	let keyCtx;
-	if (opts.cache && opts.cache.mode !== "off") {
-		const { FrameCache, capsId, combineAssetDigests } = await import("./frameCache.js").then((n) => n.s);
-		const { glissadeVersion } = await import("./version.js").then((n) => n.n);
+	const cacheOn = !!(opts.cache && opts.cache.mode !== "off");
+	if (cacheOn || opts.incremental) {
+		const { capsId, combineAssetDigests } = await import("./frameCache.js").then((n) => n.s);
+		keyCtx = {
+			version: glissadeVersion(),
+			capsId: capsId(backend.caps),
+			assetsDigest: combineAssetDigests(assetDigests)
+		};
+	}
+	if (cacheOn) {
+		const { FrameCache } = await import("./frameCache.js").then((n) => n.s);
 		frameCache = new FrameCache({
 			dir: opts.cache.dir,
 			mode: opts.cache.mode,
 			...opts.cache.maxSize !== void 0 ? { maxSize: opts.cache.maxSize } : {}
 		});
-		const version = glissadeVersion();
-		const caps = capsId(backend.caps);
-		keyCtx = {
-			version,
-			capsId: caps,
-			assetsDigest: combineAssetDigests(assetDigests)
-		};
+		const version = keyCtx.version;
+		const caps = keyCtx.capsId;
 		const { LayerCache } = await import("./layerCache.js");
 		backend.setLayerStore(new LayerCache({
 			dir: join(opts.cache.dir, "layers"),
@@ -446,6 +523,7 @@ async function render(opts) {
 	}
 	let videoOut;
 	let remuxDigest;
+	let remuxKeys;
 	if (isVideo) {
 		const outAbs = resolve(opts.out);
 		const container = /\.webm$/i.test(outAbs) ? "webm" : "mp4";
@@ -475,10 +553,36 @@ async function render(opts) {
 					fps,
 					firstFrame,
 					frames: total
-				}, true)) remuxDigest = digest;
+				}, true)) {
+					remuxDigest = digest;
+					remuxKeys = keys;
+				}
 			}
 		}
 	}
+	if (opts.incremental && isVideo && !remuxDigest && keyCtx && total > 1 && videoOut) {
+		const { sceneHasGpuNodes, renderIncremental } = await import("./shards.js").then((n) => n.i);
+		if (sceneHasGpuNodes(scene) && !opts.allowGpuShards) process.stderr.write("note: --incremental skipped — scene has GPU/shader nodes (not reproducible across the splice child process); pass --allow-gpu-shards to override\n");
+		else {
+			backend.dispose();
+			for (const source of videoSources) source.close();
+			return renderIncremental({
+				opts,
+				scene,
+				doc,
+				compiled,
+				keyCtx,
+				fps,
+				duration,
+				firstFrame,
+				lastFrame,
+				container: videoOut.container,
+				timingPathFor,
+				writeCaptionSidecars,
+				writeCueSidecars
+			});
+		}
+	}
 	const frameKeys = [];
 	if (!remuxDigest) for (let f = firstFrame; f <= lastFrame; f++) {
 		const dl = withDeterminismGuards("throw", () => evaluate(scene, doc, f / fps));
@@ -589,7 +693,8 @@ async function render(opts) {
 			videoCodec: videoOut.encName,
 			fps,
 			firstFrame,
-			frames: total
+			frames: total,
+			...remuxKeys && remuxKeys.length === total ? { frameKeys: remuxKeys } : {}
 		});
 		process.stderr.write(`cache: ${total}/${total} frames unchanged (audio-only) — video copy + remux → ${outAbs}\n`);
 		return {
@@ -650,7 +755,8 @@ async function render(opts) {
 		videoCodec: videoOut.encName,
 		fps,
 		firstFrame,
-		frames: total
+		frames: total,
+		frameKeys
 	});
 	return {
 		frames: total,
@@ -883,4 +989,4 @@ async function buildMixWav(opts, wavOut) {
 	});
 }
 //#endregion
-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 };
+export { readRenderManifest as _, ffmpegAvailable as a, parseFrameRange as c, render as d, renderLocales as f, frameKeyDigest as g, changedFrameRanges as h, 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, writeRenderManifest as v };

package/dist/shards.js

@@ -1,12 +1,83 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
-import { u as planFinalAudio } from "./render.js";
+import { _ as readRenderManifest, g as frameKeyDigest, h as changedFrameRanges, u as planFinalAudio, v as writeRenderManifest } 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 { existsSync, mkdirSync, mkdtempSync, renameSync, 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";
+import { ShaderEffect, evaluate, withDeterminismGuards } from "@glissade/scene";
+//#region src/incremental.ts
+/**
+* Dirty-beat incremental (0.41): render ONLY the frames whose per-frame content
+* key actually changed, and splice the rest — verbatim, byte-identical — from a
+* lossless FFV1 intermediate retained beside the prior output.
+*
+* The pain it kills: an edit that shifts timing (move one beat) changes every
+* DOWNSTREAM frame's DisplayList, so every whole-frame cache key misses AND the
+* rolled-up remux digest flips — a 35-min episode re-renders in full even though
+* the visible change is three seconds long. The per-frame key VECTOR (persisted
+* in the manifest, {@link RenderManifest.frameKeys}) lets us diff old→new and
+* re-render exactly the changed runs.
+*
+* Determinism (the north star): FFV1 is intra-only and lossless, so a kept
+* segment decodes to byte-identical pixels and the single final encode over the
+* spliced stream is byte-for-byte a full cold render. The perf optimization does
+* NOT touch the determinism contract — the frame key is the same proof the frame
+* cache and the golden corpus trust. This module is PURE planning; the ffmpeg
+* splice execution (EXPORT-gated) consumes the plan.
+*/
+/**
+* The complement-and-interleave: given the total frame count and the CHANGED
+* ranges (from {@link changedFrameRanges}), produce the ordered, gap-free segment
+* list covering `[0, total-1]` — changed runs become `render`, everything between
+* them becomes `keep`. Adjacent same-kind segments never occur (changed ranges are
+* already coalesced and disjoint), so the list alternates.
+*/
+function spliceSegments(total, changed) {
+	const segs = [];
+	let cursor = 0;
+	for (const r of changed) {
+		if (r.start > cursor) segs.push({
+			start: cursor,
+			end: r.start - 1,
+			kind: "keep"
+		});
+		segs.push({
+			start: r.start,
+			end: r.end,
+			kind: "render"
+		});
+		cursor = r.end + 1;
+	}
+	if (cursor < total) segs.push({
+		start: cursor,
+		end: total - 1,
+		kind: "keep"
+	});
+	return segs;
+}
+/**
+* Decide the incremental strategy. Pure: the caller supplies the prior manifest,
+* this render's ordered keys, and whether the retained FFV1 intermediate exists.
+* Encode-parameter changes (codec/container/fps/range) force `full` — a kept
+* segment is only byte-faithful if the surrounding encode is identical.
+*/
+function planIncremental(prev, nowKeys, intermediateExists, encode) {
+	if (prev === void 0 || !intermediateExists || prev.container !== encode.container || prev.videoCodec !== encode.videoCodec || prev.fps !== encode.fps || prev.firstFrame !== encode.firstFrame || prev.frames !== encode.frames) return { kind: "full" };
+	const changed = changedFrameRanges(prev.frameKeys, nowKeys);
+	if (changed === null) return { kind: "full" };
+	if (changed.length === 0) return { kind: "unchanged" };
+	const renderFrames = changed.reduce((n, r) => n + (r.end - r.start + 1), 0);
+	return {
+		kind: "splice",
+		changed,
+		segments: spliceSegments(nowKeys.length, changed),
+		renderFrames,
+		totalFrames: nowKeys.length
+	};
+}
+//#endregion
 //#region src/shards.ts
 /**
 * Sharded export (DESIGN.md §5.6, §8.1 item 1): `gs render --workers N` splits
@@ -32,6 +103,8 @@ import { ShaderEffect } from "@glissade/scene";
 */
 var shards_exports = /* @__PURE__ */ __exportAll({
 	ShardError: () => ShardError,
+	intermediatePathFor: () => intermediatePathFor,
+	renderIncremental: () => renderIncremental,
 	renderSharded: () => renderSharded,
 	sceneHasGpuNodes: () => sceneHasGpuNodes,
 	splitFrameRange: () => splitFrameRange
@@ -278,5 +351,227 @@ async function renderSharded(a) {
 		out: outAbs
 	};
 }
+/** The FFV1 lossless intermediate retained beside a `--incremental` output for the next splice. */
+function intermediatePathFor(videoPath) {
+	return `${videoPath}.gsintermediate.mkv`;
+}
+/**
+* Dirty-beat incremental render (0.41). Computes the per-frame key vector, diffs
+* it against the prior manifest, and re-renders ONLY the changed frame runs —
+* splicing the unchanged runs verbatim from the retained FFV1 intermediate.
+*
+* ONE pipeline for every outcome: each output segment becomes an FFV1 clip (a
+* `render` segment from a fresh child render; a `keep` segment trimmed losslessly
+* out of the prior intermediate), the clips concat-copy into the new intermediate,
+* and a single final encode produces the output. A cold `--incremental` render is
+* the degenerate all-`render` case, so a warm splice is byte-identical to a cold
+* full render by construction: FFV1 is lossless and intra-only, so a kept segment
+* decodes to the exact pixels a re-render would, and the final encode over the
+* spliced stream is byte-for-byte the cold render. That IS the determinism
+* contract, preserved THROUGH the optimization (the per-frame key is the same
+* proof the frame cache and golden corpus trust).
+*/
+async function renderIncremental(a) {
+	const { opts, scene, doc, compiled, keyCtx, fps, duration, firstFrame, lastFrame, container } = a;
+	const outAbs = resolve(opts.out);
+	const total = lastFrame - firstFrame + 1;
+	const finalEnc = pickEncoder("video", container);
+	if (finalEnc.note) process.stderr.write(`note: ${finalEnc.note}\n`);
+	const { frameCacheKey } = await import("./frameCache.js").then((n) => n.s);
+	const frameKeys = [];
+	for (let f = firstFrame; f <= lastFrame; f++) {
+		const dl = withDeterminismGuards("throw", () => evaluate(scene, doc, f / fps));
+		frameKeys.push(frameCacheKey(dl, keyCtx));
+	}
+	const newDigest = frameKeyDigest(frameKeys);
+	const intermediate = intermediatePathFor(outAbs);
+	const prev = readRenderManifest(outAbs);
+	const plan = planIncremental(prev, frameKeys, existsSync(intermediate), {
+		container,
+		videoCodec: finalEnc.name,
+		fps,
+		firstFrame,
+		frames: total
+	});
+	const segments = plan.kind === "splice" ? [...plan.segments] : plan.kind === "unchanged" ? [{
+		start: 0,
+		end: total - 1,
+		kind: "keep"
+	}] : [{
+		start: 0,
+		end: total - 1,
+		kind: "render"
+	}];
+	const renderFrames = segments.filter((s) => s.kind === "render").reduce((n, s) => n + (s.end - s.start + 1), 0);
+	process.stderr.write(plan.kind === "splice" ? `incremental: ${renderFrames}/${total} frames changed — re-rendering those, splicing ${total - renderFrames} from the intermediate\n` : plan.kind === "unchanged" ? `incremental: 0/${total} frames changed — re-using the intermediate verbatim\n` : `incremental: full render (${prev ? "ineligible for splice" : "no prior intermediate"}) — building the intermediate for next time\n`);
+	const work = mkdtempSync(join(tmpdir(), "glissade-incr-"));
+	const segVideos = [];
+	let done = 0;
+	try {
+		for (let i = 0; i < segments.length; i++) {
+			const seg = segments[i];
+			const segVideo = join(work, `seg-${String(i).padStart(3, "0")}.mkv`);
+			if (seg.kind === "keep") {
+				const t = spawnSync("ffmpeg", [
+					"-y",
+					"-i",
+					intermediate,
+					"-vf",
+					`trim=start_frame=${seg.start}:end_frame=${seg.end + 1},setpts=PTS-STARTPTS`,
+					"-fps_mode",
+					"passthrough",
+					"-c:v",
+					"ffv1",
+					"-level",
+					"3",
+					"-pix_fmt",
+					"rgb24",
+					segVideo
+				], { stdio: [
+					"ignore",
+					"ignore",
+					"pipe"
+				] });
+				if (t.status !== 0) throw new ShardError(`incremental keep-trim [${seg.start}..${seg.end}] failed (exit ${t.status}):\n${t.stderr?.toString().slice(-2e3)}`);
+			} else {
+				const segFrames = join(work, `seg-${String(i).padStart(3, "0")}-frames`);
+				mkdirSync(segFrames, { recursive: true });
+				const first = firstFrame + seg.start;
+				const last = firstFrame + seg.end;
+				const childArgs = [
+					cliEntry(),
+					"render",
+					opts.modulePath,
+					"--out",
+					segFrames,
+					"--range",
+					`${first}..${last}`,
+					"--format",
+					"png-seq",
+					"--fps",
+					String(fps),
+					"--narration",
+					"off",
+					"--music",
+					"off",
+					"--sfx",
+					"off",
+					...opts.force ? ["--force"] : [],
+					...opts.strictFonts ? ["--strict"] : [],
+					...opts.allowSystemFonts ? ["--allow-system-fonts"] : []
+				];
+				const child = spawnSync(process.execPath, childArgs, { stdio: [
+					"ignore",
+					"ignore",
+					"pipe"
+				] });
+				if (child.status !== 0) throw new ShardError(`incremental render [${first}..${last}] failed (exit ${child.status}):\n${child.stderr?.toString().slice(-2e3)}`);
+				const enc = spawnSync("ffmpeg", [
+					"-y",
+					"-framerate",
+					String(fps),
+					"-start_number",
+					String(first),
+					"-i",
+					join(segFrames, "frame-%05d.png"),
+					"-c:v",
+					"ffv1",
+					"-level",
+					"3",
+					"-pix_fmt",
+					"rgb24",
+					segVideo
+				], { stdio: [
+					"ignore",
+					"ignore",
+					"pipe"
+				] });
+				if (enc.status !== 0) throw new ShardError(`incremental segment encode [${first}..${last}] failed (exit ${enc.status}):\n${enc.stderr?.toString().slice(-2e3)}`);
+				rmSync(segFrames, {
+					recursive: true,
+					force: true
+				});
+			}
+			segVideos.push(segVideo);
+			done += seg.end - seg.start + 1;
+			opts.onProgress?.(Math.min(done, total), total);
+		}
+		const listFile = join(work, "concat.txt");
+		writeFileSync(listFile, segVideos.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+		const newIntermediate = join(work, "intermediate.mkv");
+		const concat = spawnSync("ffmpeg", [
+			"-y",
+			"-f",
+			"concat",
+			"-safe",
+			"0",
+			"-i",
+			listFile,
+			"-c",
+			"copy",
+			newIntermediate
+		], { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		if (concat.status !== 0) throw new ShardError(`incremental concat failed (exit ${concat.status}):\n${concat.stderr?.toString().slice(-2e3)}`);
+		const { audioInputs, audioArgs } = await planFinalAudio(opts, [...compiled.audio], duration, container);
+		const fin = spawnSync("ffmpeg", [
+			"-y",
+			"-i",
+			newIntermediate,
+			...audioInputs,
+			...audioArgs,
+			"-c:v",
+			finalEnc.name,
+			...VIDEO_QUALITY[finalEnc.name] ?? [],
+			...container === "webm" ? [] : [
+				"-pix_fmt",
+				"yuv420p",
+				"-movflags",
+				"+faststart"
+			],
+			"-t",
+			String(duration),
+			outAbs
+		], { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		if (fin.status !== 0) throw new ShardError(`incremental final encode failed (exit ${fin.status}):\n${fin.stderr?.toString().slice(-2e3)}`);
+		rmSync(intermediate, { force: true });
+		renameSync(newIntermediate, intermediate);
+		writeRenderManifest(outAbs, {
+			v: 1,
+			frameKeyDigest: newDigest,
+			frameKeys,
+			container,
+			videoCodec: finalEnc.name,
+			fps,
+			firstFrame,
+			frames: total
+		});
+	} 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/dist/version.js

@@ -1,4 +1,3 @@
-import { t as __exportAll } from "./rolldown-runtime.js";
 import { createRequire } from "node:module";
 //#region src/version.ts
 /**
@@ -10,7 +9,6 @@ import { createRequire } from "node:module";
 * single source of truth) rather than hard-coded so it can never drift from the
 * published version.
 */
-var version_exports = /* @__PURE__ */ __exportAll({ glissadeVersion: () => glissadeVersion });
 let cached;
 /** The @glissade/cli package version (the glissade VERSION for the cache key). */
 function glissadeVersion() {
@@ -23,4 +21,4 @@ function glissadeVersion() {
 	return cached;
 }
 //#endregion
-export { version_exports as n, glissadeVersion as t };
+export { glissadeVersion as t };

package/package.json

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