cozyclay 2.0.2 → 2.1.0

package/dist/sitemap.xml

@@ -2,7 +2,7 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://cozyclay.org/</loc>
-    <lastmod>2026-10-01</lastmod>
+    <lastmod>2026-10-08</lastmod>
   </url>
   <url>
     <loc>https://cozyclay.org/greybox-to-video/</loc>

package/dist/workflow/index.html

@@ -8,11 +8,11 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-B5XZwVfe.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-Br-K7Srs.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/analytics-MVZOEW8O.js">
-    <link rel="modulepreload" crossorigin href="/assets/shot-prompt-hN0j_O-p.js">
-    <link rel="stylesheet" crossorigin href="/assets/shot-prompt-CbqWcWYi.css">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-B41FmPYI.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-BCWDJB1d.js">
+    <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-DjJ_cJ2R.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>
   <body>

package/mcp/LIVE-PROTOCOL.md

@@ -144,11 +144,11 @@ scene document already uses.
 | name | args | value | notes |
 | --- | --- | --- | --- |
 | `ping` | `{}` | `{ "pong": true }` | liveness |
-| `describe` | `{}` | `{ document, sceneName, camera, stage, timeline, activeCharacterId, characters, objects }` | read the full live scene document plus active-scene convenience fields; the full `document` prevents one workspace's inactive scenes from leaking into another workspace's scene operations; `activeCharacterId` pins asynchronous work to the character selected when it started |
+| `describe` | `{}` | `{ document, sceneName, previsMode, camera, stage, timeline, activeCharacterId, characters, objects }` | read the full live scene document plus active-scene convenience fields; the full `document` prevents one workspace's inactive scenes from leaking into another workspace's scene operations; `activeCharacterId` pins asynchronous work to the character selected when it started; `previsMode` (`"storyboard"` or `"animation"`, optional for older editors) is the project's previs mode, and a cast entry whose `model` is `proxy-figure` is a capsule figure that `describe_scene` reports as `kind: proxy` (otherwise `kind: rig`) |
 | `capture_frame` | `{}` | `{ width: 640, height: 360, mimeType: "image/png", encoding: "base64", byteSize, data, assertions: { renderable, blackFrame, nonBlackPixels, behindCameraPlane, fartherAlongCameraForward, distanceToFloor, occludedBy, visiblePixelCount, characters } }` | leaves the authored document untouched, but is classified open-world/non-idempotent because an oversized PNG creates a mode-0600 managed temporary artifact. Character visibility and occlusion are computed from mounted engine geometry with bounded ray samples. Missing camera, black frame and compressed payloads above 1 MB fail explicitly. Inline responses honor `max_inline_bytes`; managed artifacts are capped at 20 and expire after 10 minutes. |
 | `capture_framing_png` | `{}` | `{ dataUrl, width: 1920, height: 1080, frame, shotId }` | full-resolution PNG (data URL) of the CURRENT shot camera framing at the current timeline frame, rendered through the same park-and-restore shot pipeline the editor's own exports use; `width`/`height` follow the shot aspect preset (1920x1080 at 16:9) and `shotId` names the shot under the playhead. The viewport and the authored document are untouched (idempotent read), and the editor's 640x360 `capture_frame` contract is unchanged. Fails while no shot camera is mounted (e.g. a cast model is still downloading). |
 | `set_camera` | `{ x?, y?, z?, focalMm?, lookAtX?, lookAtY?, lookAtZ? }` | `{ camera }` | omitted fields keep their value; the **viewport must visibly move**. The `lookAt*` triple is additive to v1 and must arrive complete or not at all: given it, the editor aims the shot camera at that world point and records the resulting orientation as the camera's own (so the framing it commits is the one it just applied); without it the orientation is untouched, so an editor that ignores the fields degrades to the pre-aim behaviour instead of failing. `frame_shot` always sends the framing pivot, because the shot vocabulary (`deriveShot`, `captureFraming`) measures the shot as if the lens points at that pivot — a placed-but-unaimed camera reports a framing it is not holding. |
-| `add_character` | `{ subject, x?, z?, rot?, model? }` | `{ id }` | `model` is one of the stable character model ids |
+| `add_character` | `{ subject, x?, z?, rot?, model?, posture? }` | `{ id }` | `model` is one of the stable character model ids, or `proxy-figure` for a rigless capsule figure; `posture` (`stand`, `sit`, `lie`; `stand` when omitted) applies to a capsule figure |
 | `update_character` | `{ ref, x?, y?, z?, rot?, subject?, hidden? }` | `{ id }` | `ref` = id, letter (`"A"`) or 1-based slot |
 | `remove_character` | `{ ref }` | `{ id }` | must refuse to empty the cast |
 | `place_object` | `{ kind, x?, z?, y?, rot?, name?, parent? }` | `{ id }` | `kind` from OBJECT_LIBRARY; optional `name` labels the object and optional `parent` attaches it under another object |
@@ -162,6 +162,27 @@ scene document already uses.
 | `load_motion` | `{ url, prompt?, blocks?, drop? }` | `{ loaded, url, blocks }` | install an ARDY motion on the selected character. It has the dedicated 30-second editor-processing timeout; motion-job completion carries the character id captured when generation started |
 | `load_scenes` | `{ document }` | `{ sceneName, activeSceneId, scenes: [{ id, name }] }` | replace the whole scene document (same shape `serializeSceneDocument` emits); the response attests the full scene list and active scene for `add_scene` and `switch_scene` parity |
 
+### Previs mode and character kind in the Studio context
+
+`inspect_studio` returns the `studio-context-v1` context that every `run_action`
+is admitted against. Two parts of it describe what a project and its cast can do:
+
+| field | value | meaning |
+| --- | --- | --- |
+| `scene.previsMode` | `"storyboard"` \| `"animation"` | the project's previs mode; optional for older editors |
+| `capabilities.storyboard` | boolean | `true` exactly when `scene.previsMode` is `storyboard` |
+| `entities[].characterKind` | `"rig"` \| `"proxy"` | a rigged model, or a rigless capsule figure (`model: "proxy-figure"`) |
+| `entities[].posture` | `"stand"` \| `"sit"` \| `"lie"` | a capsule figure's posture; absent for a rig |
+
+Before an animation-only tool runs, the server reads these fields from the
+context it admits the command against (`mark_camera_move`, which sends no
+command, reads `previsMode` from `describe`). In a storyboard project `generate_motion`, `set_prompt_blocks`, `load_motion` and
+`mark_camera_move` answer `{ ok: false, code: "NOT_IN_MODE", reason }` and send
+no command; `generate_motion` and `load_motion` on a capsule figure answer
+`{ ok: false, code: "TARGET_NOT_READY", reason }` with the kind's reason. The
+editor's own motion, take, IK and pose commands refuse a capsule figure with
+`TARGET_NOT_READY` as well, so `studio_run` reaches the same answer.
+
 ## Hard rules for the editor side
 
 - Every mutation MUST go through the same React state paths the UI itself

package/mcp/README.md

@@ -35,7 +35,7 @@ Then point a client at it. For Claude Desktop, in `claude_desktop_config.json`:
 }
 ```
 
-Restart the client; 26 tools appear.
+Restart the client; 28 tools appear.
 
 Prefer a long-lived endpoint? `node server.mjs --http 5183` serves Streamable HTTP at
 `http://127.0.0.1:5183/mcp` (one isolated session per client), with a plain status page at `/`.
@@ -68,10 +68,12 @@ generated frame matches the blocking instead of drifting off into a generic shot
 | `capture_frame` | a compressed live render with camera-plane, visibility and occlusion assertions |
 | `set_camera` | move the lens / change focal length directly |
 | `frame_shot` | frame by intent — size, view, level, side |
-| `add_character` / `place_character` / `remove_character` | the cast |
+| `add_character` / `place_character` / `remove_character` | the cast (`add_character { model: "proxy-figure", posture: "stand" \| "sit" \| "lie" }` adds a rigless capsule figure) |
 | `focus_character` | choose who the camera frames |
 | `place_object` / `update_object` / `remove_object` | the set — `place_object` also accepts `name` and `parent`, so multi-part assets like "Building A" land as one named assembly |
 | `import_mesh` | load a local GLB, OBJ or FBX from a filesystem path as a mesh prop (live editor required); optional floor position, yaw, standing height, clay |
+| `sculpt_object` | build a clay prop from a recipe of soft parts (blob, box, cylinder, torus, frame), usually from a reference image; pass `id` with `recipe` to re-sculpt or with `edits` to patch parts; `capture: true` returns the frame too. Works without an editor. Contract: `docs/sculpt-from-image.md` |
+| `compare_sculpt` | score a sculpt's silhouette against its reference image (PNG/JPEG path): IoU, proportion delta, missing area by height band, parts that stick out, and a reference \| overlay sheet; `candidates` ranks up to 12 edit sets without applying any. Works without an editor |
 | `group_objects` | attach children to a parent so they move as one; pass `parent: null` to detach |
 | `apply_batch` | execute up to 100 object mutations as one user-visible undo transaction |
 | `render_prompt` | the shot as an AI image or video prompt |
@@ -131,6 +133,39 @@ result onto the active character with prompt blocks on the timeline. Beats longe
 per-block limit are split into consecutive blocks, so one phase can produce multiple blocks.
 Pass a previous `motion_url` to reload a clip without generating again.
 
+## Storyboard projects and capsule figures
+
+The tool list is fixed when the server starts, so it is the same 28 tools in every project. A
+tool that does not apply to the project or to its target answers a structured refusal instead
+of acting; nothing is sent to the editor and nothing changes. The refusal is the tool's only
+text content, with `isError: true`:
+
+```json
+{ "ok": false, "code": "NOT_IN_MODE", "reason": "This project is a Storyboard - generate_motion is available in Animation projects." }
+```
+
+| code | when | tools |
+| --- | --- | --- |
+| `NOT_IN_MODE` | the project's `previsMode` is `storyboard` | `generate_motion`, `set_prompt_blocks`, `load_motion`, `mark_camera_move` |
+| `TARGET_NOT_READY` | the target character is a capsule figure (`model: "proxy-figure"`) | `generate_motion` (the editor's active character), `load_motion` (its `character`, else the active one) |
+
+`describe_scene` reports `previsMode: storyboard` or `previsMode: animation` (the connected
+editor's project; `open_project` sets it without one) and marks each cast member
+`kind: rig` or `kind: proxy`, with a capsule figure's `posture`.
+
+A **storyboard project** is a sequence of still shots: one picture per panel, held for a
+number of frames, with a caption. Block it with the camera, cast and set tools, and run the
+still-shot commands (`shot.createStill`, `shot.setCaption`, `shot.setHold`, ...) through
+`studio_run`. Motion, prompt blocks and named camera moves belong to Animation projects.
+
+A **capsule figure** is a rigless stand-in for blocking: `add_character { subject, model:
+"proxy-figure", posture: "sit" }`. It places, turns and frames like any cast member and holds a
+posture (`stand`, `sit` or `lie`), but it has no skeleton, so motion and takes are refused with
+`TARGET_NOT_READY` and the kind's reason, for example `Capsule figures have no rig - Motion
+generation works on rigged characters only.` The editor refuses its own IK, pose, physics,
+collision and line-edit commands on a capsule figure with the same code when they arrive
+through `studio_run`. Use a rigged model for anything that moves a body.
+
 ## Round-trips with the studio
 
 `save_project` writes a real `.cclayproject` file, so a scene blocked here opens in the studio to

package/mcp/ardy-prompts.mjs

@@ -200,7 +200,7 @@ export function normalizePhases(phases, max = 8) {
 	const expanded = [];
 	const sources = [];
 	for (const [index, phase] of phases.entries()) {
-		expanded.push(String(phase ?? ""));
+		expanded.push(phase);
 		// Which input each output came from, so a caller that attached a duration
 		// to a beat can still line its beats up with the prompts they produced.
 		sources.push(index);

package/mcp/image-file.mjs

@@ -0,0 +1,132 @@
+// Reference images for sculpt comparison: read a PNG or JPEG from a path into
+// RGBA, and write a PNG back. PNG is decoded here (zlib + the five filters);
+// JPEG goes through jpeg-js. Nothing is sent to a model — the pixels become a
+// silhouette mask on this machine.
+import { constants as fsConstants } from "node:fs";
+import { open as openFile } from "node:fs/promises";
+import { deflateSync, inflateSync } from "node:zlib";
+import jpeg from "jpeg-js";
+
+import { normalizeMeshPath } from "./mesh-file.mjs";
+
+export const REFERENCE_MAX_BYTES = 20 * 1024 * 1024;
+const MAX_PIXELS = 40_000_000;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function paeth(a, b, c) {
+	const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+	return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+/** 8-bit, non-interlaced PNG (grey, grey+alpha, RGB, RGBA, palette) to RGBA. */
+export function decodePng(bytes) {
+	const buf = Buffer.from(bytes);
+	if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) throw new Error("not a PNG");
+	let offset = 8, width = 0, height = 0, depth = 0, type = 0, interlace = 0, palette = null, transparency = null;
+	const idat = [];
+	while (offset + 8 <= buf.length) {
+		const length = buf.readUInt32BE(offset), kind = buf.toString("latin1", offset + 4, offset + 8);
+		const data = buf.subarray(offset + 8, offset + 8 + length);
+		if (kind === "IHDR") {
+			width = data.readUInt32BE(0);
+			height = data.readUInt32BE(4);
+			depth = data[8];
+			type = data[9];
+			interlace = data[12];
+		} else if (kind === "PLTE") palette = data;
+		else if (kind === "tRNS") transparency = data;
+		else if (kind === "IDAT") idat.push(data);
+		else if (kind === "IEND") break;
+		offset += 12 + length;
+	}
+	if (!width || !height) throw new Error("PNG has no image header");
+	if (width * height > MAX_PIXELS) throw new Error(`image is too large (${width}x${height})`);
+	if (depth !== 8 || interlace !== 0) throw new Error("only 8-bit non-interlaced PNGs are supported; re-save it or use a JPEG");
+	const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[type];
+	if (!channels) throw new Error(`unsupported PNG colour type ${type}`);
+	const raw = inflateSync(Buffer.concat(idat));
+	const stride = width * channels;
+	const pixels = Buffer.alloc(stride * height);
+	for (let y = 0; y < height; y += 1) {
+		const filter = raw[y * (stride + 1)];
+		const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+		for (let x = 0; x < stride; x += 1) {
+			const a = x >= channels ? pixels[y * stride + x - channels] : 0;
+			const b = y > 0 ? pixels[(y - 1) * stride + x] : 0;
+			const c = x >= channels && y > 0 ? pixels[(y - 1) * stride + x - channels] : 0;
+			const value = line[x];
+			pixels[y * stride + x] = (filter === 0 ? value : filter === 1 ? value + a : filter === 2 ? value + b : filter === 3 ? value + ((a + b) >> 1) : value + paeth(a, b, c)) & 0xff;
+		}
+	}
+	const rgba = new Uint8Array(width * height * 4);
+	for (let i = 0; i < width * height; i += 1) {
+		const s = i * channels, d = i * 4;
+		if (type === 3) {
+			const index = pixels[s];
+			rgba[d] = palette?.[index * 3] ?? 0; rgba[d + 1] = palette?.[index * 3 + 1] ?? 0; rgba[d + 2] = palette?.[index * 3 + 2] ?? 0;
+			rgba[d + 3] = transparency && index < transparency.length ? transparency[index] : 255;
+		} else if (type === 0 || type === 4) {
+			rgba[d] = rgba[d + 1] = rgba[d + 2] = pixels[s];
+			rgba[d + 3] = type === 4 ? pixels[s + 1] : 255;
+		} else {
+			rgba[d] = pixels[s]; rgba[d + 1] = pixels[s + 1]; rgba[d + 2] = pixels[s + 2];
+			rgba[d + 3] = type === 6 ? pixels[s + 3] : 255;
+		}
+	}
+	return { width, height, data: rgba };
+}
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+	let c = n;
+	for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+	return c >>> 0;
+});
+function crc32(bytes) {
+	let c = 0xffffffff;
+	for (const byte of bytes) c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8);
+	return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(kind, data) {
+	const head = Buffer.alloc(8);
+	head.writeUInt32BE(data.length, 0);
+	head.write(kind, 4, "latin1");
+	const crc = Buffer.alloc(4);
+	crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])), 0);
+	return Buffer.concat([head, data, crc]);
+}
+
+/** RGBA to a PNG buffer (filter 0, deflate level 6). */
+export function encodePng(width, height, rgba) {
+	const header = Buffer.alloc(13);
+	header.writeUInt32BE(width, 0);
+	header.writeUInt32BE(height, 4);
+	header[8] = 8; header[9] = 6;
+	const raw = Buffer.alloc((width * 4 + 1) * height);
+	for (let y = 0; y < height; y += 1) Buffer.from(rgba.buffer, rgba.byteOffset + y * width * 4, width * 4).copy(raw, y * (width * 4 + 1) + 1);
+	return Buffer.concat([PNG_SIGNATURE, chunk("IHDR", header), chunk("IDAT", deflateSync(raw, { level: 6 })), chunk("IEND", Buffer.alloc(0))]);
+}
+
+/** A PNG or JPEG from a local path (file:// and ~/ accepted) as RGBA. */
+export async function readImageFromPath(raw) {
+	const path = normalizeMeshPath(raw);
+	let file;
+	try {
+		file = await openFile(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+	} catch (error) {
+		throw new Error(`Could not read the reference image: ${error.message}`);
+	}
+	try {
+		const stat = await file.stat();
+		if (stat.isDirectory()) throw new Error("The reference path is a directory, not an image.");
+		if (stat.size > REFERENCE_MAX_BYTES) throw new Error(`The reference image is larger than ${REFERENCE_MAX_BYTES / (1024 * 1024)} MB.`);
+		const bytes = await file.readFile();
+		if (bytes.subarray(0, 8).equals(PNG_SIGNATURE)) return decodePng(bytes);
+		if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+			const image = jpeg.decode(bytes, { useTArray: true, formatAsRGBA: true, maxResolutionInMP: MAX_PIXELS / 1e6, maxMemoryUsageInMB: 512 });
+			return { width: image.width, height: image.height, data: image.data };
+		}
+		throw new Error("The reference must be a PNG or a JPEG.");
+	} finally {
+		await file.close();
+	}
+}

package/mcp/live-hub.mjs

@@ -18,7 +18,7 @@ export const STUDIO_COMMAND_TIMEOUT_MS = 30_000;
 const studioCommands = new Set([
 	"inspect_studio", "operate_studio", "arrange_objects", "arrange_characters", "patch_elements",
 	"frame_shot", "verify_result", "undo_edit", "read_studio_context", "resolve_studio_image",
-	"capture_framing_png", "reconcile_studio_command", "run_action",
+	"capture_framing_png", "capture_plan_png", "reconcile_studio_command", "run_action",
 ]);
 
 const mutationCommands = new Set([
@@ -224,7 +224,7 @@ export class LiveHub {
 			baseline(value) { if (mutation) mutation.before = mutationState(mutation.name, value); },
 			receipt(command, value) {
 				if (command === "inspect_studio") {
-					studioContext = value?.context;
+					studioContext = value?.context ?? (value?.host && value?.revision ? { host: value.host, revision: value.revision } : undefined);
 				} else if (command === "run_action") {
 					// The bus attests application itself. No legacy describe diff or
 					// post-ack read may turn an admitted refusal into uncertainty.

package/mcp/package.json

@@ -21,6 +21,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.30.0",
+		"jpeg-js": "0.4.4",
 		"ws": "^8.19.0",
 		"zod": "^3.25.0"
 	}

package/mcp/runtime/package-lock.json

@@ -9,6 +9,7 @@
 			"version": "0.1.0",
 			"dependencies": {
 				"@modelcontextprotocol/sdk": "1.30.0",
+				"jpeg-js": "0.4.4",
 				"three": "0.185.1",
 				"ws": "8.21.3",
 				"zod": "3.25.76"
@@ -677,6 +678,12 @@
 				"url": "https://github.com/sponsors/panva"
 			}
 		},
+		"node_modules/jpeg-js": {
+			"version": "0.4.4",
+			"resolved": "https://registry.npmjs.org/jpeg-js/-/jpeg-js-0.4.4.tgz",
+			"integrity": "sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg==",
+			"license": "BSD-3-Clause"
+		},
 		"node_modules/json-schema-traverse": {
 			"version": "1.0.0",
 			"resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",

package/mcp/runtime/package.json

@@ -9,6 +9,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "1.30.0",
+		"jpeg-js": "0.4.4",
 		"three": "0.185.1",
 		"ws": "8.21.3",
 		"zod": "3.25.76"

package/mcp/server.mjs

@@ -59,8 +59,6 @@ import {
 	sweepCaptureArtifacts,
 } from "./tool-handlers.mjs";
 
-/* ------------------------------ process ---------------------------------- */
-
 sweepCaptureArtifacts();
 process.once("exit", cleanupCaptureArtifacts);
 for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { cleanupCaptureArtifacts(); process.exit(128 + (signal === "SIGINT" ? 2 : 15)); });
@@ -70,8 +68,6 @@ const projectRootPromise = realpath(configuredProjectRoot).then((root) => {
 	return root;
 });
 
-/* ------------------------------- server ---------------------------------- */
-
 /** Tool registrations are counted as they happen so the HTTP status page can
  * report the real number without reaching into SDK internals. */
 let registeredTools = 0;
@@ -149,8 +145,6 @@ const serveRegistryTool = (name, args, workspaceHandle) => {
 // is the order tools/list reports.
 for (const handler of createToolHandlers({ projectRootPromise })) registerTool(handler);
 
-/* -------------------------------- start ---------------------------------- */
-
 /** Counted as the tools are registered, so the status page cannot drift. */
 const TOOL_COUNT = registeredTools;