@glissade/cli 0.1.0 → 0.3.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/cli.js

@@ -17,7 +17,13 @@ function parseArgs(argv) {
 		if (a.startsWith("--")) {
 			const eq = a.indexOf("=");
 			if (eq >= 0) flags.set(a.slice(2, eq), a.slice(eq + 1));
-			else flags.set(a.slice(2), argv[++i] ?? "");
+			else {
+				const next = argv[i + 1];
+				if (next !== void 0 && !next.startsWith("--")) {
+					flags.set(a.slice(2), next);
+					i++;
+				} else flags.set(a.slice(2), "");
+			}
 		} else positional.push(a);
 	}
 	return {
@@ -27,21 +33,40 @@ function parseArgs(argv) {
 }
 const USAGE = `usage:
   gs render <scene-module> [options]
+  gs dev <scene-module> [--record] [--port <n>]
 
-options:
+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)
+  --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
+
+dev options:
+  --record         add a Record button; writes .trace.json sidecars next to the module
+  --port <n>       listen port (default: any free port)
 `;
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
-	if (command !== "render") {
+	if (command !== "render" && command !== "dev") {
 		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 (command === "dev") {
+		const { dev } = await import("./dev.js").then((n) => n.n);
+		const portFlag = flags.get("port");
+		const server = await dev({
+			modulePath,
+			...portFlag ? { port: parseInt(portFlag, 10) } : {},
+			record: flags.has("record")
+		});
+		process.stderr.write(`gs dev: http://localhost:${server.port}/${flags.has("record") ? "  (recording UI on)" : ""}\n`);
+		return;
+	}
 	let range;
 	const rangeFlag = flags.get("range");
 	if (rangeFlag) {
@@ -57,6 +82,9 @@ async function main() {
 			out: flags.get("out") ?? "out",
 			...fpsFlag ? { fps: parseInt(fpsFlag, 10) } : {},
 			...range ? { range } : {},
+			...flags.has("trace") ? { trace: flags.get("trace") } : {},
+			...flags.has("state") ? { state: flags.get("state") } : {},
+			...flags.has("force") ? { force: true } : {},
 			onProgress: (n, total) => {
 				if (n % 30 === 0 || n === total) process.stderr.write(`\rrendering ${n}/${total} frames`);
 			}

package/dist/dev.js

@@ -0,0 +1,135 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { existsSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { createServer } from "node:http";
+//#region src/dev.ts
+/**
+* gs dev (v2 §C.5): serve the scene with its machines mounted; --record adds
+* a Record button that writes .trace.json sidecars next to the module on
+* stop. This is the walkable capture path — producing a trace must never
+* require a hand-written harness page.
+*/
+var dev_exports = /* @__PURE__ */ __exportAll({ dev: () => dev });
+/** The in-browser harness, bundled fresh per page load (F5 picks up edits). */
+function harnessSource(absModulePath, record) {
+	return `
+import mod from ${JSON.stringify(absModulePath)};
+import { mount } from '@glissade/player';
+import { createMachine, recordTrace } from '@glissade/interact';
+
+const scene = mod.createScene();
+const canvas = document.getElementById('stage');
+canvas.width = scene.size.w;
+canvas.height = scene.size.h;
+const mounted = mount(scene, mod.timeline, canvas, { loop: true, autoplay: true });
+
+const machines = [];
+for (const spec of mod.machines ?? []) {
+  const machine = createMachine(spec.doc, {
+    resolve: (t) => scene.resolveTarget(t),
+    ...(spec.timelines ? { timelines: spec.timelines } : {}),
+  });
+  mounted.player.attach(machine);
+  machine.clock.subscribe(() => mounted.render()); // machine steps repaint even while paused
+  if (spec.wire) spec.wire({ scene, machine, element: canvas });
+  machines.push(machine);
+}
+${record ? `
+const btn = document.getElementById('rec');
+const status = document.getElementById('status');
+btn.style.display = 'inline-block';
+let recs = null;
+btn.onclick = async () => {
+  if (!machines.length) { status.textContent = 'no machines declared by this module'; return; }
+  if (!recs) {
+    recs = machines.map((m) => ({ id: m.id, rec: recordTrace(m) }));
+    btn.textContent = 'Stop & save';
+    status.textContent = 'recording…';
+    return;
+  }
+  const takes = recs.map(({ id, rec }) => ({ id, trace: rec.stop() }));
+  recs = null;
+  btn.textContent = 'Record';
+  const res = await fetch('/__trace', { method: 'POST', body: JSON.stringify(takes) });
+  status.textContent = 'saved ' + (await res.json()).saved.join(', ');
+};` : ""}
+`;
+}
+const PAGE = `<!doctype html>
+<meta charset="utf-8">
+<title>gs dev</title>
+<style>
+  body { margin: 0; background: #16161a; color: #eee; font: 13px system-ui; display: grid; place-items: center; min-height: 100vh; }
+  canvas { box-shadow: 0 4px 24px #000a; background: #fff; }
+  #ui { position: fixed; top: 12px; right: 12px; display: flex; gap: 8px; align-items: center; }
+  #rec { display: none; background: #e0245e; color: #fff; border: 0; border-radius: 6px; padding: 6px 14px; cursor: pointer; }
+</style>
+<div id="ui"><span id="status"></span><button id="rec">Record</button></div>
+<canvas id="stage"></canvas>
+<script type="module" src="/bundle.js"><\/script>
+`;
+function nextTakePath(moduleAbs, machineId) {
+	const dir = dirname(moduleAbs);
+	const base = basename(moduleAbs, extname(moduleAbs));
+	for (let n = 1;; n++) {
+		const p = join(dir, `${base}.${machineId}.take${n}.trace.json`);
+		if (!existsSync(p)) return p;
+	}
+}
+async function dev(opts) {
+	const abs = isAbsolute(opts.modulePath) ? opts.modulePath : resolve(process.cwd(), opts.modulePath);
+	const { build } = await import("esbuild");
+	const bundle = async () => {
+		return (await build({
+			stdin: {
+				contents: harnessSource(abs, opts.record ?? false),
+				resolveDir: dirname(abs),
+				sourcefile: "gs-dev-harness.ts",
+				loader: "ts"
+			},
+			bundle: true,
+			format: "esm",
+			write: false,
+			sourcemap: "inline",
+			logLevel: "silent"
+		})).outputFiles[0].text;
+	};
+	const server = createServer((req, res) => {
+		(async () => {
+			try {
+				if (req.method === "POST" && req.url === "/__trace") {
+					const chunks = [];
+					for await (const c of req) chunks.push(c);
+					const takes = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+					const saved = [];
+					for (const take of takes) {
+						const path = nextTakePath(abs, take.id);
+						writeFileSync(path, JSON.stringify(take.trace, null, 2));
+						saved.push(basename(path));
+						process.stderr.write(`gs dev: wrote ${path}\n`);
+					}
+					res.writeHead(200, { "content-type": "application/json" });
+					res.end(JSON.stringify({ saved }));
+				} else if (req.url === "/bundle.js") {
+					const js = await bundle();
+					res.writeHead(200, { "content-type": "text/javascript" });
+					res.end(js);
+				} else {
+					res.writeHead(200, { "content-type": "text/html" });
+					res.end(PAGE);
+				}
+			} catch (err) {
+				res.writeHead(500, { "content-type": "text/plain" });
+				res.end(err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err));
+			}
+		})();
+	});
+	await new Promise((resolveListen) => server.listen(opts.port ?? 0, () => resolveListen()));
+	const addr = server.address();
+	return {
+		port: typeof addr === "object" && addr ? addr.port : opts.port ?? 0,
+		close: () => new Promise((r) => server.close(() => r()))
+	};
+}
+//#endregion
+export { dev_exports as n, dev as t };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { SceneModule, VideoFrameSource } from "@glissade/scene";
+import { Scene, SceneModule, VideoFrameSource } from "@glissade/scene";
 import { Image } from "@napi-rs/canvas";
-import { AudioClip, Key } from "@glissade/core";
+import { AudioClip, Key, Timeline } from "@glissade/core";
 
 //#region src/render.d.ts
 
@@ -10,6 +10,12 @@ interface RenderOptions {
   fps?: number;
   /** seconds; defaults to [0, duration] */
   range?: [number, number];
+  /** InputTrace file: replay → bake → render (v2 §A.6 route 2). */
+  trace?: string;
+  /** Render one machine state's timeline linearly (route 3). */
+  state?: string;
+  /** Downgrade a trace hash mismatch to a warning. */
+  force?: boolean;
   onProgress?: (frame: number, total: number) => void;
 }
 declare class SceneModuleError extends Error {
@@ -99,4 +105,38 @@ interface EncoderChoice {
 }
 declare function pickEncoder(kind: 'video' | 'audio', container: 'mp4' | 'webm', encoders?: Set<string>): EncoderChoice;
 //#endregion
-export { AudioMixError, type AudioMixPlan, type EncoderChoice, FfmpegVideoFrameSource, NoEncoderError, type RenderOptions, SceneModuleError, type VideoInfo, VideoProbeError, atempoChain, availableEncoders, ffmpegAvailable, gainExpression, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, probeVideo, render, resolveAssetPath };
+//#region src/machines.d.ts
+interface MachineRenderFlags {
+  trace?: string;
+  state?: string;
+  force?: boolean;
+}
+declare class MachineExportError extends Error {
+  constructor(message: string);
+}
+/**
+ * Decide what document to render. No machines: the module timeline, untouched.
+ * With machines: --state merges one state's timeline over the ambient document;
+ * --trace replays and bakes; neither is a hard error listing the routes.
+ */
+declare function resolveRenderDoc(mod: SceneModule, scene: Scene, flags: MachineRenderFlags): Timeline;
+//#endregion
+//#region src/dev.d.ts
+/**
+ * gs dev (v2 §C.5): serve the scene with its machines mounted; --record adds
+ * a Record button that writes .trace.json sidecars next to the module on
+ * stop. This is the walkable capture path — producing a trace must never
+ * require a hand-written harness page.
+ */
+interface DevOptions {
+  modulePath: string;
+  port?: number;
+  record?: boolean;
+}
+interface DevServer {
+  port: number;
+  close(): Promise<void>;
+}
+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 };

package/dist/index.js

@@ -2,4 +2,6 @@ import { i as render, n as ffmpegAvailable, r as loadSceneModule, t as SceneModu
 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";
-export { AudioMixError, FfmpegVideoFrameSource, NoEncoderError, SceneModuleError, VideoProbeError, atempoChain, availableEncoders, ffmpegAvailable, gainExpression, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, probeVideo, render, resolveAssetPath };
+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 };

package/dist/machines.js

@@ -0,0 +1,108 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { readFileSync } from "node:fs";
+import "@glissade/scene";
+import { compileTimeline, timeline } from "@glissade/core";
+import { bakeTrace, createMachine } from "@glissade/interact";
+//#region src/machines.ts
+/**
+* Machine export routes (v2 §A.6): a scene module that declares machines
+* renders only through --trace (record → replay → bake) or --state — anything
+* else is a build error, never a silent freeze-frame. The result is always a
+* plain linear Timeline the rest of the §5 pipeline consumes unchanged.
+*/
+var machines_exports = /* @__PURE__ */ __exportAll({
+	MachineExportError: () => MachineExportError,
+	resolveRenderDoc: () => resolveRenderDoc
+});
+var MachineExportError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MachineExportError";
+	}
+};
+function specTargets(spec) {
+	const targets = /* @__PURE__ */ new Set();
+	for (const [id, s] of Object.entries(spec.doc.states)) {
+		const tl = "ref" in s.timeline ? spec.timelines?.[s.timeline.ref] : s.timeline;
+		if (!tl) throw new MachineExportError(`machine '${spec.doc.id}': state '${id}' references a timeline not in spec.timelines`);
+		for (const t of compileTimeline(tl).tracks.keys()) targets.add(t);
+	}
+	return targets;
+}
+/** §A.1: ambient timeline and every machine must own statically disjoint target sets. */
+function checkDisjoint(ambientTargets, specs) {
+	const owner = /* @__PURE__ */ new Map();
+	for (const t of ambientTargets) owner.set(t, "the scene timeline");
+	for (const spec of specs) for (const t of specTargets(spec)) {
+		const prev = owner.get(t);
+		if (prev) throw new MachineExportError(`target '${t}' is animated by both ${prev} and machine '${spec.doc.id}' — concurrent writers are the silent last-writer-wins §2.2 exists to kill (§A.1)`);
+		owner.set(t, `machine '${spec.doc.id}'`);
+	}
+}
+/**
+* Decide what document to render. No machines: the module timeline, untouched.
+* With machines: --state merges one state's timeline over the ambient document;
+* --trace replays and bakes; neither is a hard error listing the routes.
+*/
+function resolveRenderDoc(mod, scene, flags) {
+	const specs = mod.machines ?? [];
+	if (specs.length === 0) {
+		if (flags.trace || flags.state) throw new MachineExportError("this scene module declares no machines; --trace/--state do not apply");
+		return mod.timeline;
+	}
+	const ambient = compileTimeline(mod.timeline);
+	checkDisjoint(new Set(ambient.tracks.keys()), specs);
+	if (flags.state !== void 0) {
+		if (specs.length !== 1) throw new MachineExportError(`--state needs exactly one machine; this module declares ${specs.length}`);
+		const spec = specs[0];
+		const st = spec.doc.states[flags.state];
+		if (!st) throw new MachineExportError(`--state '${flags.state}': machine '${spec.doc.id}' has no such state (have: ${Object.keys(spec.doc.states).join(", ")})`);
+		const stTl = "ref" in st.timeline ? spec.timelines?.[st.timeline.ref] : st.timeline;
+		if (!stTl) throw new MachineExportError(`state '${flags.state}' references a timeline not in spec.timelines`);
+		return timeline({
+			duration: compileTimeline(stTl).duration,
+			...mod.timeline.fps !== void 0 ? { fps: mod.timeline.fps } : {},
+			...mod.timeline.assets !== void 0 ? { assets: mod.timeline.assets } : {},
+			children: [{
+				timeline: mod.timeline,
+				at: 0,
+				mode: "add"
+			}, {
+				timeline: stTl,
+				at: 0,
+				mode: "add"
+			}]
+		});
+	}
+	if (flags.trace !== void 0) {
+		const trace = JSON.parse(readFileSync(flags.trace, "utf8"));
+		const machines = specs.map((spec) => createMachine(spec.doc, {
+			resolve: (t) => scene.resolveTarget(t),
+			...spec.timelines ? { timelines: spec.timelines } : {}
+		}));
+		let machine = machines.find((m) => m.hash === trace.machineHash);
+		if (!machine) if (flags.force && machines.length === 1) machine = machines[0];
+		else {
+			for (const m of machines) m.dispose();
+			throw new MachineExportError(`trace ${trace.machineHash} matches none of this module's machines — re-record, or pass --force with a single-machine module (§C.5)`);
+		}
+		const baked = bakeTrace(machine, trace, { ...flags.force ? { force: true } : {} });
+		for (const m of machines) m.dispose();
+		return timeline({
+			...mod.timeline.fps !== void 0 ? { fps: mod.timeline.fps } : {},
+			...mod.timeline.assets !== void 0 ? { assets: mod.timeline.assets } : {},
+			children: [{
+				timeline: mod.timeline,
+				at: 0,
+				mode: "add"
+			}, {
+				timeline: baked,
+				at: 0,
+				mode: "add"
+			}]
+		});
+	}
+	throw new MachineExportError(`scene declares ${specs.length} state machine(s): every machine needs an export story (§A.6).\n  --trace <take.trace.json>   record → replay → bake (capture with 'gs dev --record')\n  --state <name>              render one state's timeline linearly`);
+}
+//#endregion
+export { machines_exports as n, resolveRenderDoc as r, MachineExportError as t };

package/dist/render.js

@@ -30,7 +30,12 @@ function ffmpegAvailable() {
 async function render(opts) {
 	const mod = await loadSceneModule(opts.modulePath);
 	const scene = mod.createScene();
-	const doc = mod.timeline;
+	const { resolveRenderDoc } = await import("./machines.js").then((n) => n.n);
+	const 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 { compileTimeline } = await import("@glissade/core");
 	const compiled = compileTimeline(doc);

package/package.json

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