@glissade/cli 0.2.0 → 0.4.0

package/README.md

@@ -0,0 +1,22 @@
+# @glissade/cli
+
+`gs` — headless rendering and the dev/capture loop. `gs render` evaluates every frame, rasterizes on Skia (no browser anywhere), writes a PNG sequence or muxes mp4/webm via FFmpeg with sample-accurate audio. v2: `gs dev --record` serves a scene with its state machines mounted and writes input-trace sidecars; `gs render --trace/--state` are the deterministic export routes for interactive scenes.
+
+```sh
+npm i -D @glissade/cli
+```
+
+```sh
+gs render scene.ts --out out.mp4 --fps 60
+gs dev scene.ts --record        # capture a take
+gs render scene.ts --trace scene.button.take1.trace.json --out take.mp4
+```
+
+## Part of glissade
+
+*(glide & slide)* — programmatic motion graphics for TypeScript: realtime-first in any web page, deterministic headless video export from the same code, a visual studio over the same document. No generator functions.
+
+- [Repository & full README](https://github.com/tyevco/glissade)
+- [Getting started](https://github.com/tyevco/glissade/blob/main/docs/getting-started.md) · [Concepts](https://github.com/tyevco/glissade/blob/main/docs/concepts.md) · [Interactivity](https://github.com/tyevco/glissade/blob/main/docs/interactivity.md)
+
+Apache-2.0.

package/dist/captions.js

@@ -0,0 +1,71 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { compileTimeline, key, timeline, track } from "@glissade/core";
+import { toSrt, toVtt } from "@glissade/narrate";
+//#region src/captions.ts
+/**
+* Render-time caption handling (--captions burn|sidecar|off). Captions are
+* ordinary document data (a string track + a Text node), so hiding them is a
+* DOCUMENT operation: an override track on 'captions/opacity' merged over
+* the scene doc — never a scene-graph mutation.
+*/
+var captions_exports = /* @__PURE__ */ __exportAll({
+	hideCaptionsDoc: () => hideCaptionsDoc,
+	parseCaptionsMode: () => parseCaptionsMode,
+	timingPathFor: () => timingPathFor,
+	writeCaptionSidecars: () => writeCaptionSidecars
+});
+function parseCaptionsMode(raw) {
+	if (raw === void 0 || raw === "" || raw === "burn") return "burn";
+	if (raw === "sidecar" || raw === "off") return raw;
+	throw new Error(`--captions must be burn, sidecar, or off (got '${raw}')`);
+}
+/** `<module>.narration.timing.json`, when the scene has been narrated. */
+function timingPathFor(modulePath) {
+	const candidate = modulePath.replace(/\.[jt]sx?$/, "") + ".narration.timing.json";
+	return existsSync(candidate) ? candidate : null;
+}
+/**
+* Hide the caption node for sidecar/off renders. The override spans the whole
+* duration: coalescing is last-insertion-wins only inside the later track's
+* key range (§2.2), so a point key would lose to an authored opacity track.
+*/
+function hideCaptionsDoc(doc, captionsId = "captions") {
+	const duration = compileTimeline(doc).duration;
+	const hide = track(`${captionsId}/opacity`, "number", [key(0, 0, { interp: "hold" }), key(Math.max(duration, 1e-6), 0)]);
+	return timeline({
+		duration,
+		...doc.fps !== void 0 ? { fps: doc.fps } : {},
+		...doc.assets !== void 0 ? { assets: doc.assets } : {},
+		children: [{
+			timeline: doc,
+			at: 0,
+			mode: "add"
+		}, {
+			timeline: {
+				version: 1,
+				tracks: [hide]
+			},
+			at: 0,
+			mode: "add"
+		}]
+	});
+}
+/** Write .srt + .vtt next to the render output; returns the paths. */
+function writeCaptionSidecars(timingPath, outPath) {
+	const timing = JSON.parse(readFileSync(timingPath, "utf8"));
+	const isFile = /\.(mp4|webm)$/i.test(outPath);
+	const dir = isFile ? dirname(outPath) : outPath;
+	const stem = isFile ? basename(outPath).replace(/\.(mp4|webm)$/i, "") : "captions";
+	const srt = join(dir, `${stem}.srt`);
+	const vtt = join(dir, `${stem}.vtt`);
+	writeFileSync(srt, toSrt(timing));
+	writeFileSync(vtt, toVtt(timing));
+	return {
+		srt,
+		vtt
+	};
+}
+//#endregion
+export { parseCaptionsMode as n, captions_exports as t };

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { i as render } from "./render.js";
+import { n as parseCaptionsMode } from "./captions.js";
 //#region src/cli.ts
 /**
 * gs — the glissade CLI (DESIGN.md §5.7).
@@ -9,6 +10,13 @@ function fail(msg) {
 	console.error(`gs: ${msg}`);
 	process.exit(1);
 }
+function parseCaptionsModeOrFail(raw) {
+	try {
+		return parseCaptionsMode(raw);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+}
 function parseArgs(argv) {
 	const positional = [];
 	const flags = /* @__PURE__ */ new Map();
@@ -34,6 +42,8 @@ function parseArgs(argv) {
 const USAGE = `usage:
   gs render <scene-module> [options]
   gs dev <scene-module> [--record] [--port <n>]
+  gs import <lottie.json> [--out <dir>] [--allow-degraded]
+  gs narrate <scene-module|script.narration.json> [--provider <id>] [--force]
 
 render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
@@ -42,20 +52,59 @@ render options:
   --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
+  --captions <m>   burn (default) | sidecar | off; burn/sidecar also write .srt/.vtt
 
 dev options:
   --record         add a Record button; writes .trace.json sidecars next to the module
   --port <n>       listen port (default: any free port)
+
+import options:
+  --out <dir>          output directory for the generated scene module (default: .)
+  --allow-degraded     downgrade degradable rejections (expressions, merge-paths modes != 1) to warnings
+
+narrate options (the explicit TTS prepare step; render itself stays offline):
+  --provider <id>  fake | espeak | openai (default: the script's provider, else espeak)
+  --force          ignore the cache and re-synthesize every segment
 `;
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
-	if (command !== "render" && command !== "dev") {
+	if (command !== "render" && command !== "dev" && command !== "import" && command !== "narrate") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
 	const { positional, flags } = parseArgs(rest);
 	const modulePath = positional[0];
-	if (!modulePath) fail(`missing <scene-module>\n${USAGE}`);
+	if (!modulePath) fail(`missing ${command === "import" ? "<lottie.json>" : "<scene-module>"}\n${USAGE}`);
+	if (command === "narrate") {
+		const { narrateCommand } = await import("./narrate.js");
+		try {
+			const result = await narrateCommand({
+				input: modulePath,
+				...flags.has("provider") ? { provider: flags.get("provider") } : {},
+				...flags.has("force") ? { force: true } : {}
+			});
+			const parts = [result.synthesized.length > 0 ? `synthesized ${result.synthesized.join(", ")}` : null, result.reused.length > 0 ? `reused ${result.reused.length} cached` : null].filter(Boolean);
+			process.stderr.write(`gs narrate: ${parts.join("; ") || "nothing to do"} → ${result.timingPath}\n`);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
+	if (command === "import") {
+		const { importCommand } = await import("./import.js").then((n) => n.n);
+		try {
+			const result = await importCommand({
+				input: modulePath,
+				out: flags.get("out") ?? ".",
+				allowDegraded: flags.has("allow-degraded")
+			});
+			for (const w of result.warnings) process.stderr.write(`gs import: warning: ${w}\n`);
+			process.stderr.write(`gs import: wrote ${result.out}\n`);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	if (command === "dev") {
 		const { dev } = await import("./dev.js").then((n) => n.n);
 		const portFlag = flags.get("port");
@@ -85,6 +134,7 @@ async function main() {
 			...flags.has("trace") ? { trace: flags.get("trace") } : {},
 			...flags.has("state") ? { state: flags.get("state") } : {},
 			...flags.has("force") ? { force: true } : {},
+			captions: parseCaptionsModeOrFail(flags.get("captions")),
 			onProgress: (n, total) => {
 				if (n % 30 === 0 || n === total) process.stderr.write(`\rrendering ${n}/${total} frames`);
 			}

package/dist/import.js

@@ -0,0 +1,31 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { generateSceneModule, importLottie } from "@glissade/lottie";
+//#region src/import.ts
+/**
+* gs import (lottie-import.md §3.1): Lottie/bodymovin .json → a generated
+* TypeScript scene module (nodes + inline Timeline) consumable by gs render.
+*/
+var import_exports = /* @__PURE__ */ __exportAll({ importCommand: () => importCommand });
+async function importCommand(opts) {
+	const inputAbs = resolve(opts.input);
+	let json;
+	try {
+		json = JSON.parse(readFileSync(inputAbs, "utf8"));
+	} catch (err) {
+		throw new Error(`${opts.input}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const result = importLottie(json, { allowDegraded: opts.allowDegraded === true });
+	const code = generateSceneModule(result, { source: basename(inputAbs) });
+	const outDir = resolve(opts.out);
+	mkdirSync(outDir, { recursive: true });
+	const outFile = join(outDir, `${basename(inputAbs).replace(/\.json$/i, "")}.ts`);
+	writeFileSync(outFile, code);
+	return {
+		out: outFile,
+		warnings: result.warnings
+	};
+}
+//#endregion
+export { import_exports as n, importCommand as t };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Scene, SceneModule, VideoFrameSource } from "@glissade/scene";
-import { Image } from "@napi-rs/canvas";
 import { AudioClip, Key, Timeline } from "@glissade/core";
+import { Image } from "@napi-rs/canvas";
 
 //#region src/render.d.ts
 
@@ -16,6 +16,8 @@ interface RenderOptions {
   state?: string;
   /** Downgrade a trace hash mismatch to a warning. */
   force?: boolean;
+  /** burn (default): captions render in-frame; sidecar/off hide the caption node. */
+  captions?: 'burn' | 'sidecar' | 'off';
   onProgress?: (frame: number, total: number) => void;
 }
 declare class SceneModuleError extends Error {
@@ -139,4 +141,21 @@ interface DevServer {
 }
 declare function dev(opts: DevOptions): Promise<DevServer>;
 //#endregion
-export { AudioMixError, type AudioMixPlan, type DevOptions, type DevServer, type EncoderChoice, FfmpegVideoFrameSource, MachineExportError, type MachineRenderFlags, NoEncoderError, type RenderOptions, SceneModuleError, type VideoInfo, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, probeVideo, render, resolveAssetPath, resolveRenderDoc };
+//#region src/import.d.ts
+/**
+ * gs import (lottie-import.md §3.1): Lottie/bodymovin .json → a generated
+ * TypeScript scene module (nodes + inline Timeline) consumable by gs render.
+ */
+interface ImportOptions {
+  input: string;
+  /** Output directory; the module is written as <basename>.ts inside it. */
+  out: string;
+  allowDegraded?: boolean;
+}
+interface ImportCommandResult {
+  out: string;
+  warnings: string[];
+}
+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 };

package/dist/index.js

@@ -4,4 +4,5 @@ import { a as planAudioMix, i as gainExpression, n as atempoChain, o as resolveA
 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";
-export { AudioMixError, FfmpegVideoFrameSource, MachineExportError, NoEncoderError, SceneModuleError, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, probeVideo, render, resolveAssetPath, resolveRenderDoc };
+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 };

package/dist/narrate.js

@@ -0,0 +1,20 @@
+import { scriptPathFor, synthesizeScript } from "@glissade/narrate/providers";
+//#region src/narrate.ts
+/**
+* gs narrate — the explicit TTS prepare step. Provider calls happen here and
+* only here; gs render consumes the committed timing manifest + cached wavs,
+* fully offline.
+*/
+async function narrateCommand(opts) {
+	const result = await synthesizeScript(scriptPathFor(opts.input), {
+		...opts.provider !== void 0 ? { provider: opts.provider } : {},
+		...opts.force !== void 0 ? { force: opts.force } : {}
+	});
+	return {
+		timingPath: result.timingPath,
+		synthesized: result.synthesized,
+		reused: result.reused
+	};
+}
+//#endregion
+export { narrateCommand };

package/dist/render.js

@@ -31,12 +31,15 @@ async function render(opts) {
 	const mod = await loadSceneModule(opts.modulePath);
 	const scene = mod.createScene();
 	const { resolveRenderDoc } = await import("./machines.js").then((n) => n.n);
-	const doc = resolveRenderDoc(mod, scene, {
+	let doc = resolveRenderDoc(mod, scene, {
 		...opts.trace !== void 0 ? { trace: opts.trace } : {},
 		...opts.state !== void 0 ? { state: opts.state } : {},
 		...opts.force !== void 0 ? { force: opts.force } : {}
 	});
 	const fps = opts.fps ?? doc.fps ?? 60;
+	const captionsMode = opts.captions ?? "burn";
+	const { hideCaptionsDoc, timingPathFor, writeCaptionSidecars } = await import("./captions.js").then((n) => n.t);
+	if (captionsMode !== "burn" && scene.resolveTarget("captions/opacity") !== void 0) doc = hideCaptionsDoc(doc);
 	const { compileTimeline } = await import("@glissade/core");
 	const compiled = compileTimeline(doc);
 	const duration = compiled.duration;
@@ -79,8 +82,19 @@ async function render(opts) {
 	}
 	backend.dispose();
 	for (const source of videoSources) source.close();
+	const emitSidecars = (target) => {
+		if (captionsMode === "off") return;
+		const timingPath = timingPathFor(opts.modulePath);
+		if (!timingPath) {
+			if (captionsMode === "sidecar") process.stderr.write("note: --captions sidecar: no narration timing manifest found; run gs narrate first\n");
+			return;
+		}
+		const { srt, vtt } = writeCaptionSidecars(timingPath, target);
+		process.stderr.write(`captions: ${srt}, ${vtt}\n`);
+	};
 	if (!isVideo) {
 		if (compiled.audio.length > 0) process.stderr.write("note: PNG-sequence output ignores timeline audio; render to .mp4/.webm to mix it\n");
+		emitSidecars(framesDir);
 		return {
 			frames: total,
 			out: framesDir
@@ -88,6 +102,7 @@ async function render(opts) {
 	}
 	const outAbs = resolve(opts.out);
 	mkdirSync(dirname(outAbs), { recursive: true });
+	emitSidecars(outAbs);
 	const isWebm = /\.webm$/i.test(outAbs);
 	const container = isWebm ? "webm" : "mp4";
 	const { pickEncoder } = await import("./encoders.js").then((n) => n.r);

package/package.json

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