cozyclay 2.0.2 → 2.1.1

package/mcp/tool-handlers.mjs

@@ -30,6 +30,8 @@ import { z } from "zod";
 
 import { MAX_COMMAND_TIMEOUT_MS } from "./live-hub.mjs";
 import { readMeshFromPath } from "./mesh-file.mjs";
+import { encodePng, readImageFromPath } from "./image-file.mjs";
+import { rankingRow, scoreSculptAgainstReference } from "../src/sculpt-compare.js";
 import { DEFAULT_POSE } from "../src/poses.js";
 import { generationArgs } from '../src/motion/generation.js';
 import { BLOCK_MAX_SECONDS, PROMPT_GUIDE, normalizePhases, splitLongBeat, tileClipFrames } from "./ardy-prompts.mjs";
@@ -47,31 +49,37 @@ import {
 	slateLine,
 } from "../src/shot.js";
 import {
-	CHARACTER_MODEL_IDS,
+	CHARACTER_KIND_IDS,
+	POSTURES,
 	activeScene,
+	isProxyFigure,
 	addScene,
 	createCharacterEntry,
 	createSceneDocument,
 	readSceneDocument,
 	serializeSceneDocument,
 } from "../src/scenes.js";
+import { normalizeSculptRecipe, patchSculptRecipe } from "../src/sculpt-recipe.js";
 import {
 	OBJECT_LIBRARY,
+	SCULPT_KIND,
 	createSceneObject,
+	createSculptObject,
 	objectSize,
 	removeSceneObject,
 	setSceneObjectParent,
 	updateSceneObject,
 } from "../src/scene-objects.js";
 import { classifyMove, captureFraming, moveSlate } from "../src/camera-move.js";
-import { createProjectDocument, readProjectDocument } from "../src/project.js";
-
-/* ------------------------------- state ---------------------------------- */
+import { DEFAULT_PREVIS_MODE, PREVIS_MODES, createProjectDocument, readProjectDocument } from "../src/project.js";
+import { kindRefusal } from "../src/character-kind.js";
 
 /** The authoring state. One scene document, one camera, one project name. */
 export const state = {
 	doc: createSceneDocument(),
 	name: "Untitled",
+	/** the project's previs mode ("storyboard" | "animation"); the live editor reports it with every describe */
+	previsMode: DEFAULT_PREVIS_MODE,
 	camera: { x: 0, y: 1.6, z: 4.5, focalMm: 35 },
 	timeline: { currentFrame: 0, frameCount: 360, fps: 24 },
 	/** which character the camera frames against; null means the first of the cast */
@@ -97,7 +105,7 @@ export const liveWorkspace = new AsyncLocalStorage();
 const liveWorkspaceTools = new Set([
 	"describe_scene", "describe_shot", "render_prompt", "mark_camera_move", "describe_camera_move", "save_project",
 	"set_camera", "frame_shot", "add_character", "place_character", "remove_character",
-	"focus_character", "place_object", "import_mesh", "group_objects", "set_prompt_blocks", "generate_motion", "update_object",
+	"focus_character", "place_object", "import_mesh", "sculpt_object", "compare_sculpt", "group_objects", "set_prompt_blocks", "generate_motion", "update_object",
 	"remove_object", "apply_batch", "add_scene", "switch_scene", "open_project", "capture_frame", "load_motion",
 	"studio_commands", "studio_run",
 ]);
@@ -153,6 +161,8 @@ const TOOL_ANNOTATIONS = Object.freeze({
 	focus_character: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
 	place_object: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
 	import_mesh: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+	sculpt_object: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+	compare_sculpt: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 	group_objects: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
 	set_prompt_blocks: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
 	load_motion: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
@@ -176,6 +186,15 @@ const TOOL_ANNOTATIONS = Object.freeze({
 /** The document identity a Studio command is admitted in. */
 const STUDIO_IDENTITY_KEYS = ["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"];
 
+/** The Studio context behind an inspect answer. inspect_studio answers the
+ * revision and document identity, not the whole context (older editors embedded
+ * it); entities, selection and the mode are read apart, at that identity. */
+const contextOf = async (inspected, workspaceHandle = liveWorkspace.getStore()) => {
+	if (inspected?.context) return inspected.context;
+	if (!inspected?.host || !Number.isSafeInteger(inspected.revision?.scene)) return undefined;
+	const read = await liveHub.command("read_studio_context", { host: inspected.host }, workspaceHandle);
+	return read?.context ?? read;
+};
 /** One registered editor command through the editor's own bus, admitted at
  * the open document and its current revision like the agent's run_action. Its
  * declaration (read from the editor, never from this server) sets the hub
@@ -183,15 +202,18 @@ const STUDIO_IDENTITY_KEYS = ["workspaceId", "documentEpoch", "sceneId", "sceneE
 const executeStudioCommand = async ({ action, args, expectedRevision, commandId, timeoutMs, confirmationToken, inspected }) => {
 	const workspaceHandle = liveWorkspace.getStore();
 	inspected ??= await liveHub.command("inspect_studio", { scope: "actions", ids: [action] }, workspaceHandle);
-	const context = inspected?.context;
+	const context = await contextOf(inspected, workspaceHandle);
 	if (!context?.host || !Number.isSafeInteger(context.revision?.scene)) throw new Error("The editor did not return a Studio context to admit this command against.");
+	// Admission stays at the revision the inspect answered: an edit that lands
+	// between that inspect and the context read is the editor's to refuse (STALE_SCENE).
+	const inspectedRevision = Number.isSafeInteger(inspected?.revision?.scene) ? inspected.revision.scene : context.revision.scene;
 	const declared = inspected.actions?.find((row) => row.id === action);
 	const receipt = await liveHub.command("run_action", {
 		name: "run_action",
 		args: { action, args: typeof args === "function" ? await args(context) : args ?? {}, ...(confirmationToken ? { confirmationToken } : {}) },
 		commandId: commandId ?? randomUUID(),
 		host: Object.fromEntries(STUDIO_IDENTITY_KEYS.map((key) => [key, context.host[key]])),
-		expectedRevision: expectedRevision ?? context.revision.scene,
+		expectedRevision: expectedRevision ?? inspectedRevision,
 	}, workspaceHandle, { timeoutMs: timeoutMs ?? (declared?.timeoutMs === undefined ? undefined : Math.min(MAX_COMMAND_TIMEOUT_MS, declared.timeoutMs + (declared.generation ? 5000 : 0))) });
 	return receipt;
 };
@@ -202,6 +224,27 @@ const studioResult = (...receipts) => ({
 });
 const runStudioCommand = async options => studioResult(await executeStudioCommand(options));
 
+// The tool list is fixed when the server starts, so a tool the project's mode
+// or the target's kind cannot run answers a structured refusal instead of acting.
+const refusal = (code, reason) => ({ content: [{ type: "text", text: JSON.stringify({ ok: false, code, reason }) }], isError: true });
+
+/** NOT_IN_MODE in a storyboard project; TARGET_NOT_READY when `feature` is given
+ * and the target (`characterId`, else the active character) is a capsule figure.
+ * Null when the tool may run. `context` is the connected editor's Studio context;
+ * without one the in-memory project answers. */
+const previsRefusal = (toolName, { feature, context, characterId } = {}) => {
+	if ((context ? context.scene?.previsMode : state.previsMode) === "storyboard") {
+		return refusal("NOT_IN_MODE", `This project is a Storyboard - ${toolName} is available in Animation projects.`);
+	}
+	if (!feature) return null;
+	const proxy = context
+		? context.entities?.find((entity) => entity.id === (characterId ?? context.activeCharacterId))?.characterKind === "proxy"
+		: isProxyFigure(findCharacter(characterId ?? state.focus));
+	return proxy ? refusal("TARGET_NOT_READY", kindRefusal(feature)) : null;
+};
+/** The Studio context and one command's declaration, as executeStudioCommand admits it. */
+const inspectAction = (action) => liveHub.command("inspect_studio", { scope: "actions", ids: [action] }, liveWorkspace.getStore());
+
 const scene = () => activeScene(state.doc.scenes, state.doc.activeSceneId);
 const stage = () => scene().stage;
 
@@ -299,6 +342,7 @@ const applyLiveDescription = (description) => {
 		if (!parsed.document) throw new Error("Live editor returned an invalid scene document.");
 		state.doc = parsed.document;
 	}
+	if (PREVIS_MODES.includes(description.previsMode)) state.previsMode = description.previsMode;
 	const sc = scene();
 	if (typeof description.sceneName === "string" && description.sceneName) sc.name = description.sceneName;
 	if (description.camera && typeof description.camera === "object") {
@@ -339,11 +383,11 @@ const applyLiveDescription = (description) => {
 			// A") defeats the name match, and a record without a renderer survives
 			// the save but cannot be drawn after the load.
 			const kind =
-				(typeof object.renderer === "string" && OBJECT_LIBRARY.some((entry) => entry.kind === object.renderer)
+				(typeof object.renderer === "string" && (object.renderer === SCULPT_KIND || OBJECT_LIBRARY.some((entry) => entry.kind === object.renderer))
 					? object.renderer
 					: null) ??
 				OBJECT_LIBRARY.find(({ label }) => object.name === label || object.name?.startsWith(`${label} `))?.kind;
-			const defaults = previous ?? (kind ? createSceneObject(kind, sc.objects, object) : null);
+			const defaults = previous ?? (kind === SCULPT_KIND ? createSculptObject({ recipe: object.recipe }, sc.objects, object).object ?? null : kind ? createSceneObject(kind, sc.objects, object) : null);
 			// The editor is the source of truth for anything it reports; the
 			// library defaults only fill what the frame omits. Defaulting AFTER
 			// the spread would reset a reported scale back to 1 and make every
@@ -372,7 +416,64 @@ const liveError = (error) => ({
 	isError: true,
 });
 
-/* ------------------------------ formatting ------------------------------- */
+/** capture_frame's checked frame as a tool result; sculpt_object { capture: true } reuses it. */
+const captureFrameResult = async (maxInlineBytes) => {
+	if (!liveHub?.connected) return liveError(new Error(noLiveEditor("capture_frame requires a connected CozyClay editor with a renderable shot camera.")));
+		try {
+			const workspaceHandle = liveWorkspace.getStore();
+			const frame = await liveHub.command("capture_frame", {}, workspaceHandle);
+			const beforeHash = createHash("sha256").update(frame?.authoredStateBefore ?? "").digest("hex");
+			const afterHash = createHash("sha256").update(frame?.authoredStateAfter ?? "").digest("hex");
+			if (beforeHash !== afterHash) {
+				throw new Error(`capture_frame changed authored editor state; capture was rejected (${beforeHash} -> ${afterHash}).`);
+			}
+			if (!frame || frame.width !== 640 || frame.height !== 360 || frame.mimeType !== "image/png" || typeof frame.data !== "string") {
+				throw new Error("Live editor returned an invalid capture payload.");
+			}
+			const bytes = Buffer.from(frame.data, "base64");
+			if (bytes.length === 0 || bytes.length !== frame.byteSize || bytes.length > MAX_CAPTURE_BYTES) {
+				throw new Error(`Live editor returned an invalid compressed image size (maximum ${MAX_CAPTURE_BYTES} bytes).`);
+			}
+			if (frame.assertions?.renderable !== true || frame.assertions?.blackFrame === true) {
+				throw new Error("Live editor rejected the capture as non-renderable or black.");
+			}
+			const metadata = {
+				width: frame.width,
+				height: frame.height,
+				mimeType: frame.mimeType,
+				encoding: frame.encoding,
+				byteSize: frame.byteSize,
+				assertions: frame.assertions,
+				stateHashBefore: beforeHash,
+				stateHashAfter: afterHash,
+			};
+			if (bytes.length > maxInlineBytes) {
+				while (captureArtifacts.length >= MAX_CAPTURE_ARTIFACTS) {
+					const oldest = captureArtifacts.shift();
+					await unlink(oldest).catch(() => {});
+				}
+				const path = join(tmpdir(), `cozyclay-capture-${randomUUID()}.png`);
+				await writeFile(path, bytes, { mode: 0o600 });
+				captureArtifacts.push(path);
+				const expiry = setTimeout(() => {
+					const index = captureArtifacts.indexOf(path);
+					if (index >= 0) captureArtifacts.splice(index, 1);
+					void unlink(path).catch(() => {});
+				}, CAPTURE_ARTIFACT_TTL_MS);
+				expiry.unref?.();
+				return text(JSON.stringify({ ...metadata, artifact: { path, width: frame.width, height: frame.height, byteSize: bytes.length } }));
+			}
+			return {
+				content: [
+					{ type: "text", text: JSON.stringify({ ...metadata, image: { transport: "inline", width: frame.width, height: frame.height, byteSize: bytes.length } }) },
+					{ type: "image", data: frame.data, mimeType: frame.mimeType },
+				],
+			};
+		} catch (error) {
+			return liveError(error);
+		}
+};
+
 
 const round = (n, places = 2) => Number(n.toFixed(places));
 const metres = (n) => `${round(n)}m`;
@@ -393,6 +494,7 @@ function sceneReport({ characterCursor = 0, objectCursor = 0, limit = 50 } = {})
 	const lines = [
 		`Project: ${state.name}`,
 		`Scene: ${sc.name}  (${state.doc.scenes.length} scene${state.doc.scenes.length === 1 ? "" : "s"} in project)`,
+		`previsMode: ${state.previsMode}`,
 		"",
 		"CAMERA",
 		`  position   x ${round(state.camera.x)}  y ${round(state.camera.y)}  z ${round(state.camera.z)}`,
@@ -411,7 +513,7 @@ function sceneReport({ characterCursor = 0, objectCursor = 0, limit = 50 } = {})
 				`facing ${round(c.rot, 1)}deg  [${c.model}]` +
 				`${c.pose ? " posed" : ""}${c.hidden ? " hidden" : ""}` +
 				`${c === framed ? "  <- framed" : ""}`,
-			`    model: ${c.model}  pose: ${JSON.stringify(c.pose ?? null)}  tint: ${c.tint ?? null}  scale: ${c.scale ?? 1}`,
+			`    model: ${c.model}  kind: ${isProxyFigure(c) ? "proxy" : "rig"}${isProxyFigure(c) ? `  posture: ${c.posture ?? "stand"}` : ""}  pose: ${JSON.stringify(c.pose ?? null)}  tint: ${c.tint ?? null}  scale: ${c.scale ?? 1}`,
 			`    motionRef: ${JSON.stringify(c.motionRef ?? null)}`,
 			`    layer: ${JSON.stringify({ waypoints: c.layer?.waypoints ?? [], promptClips: c.layer?.promptClips ?? [] })}`,
 		);
@@ -427,13 +529,13 @@ function sceneReport({ characterCursor = 0, objectCursor = 0, limit = 50 } = {})
 				`  ${object.id}  ${object.name}  at x ${round(object.x)}, y ${round(object.y)}, z ${round(object.z)}` +
 					`  yaw ${round(object.rot, 1)}deg  size ${round(size.width)}x${round(size.height)}x${round(size.depth)}m` +
 					`${object.hidden ? " hidden" : ""}`,
-				`    rotX: ${round(object.rotX ?? 0, 1)}  rotZ: ${round(object.rotZ ?? 0, 1)}  color: ${object.color ?? null}  parent: ${object.parent ?? null}`,
+				`    rotX: ${round(object.rotX ?? 0, 1)}  rotZ: ${round(object.rotZ ?? 0, 1)}  color: ${object.color ?? null}${object.opacity < 1 ? `  opacity: ${round(object.opacity, 2)}` : ""}  parent: ${object.parent ?? null}`,
 			);
 			if (object.path?.points?.length >= 2) {
 				const points = object.path.points;
 				const first = points[0];
 				const last = points[points.length - 1];
-				lines.push(`    path: ${points.length} pts  (${round(first.x, 1)},${round(first.z, 1)}) → (${round(last.x, 1)},${round(last.z, 1)})  speed: ${object.path.speed || "fills take"}${object.path.extend ? "  keeps going" : ""}${object.path.loop ? "  loops" : ""}`);
+				lines.push(`    path: ${points.length} pts  (${round(first.x, 1)},${round(first.z, 1)}) → (${round(last.x, 1)},${round(last.z, 1)})  speed: ${object.path.speed || "fills take"}${object.path.extend ? "  keeps going" : ""}${object.path.loop ? "  loops" : ""}${object.path.marks?.length ? `  marks: ${object.path.marks.map((mark) => (typeof mark === "number" ? round(mark, 2) : `${round(mark.t, 2)}${mark.bank ? ` bank ${round(mark.bank, 1)}` : ""}${mark.pitch ? ` pitch ${round(mark.pitch, 1)}` : ""}`)).join(", ")}` : ""}`);
 			}
 		}
 	}
@@ -484,11 +586,9 @@ function shotReport() {
 	].join("\n");
 }
 
-/* --------------------------------- tools --------------------------------- */
-
 const studioAliasTools = new Set([
 	"set_camera", "frame_shot", "place_object", "update_object", "remove_object",
-	"import_mesh", "group_objects", "add_scene", "switch_scene", "apply_batch", "open_project",
+	"import_mesh", "sculpt_object", "group_objects", "add_scene", "switch_scene", "apply_batch", "open_project",
 	"add_character", "place_character", "remove_character", "set_prompt_blocks", "load_motion", "generate_motion",
 ]);
 const studioAdmissionSchema = {
@@ -616,60 +716,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				},
 			},
 			async ({ max_inline_bytes }) => {
-				if (!liveHub?.connected) return liveError(new Error(noLiveEditor("capture_frame requires a connected CozyClay editor with a renderable shot camera.")));
-				try {
-					const workspaceHandle = liveWorkspace.getStore();
-					const frame = await liveHub.command("capture_frame", {}, workspaceHandle);
-					const beforeHash = createHash("sha256").update(frame?.authoredStateBefore ?? "").digest("hex");
-					const afterHash = createHash("sha256").update(frame?.authoredStateAfter ?? "").digest("hex");
-					if (beforeHash !== afterHash) {
-						throw new Error(`capture_frame changed authored editor state; capture was rejected (${beforeHash} -> ${afterHash}).`);
-					}
-					if (!frame || frame.width !== 640 || frame.height !== 360 || frame.mimeType !== "image/png" || typeof frame.data !== "string") {
-						throw new Error("Live editor returned an invalid capture payload.");
-					}
-					const bytes = Buffer.from(frame.data, "base64");
-					if (bytes.length === 0 || bytes.length !== frame.byteSize || bytes.length > MAX_CAPTURE_BYTES) {
-						throw new Error(`Live editor returned an invalid compressed image size (maximum ${MAX_CAPTURE_BYTES} bytes).`);
-					}
-					if (frame.assertions?.renderable !== true || frame.assertions?.blackFrame === true) {
-						throw new Error("Live editor rejected the capture as non-renderable or black.");
-					}
-					const metadata = {
-						width: frame.width,
-						height: frame.height,
-						mimeType: frame.mimeType,
-						encoding: frame.encoding,
-						byteSize: frame.byteSize,
-						assertions: frame.assertions,
-						stateHashBefore: beforeHash,
-						stateHashAfter: afterHash,
-					};
-					if (bytes.length > max_inline_bytes) {
-						while (captureArtifacts.length >= MAX_CAPTURE_ARTIFACTS) {
-							const oldest = captureArtifacts.shift();
-							await unlink(oldest).catch(() => {});
-						}
-						const path = join(tmpdir(), `cozyclay-capture-${randomUUID()}.png`);
-						await writeFile(path, bytes, { mode: 0o600 });
-						captureArtifacts.push(path);
-						const expiry = setTimeout(() => {
-							const index = captureArtifacts.indexOf(path);
-							if (index >= 0) captureArtifacts.splice(index, 1);
-							void unlink(path).catch(() => {});
-						}, CAPTURE_ARTIFACT_TTL_MS);
-						expiry.unref?.();
-						return text(JSON.stringify({ ...metadata, artifact: { path, width: frame.width, height: frame.height, byteSize: bytes.length } }));
-					}
-					return {
-						content: [
-							{ type: "text", text: JSON.stringify({ ...metadata, image: { transport: "inline", width: frame.width, height: frame.height, byteSize: bytes.length } }) },
-							{ type: "image", data: frame.data, mimeType: frame.mimeType },
-						],
-					};
-				} catch (error) {
-					return liveError(error);
-				}
+				return captureFrameResult(max_inline_bytes);
 			},
 		),
 
@@ -860,23 +907,29 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				title: "Add a character to the cast",
 				description:
 					"Unlike place_character, add_character adds a new cast member instead of changing an existing one. " +
-					"The cast is unbounded — each one gets its own letter (A, B, C…), position and prompt description.",
+					"The cast is unbounded — each one gets its own letter (A, B, C…), position and prompt description. " +
+					'model "proxy-figure" adds a capsule figure: a rigless stand-in for blocking that holds a posture (stand, sit or lie) ' +
+					"and refuses motion, takes, IK and posing with TARGET_NOT_READY.",
 				inputSchema: {
 					subject: z.string().describe('prompt description, e.g. "a courier holding a package"'),
 					x: z.number().default(0).describe("floor position x in metres"),
 					z: z.number().default(0).describe("floor position z in metres"),
 					facing: z.number().default(0).describe("yaw in degrees; 0 faces the default camera"),
 					model: z
-						.enum(CHARACTER_MODEL_IDS)
+						.enum(CHARACTER_KIND_IDS)
+						.optional()
+						.describe('which mannequin to use; "proxy-figure" is a rigless capsule figure for blocking'),
+					posture: z
+						.enum(POSTURES)
 						.optional()
-						.describe("which mannequin to use"),
+						.describe("capsule figure posture (stand, sit or lie); stand when omitted"),
 				},
 			},
-			async ({ subject: desc, x, z: zPos, facing, model, ...admission }) => {
+			async ({ subject: desc, x, z: zPos, facing, model, posture, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
 						return await runStudioCommand({ ...admission, action: "character.add", args: {
-							character: { subject: desc, x, z: zPos, rot: facing, model, pose: DEFAULT_POSE },
+							character: { subject: desc, x, z: zPos, rot: facing, model, posture, pose: DEFAULT_POSE },
 						} });
 					} catch (error) {
 						return liveError(error);
@@ -890,7 +943,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				const taken = new Set(st.characters.map((c) => c.id));
 				let id = `char-${String.fromCharCode(97 + index)}`;
 				for (let n = index + 1; taken.has(id); n += 1) id = `char-${n}`;
-				const entry = createCharacterEntry({ id, subject: desc, x, z: zPos, rot: facing, model }, index);
+				const entry = createCharacterEntry({ id, subject: desc, x, z: zPos, rot: facing, model, posture }, index);
 				st.characters = [...st.characters, entry];
 				return text(`Added ${String.fromCharCode(65 + index)} (${entry.id}).\n\n${sceneReport()}`);
 			},
@@ -1005,7 +1058,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 			{
 				title: "Place an object in the set",
 				description:
-					`Unlike update_object and import_mesh, place_object adds a catalog prop instead of changing an existing one or loading a GLB, OBJ or FBX from disk. Available kinds: ${OBJECT_LIBRARY.map((o) => o.kind).join(", ")}. ` +
+					`Unlike update_object, import_mesh and sculpt_object, place_object adds a catalog prop instead of changing an existing one, loading a GLB, OBJ or FBX from disk, or building one from a recipe. Available kinds: ${OBJECT_LIBRARY.map((o) => o.kind).join(", ")}. ` +
 					"It returns the object id, which update_object and remove_object take.",
 				inputSchema: {
 					kind: z
@@ -1105,6 +1158,132 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 			},
 		),
 
+		tool(
+			"sculpt_object",
+			{
+				title: "Sculpt a clay prop from a recipe of soft parts",
+				description:
+					"Unlike place_object, import_mesh and compare_sculpt, sculpt_object builds or changes a clay prop from a recipe of parts you write, typically after reading a reference image. It needs no file and no catalogue entry. " +
+					"recipe = { version: 1, parts: [{ id, shape, size: [x, y, z], position?, rotation?, color?, parent?, mirror?, roundness?, taper?, border? }] }. " +
+					"Units are metres and degrees. The floor is y = 0, front is +z, and the subject's own left is +x. size is the full extent; position is the part's centre, in its parent part's frame when parent is set. " +
+					"shape: blob (soft superellipsoid: roundness 0 is an ellipsoid, 1 is a rounded box; taper narrows the top when positive and the bottom when negative), box (roundness bevels the edges), " +
+					"cylinder (taper 1 is a cone), torus (size [outer, outer, tube]), frame (a rectangular ring in x/y with a border width, for glasses rims, windows and picture frames). " +
+					"mirror: true adds a copy reflected across x = 0 of the parent frame, with its children; author the subject's left (+x) side once. color is #rrggbb. At most 48 parts after mirrors. " +
+					"To fix a sculpt, pass its id with edits instead of a whole recipe: [{ set: partId, ...fields }, { add: part }, { remove: partId }] (parent: null and mirror: false clear; remove takes the part's children). " +
+					"capture: true also returns the editor's frame (connected editor only), so one call is one round. " +
+					"Workflow: measure the reference's outline landmarks (limb tips, head top, feet as fractions of height) and place parts on them, compare_sculpt against the reference image, then rank 3-6 candidate edits with compare_sculpt { candidates } and apply the winner. Add small identity details (eyes, rims, plates) last as children of their parent part. " +
+					"A recipe or edit that cannot be drawn is refused with the path of the bad field.",
+				inputSchema: {
+					recipe: z.object({}).passthrough().optional().describe("{ version: 1, parts: [...] }; the whole recipe, for a new sculpt or a full rewrite"),
+					edits: z.array(z.object({}).passthrough()).min(1).max(48).optional().describe("part-level changes to the sculpt named by id"),
+					id: z.string().min(1).optional().describe("an existing sculpt's id to re-sculpt or patch in place (keeps its position and turn)"),
+					name: z.string().min(1).optional().describe("display name, e.g. 'Nerd turtle'"),
+					x: z.number().optional().describe("floor x in metres"),
+					z: z.number().optional().describe("floor z in metres"),
+					y: z.number().optional().describe("height above the floor in metres"),
+					facing: z.number().optional().describe("yaw in degrees"),
+					parent: z.string().optional().describe("object id to attach the new sculpt to"),
+					capture: z.boolean().optional().describe("true returns capture_frame's image with the result (connected editor only)"),
+				},
+			},
+			async ({ recipe, edits, id, name, x, z: zPos, y, facing, parent, capture, ...admission }) => {
+				if ((recipe === undefined) === (edits === undefined)) return { content: [{ type: "text", text: "Give exactly one of recipe (whole) or edits (part by part)." }], isError: true };
+				if (edits !== undefined && id === undefined) return { content: [{ type: "text", text: "edits patch an existing sculpt: give its id." }], isError: true };
+				const placement = {};
+				if (x !== undefined) placement.x = x;
+				if (zPos !== undefined) placement.z = zPos;
+				if (y !== undefined) placement.y = y;
+				if (facing !== undefined) placement.rot = facing;
+				if (liveHub?.connected) {
+					let result;
+					try {
+						result = await runStudioCommand({ ...admission, action: "object.sculpt", args: { ...(recipe === undefined ? { edits } : { recipe }), ...(id === undefined ? {} : { id }), ...(name === undefined ? {} : { name }), ...(Object.keys(placement).length ? { placement } : {}), ...(parent === undefined ? {} : { parent }) } });
+					} catch (error) {
+						return liveError(error);
+					}
+					if (capture !== true || result.isError) return result;
+					// The sculpt is applied either way; a failed capture is reported beside it, not as a failure.
+					const frame = await captureFrameResult(1_000_000);
+					return { content: [...result.content, ...frame.content] };
+				}
+				if (capture === true) return liveError(new Error(noLiveEditor("capture: true needs a connected CozyClay editor; call sculpt_object without it, or compare_sculpt.")));
+				const sc = scene();
+				if (parent !== undefined && !sc.objects.some((o) => o.id === parent)) {
+					return text(`No object "${parent}" to attach to. Call describe_scene for the current ids.`);
+				}
+				if (id !== undefined) {
+					const target = sc.objects.find((o) => o.id === id);
+					if (!target) return text(`No object "${id}". Call describe_scene for the current ids.`);
+					if (target.renderer !== SCULPT_KIND) return { content: [{ type: "text", text: `${id} is a ${target.renderer}, not a sculpt; omit id to create a new sculpt.` }], isError: true };
+					const next = edits !== undefined ? patchSculptRecipe(target.recipe, edits) : normalizeSculptRecipe(recipe);
+					if (!next.ok) return { content: [{ type: "text", text: `Recipe refused at ${next.error}` }], isError: true };
+					sc.objects = updateSceneObject(sc.objects, id, { ...placement, ...(name === undefined ? {} : { name }), recipe: next.recipe });
+					const row = sc.objects.find((o) => o.id === id);
+					const verb = edits !== undefined ? `Patched ${next.changed.join(", ")} on` : "Re-sculpted";
+					return text(`${verb} ${row.name} as ${row.id}: ${row.footprint.width} x ${row.footprint.depth} m, ${row.height} m tall.\n\n${sceneReport()}`);
+				}
+				const made = createSculptObject({ recipe, name }, sc.objects, placement);
+				if (made.error) return { content: [{ type: "text", text: `Recipe refused at ${made.error}` }], isError: true };
+				sc.objects = [...sc.objects, made.object];
+				if (parent !== undefined) sc.objects = setSceneObjectParent(sc.objects, made.object.id, parent);
+				const row = sc.objects.find((o) => o.id === made.object.id);
+				return text(`Sculpted ${row.name} as ${row.id}: ${row.footprint.width} x ${row.footprint.depth} m, ${row.height} m tall${parent !== undefined ? ` under ${parent}` : ""}.\n\n${sceneReport()}`);
+			},
+		),
+
+		tool(
+			"compare_sculpt",
+			{
+				title: "Compare a sculpt's silhouette with its reference image",
+				description:
+					"Unlike capture_frame and sculpt_object, compare_sculpt scores a sculpt's shape against a reference image instead of rendering the shot or changing the sculpt. " +
+					"Give the sculpt's id and the path of the reference (PNG or JPEG on this machine; a flat background or transparency). It reads the reference's subject as a mask, draws the sculpt's silhouette from a view (yaw: the camera's azimuth, 0 in front, positive toward the subject's own left; elevation: degrees above), " +
+					"fits it to the subject's height and position, and returns IoU, the width-to-height delta, which height band is missing area (top, middle, bottom) and which parts stick out, plus a sheet: reference | overlay (grey both, red missing, blue extra). " +
+					"Omit yaw to try -45..45 and keep the best. Pass candidates (up to 12 labelled edit sets) to score several fixes in one call without applying any; the answer ranks them against the current sculpt. Shape only: colour is not scored. Works without an editor.",
+				inputSchema: {
+					id: z.string().min(1).describe("the sculpt's object id"),
+					reference: z.string().min(1).describe("filesystem path to the reference PNG or JPEG"),
+					yaw: z.number().min(-180).max(180).optional().describe("reference camera azimuth in degrees; omitted tries -45..45"),
+					elevation: z.number().min(-60).max(60).optional().describe("reference camera elevation in degrees; default 0"),
+					candidates: z.array(z.object({ label: z.string().min(1).max(60), edits: z.array(z.object({}).passthrough()).min(1).max(48) })).min(1).max(12).optional()
+						.describe("alternative edit sets to score side by side without applying any; returns them ranked by IoU with the winner's sheet"),
+				},
+			},
+			async ({ id, reference, yaw, elevation = 0, candidates }) => {
+				const workspaceHandle = liveWorkspace.getStore();
+				if (liveHub?.connected) {
+					try { await refreshLiveDescription(workspaceHandle); } catch (error) { return liveError(error); }
+				}
+				const target = scene().objects.find((o) => o.id === id);
+				if (!target) return text(`No object "${id}". Call describe_scene for the current ids.`);
+				if (target.renderer !== SCULPT_KIND || !target.recipe) return { content: [{ type: "text", text: `${id} is a ${target.renderer}, not a sculpt.` }], isError: true };
+				let image;
+				try { image = await readImageFromPath(reference); } catch (error) { return { content: [{ type: "text", text: error.message }], isError: true }; }
+				let result;
+				try {
+					const scored = scoreSculptAgainstReference(target.recipe, image, { yaw, elevation, candidates });
+					result = scored.result;
+					if (candidates) {
+						const { ranked, refused } = scored;
+						const best = ranked[0];
+						const png = encodePng(best.result.sheet.width, best.result.sheet.height, best.result.sheet.data);
+						const summary = { id, view: best.result.report.view, ranking: ranked.map((row) => rankingRow(row, result)), ...(refused.length ? { refused } : {}),
+							note: `Nothing was applied. Apply the winner with sculpt_object { id: "${id}", edits }.` };
+						return { content: [{ type: "text", text: JSON.stringify(summary) }, { type: "image", data: png.toString("base64"), mimeType: "image/png" }] };
+					}
+				} catch (error) {
+					return { content: [{ type: "text", text: error.message }], isError: true };
+				}
+				const png = encodePng(result.sheet.width, result.sheet.height, result.sheet.data);
+				return {
+					content: [
+						{ type: "text", text: JSON.stringify({ id, ...result.report }) },
+						{ type: "image", data: png.toString("base64"), mimeType: "image/png" },
+					],
+				};
+			},
+		),
+
 		tool(
 			"group_objects",
 			{
@@ -1169,7 +1348,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 			},
 			async ({ beats, ...admission }) => {
 				if (!liveHub?.connected) {
-					return text("Prompt Blocks live on the studio timeline — open the editor and try again.");
+					return previsRefusal("set_prompt_blocks") ?? text("Prompt Blocks live on the studio timeline — open the editor and try again.");
 				}
 				const normalized = normalizePhases(beats.map((b) => b.text));
 				// The timeline runs on a 24 fps production clock.
@@ -1186,7 +1365,9 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 					}
 				}
 				try {
-					return await runStudioCommand({ ...admission, action: "character.setPromptBlocks", args: context => ({
+					const inspected = await inspectAction("character.setPromptBlocks");
+					return previsRefusal("set_prompt_blocks", { context: await contextOf(inspected) }) ??
+						await runStudioCommand({ ...admission, inspected, action: "character.setPromptBlocks", args: context => ({
 						characterId: context.activeCharacterId, blocks,
 					}) });
 				} catch (error) {
@@ -1213,8 +1394,12 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				if (!motionUrlPattern.test(args.url)) {
 					throw new Error(`Unsupported motion url "${args.url}". Use /ardy/motions/<id> or /ardy/assembled/<name>.npz.`);
 				}
-				return runStudioCommand({ ...args, action: 'motion.replace', args: async context => ({
-					characterId: args.character === undefined ? context.activeCharacterId : await liveCharacterId(args.character),
+				const inspected = liveHub?.connected ? await inspectAction('motion.replace') : undefined;
+				const characterId = args.character === undefined ? inspected?.context?.activeCharacterId : await liveCharacterId(args.character);
+				const refused = previsRefusal("load_motion", { feature: "take", context: await contextOf(inspected), characterId });
+				if (refused) return refused;
+				return runStudioCommand({ ...args, inspected, action: 'motion.replace', args: context => ({
+					characterId: args.character === undefined ? context.activeCharacterId : characterId,
 					url: args.url, prompt: args.prompt ?? '',
 				}) });
 			},
@@ -1274,10 +1459,13 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				},
 			},
 			async ({ phases, seconds = 9, seed, motion_url, drop, ...admission }) => {
-				if (!liveHub?.connected) return text(noLiveEditor("Motion requires a connected CozyClay editor."));
+				if (!liveHub?.connected) return previsRefusal("generate_motion", { feature: "motion" }) ?? text(noLiveEditor("Motion requires a connected CozyClay editor."));
 				const normalized = normalizePhases(phases.map(phase => typeof phase === 'string' ? phase : phase.text));
 				const beats = normalized.texts.map((text, index) => ({ text, seconds: phases[normalized.sources[index]]?.seconds ?? seconds / phases.length })).filter(beat => beat.text);
-				return runStudioCommand({ ...admission, action: motion_url ? 'motion.replace' : 'motion.generate', args: context => {
+				const action = motion_url ? 'motion.replace' : 'motion.generate', inspected = await inspectAction(action);
+				const refused = previsRefusal("generate_motion", { feature: "motion", context: await contextOf(inspected) });
+				if (refused) return refused;
+				return runStudioCommand({ ...admission, inspected, action, args: context => {
 					const generated = generationArgs({ characterId: context.activeCharacterId, source: { kind: 'generate', beats, ...(seed === undefined ? {} : { seed }) } });
 					return motion_url ? { characterId: generated.characterId, url: motion_url, prompt: beats.map(beat => beat.text).join(' '),
 						blocks: generated.blocks.map(({ startFrame, endFrame, text: prompt }) => ({ startFrame, endFrame, prompt })), ...(drop ? { drop } : {}) }
@@ -1292,7 +1480,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				title: "Move, rotate or scale an object",
 				description:
 					"Unlike place_object, update_object changes an existing prop instead of adding one. " +
-					"Every field is optional; omitted fields are left alone. Transforms go through the same clamp/snap path the studio's gizmo uses. hidden shows or hides the prop without deleting it.",
+					"Every field is optional; omitted fields are left alone. Transforms go through the same clamp/snap path the studio's gizmo uses. hidden shows or hides the prop without deleting it. opacity makes it see-through (glass, windows, water).",
 				inputSchema: {
 					id: z.string().describe("object id from place_object or describe_scene"),
 					x: z.number().optional(),
@@ -1321,6 +1509,14 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 							face_travel: z.boolean().optional().describe("turn to face the direction of travel (default true)"),
 							loop: z.boolean().optional(),
 							extend: z.boolean().optional().describe("keep going in the final direction after the route ends"),
+							marks: z
+								.array(z.union([
+									z.number().min(0).max(1),
+									z.object({ t: z.number().min(0).max(1), bank: z.number().min(-90).max(90).optional(), pitch: z.number().min(-90).max(90).optional() }),
+								]))
+								.max(6)
+								.optional()
+								.describe("dots along the route: an arc fraction 0-1, or { t, bank, pitch } (degrees, +-90) to lean there; level again at the neighbouring marks and ends"),
 						})
 						.nullable()
 						.optional()
@@ -1328,20 +1524,21 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 					height: z.number().positive().optional().describe("cutout or mesh height in metres"),
 					clay: z.boolean().optional().describe("mesh only: replace file materials with matte clay"),
 					hidden: z.boolean().optional().describe("true hides the prop without deleting it"),
+					opacity: z.number().min(0.05).max(1).optional().describe("1 is solid; lower is see-through, e.g. 0.3 for clear glass"),
 				},
 			},
-			async ({ id, x, y, z: zPos, facing, tilt, roll, scale, scale_x, scale_y, scale_z, color, name, path, height, clay, hidden, ...admission }) => {
+			async ({ id, x, y, z: zPos, facing, tilt, roll, scale, scale_x, scale_y, scale_z, color, name, path, height, clay, hidden, opacity, ...admission }) => {
 				const travelPath = path === null
 					? null
 					: path
-						? { points: path.points.map((point) => ({ x: point.x, y: point.y ?? 0, z: point.z })), speed: path.speed ?? 0, faceTravel: path.face_travel !== false, loop: path.loop === true, extend: path.extend === true }
+						? { points: path.points.map((point) => ({ x: point.x, y: point.y ?? 0, z: point.z })), speed: path.speed ?? 0, faceTravel: path.face_travel !== false, loop: path.loop === true, extend: path.extend === true, ...(path.marks ? { marks: path.marks } : {}) }
 						: undefined;
 				if (liveHub?.connected) {
 					try {
 						return await runStudioCommand({ ...admission, action: "object.update", args: { id, patch: {
 							x, y, z: zPos, rot: facing, rotX: tilt, rotZ: roll,
 							scaleX: scale_x ?? scale, scaleY: scale_y ?? scale, scaleZ: scale_z ?? scale,
-							color, name, path: travelPath, height, clay, hidden,
+							color, name, path: travelPath, height, clay, hidden, opacity,
 						} } });
 					} catch (error) {
 						return liveError(error);
@@ -1371,6 +1568,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				if (height !== undefined) patch.height = height;
 				if (clay !== undefined) patch.clay = clay;
 				if (hidden !== undefined) patch.hidden = hidden;
+				if (opacity !== undefined) patch.opacity = opacity;
 				sc.objects = updateSceneObject(sc.objects, id, patch);
 				return text(`Updated ${id}.\n\n${sceneReport()}`);
 			},
@@ -1522,6 +1720,9 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				} catch (error) {
 					return liveError(error);
 				}
+				// describe carries the editor's previsMode into state.
+				const refused = previsRefusal("mark_camera_move");
+				if (refused) return refused;
 				state.markedFraming = framing();
 				return text(`Marked A position: ${slateLine(currentShot())}\n\nNow move the camera, then call describe_camera_move.`);
 			},
@@ -1676,6 +1877,7 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 					}
 				}
 				state.doc = nextDocument;
+				state.previsMode = result.project.previsMode ?? DEFAULT_PREVIS_MODE;
 				state.name = result.project.name;
 				state.focus = null;
 				state.focusLocked = false;