cozyclay 1.2.0 → 1.3.0

package/mcp/ardy-prompts.mjs

@@ -0,0 +1,170 @@
+/**
+ * Writing prompts the way ARDY was trained to read them.
+ *
+ * ARDY's own examples are the specification (nv-tlabs/ardy, scripts/generate.py):
+ *
+ *     python scripts/generate.py "A person walks in a circle."
+ *     python scripts/generate.py "A person jumps." --model core --duration 8.0
+ *     python scripts/generate.py "A person waves." --model g1 --num_samples 4
+ *
+ * Three properties do the work: an explicit subject ("A person"), exactly one
+ * physical action, and a full stop. The demo's preset Prompt List is built the
+ * same way, so this is the distribution the text encoder actually saw.
+ *
+ * The reason one action per prompt matters is architectural, not stylistic:
+ * the interactive demo builds its denoiser with `num_text_tokens=1`
+ * (scripts/interactive_demo/loading.py), so the entire prompt collapses into a
+ * SINGLE conditioning embedding. Two actions in one sentence do not run in
+ * sequence — they average into one confused pose. A sequence of actions is
+ * expressed as a sequence of prompts (CozyClay's Prompt Blocks), never as a
+ * compound sentence.
+ *
+ * What that rules out, and what this module rewrites:
+ *   - no subject            "runs forward"        -> "A person runs forward."
+ *   - compound actions      "stands, then runs"   -> split across phases
+ *   - interior states       "in astonishment"     -> dropped; ARDY animates
+ *                                                    bodies, not feelings
+ *   - camera/scene language "the rocket looms"    -> dropped; the prompt
+ *                                                    describes the BODY only
+ */
+
+/**
+ * Quality policy, mirrored from the studio (App.jsx PROMPT_BLOCK_MAX_FRAMES):
+ * one block never spans more than 4 s. ARDY's trained window is 10 s, but a
+ * long single block drifts — chained 4 s blocks keep each call inside the
+ * model's sweet spot. The studio refuses to generate a longer block, so a tool
+ * that produced one would be authoring something the UI would then reject.
+ */
+export const BLOCK_MAX_SECONDS = 4;
+
+/**
+ * Split a beat that runs longer than the cap into consecutive blocks that do
+ * not. The wording is kept for each piece: continuing the same action is
+ * exactly what the chained-block design is for. Returns whole seconds-ish
+ * spans that sum to the original duration.
+ */
+export function splitLongBeat(seconds, max = BLOCK_MAX_SECONDS) {
+	if (!(seconds > max)) return [seconds];
+	const count = Math.ceil(seconds / max);
+	const even = seconds / count;
+	return Array.from({ length: count }, () => even);
+}
+
+/** Shown in the tool description so a caller writes good phases first time. */
+export const PROMPT_GUIDE = [
+	"ARDY prompt rules (from nv-tlabs/ardy):",
+	'  - One action per phase, phrased like ARDY\'s own examples: "A person walks in a circle."',
+	"  - Subject + single present-tense action + full stop. The prompt becomes ONE embedding",
+	"    (num_text_tokens=1), so two actions in one phase average together instead of playing in order.",
+	"  - Sequence = more phases, never a compound sentence.",
+	`  - A block holds at most ${BLOCK_MAX_SECONDS} s. Longer beats are chained into consecutive blocks,`,
+	"    because a single long block drifts away from its prompt.",
+	"  - Describe the BODY: no emotions, no camera, no scenery, no props the model cannot infer.",
+	"  - WRITE THE AMPLITUDE. A diffusion model regresses toward the mean, so a neutral verb",
+	"    generates a smaller motion than the words suggest. Pick the strong verb and state the",
+	"    magnitude: 'strides forward quickly' over 'walks forward', 'stops abruptly' over 'slows",
+	"    to a stop', 'leans far back and looks straight up' over 'looks up'. Simultaneous detail",
+	"    describing ONE pose is fine; sequential actions still need separate phases.",
+	'  - Good: ["A person strides forward quickly.", "A person stops abruptly.", "A person leans far back and looks straight up."]',
+	'  - Bad:  ["walks forward slowly, then stops abruptly", "staggers back in astonishment"]',
+].join("\n");
+
+/** Interior states and cinematic language ARDY has no body channel for. */
+const UNRENDERABLE = [
+	/\b(in|with)\s+(astonishment|awe|wonder|surprise|fear|joy|excitement|disbelief)\b/gi,
+	/\b(astonished|amazed|awestruck|terrified|delighted|confused|nervous|curious)ly?\b/gi,
+	/\b(as if|like)\s+[^,.]+/gi,
+	/\b(at|toward|towards)\s+(something|the)\s+(enormous|huge|massive|towering|giant)\b/gi,
+	/\b(the\s+)?(camera|shot|frame|rocket|spaceship|building)\b[^,.]*/gi,
+];
+
+/** Connectives that mean "a second action is hiding in this sentence". */
+const SPLIT_ON = /\s*,?\s*\b(?:and then|then|after that|before|while|as)\b\s*/i;
+
+const SUBJECT = /^(a|the)\s+(person|man|woman|character|figure|human)\b/i;
+
+const tidy = (s) =>
+	s
+		.replace(/\s+/g, " ")
+		.replace(/\s+([,.])/g, "$1")
+		.replace(/[,;]+$/, "")
+		.trim();
+
+/**
+ * Rewrite one caller phrase into ARDY's sentence shape.
+ * Returns `{ text, notes }` — notes explain every edit, so a caller can see
+ * why their wording changed rather than silently getting something else.
+ */
+export function normalizePhase(raw) {
+	const notes = [];
+	let s = tidy(String(raw ?? ""));
+	if (!s) return { text: "", notes: ["empty phrase"] };
+
+	for (const pattern of UNRENDERABLE) {
+		if (pattern.test(s)) {
+			s = tidy(s.replace(pattern, ""));
+			notes.push("dropped language ARDY cannot animate (emotion, camera or scenery)");
+			break;
+		}
+	}
+
+	// Keep the first action; a trailing clause belongs in its own phase.
+	const parts = s.split(SPLIT_ON).map(tidy).filter(Boolean);
+	if (parts.length > 1) {
+		s = parts[0];
+		notes.push(`kept the first action; "${parts.slice(1).join(" / ")}" belongs in its own phase`);
+	}
+
+	// A comma usually joins two actions too ("walks forward, stops abruptly").
+	const commaParts = s.split(/\s*,\s*/).map(tidy).filter(Boolean);
+	if (commaParts.length > 1) {
+		s = commaParts[0];
+		notes.push("kept one action per prompt");
+	}
+
+	s = s.replace(/^(and|then|so)\s+/i, "");
+	if (!SUBJECT.test(s)) {
+		s = s.replace(/^[A-Z]/, (c) => c.toLowerCase());
+		s = `A person ${s}`;
+		notes.push('added the subject ARDY expects ("A person ...")');
+	} else {
+		s = s.replace(/^./, (c) => c.toUpperCase());
+	}
+
+	if (!/[.!?]$/.test(s)) {
+		s = `${s}.`;
+		notes.push("closed the sentence");
+	}
+	return { text: tidy(s), notes };
+}
+
+/**
+ * Normalise a whole beat list. A phrase that carried a trailing action gets it
+ * back as its own phase, so "stands up then runs" becomes two real beats
+ * instead of one averaged embedding — capped so a caller cannot blow past the
+ * schema's phase limit.
+ */
+export function normalizePhases(phases, max = 8) {
+	const expanded = [];
+	const sources = [];
+	for (const [index, phase] of phases.entries()) {
+		const pieces = String(phase ?? "")
+			.split(SPLIT_ON)
+			.map(tidy)
+			.filter(Boolean);
+		const parts = pieces.length ? pieces : [phase];
+		expanded.push(...parts);
+		// Which input each output came from, so a caller that attached a duration
+		// to a beat can split that duration across the pieces it became.
+		sources.push(...parts.map(() => index));
+	}
+	const capped = expanded.slice(0, max);
+	const results = capped.map((piece) => normalizePhase(piece));
+	return {
+		texts: results.map((r) => r.text),
+		notes: results.map((r) => r.notes),
+		sources: sources.slice(0, max),
+		expanded: expanded.length > phases.length,
+		dropped: expanded.length - capped.length,
+	};
+}

package/mcp/live-hub.mjs

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+
+import { WebSocket, WebSocketServer } from "ws";
+
+const CLOSE_REPLACED = 4000;
+const COMMAND_TIMEOUT_MS = 5_000;
+
+/**
+ * Transport-only implementation of LIVE-PROTOCOL.md. Scene semantics remain
+ * with the editor and the server's existing CozyClay imports.
+ */
+export class LiveHub {
+	constructor(server = null) {
+		this.server = server;
+		this.editor = null;
+		this.pending = new Map();
+	}
+
+	get connected() {
+		return this.editor?.readyState === WebSocket.OPEN;
+	}
+
+	async command(name, args) {
+		const socket = this.editor;
+		if (!socket || socket.readyState !== WebSocket.OPEN) throw new Error("No live editor is connected.");
+
+		const id = randomUUID();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error(`Live editor timed out running ${name}.`));
+			}, COMMAND_TIMEOUT_MS);
+			this.pending.set(id, { socket, resolve, reject, timer });
+			try {
+				socket.send(JSON.stringify({ type: "cmd", id, name, args }));
+			} catch (error) {
+				clearTimeout(timer);
+				this.pending.delete(id);
+				reject(new Error(`Could not send ${name} to the live editor: ${error.message}`));
+			}
+		});
+	}
+
+	accept(socket) {
+		let greeted = false;
+		socket.on("message", (message, isBinary) => {
+			if (isBinary) return;
+			let frame;
+			try {
+				frame = JSON.parse(message.toString());
+			} catch {
+				return;
+			}
+			if (!greeted) {
+				if (frame?.type !== "hello" || frame.role !== "editor" || frame.version !== 1) {
+					socket.close(1002, "Expected editor hello version 1");
+					return;
+				}
+				greeted = true;
+				const displaced = this.editor;
+				this.editor = socket;
+				if (displaced && displaced !== socket) displaced.close(CLOSE_REPLACED, "Replaced by a newer editor");
+				return;
+			}
+			if (frame?.type !== "result" || typeof frame.id !== "string") return;
+			const pending = this.pending.get(frame.id);
+			if (!pending || pending.socket !== socket) return;
+			clearTimeout(pending.timer);
+			this.pending.delete(frame.id);
+			if (frame.ok === true) pending.resolve(frame.value);
+			else pending.reject(new Error(typeof frame.error === "string" ? frame.error : "Live editor rejected the command."));
+		});
+		socket.on("close", () => this.disconnect(socket));
+		socket.on("error", () => this.disconnect(socket));
+	}
+
+	disconnect(socket) {
+		if (this.editor === socket) this.editor = null;
+		for (const [id, pending] of this.pending) {
+			if (pending.socket !== socket) continue;
+			clearTimeout(pending.timer);
+			this.pending.delete(id);
+			pending.reject(new Error("Live editor disconnected while the command was running."));
+		}
+	}
+}
+
+/** Bind only to loopback. A taken port is an intentional memory-only mode. */
+export async function startLiveHub(port) {
+	let server;
+	try {
+		server = new WebSocketServer({ host: "127.0.0.1", port, path: "/live" });
+		await new Promise((resolve, reject) => {
+			server.once("listening", resolve);
+			server.once("error", reject);
+		});
+	} catch (error) {
+		if (server) server.close();
+		if (error?.code === "EADDRINUSE") return null;
+		throw error;
+	}
+	const hub = new LiveHub(server);
+	server.on("connection", (socket) => hub.accept(socket));
+	return hub;
+}

package/mcp/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "@cozyclay/mcp",
+	"version": "0.1.0",
+	"private": true,
+	"description": "MCP server for CozyClay — block a scene, place the camera, and get film vocabulary and AI prompts back.",
+	"type": "module",
+	"bin": {
+		"cozyclay-mcp": "server.mjs"
+	},
+	"scripts": {
+		"start": "node server.mjs",
+		"verify": "node verify.mjs",
+		"verify:prompts": "node verify-prompts.mjs",
+		"verify:live": "node verify-live.mjs"
+	},
+	"engines": {
+		"node": ">=22"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"ws": "^8.19.0",
+		"zod": "^3.25.0"
+	}
+}