@glissade/cli 0.6.0 → 0.7.0-pre.0

package/dist/audioMix.js

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./rolldown-runtime.js";
 import { dirname, isAbsolute, resolve } from "node:path";
-import "@glissade/core";
+import { audioOffsetSamples } from "@glissade/core";
 //#region src/audioMix.ts
 /**
 * Audio mixing on the CLI path (DESIGN.md §5.3): the timeline's AudioClip
@@ -78,7 +78,7 @@ function planAudioMix(clips, modulePath, duration) {
 			steps.push(`volume='${gainExpression(clip.gain.keys)}':eval=frame`);
 		}
 		if (clip.at > 0) {
-			const ms = Math.round(clip.at * 1e3);
+			const ms = audioOffsetSamples(clip.at) / 48e3 * 1e3;
 			steps.push(`adelay=${ms}:all=1`);
 		}
 		steps.push("apad");

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as render } from "./render.js";
+import { a as render, i as parseFrameRange } from "./render.js";
 import { n as parseCaptionsMode } from "./captions.js";
 //#region src/cli.ts
 /**
@@ -50,7 +50,9 @@ const USAGE = `usage:
 render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
   --fps <n>        frames per second (default: timeline fps, else 60)
-  --range <a..b>   seconds to render (default: 0..duration)
+  --range <a..b>   integer FRAME indices to render, inclusive (default: whole timeline)
+  --frame <n>      render a single frame index (a still, through the same path)
+  --format png-seq force a PNG sequence even when --out looks like a video
   --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
@@ -156,13 +158,23 @@ async function main() {
 		process.stderr.write(`gs dev: http://localhost:${server.port}/${flags.has("record") ? "  (recording UI on)" : ""}\n`);
 		return;
 	}
-	let range;
+	let frameRange;
 	const rangeFlag = flags.get("range");
-	if (rangeFlag) {
-		const m = /^([\d.]+)\.\.([\d.]+)$/.exec(rangeFlag);
-		if (!m) fail(`--range must be 'a..b' in seconds, got '${rangeFlag}'`);
-		range = [parseFloat(m[1]), parseFloat(m[2])];
+	if (rangeFlag) try {
+		frameRange = parseFrameRange(rangeFlag);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+	const frameFlag = flags.get("frame");
+	let frame;
+	if (frameFlag !== void 0) {
+		if (!/^\d+$/.test(frameFlag)) fail(`--frame must be a non-negative integer frame index, got '${frameFlag}'`);
+		frame = Number(frameFlag);
 	}
+	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");
+	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();
 	try {
@@ -170,7 +182,9 @@ async function main() {
 			modulePath,
 			out: flags.get("out") ?? "out",
 			...fpsFlag ? { fps: parseInt(fpsFlag, 10) } : {},
-			...range ? { range } : {},
+			...frame !== void 0 ? { frame } : {},
+			...frameRange ? { frameRange } : {},
+			...formatFlag === "png-seq" ? { format: "png-seq" } : {},
 			...flags.has("trace") ? { trace: flags.get("trace") } : {},
 			...flags.has("state") ? { state: flags.get("state") } : {},
 			...flags.has("force") ? { force: true } : {},

package/dist/index.d.ts

@@ -8,8 +8,14 @@ interface RenderOptions {
   modulePath: string;
   out: string;
   fps?: number;
-  /** seconds; defaults to [0, duration] */
+  /** seconds; defaults to [0, duration] (programmatic API — the CLI uses frame indices). */
   range?: [number, number];
+  /** inclusive FRAME indices [first, last] (§5: export APIs are frame-indexed). Wins over `range`. */
+  frameRange?: [number, number];
+  /** a single FRAME index — a still through the same path. Wins over `frameRange`/`range`. */
+  frame?: number;
+  /** force a PNG sequence even when `out` has a video extension. */
+  format?: 'png-seq';
   /** InputTrace file: replay → bake → render (v2 §A.6 route 2). */
   trace?: string;
   /** Render one machine state's timeline linearly (route 3). */
@@ -29,6 +35,12 @@ interface RenderOptions {
 declare class SceneModuleError extends Error {
   constructor(modulePath: string, detail: string);
 }
+/**
+ * Parse the CLI `--range a..b` flag as INCLUSIVE integer FRAME indices (§5:
+ * export APIs are frame-indexed; Player APIs are seconds). Decimal or malformed
+ * ranges are rejected, since a frame index is an integer.
+ */
+
 declare function loadSceneModule(modulePath: string): Promise<SceneModule>;
 declare function ffmpegAvailable(): boolean;
 declare function render(opts: RenderOptions): Promise<{

package/dist/index.js

@@ -1,4 +1,4 @@
-import { i as render, n as ffmpegAvailable, r as loadSceneModule, t as SceneModuleError } from "./render.js";
+import { a as render, n as ffmpegAvailable, r as loadSceneModule, t as SceneModuleError } from "./render.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";

package/dist/render.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
-import { evaluate } from "@glissade/scene";
+import { evaluate, withDeterminismGuards } from "@glissade/scene";
 import { SkiaBackend } from "@glissade/backend-skia";
 //#region src/render.ts
 /**
@@ -18,6 +18,19 @@ var SceneModuleError = class extends Error {
 		this.name = "SceneModuleError";
 	}
 };
+/**
+* Parse the CLI `--range a..b` flag as INCLUSIVE integer FRAME indices (§5:
+* export APIs are frame-indexed; Player APIs are seconds). Decimal or malformed
+* ranges are rejected, since a frame index is an integer.
+*/
+function parseFrameRange(flag) {
+	const m = /^(\d+)\.\.(\d+)$/.exec(flag.trim());
+	if (!m) throw new Error(`--range must be integer frames 'a..b' (e.g. 0..120), got '${flag}'`);
+	const a = Number(m[1]);
+	const b = Number(m[2]);
+	if (b < a) throw new Error(`--range end (${b}) is before start (${a})`);
+	return [a, b];
+}
 async function loadSceneModule(modulePath) {
 	const abs = isAbsolute(modulePath) ? modulePath : resolve(process.cwd(), modulePath);
 	const loaded = await createJiti(pathToFileURL(process.cwd() + "/").href).import(pathToFileURL(abs).href, { default: true });
@@ -43,11 +56,19 @@ async function render(opts) {
 	const { compileTimeline } = await import("@glissade/core");
 	const compiled = compileTimeline(doc);
 	const duration = compiled.duration;
-	const [from, to] = opts.range ?? [0, duration];
-	const firstFrame = Math.round(from * fps);
-	const lastFrame = Math.max(firstFrame, Math.ceil(to * fps) - 1);
+	let firstFrame;
+	let lastFrame;
+	if (opts.frame !== void 0) firstFrame = lastFrame = opts.frame;
+	else if (opts.frameRange) {
+		[firstFrame, lastFrame] = opts.frameRange;
+		lastFrame = Math.max(firstFrame, lastFrame);
+	} else {
+		const [from, to] = opts.range ?? [0, duration];
+		firstFrame = Math.round(from * fps);
+		lastFrame = Math.max(firstFrame, Math.ceil(to * fps) - 1);
+	}
 	const total = lastFrame - firstFrame + 1;
-	const isVideo = /\.(mp4|webm)$/i.test(opts.out);
+	const isVideo = opts.format !== "png-seq" && /\.(mp4|webm)$/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 framesDir = isVideo ? mkdtempSync(join(tmpdir(), "glissade-frames-")) : resolve(opts.out);
 	mkdirSync(framesDir, { recursive: true });
@@ -76,7 +97,7 @@ async function render(opts) {
 		}
 	}
 	for (let f = firstFrame; f <= lastFrame; f++) {
-		backend.render(evaluate(scene, doc, f / fps));
+		backend.render(withDeterminismGuards("throw", () => evaluate(scene, doc, f / fps)));
 		writeFileSync(join(framesDir, `frame-${String(f).padStart(5, "0")}.png`), backend.encodePng());
 		opts.onProgress?.(f - firstFrame + 1, total);
 	}
@@ -214,4 +235,4 @@ async function render(opts) {
 	};
 }
 //#endregion
-export { render as i, ffmpegAvailable as n, loadSceneModule as r, SceneModuleError as t };
+export { render as a, parseFrameRange as i, ffmpegAvailable as n, loadSceneModule as r, SceneModuleError as t };

package/package.json

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