cozyclay 3.2.0 → 3.2.1

package/src/commands/project.js

@@ -1,6 +1,6 @@
 import { studioActionDeclaration } from "../studio-actions.js";
 import { fail } from "./shared.js";
-import { PREVIS_MODES } from "../project.js";
+import { CAST_STYLES, PREVIS_MODES } from "../project.js";
 
 const input = (properties = {}, required = []) => ({ type: "object", properties, required, additionalProperties: false });
 const name = { type: "string", minLength: 1, maxLength: 240 };
@@ -12,8 +12,8 @@ const saveAs = { ...save, id: "project.saveAs", label: "Save project as" };
 const exportAsAnimation = studioActionDeclaration("project.exportAsAnimation");
 // The deadline covers the user in the file picker, so it is the hub's ceiling, not the 30 s default.
 const opening = { ...document("project.open", "Open a project file", { serialized: { type: "string", maxLength: 400_000_000 }, handleToken: token, projectToken: token }), timeoutMs: 300_000 };
-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", "launch"] }, name });
+const fresh = document("project.new", "Start a new project", { name, previsMode: { type: "string", enum: [...PREVIS_MODES] }, castStyle: { type: "string", enum: [...CAST_STYLES] } });
+const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "launch"] }, name, castStyle: { type: "string", enum: [...CAST_STYLES] } });
 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, exportAsAnimation, opening, fresh, starter, restore, browse]);

package/src/commands/sculpt-compare.js

@@ -0,0 +1,53 @@
+// sculpt.compare: the editor's read-only way to score a sculpt against its
+// reference, one view ({ reference, yaw }) or several weighted ones
+// ({ views: [{ yaw, reference, weight }] }, #970). 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, sculpt-views.js).
+import { SCULPT_KIND } from '../scene-objects.js';
+import { rankingRow, scoreSculptAgainstReference } from '../sculpt-compare.js';
+import { scoreSculptAgainstViews } from '../sculpt-views.js';
+import { browserSculptImages, shrinkRgba } from './sculpt-images.js';
+import { fail } from './shared.js';
+import { StudioSchemas } from '../studio-agent-protocol.js';
+
+const id = StudioSchemas.TargetGuard.properties.targetId;
+const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
+const openObject = { type: 'object', properties: {}, additionalProperties: true };
+const yaw = { type: 'number', minimum: -180, maximum: 180 };
+const reference = { oneOf: [input({ assetId: id }), input({ dataUrl: { type: 'string', pattern: '^data:image/(png|jpeg|webp|gif);base64,', maxLength: 6000000 } })] };
+export 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. Instead of reference, views [{ yaw, reference, weight? }] scores several views of the subject (a blueprint\'s front 0, side 90, back 180) and blends their IoUs by weight (default front 0.6, side 0.25, back 0.15; a view whose height:width differs from the front\'s by more than 35% gets 0); the output adds one row per view. candidates (up to 12 { label, edits }) are scored from the same view(s) and ranked against the current sculpt; none is applied. Apply the winner with object.sculpt { id, edits }.',
+	input: input({ id, reference, yaw, elevation: { type: 'number', minimum: -60, maximum: 60 },
+		views: { type: 'array', minItems: 1, maxItems: 4, items: input({ yaw, reference, weight: { type: 'number', minimum: 0, maximum: 1 } }, ['yaw', 'reference']) },
+		candidates: { type: 'array', minItems: 1, maxItems: 12, items: input({ label: { type: 'string', maxLength: 60 }, edits: { type: 'array', minItems: 1, maxItems: 48, items: openObject } }) } }, ['id']) };
+// A receipt is at most 8 KiB, so the sheet is shrunk until the whole output fits this.
+const SCULPT_COMPARE_OUTPUT_BYTES = 6500;
+
+/** The run function for sculpt.compare; `objectOf` resolves an id or fails STALE_TARGET. */
+export const runSculptCompare = (ports, objectOf) => async ({ id: objectId, reference, views, 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.`);
+	if ((reference === undefined) === (views === undefined)) fail('INVALID_ARGUMENT', 'Give exactly one of reference (one view) or views (several weighted views).');
+	const images = ports.sculptImages ?? browserSculptImages;
+	let decoded, scored;
+	try { decoded = views ? await Promise.all(views.map(async view => ({ ...view, image: await images.decode(view.reference) }))) : await images.decode(reference); }
+	catch (error) { fail('INVALID_ARGUMENT', `Could not read the reference image: ${error?.message || error}`); }
+	context?.signal?.throwIfAborted();
+	try { scored = views ? scoreSculptAgainstViews(target.recipe, decoded, { elevation, candidates }) : scoreSculptAgainstReference(target.recipe, decoded, { 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}`;
+	const where = views ? `${views.length} weighted views (${result.report.views.map(row => `${row.view} ${row.weight}`).join(', ')})` : `the reference at yaw ${result.report.view.yaw}`;
+	return { affectedIds: [], output, summary: `Compared ${target.name || objectId} with ${where}: ${lead}.` };
+};

package/src/content-tile.jsx

@@ -0,0 +1,36 @@
+// The Content grid's tile and its grab wire, shared by the asset pane's
+// folders (asset-pane.jsx) and the sculpt shelf (sculpt-shelf-tiles.jsx).
+
+/** The grab wire every card shares: left button only, App owns the rest. */
+export function grabProps(onAssetGrab, payload) {
+	return {
+		onPointerDown: (event) => {
+			if (event.button !== 0) return;
+			event.preventDefault();
+			onAssetGrab?.(payload, event);
+		},
+	};
+}
+
+/** The Content grid's one tile grammar: a square thumbnail, an 11px name and
+ * a 10px type line. Click selects (amber ring), a left-button press starts the
+ * App-owned drag, double-click places the asset at the origin. */
+export function ContentTile({ assetKey, label, type, title, preview, selected, onSelect, grab, onPlace, failed = false }) {
+	return (
+		<button
+			type="button"
+			className={"content-tile" + (failed ? " is-failed" : "")}
+			data-testid="content-asset"
+			data-asset-key={assetKey}
+			aria-pressed={selected}
+			title={title}
+			{...(grab ?? {})}
+			onClick={() => onSelect(assetKey)}
+			onDoubleClick={onPlace ? () => onPlace() : undefined}
+		>
+			<span className="content-tile-thumb">{preview}</span>
+			<span className="content-tile-name">{label}</span>
+			<span className="content-tile-type">{type}</span>
+		</button>
+	);
+}

package/src/domains/cast.js

@@ -221,8 +221,6 @@ export function useCast(appContext) {
 	}
 
 	function removeCharacter(charId) {
-		const list = appContext.live.characters;
-		if (list.length <= 1) return;
 		domain.run('character.remove', { characterId: charId });
 		// The full-take cache remains native until the motion owner migrates.
 		if (!appContext.storeDomain('motion')) appContext.shared.motionFullRef.current.delete(charId);
@@ -373,6 +371,7 @@ export function useCast(appContext) {
 
 	function setLayerField(key, value) {
 		const entry = domain.read().find(entry => entry.id === domain.activeId) ?? domain.read()[0];
+		if (!entry) return;
 		const next = typeof value === 'function' ? value(entry.layer[key]) : value;
 		if (sameCastValue(entry.layer[key], next)) return;
 		return domain.run('cast.setLayer', { characterId: entry.id, layer: { [key]: next } });
@@ -743,7 +742,8 @@ export function useCast(appContext) {
 		return appContext.storeDomain('motion').switchLayer(entry.id);
 	}
 	function switchActiveCharacterLayer() {
-		const entry = domain.projection().find(entry => entry.id === domain.activeId) ?? domain.projection()[0];
+		// An empty stage loads no layer (id null).
+		const entry = domain.projection().find(entry => entry.id === domain.activeId) ?? domain.projection()[0] ?? { id: null };
 		const previous = appContext.shared.loadedLayerCharRef.current;
 		if (previous === entry.id) return;
 		switchNativeMotionLayer(previous, entry);
@@ -784,7 +784,6 @@ export function useCast(appContext) {
 			const live = appContext.live.state;
 			const character = characterForRef(live.characters, args.ref);
 			if (!character) throw new Error("Character not found");
-			if (live.characters.length <= 1) throw new Error("Cannot remove the final character");
 			domain.run('character.remove', { characterId: character.id });
 			return { id: character.id };
 		}
@@ -793,8 +792,10 @@ export function useCast(appContext) {
 	function toggleCharacterHidden(charId) { return domain.run('character.update', { characterId: charId, patch: { hidden: castMemberOf(charId).hidden !== true } }); }
 	domain.snapshotMotion = snapshotNativeMotion;
 	domain.syncLayer = () => {
+		// An empty stage has no layer to edit: the buffer holds no route.
 		const entry = domain.read().find(entry => entry.id === appContext.shared.loadedLayerCharRef.current) ?? domain.read()[0];
-		appContext.shared.bufferRef.current = { ...appContext.shared.bufferRef.current, ...entry.layer };
+		appContext.shared.bufferRef.current = { ...appContext.shared.bufferRef.current, ...(entry?.layer ?? { waypoints: [] }) };
+		if (!entry) return setActiveWaypointId(null);
 		
 		setActiveWaypointId(id => entry.layer.waypoints.some(waypoint => waypoint.id === id) ? id : null);
 	};
@@ -809,7 +810,7 @@ export function useCast(appContext) {
 		const shots = appContext.storeDomain('shot');
 		if (!shots) return;
 		const current = domain.projection(), active = current.find(entry => entry.id === domain.activeId) ?? current[0];
-		const extent = timelineContentExtent(current, active.id, appContext.shared.bufferRef.current.motion, null);
+		const extent = timelineContentExtent(current, active?.id ?? null, appContext.shared.bufferRef.current.motion, null);
 		domain.setTimeline(Math.max(24, timelineSpan(extent, shots.read(), shots.state().frameCount)));
 	};
 	domain.extendTimeline = domain.syncTimeline;

package/src/domains/motion.js

@@ -33,6 +33,7 @@ import { isProxyFigure } from "../scenes.js";
 import { refuseRigOnly } from "../character-kind.js";
 import { DEFAULT_POSE, restoreBindPositions, applyPose, applyHipsOffset } from "../poses.js";
 import { bakeIkDragKey, bakeIkDragRange, chainsChangedBy, clampDragTarget, ikDragRecord, ikDragTouch, solveDragTarget } from "../motion/ik-drag.js";
+import { fingersOf, solveFingerGesture, restFingers } from "../motion/fingers.js";
 import { ikKeyJson, ikTrackKeyFromJson } from "../motion/ik-key-json.js";
 import { chooseIkEntryPose } from "../ik-camera.js";
 import { applyRangePin, captureRangePinTarget, normalizeRangePin, rangePinTargetWorld, rangePinTracks, removeRangePinKeys } from "../motion/range-pin.js";
@@ -71,8 +72,7 @@ export function createMotionDomain(appContext, characters) {
 	let release = native.subscribe(notify), viewRevision = 0;
 	const documentStore = { ...Object.fromEntries(Object.keys(native).map(key => [key, (...args) => native[key](...args)])),
 		subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); } };
-	const read = () => documentStore.read('motion');
-	const layer = id => read().find(row => row.id === id) ?? emptyMotionLayer(id);
+	const read = () => documentStore.read('motion'), layer = id => read().find(row => row.id === id) ?? emptyMotionLayer(id);
 	function materialize(take) {
 		if (take?.source && !takes.has(take.resourceId)) {
 			try { const compiled = compileTakeSource(take.source); if (compiled) takes.set(take.resourceId, compiled); }
@@ -110,7 +110,7 @@ export function createMotionDomain(appContext, characters) {
 				const resolved = resolveIkRig(rig); if (resolved) Object.assign(state, resolved, { rig });
 				if (savedRigs?.has(id)) appContext.shared.restoreExportRig(savedRigs.get(id));
 				else if (resolved) {
-					if (take) applyTakeFrame(rig, take, Math.min(frame(), take.frames - 1));
+					restFingers(resolved.fkJoints); if (take) applyTakeFrame(rig, take, Math.min(frame(), take.frames - 1));
 					else {
 						const character = cast.read().find(entry => entry.id === id);
 						restoreBindPositions(rig); applyPose(rig, { ...REST_BONES, ...(character?.pose ?? DEFAULT_POSE).bones });
@@ -253,7 +253,7 @@ export function createMotionDomain(appContext, characters) {
 		rigOnly(id, 'pose');
 		const rig = rigFor(id), resolved = rig && resolveIkRig(rig);
 		if (!resolved) throw new StudioProtocolError('TARGET_NOT_READY', 'The character rig is not loaded.');
-		restoreBindPositions(rig); applyPose(rig, { ...REST_BONES, ...pose.bones }); applyHipsOffset(rig, pose.rootY ?? 0);
+		restoreBindPositions(rig); restFingers(resolved.fkJoints); applyPose(rig, { ...REST_BONES, ...pose.bones }); applyHipsOffset(rig, pose.rootY ?? 0);
 		editKeys(id, state => {
 			state.tracked = new Set([...resolved.chains.keys(), ...resolved.fkJoints.keys()]);
 			ikBakeKeyframe(resolved.chains, state, at, resolved.fkJoints);
@@ -761,6 +761,7 @@ export function useMotion(appContext) {
 		ikDragRef.current = Object.assign(ikDragRecord(ikDragRef.current, appContext.shared.tlFrame), { characterId: appContext.shared.activeChar.id });
 		const touch = (id) => ikDragTouch(appContext.shared.ikStateRef.current, ikDragRef.current, id), activeId = appContext.shared.activeChar.id;
 		const clamp = () => clampDragTarget({ kind, trackId, targetWorld, bodyContact, chains: ikChains, record: ikDragRef.current, bypass: input?.bypass, open: () => ({ rigs: appContext.shared.rigs, activeId, cast: appContext.shared.characters, allow: domain.layer(activeId).take?.source?.spec?.checks?.allow, notify: appContext.notify }) });
+		if (kind === "finger") return solveFingerGesture(fingersOf(appContext.shared.ikStateRef.current.fkJoints)?.get(trackId), targetWorld, touch);
 		if (kind === "chain") {
 			const chain = appContext.shared.ikStateRef.current.chains?.get(trackId);
 			if (!chain) return;
@@ -915,7 +916,7 @@ export function useMotion(appContext) {
 		restoreBindPositions(appContext.shared.activeRig);
 		// Reset-then-pose, the same shape the Character effect applies: unlisted
 		// joints return to rest instead of keeping stale limbs from the clip.
-		applyPose(appContext.shared.activeRig, { ...REST_BONES, ...pose.bones });
+		restFingers(ikFkJoints); applyPose(appContext.shared.activeRig, { ...REST_BONES, ...pose.bones });
 		// The hips' measured height rides into the bake: the hips FK joint keys
 		// its local position (p), so a crouched pose keys a crouched body.
 		applyHipsOffset(appContext.shared.activeRig, pose.rootY ?? 0);

package/src/domains/scenes.js

@@ -37,6 +37,8 @@ import {
 	clearStoredProjectHandle,
 	DEFAULT_PREVIS_MODE,
 	normalizePrevisMode,
+	DEFAULT_CAST_STYLE,
+	normalizeCastStyle,
 	buildAnimationProjectFromStoryboard,
 } from "../project.js";
 import { playgroundSceneUrl, fetchSceneProject } from "../playground.js";
@@ -56,11 +58,13 @@ import { createIkState } from "../motion/ik.js";
 
 // The scene list and project identity share one history. Dirty is derived from
 // the saved checkpoint, not an authored edit, and has its own non-history slice.
-// previsMode is project identity too: it is set only by a document boundary
-// (blank creation, starter/file open, session restore), never by an edit.
-function createScenesDomain(appContext, initial, name, previsMode = DEFAULT_PREVIS_MODE) {
+// previsMode and castStyle are project identity too: they are set only by a
+// document boundary (blank creation, starter/file open, session restore),
+// never by an edit.
+function createScenesDomain(appContext, initial, name, previsMode = DEFAULT_PREVIS_MODE, castStyle = DEFAULT_CAST_STYLE) {
 	const ordered = rows => rows.map((scene, order) => ({ ...scene, order }));
-	let native = createDocumentStore({ owned: { scenes: ordered(initial.scenes), project: { name, activeSceneId: initial.activeSceneId, previsMode: normalizePrevisMode(previsMode) } } });
+	const project = (fields, mode, style) => ({ ...fields, previsMode: normalizePrevisMode(mode), castStyle: normalizeCastStyle(style) });
+	let native = createDocumentStore({ owned: { scenes: ordered(initial.scenes), project: project({ name, activeSceneId: initial.activeSceneId }, previsMode, castStyle) } });
 	const listeners = new Set();
 	const notify = () => { for (const listener of listeners) listener(); };
 	let release = native.subscribe(notify);
@@ -96,7 +100,7 @@ function createScenesDomain(appContext, initial, name, previsMode = DEFAULT_PREV
 		appContext.publishScenes(read());
 		appContext.shared.activeSceneIdRef.current = metadata().activeSceneId;
 		if (appContext.live.state) appContext.patchLive({ scenes: read(), activeSceneId: metadata().activeSceneId });
-		storeProjectSession(metadata().name, metadata().previsMode);
+		storeProjectSession(metadata().name, metadata());
 		domain.persist?.();
 		domain.refreshDirty?.();
 	};
@@ -120,9 +124,9 @@ function createScenesDomain(appContext, initial, name, previsMode = DEFAULT_PREV
 		},
 		// Session cache/file loads are explicit non-authored boundaries. They
 		// retire scene history, just as opening a scene retired native history.
-		replaceDocument(scenes, activeSceneId, name = metadata().name, previsMode = metadata().previsMode) {
+		replaceDocument(scenes, activeSceneId, name = metadata().name, previsMode = metadata().previsMode, castStyle = metadata().castStyle) {
 			release(); native.dispose();
-			native = createDocumentStore({ owned: { scenes: ordered(scenes), project: { name, activeSceneId, previsMode: normalizePrevisMode(previsMode) } } });
+			native = createDocumentStore({ owned: { scenes: ordered(scenes), project: project({ name, activeSceneId }, previsMode, castStyle) } });
 			release = native.subscribe(notify); notify();
 		},
 		setDirty(value) {
@@ -141,10 +145,10 @@ export function useScenes(appContext) {
 	const [domain] = useState(() => {
 		if (appContext.storeDomain("scenes")) return appContext.storeDomain("scenes");
 		const session = loadProjectSession();
-		return createScenesDomain(appContext, appContext.shared.startup.document, session?.name ?? null, session?.previsMode);
+		return createScenesDomain(appContext, appContext.shared.startup.document, session?.name ?? null, session?.previsMode, session?.castStyle);
 	});
 	const scenes = useDocumentDomain(domain.documentStore, "scenes");
-	const { activeSceneId, name: projectName, previsMode } = useDocumentDomain(domain.documentStore, "project");
+	const { activeSceneId, name: projectName, previsMode, castStyle } = useDocumentDomain(domain.documentStore, "project");
 	const projectDirty = useDocumentDomain(domain.dirtyStore, "projectDirty");
 	const runtimeValues = useRef(new Map());
 	async function runProject(id, args = {}) {
@@ -228,6 +232,7 @@ export function useScenes(appContext) {
 			workflow: loadWorkflowGraph(),
 			name,
 			previsMode: domain.metadata().previsMode,
+			castStyle: domain.metadata().castStyle,
 		};
 	}
 
@@ -263,7 +268,7 @@ export function useScenes(appContext) {
 		appContext.shared.projectSnapshotRef.current = snapshot;
 		if (domain.metadata().name === previousName) domain.nameSaved(name);
 		refreshProjectDirty();
-		storeProjectSession(domain.metadata().name, domain.metadata().previsMode);
+		storeProjectSession(domain.metadata().name, domain.metadata());
 	}
 
 	function projectProblemsNotice(problems) {
@@ -405,8 +410,8 @@ export function useScenes(appContext) {
 		// too — otherwise an older .cozyclay would open a sixth too fast.
 		const doc = migrateToCurrentScenes(source);
 		const mergedCustomPoses = mergeProjectCustomPoses(appContext.shared.customPoses, project.customPoses);
-		const projectPrevisMode = normalizePrevisMode(project.previsMode);
-		domain.replaceDocument(doc.scenes, doc.activeSceneId, project.name, projectPrevisMode);
+		const projectPrevisMode = normalizePrevisMode(project.previsMode), projectCastStyle = normalizeCastStyle(project.castStyle);
+		domain.replaceDocument(doc.scenes, doc.activeSceneId, project.name, projectPrevisMode, projectCastStyle);
 		if (project.workspaceLayout) appContext.shared.setWorkspaceLayout({ ...DEFAULT_WORKSPACE_LAYOUT, ...project.workspaceLayout });
 		appContext.bus.run('cast.setCustomPoses', { poses: mergedCustomPoses });
 		const resolvedWorkflow = resolveWorkflowOutputs(normalizeWorkflowGraph(project.workflow), new Map((project.assets ?? []).map((asset) => [asset.id, asset])));
@@ -417,7 +422,7 @@ export function useScenes(appContext) {
 		appContext.shared.projectSnapshotRef.current = collectProjectSnapshot(project.name);
 		domain.pendingCheckpoint = { clock: appContext.undoClock, name: project.name };
 		domain.setDirty(false);
-		storeProjectSession(project.name, projectPrevisMode);
+		storeProjectSession(project.name, { previsMode: projectPrevisMode, castStyle: projectCastStyle });
 		setProjectStartupOpen(false);
 		setProjectManifest(resourceManifest({ scenesDocument: doc, workflow: resolvedWorkflow, poseLibrary: mergedCustomPoses, assets: project.assets ?? [], workflowOutputRefs }));
 		track("project:opened", { age_bucket: bucketProjectAge(Date.now() - (project.savedAt ?? Date.now())) });
@@ -425,7 +430,8 @@ export function useScenes(appContext) {
 
 	/** Open a bundled starter scene as a fresh, saveable project. Used by the
 	 * first-run dialog and by `npx cozyclay --scene <id>` (`?scene=`). */
-	async function openStarterScene(id, source = "starter", context = null, name = null) {
+	// A cast style chosen on the start screen overrides the starter's own.
+	async function openStarterScene(id, source = "starter", context = null, name = null, castStyle = undefined) {
 		if (source === "starter" && domain.dirtyStore.read("projectDirty") && !window.confirm(ko("Discard unsaved changes and start a new project?", "저장되지 않은 변경사항을 버리고 새 프로젝트를 시작할까요?"))) return false;
 		const url = playgroundSceneUrl(`?scene=${encodeURIComponent(id)}`);
 		const project = url ? await fetchSceneProject(url) : null;
@@ -434,7 +440,7 @@ export function useScenes(appContext) {
 			return false;
 		}
 		context?.check();
-		applyProject({ ...project, name: name?.trim() || project.name, savedAt: null }, true);
+		applyProject({ ...project, name: name?.trim() || project.name, savedAt: null, ...(castStyle ? { castStyle } : {}) }, true);
 		appContext.shared.projectHandleRef.current = null;
 		track("scene:loaded", { scene_source: source });
 		return true;
@@ -504,35 +510,39 @@ export function useScenes(appContext) {
 		}
 	}
 
-	function requestNewProject(authorized = false, { previsMode } = {}) {
-		if (!authorized) return runProject("project.new", previsMode === undefined ? undefined : { previsMode });
+	// The start screen's choices (previs mode, cast style); a field left out is
+	// not sent, so the command's own default applies.
+	const chosen = ({ previsMode, castStyle } = {}) => ({ ...(previsMode === undefined ? {} : { previsMode }), ...(castStyle === undefined ? {} : { castStyle }) });
+
+	function requestNewProject(authorized = false, choices = {}) {
+		if (!authorized) return runProject("project.new", Object.keys(chosen(choices)).length ? chosen(choices) : undefined);
 		if (domain.dirtyStore.read("projectDirty") && !window.confirm(ko("Discard unsaved changes and start a new project?", "저장되지 않은 변경사항을 버리고 새 프로젝트를 시작할까요?"))) return;
-		// The mode chosen on the start screen rides on the name dialog until its
+		// The choices made on the start screen ride on the name dialog until its
 		// submit commits the project.
-		setProjectNameDialog({ kind: "new", initialName: projectName ?? "My Project", ...(previsMode === undefined ? {} : { previsMode }) });
+		setProjectNameDialog({ kind: "new", initialName: projectName ?? "My Project", ...chosen(choices) });
 	}
 
-	function newProject(name, authorized = false, { previsMode } = {}) {
+	function newProject(name, authorized = false, choices = {}) {
 		if (!authorized) {
-			if (previsMode === undefined && projectNameDialog?.kind === "new") previsMode = projectNameDialog.previsMode;
-			return runProject("project.new", { ...(typeof name === "string" ? { name } : {}), ...(previsMode === undefined ? {} : { previsMode }) });
+			const pending = projectNameDialog?.kind === "new" ? chosen(projectNameDialog) : {};
+			return runProject("project.new", { ...(typeof name === "string" ? { name } : {}), ...pending, ...chosen(choices) });
 		}
-		if (typeof name !== "string") return requestNewProject(true, { previsMode });
+		if (typeof name !== "string") return requestNewProject(true, choices);
 		name = name.trim() || "My Project";
-		previsMode = normalizePrevisMode(previsMode);
+		const previsMode = normalizePrevisMode(choices.previsMode), castStyle = normalizeCastStyle(choices.castStyle);
 		setProjectNameDialog(null);
 		const fresh = createSceneDocument(ko("SCENE 01", "씬 01"));
 		storeWorkflowGraph(createWorkflowGraph());
 		appContext.shared.motionFullRef.current.clear();
-		domain.replaceDocument(fresh.scenes, fresh.activeSceneId, name, previsMode);
+		domain.replaceDocument(fresh.scenes, fresh.activeSceneId, name, previsMode, castStyle);
 		persistScenes(fresh.scenes, fresh.activeSceneId);
 		openScene(fresh.scenes[0], fresh.scenes);
 		appContext.shared.projectHandleRef.current = null;
 		clearStoredProjectHandle();
 		appContext.shared.projectSnapshotRef.current = collectProjectSnapshot(name);
 		domain.setDirty(false);
-		storeProjectSession(name, previsMode);
-		track("scene:created", { scene_source: "new_project", previs_mode: previsMode });
+		storeProjectSession(name, { previsMode, castStyle });
+		track("scene:created", { scene_source: "new_project", previs_mode: previsMode, cast_style: castStyle });
 		setProjectStartupOpen(false);
 		appContext.shared.setFirstSuccessGuideOpen(true);
 		domain.pendingCheckpoint = { clock: appContext.undoClock, name };
@@ -768,8 +778,8 @@ export function useScenes(appContext) {
 			return value;
 		};
 		if (id === "project.browse") { setProjectStartupOpen(false); setProjectBrowserOpen(true); return; }
-		if (id === "project.new") return newProject(args.name, true, { previsMode: args.previsMode });
-		if (id === "project.openStarter") return openStarterScene(args.id, args.source, context, args.name);
+		if (id === "project.new") return newProject(args.name, true, { previsMode: args.previsMode, castStyle: args.castStyle });
+		if (id === "project.openStarter") return openStarterScene(args.id, args.source, context, args.name, args.castStyle);
 		if (id === "project.restore") return restoreStoredProject({ handle: runtime("handleToken") }, context);
 		if (args.handleToken) return openProjectByHandle(runtime("handleToken"), context);
 		if (args.projectToken) { applyProject(runtime("projectToken"), true); return true; }
@@ -788,14 +798,14 @@ export function useScenes(appContext) {
 	domain.refreshDirty = () => refreshProjectDirty(false);
 	return {
 		...domain, applyExternalScene, loadLiveScenes, refreshProjectDirty,
-		scenes, activeSceneId, sceneSaveError, snapshotActiveScene, persistScenes, projectName, previsMode,
+		scenes, activeSceneId, sceneSaveError, snapshotActiveScene, persistScenes, projectName, previsMode, castStyle,
 		projectDirty, setProjectDirty: domain.setDirty, projectSaveState, setProjectSaveState, projectMenuOpen,
 		setProjectMenuOpen, projectBrowserOpen, setProjectBrowserOpen, projectNameDialog, setProjectNameDialog,
 		projectStartupOpen, setProjectStartupOpen, projectManifest, setProjectManifest, saveBlockedReasons,
 		setSaveBlockedReasons, workflowRevision, setWorkflowRevision, collectProjectSnapshot,
 		collectProjectSerialized, projectProblemsNotice, rehydrateProjectAssets, saveProject, applyProject,
 		exportAsAnimationProject,
-		openStarterScene: async (id, source = "starter", name = null) => (await runProject("project.openStarter", { id, source, ...(name ? { name } : {}) })).output?.opened === true,
+		openStarterScene: async (id, source = "starter", name = null, castStyle = undefined) => (await runProject("project.openStarter", { id, source, ...(name ? { name } : {}), ...(castStyle ? { castStyle } : {}) })).output?.opened === true,
 		openProject, openProjectByHandle, requestNewProject, newProject, restoreOffer,
 		setRestoreOffer, restoreStoredProject, flushScenes, openScene, selectSceneDocument,
 		createSceneDocumentFromUi, duplicateSceneDocumentFromUi, renameSceneDocumentFromUi,

package/src/execution-telemetry.js

@@ -1,7 +1,7 @@
 import { bucketMs, track, EXECUTION_TELEMETRY_VALUES } from "./analytics.js";
 export { AGENT_TOOL_CATEGORIES, EXECUTION_TELEMETRY_EVENTS, EXECUTION_TELEMETRY_PROPERTY_KEYS, EXECUTION_TELEMETRY_VALUES } from "./analytics.js";
 const WORKFLOW_FAILURE_CODES = new Set(["aborted", "capture_failed", "generation_failed", "unknown"]);
-const AGENT_FAILURE_CODES = new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "unknown"]);
+const AGENT_FAILURE_CODES = new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "network", "unknown"]);
 function secureId() {
 	try {
 		if (!globalThis.crypto?.getRandomValues) return null;
@@ -41,13 +41,17 @@ function executionFailureCode(error, channel, fallbackCode = "unknown") {
 	return allowed.has(fallbackCode) ? fallbackCode : "unknown";
 }
 
+/** The closed `tool_name` for an MCP tool event: a live tool name, else "other". */
+export function mcpToolName(name) {
+	return EXECUTION_TELEMETRY_VALUES.tool_name.has(name) ? name : "other";
+}
+
 export function mcpToolCategory(name) {
-	
 	if (name === "capture_frame") return "frame_capture";
 	if (name === "set_camera" || name === "frame_shot" || name === "mark_camera_move" || name === "describe_camera_move") return "camera";
 	
 	if (name === "save_project" || name === "open_project") return "project_io";
-	if (name === "describe_scene" || name === "describe_shot" || name === "render_prompt" || name === "live_status" || name === "compare_sculpt") return "read";
+	if (name === "describe_scene" || name === "describe_shot" || name === "render_prompt" || name === "live_status" || name === "compare_sculpt" || name === "studio_commands") return "read";
 	if (name === "add_character" || name === "place_character" || name === "remove_character" || name === "focus_character" || name === "place_object" || name === "import_mesh" || name === "sculpt_object" || name === "group_objects" || name === "update_object" || name === "remove_object" || name === "apply_batch" || name === "add_scene" || name === "switch_scene") return "scene_write";
 	return "other";
 }

package/src/export-menu-telemetry.js

@@ -0,0 +1,26 @@
+// export:menu_opened: one event each time the Export flyout opens, by click or
+// keyboard (the open state's false -> true edge), so reopening counts again.
+// webcodecs is the synchronous constructor check only; whether a codec config
+// is supported stays with the export attempt (unsupported_codec).
+import { useEffect } from "react";
+import { bucketCount, track } from "./analytics.js";
+
+/** The closed properties for one open: surface, mode, webcodecs and the shot (storyboard: panel) count bucket. */
+export function exportMenuOpenedProps({ embedMode, previsMode, shots }, scope = globalThis) {
+	const storyboard = previsMode === "storyboard";
+	const list = Array.isArray(shots) ? shots : [];
+	return {
+		surface: embedMode ? "embed" : "studio",
+		mode: storyboard ? "storyboard" : "animation",
+		webcodecs: typeof scope.VideoEncoder === "function" && typeof scope.VideoFrame === "function",
+		shots: bucketCount(storyboard ? list.filter((entry) => entry.kind === "still").length : list.length),
+	};
+}
+
+// Keyed on the open flag only: the render that opens the flyout supplies the shell it reports.
+export function useExportMenuTelemetry(open, shell) {
+	useEffect(() => {
+		if (!open) return;
+		try { track("export:menu_opened", exportMenuOpenedProps(shell)); } catch { /* telemetry is advisory */ }
+	}, [open]);
+}

package/src/finger-handles.jsx

@@ -0,0 +1,128 @@
+import { useEffect, useRef, useState } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { POSER_LAYER } from "./dualview.jsx";
+import { fingerTip, fingersOf } from "./motion/fingers.js";
+import { claimFingertip } from "./motion/fingertip-pick.js";
+import { handleColor } from "./pose-gizmo.js";
+
+// A fingertip handle is a real sphere in the scene, a little wider than the finger, so it sits on the tip,
+// shades with the lights and hides behind the body by depth like the mesh does.
+const TIP_R = 0.009;
+// The tip bone sits inside the fingertip; the sphere rides this far further along the last bone so most of
+// it shows past the skin.
+const TIP_PUSH = 0.008;
+// Picking reaches a few pixels past the sphere's projected edge, nearest tip first.
+const PICK_SLACK_PX = 6;
+// A tip may sit this far under the first body surface and still be grabbed: the IK controls' exposure rule
+// (ikControlIsExposed) with their default allowance, twice the handle radius (#913).
+const TIP_VISIBILITY_DEPTH = TIP_R * 2;
+
+/** The focused hand's fingers, and fingertip editing: a mode of the focused hand, on only while a hand is focused. */
+export function useFingerEdit(ikFocus, fkJoints) {
+	const [fingerEdit, setFingerEdit] = useState(false);
+	// IkHandles fills this with its exposure probe; the fingertip pick asks it before taking a press.
+	const exposureProbeRef = useRef(null);
+	const side = ikFocus === "leftHand" ? "Left" : ikFocus === "rightHand" ? "Right" : null;
+	const handFingers = side ? [...(fingersOf(fkJoints)?.values() ?? [])].filter((finger) => finger.side === side) : [];
+	return { handFingers, fingerEditing: fingerEdit && handFingers.length > 0, setFingerEdit, exposureProbeRef };
+}
+
+/**
+ * Fingertip handles for the focused hand. Dragging a tip solves that finger toward the pointer on a
+ * camera-facing plane (onSolve("finger", fingerId, point)); release bakes like any IK drag (onDragEnd).
+ * A tip the body hides cannot be grabbed (exposureProbeRef, the IK controls' rule); that press goes to IkHandles.
+ * The press is claimed in the window capture phase, ahead of IkHandles, so it never reads as an empty
+ * click that would drop the hand's focus.
+ */
+export function FingerHandles({ fingers: handFingers, enabled, onSolve, onDragEnd, exposureProbeRef }) {
+	const { camera, gl } = useThree();
+	const meshes = useRef(new Map());
+	const solveRef = useRef(onSolve), endRef = useRef(onDragEnd);
+	useEffect(() => { solveRef.current = onSolve; endRef.current = onDragEnd; });
+	const fingers = enabled ? handFingers : [];
+
+	useFrame(() => {
+		const along = new THREE.Vector3();
+		for (const finger of fingers) {
+			const mesh = meshes.current.get(finger.id);
+			if (!mesh) continue;
+			fingerTip(finger, mesh.position);
+			finger.bones[2].getWorldPosition(along);
+			mesh.userData.push = along.subVectors(mesh.position, along).normalize().multiplyScalar(TIP_PUSH).clone();
+			mesh.position.add(mesh.userData.push);
+		}
+	});
+
+	const active = fingers.length > 0;
+	useEffect(() => {
+		if (!active) return undefined;
+		const el = gl.domElement, ndc = new THREE.Vector2(), hit = new THREE.Vector3(), ray = new THREE.Raycaster();
+		let drag = null;
+		const toNdc = (ev) => {
+			const rect = el.getBoundingClientRect();
+			return ndc.set(((ev.clientX - rect.left) / rect.width) * 2 - 1, -((ev.clientY - rect.top) / rect.height) * 2 + 1);
+		};
+		const onMove = (ev) => {
+			if (!drag) return;
+			ray.setFromCamera(toNdc(ev), camera);
+			if (!ray.ray.intersectPlane(drag.plane, hit)) return;
+			drag.moved = true;
+			solveRef.current?.("finger", drag.id, hit.clone().sub(drag.push));
+		};
+		const release = () => {
+			window.removeEventListener("pointermove", onMove, true);
+			window.removeEventListener("pointerup", onUp, true);
+			window.removeEventListener("pointercancel", onUp, true);
+		};
+		const onUp = () => {
+			const moved = drag?.moved;
+			drag = null;
+			release();
+			if (moved) endRef.current?.();
+		};
+		const onDown = (ev) => {
+			if (ev.button !== 0 || ev.target !== el) return;
+			const rect = el.getBoundingClientRect(), centre = new THREE.Vector3(), edge = new THREE.Vector3();
+			const right = new THREE.Vector3().setFromMatrixColumn(camera.matrixWorld, 0);
+			const toScreen = (point) => { point.project(camera); return [rect.left + ((point.x + 1) / 2) * rect.width, rect.top + ((1 - point.y) / 2) * rect.height]; };
+			const candidates = [...meshes.current].filter(([, mesh]) => mesh).map(([id, mesh]) => {
+				const [cx, cy] = toScreen(centre.copy(mesh.position));
+				const [ex] = toScreen(edge.copy(mesh.position).addScaledVector(right, TIP_R));
+				return { id, mesh, gap: Math.hypot(cx - ev.clientX, cy - ev.clientY), reach: Math.abs(ex - cx) + PICK_SLACK_PX };
+			});
+			const exposed = exposureProbeRef?.current;
+			const picked = claimFingertip(ev, candidates, ({ mesh }) => !exposed || exposed(mesh.position, TIP_VISIBILITY_DEPTH));
+			if (!picked) return;
+			const normal = camera.getWorldDirection(new THREE.Vector3());
+			drag = { id: picked.id, moved: false, push: picked.mesh.userData.push?.clone() ?? new THREE.Vector3(), plane: new THREE.Plane().setFromNormalAndCoplanarPoint(normal, picked.mesh.position) };
+			window.addEventListener("pointermove", onMove, true);
+			window.addEventListener("pointerup", onUp, true);
+			window.addEventListener("pointercancel", onUp, true);
+		};
+		window.addEventListener("pointerdown", onDown, true);
+		return () => {
+			window.removeEventListener("pointerdown", onDown, true);
+			release();
+		};
+	}, [active, camera, gl, exposureProbeRef]);
+
+	if (!active) return null;
+	return (
+		<group>
+			{fingers.map((finger) => (
+				<mesh
+					key={finger.id}
+					raycast={() => {}}
+					ref={(mesh) => {
+						if (mesh) { mesh.layers.set(POSER_LAYER); meshes.current.set(finger.id, mesh); }
+						else meshes.current.delete(finger.id);
+					}}
+				>
+					<sphereGeometry args={[TIP_R, 20, 14]} />
+					<meshStandardMaterial color={handleColor(finger.trackIds[0])} roughness={0.45} metalness={0} />
+				</mesh>
+			))}
+		</group>
+	);
+}