@glissade/cli 0.27.1 → 0.28.0-pre.1

package/dist/cli.js

@@ -76,6 +76,7 @@ const USAGE = `usage:
   gs measure-loudness <scene-module> [--profile <youtube|shorts|podcast|broadcast|ebu>] [--locale <code>]
   gs fonts audit <scene-module>   list registered families, formats, and missing-glyph runs (§3.6)
   gs cache verify <scene-module> [--range a..b] [--sample <n>]   assert cache hits == cold renders (§3.5)
+  gs mcp <scene-module>   start an MCP stdio server for this scene: describe / list_targets / apply_patch / undo / render_frame (the AI-native write layer)
 
 render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
@@ -166,7 +167,7 @@ narration-lint options (lint the committed *.narration.timing.json + the real ca
 `;
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
-	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache") {
+	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -223,6 +224,15 @@ async function main() {
 	const { positional, flags } = parseArgs(rest);
 	const modulePath = positional[0];
 	if (!modulePath) fail(`missing ${command === "import" ? "<lottie.json|asset.svg>" : "<scene-module>"}\n${USAGE}`);
+	if (command === "mcp") {
+		const { startMcpServer } = await import("./mcp.js");
+		try {
+			await startMcpServer(modulePath);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	if (command === "narrate") {
 		const { narrateCommand } = await import("./narrate.js");
 		try {

package/dist/mcp.js

@@ -0,0 +1,340 @@
+import { o as loadSceneModule } from "./render.js";
+import { t as glissadeVersion } from "./version.js";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { evaluate } from "@glissade/scene";
+import { SkiaBackend } from "@glissade/backend-skia";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { emptySidecar, mergeSidecar } from "@glissade/core/sidecar";
+import { applyPatches } from "@glissade/core/studio-host";
+import { describe } from "@glissade/scene/describe";
+//#region src/mcpSession.ts
+/**
+* gs mcp session (0.28): the stateful core behind the AI-native WRITE layer. It
+* holds one loaded scene + its editor sidecar, and exposes the author→render→verify
+* loop as plain methods (mcp.ts wraps them as MCP tools; keeping the logic here
+* makes it unit-testable without the stdio transport):
+*
+*  - describe()      — the API manifest: which props are animatable, per node TYPE.
+*  - listTargets()   — the concrete `<nodeId>/<prop>` targets in THIS scene.
+*  - applyPatch()    — a VALIDATED, REVERSIBLE Timeline Patch batch (records the inverse).
+*  - undo()          — apply the last inverse.
+*  - renderFrame(t)  — render one frame of the (patched) scene → PNG, the verifier.
+*
+* Every seam is a shipped primitive — describe() (0.18, can't drift), Timeline Patch
+* (pure doc→doc, describe-validated, reversible), the sidecar merge, and a single
+* deterministic Skia frame — so the whole loop stays pure. An agent authors, renders,
+* and verifies a scene without ever reading source, and a bad patch can't emit a
+* track for a non-animatable prop (fail-loud at the write boundary).
+*/
+var McpSession = class McpSession {
+	mod;
+	scene;
+	codeTimeline;
+	sidecar = emptySidecar();
+	undoStack = [];
+	constructor(mod) {
+		this.mod = mod;
+		this.scene = mod.createScene();
+		this.codeTimeline = mod.timeline;
+	}
+	static async load(modulePath) {
+		return new McpSession(await loadSceneModule(modulePath));
+	}
+	/** Seed a first edit on a code-only track from the code timeline's baseline (§6.2). */
+	baseline = (timelineId, target) => {
+		if (timelineId !== "main") return null;
+		const tr = this.codeTimeline.tracks.find((t) => t.target === target);
+		return tr ? {
+			type: tr.type,
+			keys: tr.keys
+		} : null;
+	};
+	/** The API manifest — the agent reads which props are animatable (per node type). */
+	describe() {
+		return describe();
+	}
+	/** The concrete animatable `<nodeId>/<prop>` targets in THIS scene (id-substituted). */
+	listTargets() {
+		const manifest = describe();
+		const out = [];
+		for (const [id, node] of this.scene.nodes) {
+			const desc = manifest.nodes[node.describeType];
+			if (!desc) continue;
+			for (const [prop, p] of Object.entries(desc.props)) if (p.animatable && p.target) out.push({
+				target: p.target.replace("<id>", id),
+				nodeId: id,
+				nodeType: node.describeType,
+				prop,
+				type: p.type
+			});
+		}
+		return out;
+	}
+	/**
+	* True if `target` (`<nodeId>/<prop.path>`) is a real animatable target of THIS
+	* scene — the node exists and registered that prop. This is the describe()-backed
+	* write-boundary check (resolveTarget reflects the same registrations describe()
+	* enumerates, PLUS sub-components like `position.x`). Fail-loud on a bad target.
+	*/
+	isValidTarget(target) {
+		const slash = target.indexOf("/");
+		if (slash <= 0) return false;
+		const node = this.scene.nodes.get(target.slice(0, slash));
+		return node !== void 0 && node.resolveTarget(target.slice(slash + 1)) !== void 0;
+	}
+	/** Apply a validated, reversible patch batch. Records the inverse; doc is untouched on error. */
+	applyPatch(patches) {
+		for (const p of patches) if ("target" in p && !this.isValidTarget(p.target)) return {
+			ok: false,
+			error: `'${p.target}' is not an animatable target of this scene (unknown node or non-animatable prop) — call list_targets`
+		};
+		const r = applyPatches(this.sidecar, patches, this.baseline);
+		if (r.ok) {
+			this.sidecar = r.doc;
+			this.undoStack.push(r.inverse);
+		}
+		return r;
+	}
+	/** Undo the last applyPatch (apply its recorded inverse). */
+	undo() {
+		const inv = this.undoStack.pop();
+		if (!inv) return {
+			ok: false,
+			error: "nothing to undo"
+		};
+		const r = applyPatches(this.sidecar, inv, this.baseline);
+		if (r.ok) {
+			this.sidecar = r.doc;
+			return { ok: true };
+		}
+		this.undoStack.push(inv);
+		return {
+			ok: false,
+			error: r.error
+		};
+	}
+	/** The code timeline with the session's edits merged in (what render_frame evaluates). */
+	mergedTimeline() {
+		return mergeSidecar(this.codeTimeline, this.sidecar);
+	}
+	/** How many undoable edits are on the stack. */
+	editCount() {
+		return this.undoStack.length;
+	}
+	/**
+	* Render ONE frame of the current (patched) scene to a PNG — the agent's verifier.
+	* Builds a FRESH scene each call (like `gs render` does per run): the verifier is
+	* stateless, so a track that was added then undone — leaving the sidecar back at a
+	* prior/empty state — can't leave a stale binding on a reused scene instance
+	* (evaluate binds the current timeline's tracks but won't unbind a track absent
+	* from it). This keeps render_frame a pure function of (current merged timeline, t).
+	*/
+	async renderFrame(t, outPath) {
+		const scene = this.mod.createScene();
+		if ([...scene.nodes.values()].some((n) => n.constructor.isLayoutNode === true)) {
+			const { loadYogaLayoutEngine } = await import("@glissade/scene/layout");
+			await loadYogaLayoutEngine();
+		}
+		const dl = evaluate(scene, this.mergedTimeline(), t);
+		const backend = new SkiaBackend(scene.size.w, scene.size.h);
+		try {
+			scene.setTextMeasurer(backend);
+			backend.render(dl);
+			writeFileSync(outPath, backend.encodePng());
+		} finally {
+			backend.dispose();
+		}
+		return {
+			path: outPath,
+			width: scene.size.w,
+			height: scene.size.h
+		};
+	}
+};
+//#endregion
+//#region src/mcp.ts
+/**
+* `gs mcp <scene>` (0.28): the AI-native WRITE layer as an MCP stdio server. It
+* loads one scene and exposes the author→render→verify loop as tools an agent
+* calls WITHOUT reading source — turning describe() from a read-only manifest into
+* a full action space:
+*
+*   describe        → the API manifest (which props are animatable, per node type)
+*   list_targets    → the concrete `<nodeId>/<prop>` animatable targets in THIS scene
+*   apply_patch     → a VALIDATED, REVERSIBLE Timeline Patch batch (returns the inverse)
+*   undo            → revert the last apply_patch
+*   render_frame    → render one frame → a PNG the agent SEES inline (the verifier)
+*   get_timeline    → the current (patched) merged timeline as JSON
+*
+* Lives in `cli` (Node-only) — NEVER on the ≤39 kB embed path. The tool logic is in
+* `mcpSession.ts` (unit-tested); this file is the thin JSON-RPC/stdio wiring.
+*/
+const TOOLS = [
+	{
+		name: "describe",
+		description: "The glissade API manifest: every node type with its props (animatable ones carry a track target template), value types, easings, builder methods and helpers. Read this to know what is animatable before patching.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		}
+	},
+	{
+		name: "list_targets",
+		description: "The concrete animatable targets of the LOADED scene: for every node, its '<nodeId>/<prop>' track targets (id-substituted) + the value type each expects. Patch only these.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		}
+	},
+	{
+		name: "apply_patch",
+		description: "Apply a batch of Timeline Patch ops to the scene's edit sidecar — validated (a target that isn't animatable on this scene is rejected before it touches the doc) and reversible (undo restores it). Ops: setTrackKeys/removeTrack/addKey/removeKey/moveKey/setKeyValue/setKeyEase/setLabel/removeLabel. Each track op carries { op, timelineId:'main', target:'<id>/<prop>', ... }.",
+		inputSchema: {
+			type: "object",
+			properties: { patches: {
+				type: "array",
+				items: { type: "object" },
+				description: "TimelinePatch[]"
+			} },
+			required: ["patches"],
+			additionalProperties: false
+		}
+	},
+	{
+		name: "undo",
+		description: "Revert the most recent apply_patch (apply its recorded inverse).",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		}
+	},
+	{
+		name: "render_frame",
+		description: "Render ONE frame of the current (patched) scene at time t (seconds) to a PNG and return it inline as an image — the deterministic verifier. Call it after a patch to SEE the result.",
+		inputSchema: {
+			type: "object",
+			properties: { t: {
+				type: "number",
+				description: "time in seconds",
+				minimum: 0
+			} },
+			required: ["t"],
+			additionalProperties: false
+		}
+	},
+	{
+		name: "get_timeline",
+		description: "The current merged timeline (code + your edits) as JSON — tracks, labels, duration.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		}
+	}
+];
+const text = (value) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(value, null, 2)
+}] });
+/** Start the gs mcp stdio server for a scene module. Resolves when the transport closes. */
+async function startMcpServer(modulePath) {
+	const session = await McpSession.load(modulePath);
+	const frameDir = mkdtempSync(join(tmpdir(), "gs-mcp-frames-"));
+	const server = new Server({
+		name: "glissade",
+		version: glissadeVersion()
+	}, { capabilities: { tools: {} } });
+	server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map((t) => ({ ...t })) }));
+	server.setRequestHandler(CallToolRequestSchema, async (req) => {
+		const { name, arguments: args = {} } = req.params;
+		try {
+			switch (name) {
+				case "describe": return text(session.describe());
+				case "list_targets": return text(session.listTargets());
+				case "get_timeline": return text(session.mergedTimeline());
+				case "apply_patch": {
+					const patches = args.patches;
+					if (!Array.isArray(patches)) return {
+						content: [{
+							type: "text",
+							text: "error: `patches` must be an array of TimelinePatch ops"
+						}],
+						isError: true
+					};
+					const r = session.applyPatch(patches);
+					return r.ok ? text({
+						ok: true,
+						edits: session.editCount(),
+						inverse: r.inverse
+					}) : {
+						content: [{
+							type: "text",
+							text: `patch rejected: ${r.error}`
+						}],
+						isError: true
+					};
+				}
+				case "undo": {
+					const r = session.undo();
+					return r.ok ? text({
+						ok: true,
+						edits: session.editCount()
+					}) : {
+						content: [{
+							type: "text",
+							text: r.error ?? "undo failed"
+						}],
+						isError: true
+					};
+				}
+				case "render_frame": {
+					const t = Number(args.t);
+					if (!Number.isFinite(t) || t < 0) return {
+						content: [{
+							type: "text",
+							text: "error: `t` must be a number ≥ 0 (seconds)"
+						}],
+						isError: true
+					};
+					const out = join(frameDir, `frame-${Date.now()}.png`);
+					const info = await session.renderFrame(t, out);
+					const b64 = readFileSync(out).toString("base64");
+					return { content: [{
+						type: "text",
+						text: `rendered ${info.width}×${info.height} @ t=${t}s → ${out}`
+					}, {
+						type: "image",
+						data: b64,
+						mimeType: "image/png"
+					}] };
+				}
+				default: return {
+					content: [{
+						type: "text",
+						text: `unknown tool: ${name}`
+					}],
+					isError: true
+				};
+			}
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: `error: ${err instanceof Error ? err.message : String(err)}`
+				}],
+				isError: true
+			};
+		}
+	});
+	await server.connect(new StdioServerTransport());
+	await new Promise((resolve) => server.onclose = resolve);
+}
+//#endregion
+export { startMcpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.27.1",
+  "version": "0.28.0-pre.1",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "engines": {
@@ -20,18 +20,19 @@
     "dist"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.27.1",
-    "@glissade/core": "0.27.1",
-    "@glissade/interact": "0.27.1",
-    "@glissade/lottie": "0.27.1",
-    "@glissade/svg": "0.27.1",
-    "@glissade/narrate": "0.27.1",
-    "@glissade/player": "0.27.1",
-    "@glissade/scene": "0.27.1",
-    "@glissade/sfx": "0.27.1"
+    "@glissade/backend-skia": "0.28.0-pre.1",
+    "@glissade/core": "0.28.0-pre.1",
+    "@glissade/interact": "0.28.0-pre.1",
+    "@glissade/lottie": "0.28.0-pre.1",
+    "@glissade/narrate": "0.28.0-pre.1",
+    "@glissade/player": "0.28.0-pre.1",
+    "@glissade/scene": "0.28.0-pre.1",
+    "@glissade/sfx": "0.28.0-pre.1",
+    "@glissade/svg": "0.28.0-pre.1"
   },
   "repository": {
     "type": "git",