cozyclay 2.0.0 → 2.1.0

package/src/coplanar-depth.js

@@ -0,0 +1,216 @@
+import * as THREE from "three";
+
+/**
+ * Depth ranks for coplanar faces of scene-object primitives.
+ *
+ * Agent-built assemblies stack parts whose same-facing faces lie in exactly
+ * one plane (a hood and a grille sharing a top at y=1.05). The depth test
+ * cannot order them, so as the camera moves the winner flips every frame and
+ * the strip sparkles. The ranks computed here let the renderer pull the
+ * later-created part toward the camera by a polygon offset, which holds
+ * whatever the camera does. The records are never edited.
+ */
+
+const DEG = Math.PI / 180;
+/** Planes closer than this are one plane. */
+const PLANE_EPS = 1e-3;
+/** Normals this aligned (cosine) face the same way. */
+const NORMAL_DOT = 0.9999;
+/** Overlap shallower than this is two faces touching along an edge. */
+const OVERLAP_EPS = 1e-4;
+/** Bounds the offset: a deeper chain shares the top rank. */
+export const MAX_DEPTH_RANK = 6;
+
+// Planar faces per kind, in the primitive's local frame BEFORE scale: the axis
+// the face is perpendicular to, which side, and where along that axis it sits
+// (cube/cylinder/cone sit on y in [0, 1] — see Primitive in props.jsx).
+const BOX_FACES = [
+	{ axis: 0, side: 1, at: 0.5 }, { axis: 0, side: -1, at: -0.5 },
+	{ axis: 1, side: 1, at: 1 }, { axis: 1, side: -1, at: 0 },
+	{ axis: 2, side: 1, at: 0.5 }, { axis: 2, side: -1, at: -0.5 },
+];
+const CAP_TOP = { axis: 1, side: 1, at: 1 };
+const CAP_BASE = { axis: 1, side: -1, at: 0 };
+const FACES_BY_KIND = {
+	cube: BOX_FACES,
+	cylinder: [CAP_TOP, CAP_BASE],
+	cone: [CAP_BASE],
+	// 2x2, a hair above the floor, drawn double-sided
+	plane: [{ axis: 1, side: 1, at: 0.004, flat: true }, { axis: 1, side: -1, at: 0.004, flat: true }],
+};
+// Local centre of the box the faces live on, per axis (x/z centred, y from 0).
+const MID = [0, 0.5, 0];
+const HALF = [0.5, 0.5, 0.5];
+const PLANE_HALF = [1, 0, 1];
+
+const rot = new THREE.Matrix4();
+const euler = new THREE.Euler();
+
+/** World-space rectangular faces of one object, or null when it has none. */
+function facesOf(object) {
+	const kind = object.renderer ?? object.kind;
+	const table = FACES_BY_KIND[kind];
+	if (!table || object.attach || object.hidden === true) return null;
+	euler.set((object.rotX ?? 0) * DEG, (object.rot ?? 0) * DEG, (object.rotZ ?? 0) * DEG);
+	rot.makeRotationFromEuler(euler);
+	const e = rot.elements;
+	// column a of the rotation = where local axis a points in the world
+	const axes = [[e[0], e[1], e[2]], [e[4], e[5], e[6]], [e[8], e[9], e[10]]];
+	const scale = [object.scaleX ?? 1, object.scaleY ?? 1, object.scaleZ ?? 1];
+	const pos = [object.x ?? 0, object.y ?? 0, object.z ?? 0];
+	if (![...scale, ...pos, ...axes[0]].every(Number.isFinite)) return null;
+	const faces = [];
+	for (const face of table) {
+		const a = face.axis;
+		const u = (a + 1) % 3;
+		const v = (a + 2) % 3;
+		// a mirrored scale turns the outward normal around with it
+		const flip = face.side * (scale[a] < 0 ? -1 : 1);
+		const half = face.flat ? PLANE_HALF : HALF;
+		const centre = [0, 0, 0];
+		for (let i = 0; i < 3; i += 1) {
+			const local = i === a ? face.at : face.flat ? 0 : MID[i];
+			for (let k = 0; k < 3; k += 1) centre[k] += axes[i][k] * local * scale[i];
+		}
+		faces.push({
+			n: [axes[a][0] * flip, axes[a][1] * flip, axes[a][2] * flip],
+			c: [centre[0] + pos[0], centre[1] + pos[1], centre[2] + pos[2]],
+			u: axes[u],
+			v: axes[v],
+			hu: half[u] * Math.abs(scale[u]),
+			hv: half[v] * Math.abs(scale[v]),
+		});
+	}
+	// world box of the faces, for the pair prefilter
+	const min = [Infinity, Infinity, Infinity];
+	const max = [-Infinity, -Infinity, -Infinity];
+	for (const f of faces) {
+		for (let k = 0; k < 3; k += 1) {
+			const reach = Math.abs(f.u[k]) * f.hu + Math.abs(f.v[k]) * f.hv;
+			min[k] = Math.min(min[k], f.c[k] - reach);
+			max[k] = Math.max(max[k], f.c[k] + reach);
+		}
+	}
+	return { faces, min, max };
+}
+
+const dot = (p, q) => p[0] * q[0] + p[1] * q[1] + p[2] * q[2];
+
+// Overlap of two rectangles lying in one plane, by separating axes in the
+// plane: the rectangles' own edge directions are the only candidates.
+function overlaps(a, b) {
+	const rel = [b.c[0] - a.c[0], b.c[1] - a.c[1], b.c[2] - a.c[2]];
+	for (const axis of [a.u, a.v, b.u, b.v]) {
+		const reachA = Math.abs(dot(axis, a.u)) * a.hu + Math.abs(dot(axis, a.v)) * a.hv;
+		const reachB = Math.abs(dot(axis, b.u)) * b.hu + Math.abs(dot(axis, b.v)) * b.hv;
+		if (Math.abs(dot(axis, rel)) >= reachA + reachB - OVERLAP_EPS) return false;
+	}
+	return true;
+}
+
+/** Every pair of same-facing faces of a and b that share a plane and overlap. */
+function conflictingFaces(a, b) {
+	const found = [];
+	for (const fa of a.faces) {
+		for (const fb of b.faces) {
+			if (dot(fa.n, fb.n) <= NORMAL_DOT) continue;
+			const gap = dot(fa.n, [fb.c[0] - fa.c[0], fb.c[1] - fa.c[1], fb.c[2] - fa.c[2]]);
+			if (Math.abs(gap) > PLANE_EPS) continue;
+			if (overlaps(fa, fb)) found.push(fa);
+		}
+	}
+	return found;
+}
+
+function conflict(a, b) {
+	for (const fa of a.faces) {
+		for (const fb of b.faces) {
+			if (dot(fa.n, fb.n) <= NORMAL_DOT) continue;
+			const gap = dot(fa.n, [fb.c[0] - fa.c[0], fb.c[1] - fa.c[1], fb.c[2] - fa.c[2]]);
+			if (Math.abs(gap) > PLANE_EPS) continue;
+			if (overlaps(fa, fb)) return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Which objects need to win the depth test over an earlier one.
+ *
+ * Two planar faces conflict when they face the same way, share a plane to
+ * within a millimetre and overlap with real area; touching boxes (opposite
+ * facing) never do. The later object in `objects` is the later-made detail, so
+ * each conflict is an edge earlier -> later, and an object's rank is the length
+ * of the longest chain ending at it (capped). Only ranked objects (> 0) get an
+ * entry. Run it on the AUTHORED records: a routed group moves rigidly, so
+ * relative geometry inside it does not change with the frame.
+ *
+ * Skipped: spheres, capsules, models, cutouts, props carried by a character
+ * and hidden props. Cylinder and cone caps are approximated by their bounding
+ * rectangle, which can over-report a conflict near a rim; that costs a
+ * sub-pixel pull on a prop and nothing else.
+ *
+ * @param {Array<object>} objects scene-object records, in creation order
+ * @returns {Map<string, number>} id -> rank
+ */
+export function coplanarDepthRanks(objects) {
+	const ranks = new Map();
+	if (!Array.isArray(objects) || objects.length < 2) return ranks;
+	const shapes = objects.map((object) => (object && typeof object === "object" ? facesOf(object) : null));
+	const rank = new Array(objects.length).fill(0);
+	for (let j = 1; j < objects.length; j += 1) {
+		const b = shapes[j];
+		if (!b) continue;
+		for (let i = 0; i < j; i += 1) {
+			const a = shapes[i];
+			if (!a || rank[i] + 1 <= rank[j]) continue;
+			if (
+				a.min[0] > b.max[0] + PLANE_EPS || b.min[0] > a.max[0] + PLANE_EPS ||
+				a.min[1] > b.max[1] + PLANE_EPS || b.min[1] > a.max[1] + PLANE_EPS ||
+				a.min[2] > b.max[2] + PLANE_EPS || b.min[2] > a.max[2] + PLANE_EPS
+			) continue;
+			if (conflict(a, b)) rank[j] = Math.min(MAX_DEPTH_RANK, rank[i] + 1);
+		}
+		if (rank[j] > 0) ranks.set(objects[j].id, rank[j]);
+	}
+	return ranks;
+}
+
+const AXES = ["x", "y", "z"];
+const FACE_NAMES = { "y+": "tops", "y-": "bottoms" };
+const round = (value) => Number(value.toFixed(4));
+
+/**
+ * The coplanar conflicts coplanarDepthRanks resolves by offset, named: for
+ * each pair of objects with same-facing faces in one plane, the shared planes
+ * ("tops at y=1.05"). Informational for a receipt; it does not decide ranks.
+ *
+ * @param {Array<object>} objects scene-object records
+ * @returns {Array<{a: string, b: string, planes: Array<{face: string, axis: string|null, at: number}>}>}
+ */
+export function coplanarConflicts(objects) {
+	const pairs = [];
+	if (!Array.isArray(objects) || objects.length < 2) return pairs;
+	const shapes = objects.map((object) => (object && typeof object === "object" ? facesOf(object) : null));
+	for (let j = 1; j < objects.length; j += 1) {
+		const b = shapes[j];
+		if (!b) continue;
+		for (let i = 0; i < j; i += 1) {
+			const a = shapes[i];
+			if (!a) continue;
+			if (
+				a.min[0] > b.max[0] + PLANE_EPS || b.min[0] > a.max[0] + PLANE_EPS ||
+				a.min[1] > b.max[1] + PLANE_EPS || b.min[1] > a.max[1] + PLANE_EPS ||
+				a.min[2] > b.max[2] + PLANE_EPS || b.min[2] > a.max[2] + PLANE_EPS
+			) continue;
+			const planes = conflictingFaces(a, b).map((face) => {
+				const axis = [0, 1, 2].find((k) => Math.abs(face.n[k]) > NORMAL_DOT);
+				if (axis === undefined) return { face: "tilted faces", axis: null, at: round(dot(face.n, face.c)) };
+				const sign = face.n[axis] > 0 ? "+" : "-";
+				return { face: FACE_NAMES[`${AXES[axis]}${sign}`] ?? `${sign}${AXES[axis]} faces`, axis: AXES[axis], at: round(face.c[axis]) };
+			});
+			if (planes.length) pairs.push({ a: objects[i].id, b: objects[j].id, planes });
+		}
+	}
+	return pairs;
+}

package/src/cuts.js

@@ -11,7 +11,7 @@ import {
 	updateStableItem,
 } from "./stable-items.js";
 
-export const DEFAULT_SHOT_FRAMES = 40;
+const DEFAULT_SHOT_FRAMES = 40;
 
 const frameNumber = (value, fallback = 0) => Number.isFinite(value) ? Math.round(value) : fallback;
 
@@ -48,6 +48,12 @@ export function createShot(name = "Shot", startFrame = 0, endFrame = startFrame
 		endFrame: end,
 		cameraKeys: uniqueKeys(cameraKeys, start, end),
 		camera: createCameraBlock(camera),
+		// v5 shot-document defaults, so a fresh shot already has the shape the
+		// document normalizer gives it (and an undo restores).
+		kind: "clip",
+		caption: "",
+		cast: {},
+		stylizedAssetId: null,
 	};
 }
 
@@ -133,11 +139,6 @@ export function resizeShot(shots, shotId, edge, rawFrame, frameCount) {
 		.sort((a, b) => a.startFrame - b.startFrame);
 }
 
-/** Compatibility name for callers that move the left edge. */
-export function moveBoundary(shots, shotId, newStartFrame, frameCount) {
-	return resizeShot(shots, shotId, "start", newStartFrame, frameCount);
-}
-
 export function removeShot(shots, shotId) {
 	return removeStableItem(shots, shotId, "shots");
 }

package/src/domains/cast.js

@@ -12,7 +12,8 @@ import {
 	captureHipsOffset,
 	saveCustomPoses,
 } from "../poses.js";
-import { createCharacterEntry, createCharacterLayer } from "../scenes.js";
+import { createCharacterEntry, createCharacterLayer, isProxyFigure, PROXY_FIGURE_MODEL } from "../scenes.js";
+import { kindRefusal } from "../character-kind.js";
 import {
 	DEFAULT_SUBJECT,
 	DEFAULT_SUBJECT2,
@@ -28,12 +29,12 @@ import { judgeNextWaypoint } from "../ardy/waypoints.js";
 import { StudioProtocolError } from "../studio-agent-protocol.js";
 import { studioActionRefusal } from "../studio-actions.js";
 import { createStableItemId, removeStableItem } from "../stable-items.js";
-import { trackFeature } from "../analytics.js";
+import { track, trackFeature } from "../analytics.js";
 import { requestBridgeExtract } from "../multimodel-ingest.js";
 import { loadMotionFromUrl } from "../ardy/npz.js";
 import { snapshotPlaybackBones, applyMotionFrame, restorePlaybackBones } from "../ardy/playback.js";
 
-import { HISTORY_LIMIT } from "../history.js";
+import { shotAtFrame } from "../cuts.js";
 
 const sameCastValue = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 
@@ -43,7 +44,7 @@ export function createCastDomain(appContext, initial, customPoses = []) {
 	let native = createDocumentStore({ owned: { cast: normalize(initial) } });
 	const listeners = new Set(), motions = new Map();
 	const notify = () => { for (const listener of listeners) listener(); };
-	let release = native.subscribe(notify), loading = false;
+	let release = native.subscribe(notify);
 	const documentStore = { ...Object.fromEntries(Object.keys(native).map(key => [key, (...args) => native[key](...args)])),
 		subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); } };
 	const state = () => documentStore.read('cast'), read = () => state().characters;
@@ -74,6 +75,25 @@ export function createCastDomain(appContext, initial, customPoses = []) {
 	function write(update) {
 		return writeState(before => ({ ...before, characters: typeof update === 'function' ? update(before.characters) : update }));
 	}
+	function update(characterId, patch) {
+		const entry = read().find(entry => entry.id === characterId);
+		if (!entry) throw new StudioProtocolError('STALE_TARGET', `Character ${characterId} is not in this scene.`);
+		const raw = appContext.ports.read(), shot = shotAtFrame(raw.shots, raw.view.frame);
+		const fields = ['x', 'z', 'rot', 'posture', 'pose'];
+		const panelPatch = Object.fromEntries(Object.entries(patch).filter(([key, value]) => fields.includes(key) && value !== undefined));
+		if (shot?.kind === 'still' && !raw.targets?.get?.(characterId)?.motion && Object.keys(panelPatch).length) {
+			const current = { ...entry, ...shot.cast[characterId] };
+			const normalized = createCharacterEntry({ ...current, ...panelPatch });
+			const override = { x: normalized.x, z: normalized.z, rot: normalized.rot };
+			for (const key of ['posture', 'pose']) if (normalized[key] != null) override[key] = normalized[key];
+			// Enlist the shot owner in the already-open command/drag session:
+			// even a mixed scale + placement edit is one shared Undo entry.
+			const shots = appContext.storeDomain('shot');
+			appContext.recordAction('shot', () => shots.setCastOverride(shot.id, characterId, override), null, true);
+			patch = Object.fromEntries(Object.entries(patch).filter(([key]) => !fields.includes(key)));
+		}
+		if (Object.keys(patch).length) write(rows => rows.map(row => row.id === characterId ? { ...row, ...patch } : row));
+	}
 	function publishMotion(characterId, motion) {
 		if (motion) motions.set(characterId, motion); else motions.delete(characterId);
 		publish(); notify();
@@ -109,7 +129,7 @@ export function createCastDomain(appContext, initial, customPoses = []) {
 		}
 		return run('run.update', { txId: gesture.txId, args });
 	}
-	const domain = { documentStore, state, read, write, writeState, run, edit, beginGesture, finishGesture,
+	const domain = { documentStore, state, read, write, update, writeState, run, edit, beginGesture, finishGesture,
 		activeId: read()[0]?.id ?? null, projection: () => projection, publishMotion, normalizeCharacters: rows => rows.map(createCharacterEntry),
 		bindRender(context) { appContext = context; },
 		beginAction: () => documentStore.beginAction('cast'), canUndo: id => documentStore.canUndo(id),
@@ -121,13 +141,11 @@ export function createCastDomain(appContext, initial, customPoses = []) {
 			write(plan.draft); return plan;
 		},
 		load(value) {
-			finishGesture(true); loading = true;
-			try {
-				release(); native.dispose(); motions.clear();
-				const next = normalize(Array.isArray(value) ? { characters: value, customPoses: state().customPoses } : value);
-				native = createDocumentStore({ owned: { cast: next } }); release = native.subscribe(notify);
-				domain.activeId = read()[0]?.id ?? null; domain.loadView?.(); notify();
-			} finally { loading = false; }
+			finishGesture(true);
+			release(); native.dispose(); motions.clear();
+			const next = normalize(Array.isArray(value) ? { characters: value, customPoses: state().customPoses } : value);
+			native = createDocumentStore({ owned: { cast: next } }); release = native.subscribe(notify);
+			domain.activeId = read()[0]?.id ?? null; domain.loadView?.(); notify();
 		},
 		dispose() { finishGesture(true); unregister(); unsubscribe(); release(); native.dispose(); listeners.clear(); },
 	};
@@ -164,7 +182,6 @@ export function useCast(appContext) {
 
 	const [poseRevision, setPoseTick] = useState(0);
 
-	/* --------------------- derived cast view + shims ---------------------- */
 	// Fallback second slot mirrors the old charB defaults so preset math and
 	// the two-subject inspector never see a hole before B exists.
 	const charA = characters[0] ?? createCharacterEntry(null, 0);
@@ -181,29 +198,12 @@ export function useCast(appContext) {
 
 	const subject2 = charB.subject ?? DEFAULT_SUBJECT2;
 
-	const rigA = rigs[charA.id] ?? null;
-
-	const rigB = (characters[1] ? rigs[charB.id] : null) ?? null;
-
 	function updateCharacterAt(index, next) {
-		const entry = domain.read()[index];
+		const base = domain.read()[index], raw = appContext.ports.read();
+		const entry = base && { ...base, ...shotAtFrame(raw.shots, raw.view.frame)?.cast[base.id] };
 		if (entry) return domain.edit('character.update', { characterId: entry.id, patch: typeof next === 'function' ? next(entry) : next });
 	}
 
-	// The shims keep the legacy call sites (inspector sliders, presets, pose
-	// studio, prompts) untouched while the list stays the source of truth.
-	const setCharA = (next) => updateCharacterAt(0, next);
-
-	const setCharB = (next) => updateCharacterAt(1, next);
-
-	const setPoseA = (pose) => updateCharacterAt(0, (entry) => ({ pose: typeof pose === "function" ? pose(entry.pose ?? DEFAULT_POSE) : pose }));
-
-	const setPoseB = (pose) => updateCharacterAt(1, (entry) => ({ pose: typeof pose === "function" ? pose(entry.pose ?? DEFAULT_POSE) : pose }));
-
-	const setSubject = (value) => updateCharacterAt(0, (entry) => ({ subject: typeof value === "function" ? value(entry.subject) : value }));
-
-	const setSubject2 = (value) => updateCharacterAt(1, (entry) => ({ subject: typeof value === "function" ? value(entry.subject) : value }));
-
 	function setShowB(next) {
 		return domain.run('cast.showExtras', { show: typeof next === 'function' ? next(domain.read().some((entry, i) => i > 0 && !entry.hidden)) : next });
 	}
@@ -221,7 +221,8 @@ export function useCast(appContext) {
 	}
 
 	function moveCharacter(charId, next) {
-		const entry = domain.read().find(entry => entry.id === charId);
+		const base = domain.read().find(entry => entry.id === charId), raw = appContext.ports.read();
+		const entry = { ...base, ...shotAtFrame(raw.shots, raw.view.frame)?.cast[charId] };
 		return domain.edit('character.update', { characterId: charId, patch: typeof next === 'function' ? next(entry) : next });
 	}
 
@@ -258,6 +259,7 @@ export function useCast(appContext) {
 	const spawnCharacter = (model, x, z) => {
 		const id = nextCharacterId(domain.read());
 		domain.run('character.add', { character: { id, model, x, z, pose: DEFAULT_POSE, subject: 'a person' } });
+		if (model === PROXY_FIGURE_MODEL) track("cast:proxy_added", { surface: "assets" });
 		appContext.shared.setSelectedHierarchyId(`character:${id}`);
 		appContext.notify(ko("Character added to the scene", "인물을 씬에 추가했어요"));
 	};
@@ -270,7 +272,6 @@ export function useCast(appContext) {
 		return `character:${key.startsWith("char:") ? key.slice(5) : key}`;
 	};
 
-	/* ------------------- active character (motion layer) ------------------- */
 	// Every character owns an animation layer (root path, prompt blocks,
 	// generated clip, IK keys). The studio's motion machinery edits ONE layer
 	// at a time — the ACTIVE character's — and selection decides who that is.
@@ -332,9 +333,6 @@ export function useCast(appContext) {
 		waypointFrames: (entry.layer?.waypoints ?? []).map((waypoint) => waypoint.frame),
 	}]), [characters, activeChar.id]);
 
-	// Undo/redo (plan §6.5). The store settles any open drag first, so a
-	// mid-drag press commits that drag as one entry and then steps past it.
-	// After a step the selection can point at a deleted object — drop it to
 	/* Cast authoring uses the registered store. The native compatibility
 	 * snapshot remains for motion/IK until its owner migrates; it must not
 	 * restore the owned cast over newer character edits. */
@@ -424,10 +422,9 @@ export function useCast(appContext) {
 	const posedRig = () => rigs[posing] ?? null;
 
 	const setPosed = (pose) => {
-		if (posingIndex >= 0) updateCharacterAt(posingIndex, { pose: typeof pose === "function" ? pose(posingChar?.pose ?? DEFAULT_POSE) : pose });
+		if (posingIndex >= 0) updateCharacterAt(posingIndex, entry => ({ pose: typeof pose === "function" ? pose(entry.pose ?? DEFAULT_POSE) : pose }));
 	};
 
-	/* ------------------------- waypoint workspace --------------------------- */
 	// A walking pace turns clicked distance into clip time, so pins land at
 	// frames the character can actually reach without ice-skating.
 	const WALK_SPEED_MPS = 1.4;
@@ -681,6 +678,23 @@ export function useCast(appContext) {
 			: ko(`Saved the current pose to the library as “${pose.label}”`, `지금 자세를 “${pose.label}”로 라이브러리에 저장했어요`));
 	}
 
+	/** A handle drag is an authored pose. When it ends, the rig as it now
+	 * stands becomes the posed character's own pose — so the scene autosaves
+	 * it and undo can step it back — instead of living only on the rig until
+	 * a reload re-applies the stored pose over it. The library is untouched;
+	 * Save pose still bottles a pose there. */
+	function commitPosedPose() {
+		const rig = posedRig();
+		if (!rig || !posingChar) return;
+		domain.run('character.setPose', { characterId: posingChar.id, clearMotion: false, pose: {
+			id: `edited:${posingChar.id}`,
+			label: ko("Edited pose", "편집한 포즈"),
+			prompt: "in the exact body pose shown in the blocking frame",
+			bones: capturePose(rig),
+			rootY: captureHipsOffset(rig),
+		} });
+	}
+
 	function savePose() {
 		const rig = posedRig();
 		if (!rig) return;
@@ -720,6 +734,8 @@ export function useCast(appContext) {
 		setPhotoPoseState("running");
 		setPhotoPoseError("");
 		try {
+			// A capsule figure has no bones for a photo to pose.
+			if (isProxyFigure(posingChar ?? activeChar)) throw new StudioProtocolError("TARGET_NOT_READY", kindRefusal("photoPose", isKo));
 			if (!rig) throw new Error("rig-not-loaded");
 			objectUrl = URL.createObjectURL(file);
 			let bones = null;
@@ -907,7 +923,9 @@ export function useCast(appContext) {
 			const live = appContext.live.state;
 			const patch = finitePatch(args, ["x", "z", "rot"]);
 			const id = nextCharacterId(live.characters);
-			replaceCharacters([...live.characters, createCharacterEntry({ id, model: args.model, subject: args.subject, pose: DEFAULT_POSE, ...patch }, live.characters.length)]);
+			const entry = createCharacterEntry({ id, model: args.model, subject: args.subject, pose: DEFAULT_POSE, ...patch }, live.characters.length);
+			replaceCharacters([...live.characters, entry]);
+			if (isProxyFigure(entry)) track("cast:proxy_added", { surface: "mcp" });
 			return { id };
 		}
 		function updateLiveCharacter(args) {
@@ -947,7 +965,6 @@ export function useCast(appContext) {
 				if (typeof block.text !== "string" || !block.text.trim()) throw new Error(`Block ${i + 1} needs text`);
 				return { id: `prompt-${stamp}-${i}`, startFrame, endFrame, text: block.text.trim() };
 			});
-			const live = appContext.live.state;
 			domain.run('character.setPromptBlocks', { characterId: domain.activeId, blocks: clips });
 			return { blocks: clips.length };
 		}
@@ -982,14 +999,14 @@ export function useCast(appContext) {
 			const motion = appContext.storeDomain('motion');
 			if (motion) motion.clear(characterId); else appContext.shared.motionDomain.clearMotionNative();
 		}, characterId, true);
-		domain.write(rows => rows.map(entry => entry.id === characterId ? { ...entry, pose } : entry));
+		domain.update(characterId, { pose });
 	};
 	appContext.updateActionPorts({ addCharacterWaypoint, moveCharacterWaypoint, removeCharacterWaypoint, clearCharacterWaypoints, setWaypointMode });
 	return {
 		...domain,
 		applyExternalCharacters, publishStudioCharacters, syncStudioLayerBuffer, undoScene, redoScene, snapshotStudioDomain, removeLegacyRootWaypoint, switchActiveCharacterLayer, createLegacyCastHandlers, toggleCharacterHidden,
 		characters, editCharacters, customPoses, posing, setPosing, posingClosing,
-		studioPick, setStudioPick, rigs, rigMountEpoch, setRigMountEpoch, setPoseTick, charA, charB, showB,
+		studioPick, setStudioPick, commitPosedPose, rigs, rigMountEpoch, setRigMountEpoch, setPoseTick, charA, charB, showB,
 		poseA, poseB, subject, subject2, updateCharacterAt, setShowB, moveCharacter, removeCharacter, reportRig,
 		spawnCharacter, charKeyToHierarchyId, charIdFromHierarchyId, activeCharacterId, setActiveCharacterId,
 		rowIdForCharIndex, activeChar, selectActiveCharacterInHierarchy, activeCharIndex, activeRig, waitForRig,

package/src/domains/motion/motion-intent-codec.js

@@ -0,0 +1,50 @@
+import * as THREE from "three";
+
+const sameMotionIntent = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const emptyMotionLayer = id => ({ id, take: null, fullTake: null, ikKeys: [], ikPins: [], ikPinResiduals: [], committedIkEdits: [], takeRecipe: null, takeVersions: [] });
+const keyVector = p => ({ x: p.x, y: p.y, z: p.z });
+const keyQuaternion = q => ({ ...keyVector(q), w: q.w });
+function encodeMotionKeys(keys) {
+	return [...keys].sort(([a], [b]) => a - b).map(([frame, tracks]) => ({ frame, tracks: Object.fromEntries([...tracks].map(([track, key]) => [track, {
+		...(key.q ? { q: key.q.map(keyQuaternion) } : {}), ...(key.p ? { p: keyVector(key.p) } : {}),
+		...(key.baseQ ? { baseQ: key.baseQ.map(keyQuaternion) } : {}), ...(key.basePos ? { basePos: keyVector(key.basePos) } : {}),
+		...(key.chainP ? { chainP: key.chainP.map(keyVector) } : {}), ...(key.keepTranslations ? { keepTranslations: true } : {}),
+		...(key.correctionRange ? { correctionRange: { start: key.correctionRange.start, end: key.correctionRange.end } } : {}),
+		...(key.blend != null ? { blend: key.blend } : {}),
+		...(key.pin ? { pin: key.pin } : {}),
+	}])) }));
+}
+function decodeMotionKeys(rows) {
+	const q = value => new THREE.Quaternion(value.x, value.y, value.z, value.w).normalize();
+	const p = value => new THREE.Vector3(value.x, value.y, value.z);
+	return new Map(rows.map(row => [row.frame, new Map(Object.entries(row.tracks).map(([track, key]) => [track, {
+		q: key.q?.map(q) ?? null, p: key.p ? p(key.p) : null,
+		...(key.baseQ ? { baseQ: key.baseQ.map(q) } : {}), ...(key.basePos ? { basePos: p(key.basePos) } : {}),
+		...(key.chainP ? { chainP: key.chainP.map(p) } : {}), ...(key.keepTranslations ? { keepTranslations: true } : {}),
+		...(key.correctionRange ? { correctionRange: { start: key.correctionRange.start, end: key.correctionRange.end } } : {}),
+		...(key.blend != null ? { blend: key.blend } : {}),
+		...(key.pin ? { pin: key.pin } : {}),
+	}]))]));
+}
+function cloneRangePin(pin) {
+	return {
+		...pin,
+		target: pin.target.space === "world"
+			? { space: "world", position: [...pin.target.position] }
+			: { space: "object", objectId: pin.target.objectId, local: [...pin.target.local] },
+	};
+}
+function encodeRangePins(pins) {
+	return [...(pins instanceof Map ? pins.values() : pins ?? [])].map(cloneRangePin);
+}
+function decodeRangePins(rows) {
+	return new Map((rows ?? []).map((pin) => [pin.id, cloneRangePin(pin)]));
+}
+function encodeRangePinResiduals(values) {
+	return [...(values instanceof Map ? values.entries() : values ?? [])].map(([id, entries]) => [id, (entries ?? []).map((entry) => ({ ...entry }))]);
+}
+function decodeRangePinResiduals(rows) {
+	return new Map((rows ?? []).map(([id, entries]) => [id, (entries ?? []).map((entry) => ({ ...entry }))]));
+}
+
+export { sameMotionIntent, emptyMotionLayer, encodeMotionKeys, decodeMotionKeys, cloneRangePin, encodeRangePins, decodeRangePins, encodeRangePinResiduals, decodeRangePinResiduals };

package/src/domains/motion/motion-range-pin-rules.js

@@ -0,0 +1,23 @@
+import { rangePinTracks } from "../../ardy/range-pin.js";
+import { ko } from "../../locale.js";
+
+export function ensureRangePinState(state) {
+	if (!state) return state;
+	if (!(state.pins instanceof Map)) state.pins = new Map();
+	if (!(state.pinResiduals instanceof Map)) state.pinResiduals = new Map();
+	return state;
+}
+export function rangePinConflictFrames(draft, state) {
+	if (!Number.isInteger(draft?.startFrame) || !Number.isInteger(draft?.endFrame) || draft.endFrame < draft.startFrame) return [];
+	const tracks = rangePinTracks(draft), conflicts = [];
+	for (let frame = draft.startFrame; frame <= draft.endFrame; frame += 1) {
+		if (tracks.some((track) => { const key = state.keys.get(frame)?.get(track); return key && key.pin !== draft.id; })) conflicts.push(frame);
+	}
+	return conflicts;
+}
+export function overlappingRangePin(draft, state) {
+	return [...ensureRangePinState(state).pins.values()].find((pin) => pin.id !== draft.id && rangePinTracks(pin).some((track) => rangePinTracks(draft).includes(track)) && Math.max(pin.startFrame, draft.startFrame) <= Math.min(pin.endFrame, draft.endFrame));
+}
+export function rangePinOverlapMessage(pin) {
+	return pin ? ko(`A required body or limb track already has an overlapping pin (${pin.startFrame}–${pin.endFrame}).`, `필요한 몸통 또는 팔다리 파츠에 겹치는 고정이 있어요 (${pin.startFrame}–${pin.endFrame}).`) : "";
+}