cozyclay 3.1.6 → 3.2.1

package/src/commands/objects.js

@@ -5,8 +5,7 @@ import { elementSetSchema, registerElementSet } from './elements.js';
 import './elements/object.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 { runSculptCompare, sculptCompare } from './sculpt-compare.js';
 import { clampWarning } from '../receipt-findings.js';
 import { effectPresetSet } from '../effects/effect-record.js';
 import { withLightWarnings } from '../light-blockers.js';
@@ -52,16 +51,6 @@ 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, sculptCompare, assetImport]);
 
@@ -229,31 +218,7 @@ 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({ ...sculptCompare, available, run: runSculptCompare(ports, objectOf) });
 	registry.register({ ...assetImport, available: () => true,
 		run: async (args, context) => {
 			const { source, ...options } = args;

package/src/commands/physics.js

@@ -0,0 +1,21 @@
+// motion.physicsOverlay: the physics overlay's viewer setting (physics-overlay-settings.js), the agent's door to the
+// motion controls' Physics box. Transient: never saved, never undone.
+import { describePhysicsOverlay, setPhysicsOverlay } from "../physics-overlay-settings.js";
+
+const flag = description => ({ type: "boolean", description });
+
+export const declarations = Object.freeze([
+	{ id: "motion.physicsOverlay", label: "Physics overlay", kind: "transient",
+		input: { type: "object", required: [], additionalProperties: false, properties: {
+			com: flag("the centre of mass: a 4 cm ball with a line down to the ground, green inside the feet, red past the balance limit (what QA calls BALANCE), grey off the ground"),
+			support: flag("the support polygon: the outline of the soles on the ground"),
+			arc: flag("per air run: the hips' path (white, dashed) and the gravity parabola through the same takeoff and landing (orange); far apart is a FLOAT"),
+			trail: flag("the last 24 frames of each spring object's tip"),
+			all: flag("every part at once, before the named ones; { all: false } turns the overlay off"),
+		} },
+		description: "Draw the physics QA measures over the active character's installed take, in the editor views and in captures, contact sheets and exports (capture_frame, verify_result frames, export.shotVideo) until it is turned off: com, support, arc and trail (see each field). Updated every frame, the same in scrub, playback and export. No field turns every part on; { all: false } turns it off. Turn it on before a screenshot to see why QA reports BALANCE or FLOAT. A viewer setting: off by default, never saved or undone." },
+]);
+
+export function register(registry) {
+	registry.register({ ...declarations[0], available: () => true, run: args => ({ affectedIds: [], summary: describePhysicsOverlay(setPhysicsOverlay(args)) }) });
+}

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

@@ -12,10 +12,7 @@ import {
 	ikKeyframes,
 	ikRemoveKeyframe,
 	ikSeedTargets,
-	clampIkTargetToFloor,
-	solveIk,
 	MID_TRACKS,
-	solveMidJoint,
 	solveEffectorSwing,
 	ikPlantFeet,
 	solveHipsTranslateToFloor,
@@ -35,7 +32,8 @@ import { ko } from "../locale.js";
 import { isProxyFigure } from "../scenes.js";
 import { refuseRigOnly } from "../character-kind.js";
 import { DEFAULT_POSE, restoreBindPositions, applyPose, applyHipsOffset } from "../poses.js";
-import { bakeIkDragKey, bakeIkDragRange, chainsChangedBy, ikDragRecord, ikDragTouch } from "../motion/ik-drag.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";
@@ -74,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); }
@@ -113,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 });
@@ -256,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);
@@ -741,7 +738,7 @@ export function useMotion(appContext) {
 	// chain toward the target; mid joints reposition the elbow/knee with both
 	// ends pinned (the handle snaps to the clamped position); FK joints swing
 	// toward the pointer. The solved pose stays a preview until Apply.
-	function ikSolve(kind, trackId, targetWorld) {
+	function ikSolve(kind, trackId, targetWorld, input = null) {
 		if (ikDragRef.current && ikDragRef.current.characterId !== appContext.shared.activeChar.id) return;
 		const state = appContext.shared.ikStateRef.current;
 		const ikChains = state.chains;
@@ -762,14 +759,16 @@ export function useMotion(appContext) {
 			ikDragRef.current = { frame: appContext.shared.tlFrame, ids: new Set(pending?.ids ?? []) };
 		}
 		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);
+		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;
 			touch(trackId);
-			const clampedTarget = bodyContact ? clampIkTargetToFloor(trackId, targetWorld, 0, ikChains?.get(trackId)?.contactHeights ?? ikChains?.values().next().value?.contactHeights) : targetWorld;
+			const clampedTarget = clamp();
 			appContext.shared.ikStateRef.current.targets.set(trackId, clampedTarget.clone());
-			solveIk(chain, clampedTarget);
+			solveDragTarget(kind, chain, clampedTarget);
 			return;
 		}
 		if (kind === "mid") {
@@ -778,7 +777,7 @@ export function useMotion(appContext) {
 			const chain = midDef ? appContext.shared.ikStateRef.current.chains?.get(midDef.chain) : null;
 			if (!chain) return;
 			touch(chain.track.id);
-			solveMidJoint(chain, bodyContact ? clampIkTargetToFloor(trackId, targetWorld, 0, chain.contactHeights) : targetWorld);
+			solveDragTarget(kind, chain, clamp());
 			return;
 		}
 		// Effector swing: the rotation ring on a focused hand/foot. Rotates
@@ -917,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]);
+}