cozyclay 2.0.0 → 2.1.0

package/src/commands/objects.js

@@ -3,7 +3,11 @@ import { studioActionDeclaration } from "../studio-actions.js";
 import { characterOf, fail } from "./shared.js";
 import { elementSetSchema, registerElementSet } from './elements.js';
 import './elements/object.js';
-import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, normalizeSceneObject } from '../scene-objects.js';
+import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, normalizeSceneObject, groupUnderNewEmpty, objectPatchFields, createSculptObject, SCULPT_KIND } from '../scene-objects.js';
+import { expandSculptParts, normalizeSculptRecipe, patchSculptRecipe } from '../sculpt-recipe.js';
+import { rankingRow, scoreSculptAgainstReference } from '../sculpt-compare.js';
+import { browserSculptImages, shrinkRgba } from './sculpt-images.js';
+import { clampWarning } from '../receipt-findings.js';
 import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
 
 const id = StudioSchemas.TargetGuard.properties.targetId;
@@ -14,15 +18,24 @@ const placement = input({ x: number, y: number, z: number, rot: number }, []);
 const setInput = elementSetSchema('object');
 const scale = setInput.properties.set.properties.scale;
 setInput.properties.set.properties.scale = { oneOf: [number, scale] };
+const PATCH_HINTS = { scale: 'use scaleX, scaleY, scaleZ', rotY: 'use rot for yaw', yaw: 'use rot for yaw', rotation: 'use rot, rotX, rotZ', position: 'use x, y, z', parent: 'use object.group or object.set parent', parentId: 'use object.group or object.set parent' };
 const mutation = (id, label, input) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'objects', input });
 const semantic = [
 	mutation('object.set', 'Set object fields', setInput),
-	mutation('object.add', 'Add object', input({ kind: { type: 'string' }, placement, name: { type: 'string' }, parent: id }, ['kind'])),
+	mutation('object.add', 'Add object', input({ kind: { type: 'string' }, placement, name: { type: 'string' }, parent: id, first: { type: 'boolean' } }, ['kind'])),
+	// A clay prop from a recipe of soft parts (docs/sculpt-from-image.md). With `id` it re-sculpts that
+	// sculpt in place (one undo); without, it creates one. The recipe is checked by sculpt-recipe.js.
+	{ ...mutation('object.sculpt', 'Sculpt a clay prop from a recipe', input({ recipe: { type: 'object', properties: {}, additionalProperties: true }, edits: { type: 'array', minItems: 1, maxItems: 48, items: { type: 'object', properties: {}, additionalProperties: true } }, id, name: { type: 'string', maxLength: 240 }, placement, parent: id }, [])),
+		description: 'Create a sculpt (or re-sculpt one by id) from a recipe, or patch a sculpt by id with edits [{ set: partId, ...fields } | { add: part } | { remove: partId }]. Recipe { version: 1, parts: [{ id, shape: blob|box|cylinder|torus|frame, size: [x,y,z] m, position, rotation (deg), color, parent, mirror, roundness, taper, border }] }. Floor is y=0, front +z, the subject\'s left +x; mirror reflects across x=0.' },
 	mutation('object.remove', 'Remove objects', input({ ids })),
 	mutation('object.rename', 'Rename object', input({ id, name: { type: 'string', maxLength: 240 } })),
 	mutation('object.group', 'Group objects', input({ parent: id, children: ids })),
 	mutation('object.ungroup', 'Ungroup objects', input({ children: ids })),
-	mutation('object.update', 'Update object', input({ id, patch: { type: 'object', properties: {}, additionalProperties: true } }, [])),
+	// The Outliner's "Group under new Empty": the Empty and the reparent are one write, so one undo.
+	{ ...mutation('object.groupUnderEmpty', 'Group object under a new Empty', input({ id })), exposure: 'ui-only' },
+	{ ...mutation('object.update', 'Update object', input({ id, patch: { type: 'object', properties: {}, additionalProperties: true } }, [])), agentHidden: true },
+	// agentHidden: object.update silently ignores unknown keys, so the agent's action index and inspect_studio leave it out
+	// and the prompt points at object.set / arrange_objects; MCP, the CLI and the UI keep it.
 	mutation('objects.arrange', 'Arrange objects', STUDIO_TOOL_SCHEMAS.arrange_objects),
 ];
 const batch = { id: 'objects.batch', label: 'Batch objects', description: 'Apply legacy object operations in one retained entry.', kind: 'job', domain: 'objects',
@@ -37,8 +50,18 @@ const assetImport = { ...studioActionDeclaration('asset.import'), kind: 'job', d
 		input({ assetId: id, placement, placeAs: assetProperties.placeAs }, ['assetId', 'placeAs']),
 		input({ fileToken: id, placeAs: { type: 'string', enum: ['mesh', 'cutout'] } }, ['fileToken', 'placeAs']),
 	] } };
+// Read-only: a job that never commits, so its receipt is `completed` with the score as output,
+// authored false and no undo. The scoring is MCP compare_sculpt's (sculpt-compare.js).
+const openObject = { type: 'object', properties: {}, additionalProperties: true };
+const sculptCompare = { id: 'sculpt.compare', label: 'Compare a sculpt with its reference', kind: 'job', timeoutMs: 60000,
+	description: 'Score a sculpt\'s silhouette against a reference image without changing anything: IoU, width-to-height delta, missing area by height band (top, middle, bottom), parts that stick out, and a reference | overlay sheet (grey both, red missing, blue extra) as sheetDataUrl. reference is { assetId } of a project image or { dataUrl }. yaw is the reference camera azimuth in degrees (0 in front, positive toward the subject\'s own left); omitted tries -45..45 and keeps the best. candidates (up to 12 { label, edits }) are scored from the same view and ranked against the current sculpt; none is applied. Apply the winner with object.sculpt { id, edits }.',
+	input: input({ id, reference: { oneOf: [input({ assetId: id }), input({ dataUrl: { type: 'string', pattern: '^data:image/(png|jpeg|webp|gif);base64,', maxLength: 6000000 } })] },
+		yaw: { type: 'number', minimum: -180, maximum: 180 }, elevation: { type: 'number', minimum: -60, maximum: 60 },
+		candidates: { type: 'array', minItems: 1, maxItems: 12, items: input({ label: { type: 'string', maxLength: 60 }, edits: { type: 'array', minItems: 1, maxItems: 48, items: openObject } }) } }, ['id', 'reference']) };
+// A receipt is at most 8 KiB, so the sheet is shrunk until the whole output fits this.
+const SCULPT_COMPARE_OUTPUT_BYTES = 6500;
 const matte = { id: 'object.matte', label: 'Apply object matte', description: 'Prepare derived assets, then publish one fenced object edit.', kind: 'job', domain: 'objects', exposure: 'ui-only', input: input({ objectId: id }) };
-export const declarations = Object.freeze([...semantic, replace, batch, ...['object.attach', 'object.detach', 'object.duplicate'].map(studioActionDeclaration), matte, assetImport]);
+export const declarations = Object.freeze([...semantic, replace, batch, ...['object.attach', 'object.detach', 'object.duplicate'].map(studioActionDeclaration), matte, sculptCompare, assetImport]);
 
 export function register(registry, ports) {
 	const objectOf = objectId => ports.state().objects.find(object => object.id === objectId)
@@ -53,10 +76,43 @@ export function register(registry, ports) {
 			const object = createSceneObject(args.kind, before, args.placement);
 			if (!object) fail('INVALID_ARGUMENT', `Unknown object kind: ${args.kind}`);
 			const placed = updateSceneObject([object], object.id, { ...(args.placement ?? {}), ...(args.name === undefined ? {} : { name: args.name }) })[0];
-			const next = [...before, placed];
+			// `first`: the Outliner lists Props in record order, so a UI-made object
+			// goes to the top where it is seen, not below a long expanded group.
+			const next = args.first ? [placed, ...before] : [...before, placed];
 			owned().write(args.parent === undefined ? next : setSceneObjectParent(next, placed.id, args.parent));
 			return result(before, 'Added object.');
 		},
+		'object.sculpt': args => {
+			const before = owned().read();
+			if ((args.recipe === undefined) === (args.edits === undefined)) fail('INVALID_ARGUMENT', 'Give exactly one of recipe (whole) or edits (part by part).');
+			if (args.edits !== undefined && args.id === undefined) fail('INVALID_ARGUMENT', 'edits patch an existing sculpt: give its id.');
+			let refused, changedParts = null;
+			if (args.edits !== undefined) {
+				const target = objectOf(args.id);
+				if (target.renderer !== SCULPT_KIND) fail('INVALID_ARGUMENT', `${args.id} is a ${target.renderer}, not a sculpt.`);
+				refused = patchSculptRecipe(target.recipe, args.edits);
+				changedParts = refused.changed;
+			} else refused = normalizeSculptRecipe(args.recipe);
+			if (!refused.ok) fail('INVALID_ARGUMENT', `Recipe refused at ${refused.error}`);
+			const patch = { ...(args.placement ?? {}), ...(args.name === undefined ? {} : { name: args.name }) };
+			let objectId = args.id;
+			if (objectId !== undefined) {
+				const target = objectOf(objectId);
+				if (target.renderer !== SCULPT_KIND) fail('INVALID_ARGUMENT', `${objectId} is a ${target.renderer}, not a sculpt; omit id to create a new sculpt.`);
+				owned().write(updateSceneObject(before, objectId, { ...patch, recipe: refused.recipe }));
+			} else {
+				if (args.parent !== undefined) objectOf(args.parent);
+				const made = createSculptObject({ recipe: refused.recipe, name: args.name }, before, args.placement);
+				objectId = made.object.id;
+				const next = [...before, updateSceneObject([made.object], objectId, patch)[0]];
+				owned().write(args.parent === undefined ? next : setSceneObjectParent(next, objectId, args.parent));
+			}
+			const sculpted = owned().read().find(row => row.id === objectId);
+			const parts = expandSculptParts(sculpted.recipe).length;
+			const size = `${sculpted.footprint.width} × ${sculpted.footprint.depth} m, ${sculpted.height} m tall`;
+			return { affectedIds: [objectId, ...result(before, '').affectedIds.filter(row => row !== objectId)],
+				summary: `${args.id === undefined ? 'Sculpted' : changedParts ? `Patched ${changedParts.join(', ')} on` : 'Re-sculpted'} ${sculpted.name} (${objectId}): ${parts} parts, ${size}.` };
+		},
 		'object.remove': ({ ids }) => {
 			const before = owned().read(); ids.forEach(objectOf);
 			owned().write(ids.reduce((rows, id) => removeSceneObject(rows, id), before));
@@ -67,10 +123,16 @@ export function register(registry, ports) {
 			owned().write(updateSceneObject(before, id, { name }));
 			return result(before, 'Renamed object.');
 		},
-		'object.update': ({ id, patch }) => {
-			objectOf(id); const before = owned().read();
-			owned().write(updateSceneObject(before, id, patch));
-			return result(before, 'Updated object.');
+		'object.update': ({ id, patch }, context) => {
+			const target = objectOf(id), before = owned().read();
+			// Wire callers get an error for a key nothing reads; the UI's own patches stay lenient.
+			const unknown = Object.keys(patch ?? {}).filter(key => !objectPatchFields(target).includes(key));
+			if (unknown.length && context?.origin && context.origin !== 'ui') fail('INVALID_ARGUMENT', `object.update cannot set ${unknown.join(', ')}${unknown.some(key => PATCH_HINTS[key]) ? ` (${unknown.filter(key => PATCH_HINTS[key]).map(key => `${key}: ${PATCH_HINTS[key]}`).join('; ')})` : ''}. Supported fields: ${objectPatchFields(target).join(', ')}.`);
+			const next = updateSceneObject(before, id, patch);
+			owned().write(next);
+			const kept = next.find(row => row.id === id);
+			const warning = clampWarning(id, Object.fromEntries(['x', 'y', 'z', 'scaleX', 'scaleY', 'scaleZ'].filter(key => Object.hasOwn(patch ?? {}, key)).map(key => [key, Number(patch[key])])), kept);
+			return { ...result(before, 'Updated object.'), ...(warning ? { warnings: [warning] } : {}) };
 		},
 		'object.group': ({ parent, children }) => {
 			objectOf(parent); children.forEach(objectOf);
@@ -84,9 +146,17 @@ export function register(registry, ports) {
 			owned().write(children.reduce((rows, id) => setSceneObjectParent(rows, id, null), before));
 			return result(before, 'Ungrouped objects.');
 		},
+		'object.groupUnderEmpty': ({ id }) => {
+			const object = objectOf(id); const before = owned().read();
+			if (object.attach) fail('CAPABILITY_MISSING', 'Detach the object from its character before grouping it.');
+			const grouped = groupUnderNewEmpty(before, id);
+			if (!grouped) fail('INVALID_ARGUMENT', 'Cannot group this object.');
+			owned().write(grouped.objects);
+			return { affectedIds: [grouped.emptyId, id], summary: 'Grouped the object under a new Empty.' };
+		},
 		'objects.arrange': args => {
 			const plan = owned().arrange(args);
-			return { affectedIds: plan.affectedIds, summary: 'Arranged objects.' };
+			return { affectedIds: plan.affectedIds, summary: 'Arranged objects.', checks: plan.checks, warnings: plan.warnings };
 		},
 	};
 	// Scalar scale is a convenience at the command boundary; the registry still
@@ -157,6 +227,31 @@ export function register(registry, ports) {
 		await owned().applyMatte(objectId, context);
 		return { affectedIds: [objectId], summary: 'Applied the object matte.' };
 	} });
+	registry.register({ ...sculptCompare, available, run: async ({ id: objectId, reference, yaw, elevation = 0, candidates }, context) => {
+		const target = objectOf(objectId);
+		if (target.renderer !== SCULPT_KIND || !target.recipe) fail('INVALID_ARGUMENT', `${objectId} is a ${target.renderer}, not a sculpt.`);
+		const images = ports.sculptImages ?? browserSculptImages;
+		let image, scored;
+		try { image = await images.decode(reference); }
+		catch (error) { fail('INVALID_ARGUMENT', `Could not read the reference image: ${error?.message || error}`); }
+		context?.signal?.throwIfAborted();
+		try { scored = scoreSculptAgainstReference(target.recipe, image, { yaw, elevation, candidates }); }
+		catch (error) { fail('INVALID_ARGUMENT', error?.message || String(error)); }
+		const { result, ranked, refused } = scored;
+		const output = { id: objectId, ...result.report };
+		if (ranked) Object.assign(output, { ranking: [...ranked.map(row => rankingRow(row, result)), ...refused.map(({ label, error }) => ({ label, refused: error }))],
+			sheetLabel: ranked[0].label, note: `Nothing was applied. Apply the winner with object.sculpt { id: "${objectId}", edits }.` });
+		const sheet = (ranked ? ranked[0].result : result).sheet;
+		const room = SCULPT_COMPARE_OUTPUT_BYTES - JSON.stringify(output).length;
+		// The full-size sheet is always tried, however narrow; shrinking stops at 64 px.
+		for (let factor = 1; factor === 1 || sheet.width / factor >= 64; factor *= 2) {
+			const dataUrl = await images.encodePng(factor === 1 ? sheet : shrinkRgba(sheet, factor));
+			if (dataUrl.length + 40 <= room) { Object.assign(output, { sheetDataUrl: dataUrl, ...(factor > 1 ? { sheetScale: 1 / factor } : {}) }); break; }
+		}
+		if (!output.sheetDataUrl) output.sheetOmitted = 'The overlay sheet does not fit in a receipt at a readable size; read missingByBand and extraByPart.';
+		const lead = ranked ? `best ${ranked[0].label} at IoU ${ranked[0].result.report.iou} (current ${result.report.iou}), ${candidates.length} candidates scored, none applied` : `IoU ${result.report.iou}`;
+		return { affectedIds: [], output, summary: `Compared ${target.name || objectId} with the reference at yaw ${result.report.view.yaw}: ${lead}.` };
+	} });
 	registry.register({ ...assetImport, available: () => true,
 		run: async (args, context) => {
 			const { source, ...options } = args;

package/src/commands/project.js

@@ -1,5 +1,6 @@
 import { studioActionDeclaration } from "../studio-actions.js";
 import { fail } from "./shared.js";
+import { PREVIS_MODES } from "../project.js";
 
 const input = (properties = {}, required = []) => ({ type: "object", properties, required, additionalProperties: false });
 const name = { type: "string", minLength: 1, maxLength: 240 };
@@ -8,12 +9,13 @@ const document = (id, label, properties = {}) => ({ id, label, description: labe
 const rename = { id: "project.rename", label: "Rename project", description: "Rename the project in one retained undo entry.", kind: "mutation", undoDomain: "scenes", input: input({ name }, ["name"]) };
 const save = { ...studioActionDeclaration("project.save"), input: input({ name }) };
 const saveAs = { ...save, id: "project.saveAs", label: "Save project as" };
+const exportAsAnimation = studioActionDeclaration("project.exportAsAnimation");
 const opening = document("project.open", "Open a project file", { serialized: { type: "string", maxLength: 400_000_000 }, handleToken: token, projectToken: token });
-const fresh = document("project.new", "Start a new project", { name });
-const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "tutorial", "launch"] } });
+const fresh = document("project.new", "Start a new project", { name, previsMode: { type: "string", enum: [...PREVIS_MODES] } });
+const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "tutorial", "launch"] }, name });
 const restore = { ...document("project.restore", "Restore the remembered project", { handleToken: token }), exposure: "ui-only" };
 const browse = { id: "project.browse", label: "Browse projects", description: "Show the project browser.", kind: "transient", exposure: "ui-only", input: input() };
-export const declarations = Object.freeze([rename, save, saveAs, opening, fresh, starter, restore, browse]);
+export const declarations = Object.freeze([rename, save, saveAs, exportAsAnimation, opening, fresh, starter, restore, browse]);
 
 export function register(registry, ports) {
 	const owner = () => ports.storeDomain?.("scenes");
@@ -44,6 +46,17 @@ export function register(registry, ports) {
 				? `This browser has no file access, so the project ${saved.name} was downloaded as ${saved.fileName}.`
 				: `Saved the project ${saved.name} to ${saved.fileName}.` };
 		} });
+	registry.register({ ...exportAsAnimation, available: () => true,
+		run: async (_args, context) => {
+			const saved = await owner().exportAsAnimationProject(context);
+			if (saved?.cancelled) fail("TARGET_NOT_READY", "Not exported: the user closed the file picker.");
+			if (!saved?.saved) fail("TARGET_NOT_READY", saved?.failure === "not-storyboard"
+				? "Export as Animation project is available only for storyboard projects."
+				: "Not exported: writing the animation project file failed.");
+			return { affectedIds: [], output: { fileName: saved.fileName }, summary: saved.downloaded
+				? `This browser has no file access, so the animation project ${saved.name} was downloaded as ${saved.fileName}.`
+				: `Exported the storyboard as ${saved.name} to ${saved.fileName}.` };
+		} });
 	for (const declaration of [opening, fresh, starter, restore, browse]) registry.register({ ...declaration,
 		available, run: async (args, context) => {
 			const result = await owner().projectAction(declaration.id, args, context);

package/src/commands/sculpt-images.js

@@ -0,0 +1,53 @@
+// The image port behind sculpt.compare: a reference ({ assetId } from the asset
+// store, or { dataUrl }) decoded to RGBA, and an RGBA sheet encoded as a PNG data
+// URL. The editor uses the browser one below; a Node test hands in its own as
+// `ports.sculptImages`, so the scoring runs on the same pixels in both.
+import { getAsset, openAssetDb } from "../scene-assets.js";
+
+function canvas(width, height) {
+	if (typeof OffscreenCanvas === "function") return new OffscreenCanvas(width, height);
+	if (globalThis.document?.createElement) return Object.assign(document.createElement("canvas"), { width, height });
+	throw new Error("this browser cannot draw images: no canvas is available");
+}
+
+async function referenceBlob(reference) {
+	if (reference.dataUrl !== undefined) return (await fetch(reference.dataUrl)).blob();
+	const asset = await getAsset(await openAssetDb(), reference.assetId);
+	if (!asset || asset.width === undefined) throw new Error(`no image asset ${reference.assetId} in this project`);
+	return new Blob([asset.bytes], { type: asset.type });
+}
+
+export const browserSculptImages = Object.freeze({
+	async decode(reference) {
+		if (typeof createImageBitmap !== "function") throw new Error("this browser cannot decode images: createImageBitmap is unavailable");
+		const bitmap = await createImageBitmap(await referenceBlob(reference));
+		try {
+			const context = canvas(bitmap.width, bitmap.height).getContext("2d", { willReadFrequently: true });
+			context.drawImage(bitmap, 0, 0);
+			const { width, height, data } = context.getImageData(0, 0, bitmap.width, bitmap.height);
+			return { width, height, data };
+		} finally {
+			bitmap.close?.();
+		}
+	},
+	async encodePng({ width, height, data }) {
+		const surface = canvas(width, height);
+		surface.getContext("2d").putImageData(new ImageData(new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength), width, height), 0, 0);
+		if (!surface.convertToBlob) return surface.toDataURL("image/png");
+		const bytes = new Uint8Array(await (await surface.convertToBlob({ type: "image/png" })).arrayBuffer());
+		let binary = "";
+		for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+		return `data:image/png;base64,${btoa(binary)}`;
+	},
+});
+
+/** Nearest-neighbour shrink of an RGBA image by an integer factor. */
+export function shrinkRgba({ width, height, data }, factor) {
+	const w = Math.max(1, Math.floor(width / factor)), h = Math.max(1, Math.floor(height / factor));
+	const out = new Uint8Array(w * h * 4);
+	for (let y = 0; y < h; y += 1) for (let x = 0; x < w; x += 1) {
+		const s = ((y * factor) * width + x * factor) * 4;
+		out.set(data.subarray(s, s + 4), (y * w + x) * 4);
+	}
+	return { width: w, height: h, data: out };
+}

package/src/commands/shot.js

@@ -1,20 +1,25 @@
 // One semantic entry point for timeline, camera controls and agent framing.
 import { createCameraBlock, updateCameraBlock, removeCameraRail } from '../camera-block.js';
-import { addShotAtFrame, cutAtFrame, duplicateShot, removeShot, reorderShot, resizeShot, renameShot, moveCameraKey, removeCameraKey } from '../cuts.js';
+import { addShotAtFrame, createShot, cutAtFrame, duplicateShot, removeShot, reorderShot, resizeShot, renameShot, moveCameraKey, removeCameraKey } from '../cuts.js';
+import { reflowStillShots, stillFrameCount, STILL_FRAME_COUNT_MAX, STILL_HOLD_DEFAULT } from '../shot-authoring.js';
+import { ko } from '../locale.js';
+import { track } from '../analytics.js';
+import { isImageAssetId } from '../scene-assets.js';
 import { createStableItemId, updateStableItem } from '../stable-items.js';
 import { railFollowForNewGeometry } from '../camera-rail-schedule.js';
-import { studioActionDeclaration } from '../studio-actions.js';
+import { studioActionDeclaration, studioActionRefusal } from '../studio-actions.js';
 import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
 import { elementSetSchema, registerElementSet } from './elements.js';
 import './elements/shot.js';
 import { changedIds, fail, shotLabel } from './shared.js';
 
 const id = StudioSchemas.TargetGuard.properties.targetId;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const number = { type: 'number' };
 const frame = { type: 'integer', minimum: 0 };
 const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
 const mutation = (id, label, schema) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'shot', input: schema });
-const existing = ['shot.create', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.reorder'].map(studioActionDeclaration);
+const existing = ['shot.create', 'shot.createStill', 'shot.setCaption', 'shot.setCastOverride', 'shot.setHold', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.reorder'].map(studioActionDeclaration);
 const extra = [
   mutation('shot.set', 'Set shot fields', elementSetSchema('shot')),
   mutation('shot.rename', 'Rename shot', input({ shotId: id, name: { type: 'string', maxLength: 240 } })),
@@ -28,6 +33,9 @@ const extra = [
   mutation('shot.frame', 'Frame the shot', { ...input({ ...STUDIO_TOOL_SCHEMAS.frame_shot.properties, preset: { type: 'string' } }, []), oneOf: [STUDIO_TOOL_SCHEMAS.frame_shot, input({ preset: { type: 'string' } })] }),
   { ...mutation('shot.replace', 'Replace shot authoring', input({ shots: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } } })), exposure: 'ui-only' },
   { ...mutation('shot.captureCamera', 'Capture camera framing', input({ shotId: id }, [])), exposure: 'ui-only' },
+  // The Board's Stylize result (or null to clear it). UI-only: the picture has
+  // to be in the asset store first, which only the Stylize flow does.
+  { ...mutation('shot.setStylized', 'Set stylized panel image', input({ shotId: id, assetId: { oneOf: [{ type: 'string' }, { type: 'null' }] } })), exposure: 'ui-only' },
   { ...mutation('shot.placeCamera', 'Place camera', input(Object.fromEntries(['x', 'y', 'z', 'lookAtX', 'lookAtY', 'lookAtZ', 'focalMm'].map(key => [key, number])), [])), exposure: 'ui-only' },
 ];
 export const declarations = Object.freeze([extra[0], ...existing, ...extra.slice(1).map(entry => entry.id === 'shot.frame' ? entry : { ...entry, exposure: 'ui-only' })]);
@@ -37,16 +45,75 @@ export function register(registry, ports) {
   const mounted = () => Boolean(ports.storeDomain?.('shot')) || 'The shots document owner is not mounted.';
   const shotOf = shotId => owner().read().find(shot => shot.id === shotId) ?? fail('STALE_TARGET', `Shot ${shotId} is not in this scene.`);
   const patchShot = (shotId, update) => { shotOf(shotId); owner().write(current => updateStableItem(current, shotId, update, 'shots')); };
+  const storyboard = () => ports.storeDomain?.('scenes')?.metadata?.().previsMode === 'storyboard';
+  const stillOf = shotId => {
+    const shot = shotOf(shotId);
+    return shot.kind === 'still' ? shot : fail('INVALID_ARGUMENT', `${shot.name} is a clip shot; only stills have a hold and a place in the still order.`);
+  };
+  // Every still edit is one write: the stills (in their new array order) are
+  // laid end to end and the timeline is sized to them, or nothing changes.
+  function writeStills(shots) {
+    const next = reflowStillShots(shots), frameCount = stillFrameCount(next);
+    if (frameCount > STILL_FRAME_COUNT_MAX) {
+      const en = `Storyboard is full (${STILL_FRAME_COUNT_MAX} frames); shorten a hold or remove a panel.`;
+      throw studioActionRefusal('INVALID_ARGUMENT', en, ko(en, `스토리보드가 가득 찼습니다 (${STILL_FRAME_COUNT_MAX}프레임). 홀드를 줄이거나 패널을 지우세요.`));
+    }
+    const clip = next.find(shot => shot.kind !== 'still' && next.some(still => still.kind === 'still' && still.startFrame <= shot.endFrame && still.endFrame >= shot.startFrame));
+    if (clip) fail('TARGET_NOT_READY', `The stills would overlap the clip shot ${clip.name} (frames ${clip.startFrame}-${clip.endFrame}); move or remove it first.`);
+    owner().writeState(before => ({ ...before, shots: next, frameCount }));
+    return next;
+  }
+  function createStill({ caption = '', hold = STILL_HOLD_DEFAULT } = {}) {
+    const current = owner().read(), framing = owner().capture(), last = current.findLastIndex(shot => shot.kind === 'still');
+    const keys = framing ? [{ id: createStableItemId('camera-key'), frame: 0, framing }] : [];
+    const still = { ...createShot(`Shot ${current.length + 1}`, 0, hold - 1, keys), kind: 'still', caption };
+    const written = writeStills([...current.slice(0, last + 1), still, ...current.slice(last + 1)]);
+    // Land the playhead in the new panel (the timeline.seek path) so the placement
+    // actions that follow write this panel's cast override, not the previous one's.
+    const created = written.find(shot => shot.id === still.id), { selection, view } = ports.readView();
+    ports.publishView({ selection, view: { ...view, frame: created.startFrame }, shotId: created.id });
+  }
+  function duplicate(shotId) {
+    const source = shotOf(shotId), copied = { kind: source.kind, caption: source.caption, cast: structuredClone(source.cast), stylizedAssetId: source.stylizedAssetId };
+    if (source.kind !== 'still') {
+      const before = owner().read(), next = duplicateShot(before, shotId, owner().state().frameCount);
+      return owner().write(next.map(shot => before.includes(shot) ? shot : { ...shot, ...copied }));
+    }
+    const current = owner().read(), index = current.indexOf(source);
+    const copy = { ...createShot(`${source.name} copy`, source.startFrame, source.endFrame,
+      source.cameraKeys.map(key => ({ ...key, id: createStableItemId('camera-key') })), source.camera), ...copied };
+    writeStills([...current.slice(0, index + 1), copy, ...current.slice(index + 1)]);
+  }
+  function reorder({ shotId, startFrame, index }) {
+    if ((startFrame === undefined) === (index === undefined)) fail('INVALID_ARGUMENT', 'shot.reorder takes exactly one of startFrame or index.');
+    const shot = shotOf(shotId);
+    if (shot.kind !== 'still') {
+      if (index !== undefined) stillOf(shotId);
+      return owner().write(current => reorderShot(current, shotId, startFrame, owner().state().frameCount));
+    }
+    const current = owner().read(), others = current.filter(row => row.kind === 'still' && row.id !== shotId);
+    const target = index ?? others.filter(row => row.startFrame < startFrame).length;
+    const order = [...others.slice(0, target), shot, ...others.slice(target)];
+    let next = 0;
+    writeStills(current.map(row => row.kind === 'still' ? order[next++] : row));
+  }
   const methods = {
-    'shot.create': () => owner().write(current => addShotAtFrame(current, ports.state().frame, owner().state().frameCount, owner().capture())),
+    'shot.create': () => storyboard() ? createStill() : owner().write(current => addShotAtFrame(current, ports.state().frame, owner().state().frameCount, owner().capture())),
+    'shot.createStill': args => createStill(args),
+    'shot.setCaption': ({ shotId, caption }) => patchShot(shotId, shot => ({ ...shot, caption })),
+    'shot.setCastOverride': ({ shotId, characterId, override }) => owner().setCastOverride(shotId, characterId, override),
+    'shot.setHold': ({ shotId, hold }) => {
+      const shot = stillOf(shotId), endFrame = shot.startFrame + hold - 1;
+      writeStills(owner().read().map(row => row === shot ? { ...row, endFrame, cameraKeys: row.cameraKeys.filter(key => key.frame <= endFrame) } : row));
+    },
     'shot.split': ({ shotId }) => {
       const shot = shotOf(shotId), { frame } = ports.state();
       if (frame <= shot.startFrame || frame > shot.endFrame) fail('TARGET_NOT_READY', `The playhead (frame ${frame}) is not inside ${shot.name} after its first frame.`);
       owner().write(current => cutAtFrame(current, shotId, frame, owner().capture()));
     },
-    'shot.duplicate': ({ shotId }) => { shotOf(shotId); owner().write(current => duplicateShot(current, shotId, owner().state().frameCount)); },
+    'shot.duplicate': ({ shotId }) => duplicate(shotId),
     'shot.remove': ({ shotId }) => { shotOf(shotId); owner().write(current => removeShot(current, shotId)); },
-    'shot.reorder': ({ shotId, startFrame }) => { shotOf(shotId); owner().write(current => reorderShot(current, shotId, startFrame, owner().state().frameCount)); },
+    'shot.reorder': args => reorder(args),
     'shot.setRange': ({ shotId, range }) => {
       const shot = shotOf(shotId), startFrame = range.startFrame, endFrame = range.endFrameExclusive - 1;
       const edges = startFrame > shot.endFrame ? [['end', endFrame], ['start', startFrame]] : [['start', startFrame], ['end', endFrame]];
@@ -77,24 +144,35 @@ export function register(registry, ports) {
     'shot.setLens': ({ fovDeg }) => owner().setLens(fovDeg),
     'shot.replace': ({ shots }) => owner().write(shots),
     'shot.captureCamera': args => owner().captureCamera(args.shotId),
+    'shot.setStylized': ({ shotId, assetId }) => {
+      if (assetId !== null && !isImageAssetId(assetId)) fail('INVALID_ARGUMENT', `${assetId} is not an image asset id.`);
+      patchShot(shotId, shot => ({ ...shot, stylizedAssetId: assetId }));
+    },
     'shot.placeCamera': args => owner().placeCamera(args),
   };
   const hasShots = state => state.shots.length > 0 || 'There are no shots yet; add one with shot.create.';
   const availability = {
-    'shot.create': state => addShotAtFrame(state.shots, state.frame, state.frameCount, null) !== state.shots || `There is no free room for a new shot at the playhead (frame ${state.frame}); move it with operate_studio { frame } or shorten a shot.`,
+    'shot.createStill': () => true,
+    'shot.create': state => storyboard() || addShotAtFrame(state.shots, state.frame, state.frameCount, null) !== state.shots || `There is no free room for a new shot at the playhead (frame ${state.frame}); move it with operate_studio { frame } or shorten a shot.`,
     'shot.split': state => state.shots.some(shot => state.frame > shot.startFrame && state.frame <= shot.endFrame) || `The playhead (frame ${state.frame}) is not inside a shot after its first frame; move it with operate_studio { frame }.`,
     'shot.clearCameraRail': state => state.shots.some(shot => createCameraBlock(shot.camera).cameraRail) || 'No shot has a camera rail; lay one with shot.setCameraRail.',
   };
   registerElementSet(registry, ports, extra[0]);
   for (const declaration of declarations.filter(row => row.id !== 'shot.set')) registry.register({ ...declaration,
     available: state => mounted() === true ? (availability[declaration.id] ?? (existing.includes(declaration) ? hasShots : () => true))(state) : mounted(),
-    run(args) {
+    run(args, context) {
       if (declaration.id === 'shot.frame') {
         const plan = owner().frame(args);
         return { affectedIds: plan.affectedIds, summary: 'Framed the shot.' };
       }
-      const before = owner().read(); methods[declaration.id](args);
-      const after = owner().read(), changed = changedIds(before, after);
+      const before = owner().read(), newPanel = declaration.id === 'shot.createStill' || (declaration.id === 'shot.create' && storyboard());
+      methods[declaration.id](args);
+      // Only the origin travels: never the caption, name or id of the panel.
+      if (newPanel) track('storyboard:panel_created', { source: context?.origin && context.origin !== 'ui' ? 'agent' : 'manual' });
+      // The owner re-normalizes every shot on write, so compare content, not
+      // identity; a storyboard reflow can still move more shots than a receipt
+      // names (100), and the first 100 stand for the batch.
+      const after = owner().read(), changed = changedIds(before.map(row => after.find(next => next.id === row.id && same(next, row)) ?? row), after).slice(0, 100);
       const affectedIds = changed.length ? changed : [args.shotId ?? ports.state().activeSceneId];
       return { affectedIds, summary: changed.length ? `${declaration.label}: ${changed.map(id => after.find(row => row.id === id)).filter(Boolean).map(shotLabel).join('; ')}.` : `${declaration.label}.` };
     },

package/src/commands/view.js

@@ -1,7 +1,9 @@
 // Viewer preferences: transient, like the View menu they mirror.
-import { studioActionDeclaration } from "../studio-actions.js";
-import { StudioProtocolError, STUDIO_TOOL_SCHEMAS } from '../studio-agent-protocol.js';
+import { studioActionDeclaration, studioActionRefusal } from "../studio-actions.js";
+import { STUDIO_TOOL_SCHEMAS } from '../studio-agent-protocol.js';
+import { ko } from '../locale.js';
 import { shotAtFrame } from '../cuts.js';
+import { fail } from './shared.js';
 
 const fields = STUDIO_TOOL_SCHEMAS.operate_studio.properties;
 const groups = { 'view.select': ['selection', 'shotId'], 'timeline.seek': ['frame'], 'timeline.play': ['playing'], 'view.setMode': ['mode', 'view'] };
@@ -10,16 +12,18 @@ const operations = Object.entries({ ...groups, 'view.update': Object.keys(fields
 	input: { type: 'object', properties: Object.fromEntries(keys.map(key => [key, fields[key]])), required: [], additionalProperties: false },
 }));
 export const declarations = Object.freeze([...operations, ...["view.setPartColours", "view.setGuideMode", "view.setInset"].map(studioActionDeclaration)]);
+// A storyboard project has no Motion department; every door says so the same way.
+export const STORYBOARD_MOTION_REFUSAL = Object.freeze({ en: 'Motion tools are not part of a Storyboard project.', ko: '모션 도구는 스토리보드 프로젝트에 없어요.' });
 export const viewCommand = args => Object.entries(groups).find(([, keys]) => Object.keys(args).every(key => keys.includes(key)))?.[0] ?? 'view.update';
 
 export function register(registry, ports) {
 	registry.registerToolAlias('operate_studio', viewCommand);
 	for (const declaration of operations) registry.register({ ...declaration, available: () => true, run(args) {
-		const fail = (code, message) => { throw new StudioProtocolError(code, message); };
 		if (!Object.keys(args).length || (args.view && !Object.keys(args.view).length)) fail('INVALID_ARGUMENT', 'Specify a view operation.');
 		const state = ports.readView();
 		// Pose mode is IK editing: without a rig to solve there is nothing to pose.
 		if (args.mode === 'pose' && args.mode !== state.view.mode && !ports.canPose()) fail('TARGET_NOT_READY', 'Pose mode needs a loaded character rig to edit with IK.');
+		if (args.mode === 'motion' && state.previsMode === 'storyboard') throw studioActionRefusal('TARGET_NOT_READY', STORYBOARD_MOTION_REFUSAL.en, ko(STORYBOARD_MOTION_REFUSAL.en, STORYBOARD_MOTION_REFUSAL.ko));
 		const selection = args.selection === undefined ? state.selection : args.selection;
 		if (selection) {
 			const found = selection.kind === 'scene' ? selection.id === state.host.sceneId : selection.kind === 'camera' ? selection.id === 'camera'
@@ -31,7 +35,9 @@ export function register(registry, ports) {
 		const frame = args.frame ?? shot?.startFrame ?? state.view.frame;
 		if (frame >= Math.max(1, state.frameCount)) fail('INVALID_RANGE', 'Frame is outside the timeline.');
 		const view = { ...state.view, ...args.view, frame, mode: args.mode ?? state.view.mode, playing: args.playing ?? state.view.playing };
-		ports.publishView({ selection, view, shotId: args.shotId ?? shotAtFrame(state.shots, frame)?.id ?? null });
+		// modeSet: only a command that names a mode moves the editor out of a
+		// UI-only mode (Sculpt, #739), which the published view reads as Stage.
+		ports.publishView({ selection, view, shotId: args.shotId ?? shotAtFrame(state.shots, frame)?.id ?? null, modeSet: args.mode !== undefined });
 		return { affectedIds: [state.host.sceneId], summary: 'Updated editor view.' };
 	} });
 	const viewAction = (id, run) => registry.register({ ...studioActionDeclaration(id), available: () => true,