cozyclay 3.2.0 → 3.2.1

package/src/friction-hint.js

@@ -0,0 +1,82 @@
+// Say why a click or a key did nothing (#973). Chrome shows no title tooltip on a
+// disabled button, so the reason a control already carries in `title` was never
+// seen; a click on it now shows that reason in a short toast. Keys that need a
+// selection (Delete, Ctrl/Cmd+D, F) say so once in a while. Plain DOM, so the
+// capture-phase friction listeners can call it without a React round trip.
+import { ko } from "./locale.js";
+
+const SHOW_MS = 2200, SAME_HINT_GAP_MS = 4000, SELECTION_HINT_GAP_MS = 60_000;
+
+const FALLBACK = {
+	tool_pin: () => ko("Select a bone to pin first", "먼저 고정할 뼈를 선택하세요", "请先选择要固定的骨骼"),
+	tool_ik: () => ko("Select a character first", "먼저 캐릭터를 선택하세요", "请先选择角色"),
+	mode_pose: () => ko("Select a character to pose first", "먼저 포즈를 잡을 캐릭터를 선택하세요", "请先选择要摆姿势的角色"),
+	agent_send: () => ko("Type a message first", "먼저 메시지를 입력하세요", "请先输入消息"),
+};
+const HOSTED_AGENT = () => ko("The agent connects in the local app: npx cozyclay", "에이전트는 로컬 앱에서 연결돼요: npx cozyclay", "智能体需在本地应用中连接：npx cozyclay");
+
+let node = null, hideTimer = null, last = { text: "", at: -Infinity }, lastSelectionHintAt = -Infinity;
+let now = () => performance.now(), mount = (text) => showToast(text);
+
+/** The public cozyclay.org site, where no local agent server can run. */
+function hostedSite() {
+	const runtime = globalThis.__COZYCLAY_RUNTIME__;
+	if (runtime?.distribution === "npm") return false;
+	return /(^|\.)cozyclay\.org$/.test(globalThis.location?.hostname ?? "");
+}
+
+function showToast(text) {
+	const doc = globalThis.document;
+	if (!doc?.body) return;
+	if (!node || !node.isConnected) {
+		node = doc.createElement("div");
+		node.className = "toast friction-hint";
+		node.setAttribute("role", "status");
+		node.style.bottom = "64px";
+		doc.body.appendChild(node);
+	}
+	node.textContent = text;
+	node.hidden = false;
+	clearTimeout(hideTimer);
+	hideTimer = setTimeout(() => { if (node) node.hidden = true; }, SHOW_MS);
+}
+
+function show(text) {
+	if (!text) return;
+	const at = now();
+	if (text === last.text && at - last.at < SAME_HINT_GAP_MS) return;
+	last = { text, at };
+	mount(text);
+}
+
+/** The reason a disabled control gives: the hosted agent note, else its own title, else the per-control fallback. */
+function disabledReason(element, control) {
+	if (control === "agent_connect" && hostedSite()) return HOSTED_AGENT();
+	// data-disabled-reason is sometimes a machine id (no-shots, export-running); only a sentence is shown.
+	const reason = (element?.getAttribute?.("data-disabled-reason") || "").trim();
+	const own = (/\s/.test(reason) ? reason : element?.getAttribute?.("title") || "").trim().slice(0, 140);
+	return own || FALLBACK[control]?.() || null;
+}
+
+/** A click on a disabled control (click-friction.js). */
+export function hintDisabledClick(element, control) {
+	try { show(disabledReason(element, control)); } catch { /* a hint never affects a click */ }
+}
+
+/** Delete, Duplicate or Frame with nothing selected (shortcut-friction.js); at most once a minute. */
+export function hintNoSelection() {
+	try {
+		const at = now();
+		if (at - lastSelectionHintAt < SELECTION_HINT_GAP_MS) return;
+		lastSelectionHintAt = at;
+		show(ko("Select something first", "먼저 무언가를 선택하세요", "请先选择对象"));
+	} catch { /* advisory */ }
+}
+
+/** Tests only: capture shown hints and drive the clock; returns the restore. */
+export function frictionHintSeam({ capture, clock }) {
+	const previous = [mount, now];
+	mount = capture; now = clock;
+	last = { text: "", at: -Infinity }; lastSelectionHintAt = -Infinity;
+	return () => { [mount, now] = previous; last = { text: "", at: -Infinity }; lastSelectionHintAt = -Infinity; };
+}

package/src/live-control.js

@@ -185,7 +185,8 @@ export function createLiveControl({
 		const correlationId = props.request_id;
 		if (!correlationId) return;
 		if (EXECUTION_TELEMETRY_EVENTS.includes(payload.event)
-			&& EXECUTION_TELEMETRY_PROPERTY_KEYS[payload.event]?.some((key) => !Object.hasOwn(props, key))) return;
+			// A hub older than tool_name still sends a complete frame without it.
+			&& EXECUTION_TELEMETRY_PROPERTY_KEYS[payload.event]?.some((key) => key !== "tool_name" && !Object.hasOwn(props, key))) return;
 		const key = `${correlationId}:${payload.event}`;
 		if (capturedStages.has(key)) return;
 		capturedStages.add(key);

package/src/locale-zh/panels.js

@@ -222,4 +222,24 @@ export const ZH_PANELS = {
 	"Subjects": "角色",
 	"Subject": "角色",
 	"Add second subject": "添加第二个角色",
+	"Clear pose edits": "清除姿势修改",
+	"Reset to default pose": "重置为默认姿势",
+	"Remove every IK edit; the motion plays as it was": "移除所有 IK 修改；动作按原样播放",
+	"Left hand fingers": "左手手指",
+	"Right hand fingers": "右手手指",
+	"Edit fingertips": "编辑指尖",
+	"Editing fingertips": "正在编辑指尖",
+	"Drag a fingertip dot to bend that finger. The hand's move and rotate tools come back when you leave fingertip editing.": "拖动指尖圆点即可弯曲该手指。退出指尖编辑后，手的移动和旋转工具会恢复。",
+	"Turn on fingertip editing to drag fingertips in the viewport.": "开启指尖编辑后即可在视口中拖动指尖。",
+	"Open": "张开",
+	"Fist": "握拳",
+	"Thumb": "拇指",
+	"Index": "食指",
+	"Middle": "中指",
+	"Ring": "无名指",
+	"Pinky": "小指",
+	"Keep a copy on the asset shelf (Content › Sculpts), for any scene or project": "在素材架（内容 › 雕塑）上保存一份副本，可用于任何场景或项目",
+	"No sculpts on the shelf yet. Press Save to shelf in Sculpt mode (5), or import a .cozysculpt.json.": "素材架上还没有雕塑。在雕塑模式（5）中按“保存到素材架”，或导入 .cozysculpt.json 文件。",
+	"Select a sculpt to save it to the shelf.": "请选择一个雕塑以保存到素材架。",
+	"That card is no longer on the shelf.": "该卡片已不在素材架上。",
 };

package/src/locale-zh/shell.js

@@ -58,6 +58,7 @@ export const ZH_SHELL = {
 	"Untitled Scene": "未命名场景",
 	"Couldn't find the selected pose — pick again": "找不到所选姿势 — 请重新选择",
 	"Back to the default pose": "已返回默认姿势",
+	"Pose edits cleared — the motion stays": "已清除姿势修改 — 动作保持不变",
 	"When set, exports are written here instead of your browser's Downloads folder.": "设置后，导出文件会写入此文件夹，而不是浏览器的下载文件夹。",
 	"Folder access was denied. Choose another folder or use Downloads.": "文件夹访问被拒绝。请选择其他文件夹或使用下载文件夹。",
 	"Could not choose the export folder.": "无法选择导出文件夹。",
@@ -227,4 +228,7 @@ export const ZH_SHELL = {
 	"Help improve CozyClay with anonymous product events.": "通过匿名产品事件帮助改进 CozyClay。",
 	"Use a dark reference grid instead of the clay deck.": "使用深色参考网格替代黏土台面。",
 	"Shortcuts are read-only here. They stay active whenever focus is outside a text field.": "此处快捷键为只读。只要焦点不在文本输入框内，快捷键始终生效。",
+	"Front view (with a part selected, W moves it)": "前视图（选中部件时，W 移动部件）",
+	"Side view (with a part selected, E rotates it)": "侧视图（选中部件时，E 旋转部件）",
+	"Back view (with a part selected, R scales it)": "后视图（选中部件时，R 缩放部件）",
 };

package/src/locale-zh/workspace.js

@@ -73,6 +73,12 @@ export const ZH_WORKSPACE = {
 	"Choose project": "选择项目",
 	"Project navigation": "项目导航",
 	"Project mode": "项目模式",
+	"Cast style": "角色方式",
+	"Humanoid": "人形",
+	"Detailed previs with X/Y Bot: pose, IK and motion.": "用 X/Y Bot 做精细预演：姿势、IK 与动作。",
+	"Simple previs with capsule figures: path and posture.": "用胶囊人物做简单预演：路径与姿态。",
+	"Hybrid": "混合",
+	"Mix both; the agent may use capsules for hard shots.": "两者混用；难拍的镜头智能体可改用胶囊人物。",
 	"Block a shot in three moves": "三步完成镜头摆位",
 	"Choose a template, name the project, then place a character and frame the camera in the editor.": "选择模板、命名项目，然后在编辑器中放置角色并为摄影机取景。",
 	"Start a new project": "开始新项目",

package/src/motion/find-bone.js

@@ -0,0 +1,13 @@
+import { normalizeBoneName } from "../poses.js";
+
+/** A bone by Mixamo name; the matcher accepts the `mixamorig:` prefix and prefix-less rigs. */
+export function findBone(root, name) {
+	const target = normalizeBoneName(name);
+	let found = null;
+	root.traverse((object) => {
+		if (found || !object.isBone) return;
+		const norm = normalizeBoneName(object.name);
+		if (norm === target || norm.endsWith(target)) found = object;
+	});
+	return found;
+}

package/src/motion/fingers.js

@@ -0,0 +1,170 @@
+import * as THREE from "three";
+import { findBone } from "./find-bone.js";
+
+/**
+ * Finger posing for the IK layer. Every finger bone (Thumb/Index/Middle/Ring/Pinky 1..3, per side) is an
+ * FK joint track ("leftIndex2"), so keys, playback, take corrections and Undo reuse the joint path whole.
+ * A finger bends only around one hinge axis per bone, measured off the hand: the axis is perpendicular to
+ * the bone and to the palm normal, so a positive angle curls toward the palm. Angles are relative to the
+ * bind pose and clamped per joint.
+ */
+const FINGER_NAMES = ["Thumb", "Index", "Middle", "Ring", "Pinky"];
+const DEG = Math.PI / 180;
+// [min, max] bend in degrees per joint (base, middle, tip). The thumb folds across the palm, less far.
+const LIMITS = { Thumb: [[-20, 50], [-10, 60], [-10, 75]], other: [[-15, 90], [0, 100], [0, 80]] };
+const limitsOf = (name) => LIMITS[name] ?? LIMITS.other;
+
+const fingerTrackId = (side, name, joint) => `${side.toLowerCase()}${name}${joint}`;
+export const FINGER_TRACK_IDS = ["Left", "Right"].flatMap((side) => FINGER_NAMES.flatMap((name) => [1, 2, 3].map((joint) => fingerTrackId(side, name, joint))));
+
+const hingeCache = new WeakMap();
+/** The fingers of an FK joint map (resolveIkRig's fkJoints): each finger joint record points at its finger. */
+export const fingersOf = (fkJoints) => new Map([...(fkJoints?.values() ?? [])].filter((joint) => joint.finger).map((joint) => [joint.finger.id, joint.finger]));
+const tmp = { a: new THREE.Vector3(), b: new THREE.Vector3(), c: new THREE.Vector3(), q: new THREE.Quaternion() };
+
+function bindQuatOf(rig, bone) {
+	const saved = rig.userData?.poseBind?.get(bone);
+	return saved ? new THREE.Quaternion(saved.x, saved.y, saved.z, saved.w) : bone.quaternion.clone();
+}
+
+/** The palm normal, pointing to the side the fingers curl toward (the thumb's side of the knuckle plane). */
+function palmNormal(hand, index1, pinky1, middle1, thumb2) {
+	const at = (bone) => bone.getWorldPosition(new THREE.Vector3());
+	const handPos = at(hand), forward = at(middle1).sub(handPos), across = at(index1).sub(at(pinky1));
+	const normal = forward.clone().cross(across).normalize();
+	const knuckles = at(index1).add(at(pinky1)).multiplyScalar(0.5);
+	if (thumb2 && at(thumb2).sub(knuckles).dot(normal) < 0) normal.negate();
+	return normal;
+}
+
+/** The bone's hinge axis in its own local frame, measured once per bone (a hinge turn leaves it fixed). */
+function hingeAxis(bone, child, normal) {
+	let axis = hingeCache.get(bone);
+	if (axis) return axis;
+	const dir = child.getWorldPosition(tmp.a).sub(bone.getWorldPosition(tmp.b)).normalize();
+	const world = dir.clone().cross(normal);
+	if (world.lengthSq() < 1e-8) return null;
+	axis = world.normalize().applyQuaternion(bone.getWorldQuaternion(tmp.q).invert());
+	hingeCache.set(bone, axis);
+	return axis;
+}
+
+/**
+ * Resolve the fingers of a rig: returns a Map of "leftIndex" to its three bones, hinge axes, bind rotations
+ * and limits, and adds each bone to `fkJoints` under its track id (resolveIkRig's FK joint record shape).
+ * A rig without finger bones, or a finger missing one, simply has no entry.
+ */
+export function resolveFingers(rig, fkJoints) {
+	const fingers = new Map();
+	rig.updateMatrixWorld(true);
+	for (const side of ["Left", "Right"]) {
+		const bone = (name) => findBone(rig, `mixamorig${side}${name}`);
+		const hand = bone("Hand"), index1 = bone("HandIndex1"), pinky1 = bone("HandPinky1"), middle1 = bone("HandMiddle1");
+		if (!hand || !index1 || !pinky1 || !middle1) continue;
+		const normal = palmNormal(hand, index1, pinky1, middle1, bone("HandThumb2"));
+		for (const name of FINGER_NAMES) {
+			const bones = [1, 2, 3].map((joint) => bone(`Hand${name}${joint}`));
+			if (bones.some((entry) => !entry)) continue;
+			const tip = bone(`Hand${name}4`);
+			const axes = bones.map((entry, i) => hingeAxis(entry, bones[i + 1] ?? tip ?? entry.children[0], normal));
+			if (axes.some((axis) => !axis)) continue;
+			const id = `${side.toLowerCase()}${name}`, trackIds = [1, 2, 3].map((joint) => fingerTrackId(side, name, joint));
+			const finger = { id, side, name, bones, tip, axes, bindQuats: bones.map((entry) => bindQuatOf(rig, entry)), limits: limitsOf(name), trackIds };
+			fingers.set(id, finger);
+			bones.forEach((entry, i) => {
+				const saved = rig.userData?.poseBind?.get(entry)?.position;
+				fkJoints.set(trackIds[i], {
+					track: { id: trackIds[i], label: `${side} ${name} ${i + 1}`, bone: entry.name, child: (bones[i + 1] ?? tip)?.name ?? null, finger: true, group: "finger", visibilityDepth: 0.05 },
+					bone: entry, child: bones[i + 1] ?? tip ?? null, finger,
+					bindPos: saved ? new THREE.Vector3(saved.x, saved.y, saved.z) : entry.position.clone(),
+				});
+			});
+		}
+	}
+	return fingers;
+}
+
+/** The joint's current bend around its hinge, in radians from bind. */
+function jointAngle(finger, i) {
+	const rel = finger.bindQuats[i].clone().invert().multiply(finger.bones[i].quaternion);
+	const axis = finger.axes[i];
+	return 2 * Math.atan2(rel.x * axis.x + rel.y * axis.y + rel.z * axis.z, rel.w);
+}
+
+// Sets the joint's bend around its hinge and keeps whatever else the pose had on the bone (a take's spread
+// toward a held ball, a thumb's wrap): the rotation from bind splits into its turn about the hinge (twist)
+// and the rest (swing), and only the twist is replaced.
+function setJointAngle(finger, i, angle) {
+	const [min, max] = finger.limits[i], axis = finger.axes[i];
+	const clamped = Math.min(max * DEG, Math.max(min * DEG, angle));
+	const rel = finger.bindQuats[i].clone().invert().multiply(finger.bones[i].quaternion);
+	const along = rel.x * axis.x + rel.y * axis.y + rel.z * axis.z;
+	const twist = new THREE.Quaternion(axis.x * along, axis.y * along, axis.z * along, rel.w);
+	const swing = twist.lengthSq() < 1e-12 ? rel : rel.clone().multiply(twist.normalize().invert());
+	finger.bones[i].quaternion.copy(finger.bindQuats[i]).multiply(swing).multiply(tmp.q.setFromAxisAngle(axis, clamped));
+	finger.bones[i].updateMatrixWorld(true);
+}
+
+/** The fingertip in world space: the tip bone, or the last bone extended by its own length. */
+export function fingerTip(finger, out = new THREE.Vector3()) {
+	if (finger.tip) return finger.tip.getWorldPosition(out);
+	const end = finger.bones[2].getWorldPosition(out), mid = finger.bones[1].getWorldPosition(tmp.c);
+	return end.add(end.clone().sub(mid));
+}
+
+/**
+ * Curl the whole finger to `amount` (0 straight, 1 every joint at its maximum bend, as fingerCurl reads it). A finger
+ * already bent keeps its shape: each joint moves the same fraction of the way to straight (less curl) or to its maximum
+ * (more), so reading the curl and setting it back moves nothing, and 0 and 1 stay straight and fully bent.
+ */
+export function solveFingerCurl(finger, amount) {
+	const t = Math.min(1, Math.max(0, amount)), now = fingerCurl(finger);
+	const share = (i) => Math.max(0, jointAngle(finger, i)) / (finger.limits[i][1] * DEG);
+	const shares = finger.bones.map((_, i) => (t <= now ? share(i) * (now > 1e-6 ? t / now : 0) : share(i) + (1 - share(i)) * ((t - now) / (1 - now))));
+	shares.forEach((value, i) => setJointAngle(finger, i, value * finger.limits[i][1] * DEG));
+}
+
+/** Every finger of an FK joint map back at its bind rotation: a re-pose (a reset, a pose, a take) that names no finger
+ * leaves them straight, not at the last curl they were given. */
+export function restFingers(fkJoints) {
+	for (const finger of fingersOf(fkJoints).values()) finger.bones.forEach((bone, i) => { bone.quaternion.copy(finger.bindQuats[i]); bone.updateMatrixWorld(true); });
+}
+
+/** How curled the finger is now, 0..1 (mean of the joints' share of their maximum bend). */
+export function fingerCurl(finger) {
+	const shares = finger.bones.map((_, i) => Math.max(0, jointAngle(finger, i)) / (finger.limits[i][1] * DEG));
+	return Math.min(1, shares.reduce((sum, value) => sum + value, 0) / shares.length);
+}
+
+/** Fingertip IK: cyclic coordinate descent over the three hinges toward `target`, inside each joint's limits. */
+export function solveFingerReach(finger, target, iterations = 20) {
+	const joint = new THREE.Vector3(), tip = new THREE.Vector3(), axis = new THREE.Vector3(), toTip = new THREE.Vector3(), toTarget = new THREE.Vector3();
+	for (let pass = 0; pass < iterations; pass += 1) {
+		for (let i = 2; i >= 0; i -= 1) {
+			const bone = finger.bones[i];
+			bone.getWorldPosition(joint);
+			fingerTip(finger, tip);
+			axis.copy(finger.axes[i]).applyQuaternion(bone.getWorldQuaternion(tmp.q)).normalize();
+			toTip.copy(tip).sub(joint).projectOnPlane(axis);
+			toTarget.copy(target).sub(joint).projectOnPlane(axis);
+			if (toTip.lengthSq() < 1e-12 || toTarget.lengthSq() < 1e-12) continue;
+			const delta = Math.atan2(toTip.clone().cross(toTarget).dot(axis), toTip.dot(toTarget));
+			setJointAngle(finger, i, jointAngle(finger, i) + delta);
+		}
+		if (fingerTip(finger, tip).distanceTo(target) < 1e-4) break;
+	}
+}
+
+// One pose-mode gesture on a finger: { curl } bends the whole finger (panel), a world point is the
+// fingertip's IK target. Every joint of the finger is keyed.
+export function solveFingerGesture(finger, target, touch) {
+	if (!finger) return;
+	if (typeof target?.curl === "number") solveFingerCurl(finger, target.curl); else solveFingerReach(finger, target);
+	for (const id of finger.trackIds) touch(id);
+}
+
+export const FINGER_PRESETS = {
+	open: { Thumb: 0, Index: 0, Middle: 0, Ring: 0, Pinky: 0 },
+	fist: { Thumb: 0.7, Index: 1, Middle: 1, Ring: 1, Pinky: 1 },
+	point: { Thumb: 0.7, Index: 0, Middle: 1, Ring: 1, Pinky: 1 },
+};

package/src/motion/fingertip-pick.js

@@ -0,0 +1,21 @@
+/**
+ * The fingertip a press grabs. Candidates are `{ id, gap, reach, ... }`: the
+ * press's pixel distance to the tip's projected centre, and how far the tip
+ * reaches on screen. In range tips are tried nearest first, and the first one
+ * `isExposed(candidate)` accepts wins, so a tip the body hides (behind the palm
+ * or other fingers) is skipped for the next visible one. Null when no exposed
+ * tip is in range: the press is left for the IK handles (#913).
+ */
+export function pickFingertip(candidates, isExposed) {
+	return candidates
+		.filter((candidate) => candidate.gap <= candidate.reach)
+		.sort((a, b) => a.gap - b.gap)
+		.find((candidate) => isExposed(candidate)) ?? null;
+}
+
+/** Pick for a pointerdown and claim the event only when a tip is picked; otherwise it passes on untouched. */
+export function claimFingertip(event, candidates, isExposed) {
+	const picked = pickFingertip(candidates, isExposed);
+	if (picked) { event.stopImmediatePropagation(); event.stopPropagation(); event.preventDefault(); }
+	return picked;
+}

package/src/motion/ik-exposure.js

@@ -0,0 +1,48 @@
+import { Raycaster, Vector3 } from "three";
+import { ikControlIsExposed } from "./ik.js";
+
+/**
+ * Distance from the camera to the first opaque surface on the way to a control
+ * `targetDistance` away along `direction`, or undefined when nothing is in front.
+ * Static blockers are raycast; a skinned mesh is read off its cached cloud of
+ * skin-surface spheres ({ points, radius }), which keeps the animated silhouette
+ * without skinning every triangle once per control ray.
+ */
+export function blockerDistanceTo(ray, cameraPos, direction, targetDistance, staticBlockers, skinnedProxies) {
+	ray.set(cameraPos, direction);
+	ray.near = 0.001;
+	ray.far = Math.max(0.001, targetDistance - 0.001);
+	let blockerDistance = ray.intersectObjects(staticBlockers, false)[0]?.distance;
+	for (const proxy of skinnedProxies) {
+		const radiusSq = proxy.radius * proxy.radius;
+		for (const point of proxy.points) {
+			const dx = point.x - cameraPos.x, dy = point.y - cameraPos.y, dz = point.z - cameraPos.z;
+			const along = dx * direction.x + dy * direction.y + dz * direction.z;
+			if (along < 0 || along > targetDistance + proxy.radius) continue;
+			const perpendicularSq = dx * dx + dy * dy + dz * dz - along * along;
+			if (perpendicularSq > radiusSq) continue;
+			const distance = Math.max(0, along - Math.sqrt(radiusSq - perpendicularSq));
+			if (distance < (blockerDistance ?? Infinity)) blockerDistance = distance;
+		}
+	}
+	return blockerDistance;
+}
+
+/**
+ * An exposure probe over the blockers of the last IkHandles exposure pass:
+ * `(worldPoint, visibilityDepth) => boolean`, the same rule the IK controls use.
+ * A fingertip is smaller than the 4 cm skin-proxy spheres (neighbouring fingers
+ * read as blockers), so the probe raycasts the skinned meshes themselves; it runs
+ * once per press, not per frame. Before any pass nothing is in front: exposed.
+ */
+export function exposureProbe(camera, occluders) {
+	const ray = new Raycaster(), cameraPos = new Vector3(), direction = new Vector3();
+	ray.layers.set(0);
+	return (point, visibilityDepth) => {
+		camera.getWorldPosition(cameraPos);
+		const targetDistance = cameraPos.distanceTo(point);
+		direction.copy(point).sub(cameraPos).normalize();
+		const blockerDistance = blockerDistanceTo(ray, cameraPos, direction, targetDistance, occluders.current?.blockers ?? [], []);
+		return ikControlIsExposed(targetDistance, blockerDistance, visibilityDepth);
+	};
+}

package/src/motion/ik.js

@@ -1,5 +1,8 @@
 import * as THREE from "three";
 import { normalizeBoneName, POSE_BONES, DEFAULT_POSE } from "../poses.js";
+import { resolveFingers } from "./fingers.js";
+import { findBone } from "./find-bone.js";
+export { findBone };
 
 /**
  * Frame-based IK layer for direct character posing, following the DCC
@@ -412,16 +415,6 @@ const CHAINS = {
 	leg: (side) => [`mixamorig${side}UpLeg`, `mixamorig${side}Leg`, `mixamorig${side}Foot`],
 };
 
-export function findBone(root, name) {
-	const target = normalizeBoneName(name);
-	let found = null;
-	root.traverse((object) => {
-		if (found || !object.isBone) return;
-		const norm = normalizeBoneName(object.name);
-		if (norm === target || norm.endsWith(target)) found = object;
-	});
-	return found;
-}
 
 /**
  * Resolve the IK rig against a character: the four two-bone chains, plus
@@ -508,7 +501,7 @@ export function resolveIkRig(rig) {
 			})(),
 		});
 	}
-	return { chains: out, fkJoints, contactRadii, contactHeights: measureContactHeights(rig) };
+	return { chains: out, fkJoints, fingers: resolveFingers(rig, fkJoints), contactRadii, contactHeights: measureContactHeights(rig) };
 }
 
 /**

package/src/motion3/compiler/head-lead.js

@@ -5,10 +5,12 @@
 // step, head-steady.js walkSpans) and around every turn of the trunk faster than TURN deg/frame (from LEAD + FADE
 // frames before it, so the head starts first), faded in and out over FADE frames, and never where the spec's own keys move
 // head_yaw during that span (keys on it, or on either side of it, that differ): a keyed look wins; a head held still
-// (a stance's head_yaw 0) leads.
+// (a stance's head_yaw 0) leads. A skill's own look that rides a turn (NOT_A_LOOK: exitCar's head as it swivels out of
+// the seat) is not a keyed look: the lead goes on top of it. The agent's keys, and every other skill's, still win.
 import { walkSpans } from "./head-steady.js";
 
 const MAX = 30, TURN = 0.3, FADE = 8, STRIDE = 33;
+const NOT_A_LOOK = /\bwalk(To)? (start|step \d+|end)$|^use\[\d+\] exitCar$/; // walk.js keys, OWN_LOOK skills (skills/car.js)
 
 /** Inside a walk the trunk's heading, its sway each step taken out: the median over about a stride keeps a turn's timing. */
 function heading(trunk, walks) {
@@ -45,7 +47,7 @@ function merged(spans) {
 
 /** The keys outside walks that move head_yaw during [f0, f1]: those in it and the nearest on either side differ. */
 function looked(keys, f0, f1) {
-	const looks = keys.filter(k => k.set?.head_yaw !== undefined && !/\bwalk(To)? (start|step \d+|end)$/.test(k.src ?? "")).sort((a, b) => a.f - b.f);
+	const looks = keys.filter(k => k.set?.head_yaw !== undefined && !NOT_A_LOOK.test(k.src ?? "")).sort((a, b) => a.f - b.f);
 	const near = [looks.filter(k => k.f < f0).at(-1), ...looks.filter(k => k.f >= f0 && k.f <= f1), looks.find(k => k.f > f1)].filter(Boolean);
 	return near.some(k => JSON.stringify(k.set.head_yaw) !== JSON.stringify(near[0].set.head_yaw));
 }

package/src/motion3/hybrid-hint.js

@@ -0,0 +1,19 @@
+// A hybrid project's rig take that stopped paying: the compile result says so in one line, so the
+// agent proposes capsule figures before more repairs instead of reading output.stuck as advisory
+// (bin/agent/studio-prompt.mjs, the hybrid cast gate).
+
+/** QA group kinds that a rig rarely repairs by more compiles: contact, collision, balance, body. */
+export const HYBRID_HARD_KINDS = Object.freeze(["LOAD", "COLLIDE", "BODY", "SELF", "PERSON"]);
+export const HYBRID_CAPSULE_HINT = "hybrid project: propose capsule figures to the user before more repairs";
+
+/**
+ * The hint for a compile in a project with this castStyle, or null. It fires in a hybrid project
+ * only on a failing take (qa.ok false), when the repair watch said stuck or cap, or when the worst
+ * non-GOAL group (qa.groups is ranked) is hard. A stuck note on a passing take (the watch's
+ * "already passed QA" polish) is no reason to leave the rig.
+ */
+export function hybridCapsuleHint(castStyle, { stuck, qa } = {}) {
+	if (castStyle !== "hybrid" || qa?.ok !== false) return null;
+	const top = (qa?.groups ?? []).find(group => group.kind !== "GOAL");
+	return stuck || HYBRID_HARD_KINDS.includes(top?.kind) ? HYBRID_CAPSULE_HINT : null;
+}

package/src/motion3/load.js

@@ -7,7 +7,8 @@
 //   observe  output.observations.load: each hand that carries something, { object, mass, maxNm, at, frames }
 //   LOAD     "<side> holds <id> at <x> N m": past QA_LIMITS-style ONE_HAND N m with no second hand on the object; its
 //            hint asks for the other hand, and when the right hand holds, a patch adds a left reachGrip that arrives at
-//            the grab on the object's face nearest the left shoulder (second-hand.js holds only a right-hand carry)
+//            the grab on the object's face nearest the left shoulder, with the other faces as candidates repair compiles
+//            and picks from (repair.js; second-hand.js holds only a right-hand carry)
 // fix.grasp false turns all three off: the take of before.
 import { add, sub, scale, norm, apply, T, len } from "./compiler/math.js";
 import { SIDES } from "./compiler/pose.js";
@@ -18,6 +19,9 @@ import { handOf, spanOf, partsOf, objectPoseAt } from "./object-pose.js";
 import { SETTLE, restOf } from "./seat.js";
 
 const REACH = 10, G = 9.81, LIGHT = 2, SAG_MAX = 0.06, SAG_PER_KG = 0.006, ONE_HAND = 25, SECOND = 0.5;
+// the left palm's axis sits a palm radius (qa/grasp-checks.js PALM) out of the face, so its skin is on it, not its bone;
+// on the 12 kg box at 0 the forearm grazed the edge (+X face: QA 42), at 0.022 none (QA 0); at most FACES candidates
+const STANDOFF = 0.022, FACES = 4;
 export const LOAD_UNITS = "load: what each hand carries, kg, and its most N m (mass x 9.81 x the shoulder-to-wrist distance across) at f; frames [first, last] held";
 
 const graspOn = spec => spec?.fix !== false && spec?.fix?.grasp !== false;
@@ -91,19 +95,21 @@ export function loadChecks(sk, out) {
 }
 
 /**
- * The anchor point (object local) for the left hand on carry id at frame f: the centre of the face nearest the left
- * shoulder, of the faces other than the bottom and the one the right palm is on (the box's other side, as two hands hold it).
+ * The anchor points (object local) for the left hand on carry id at frame f, nearest the left shoulder first: the
+ * centres of the faces other than the bottom and the one the right palm is on (the box's other side, as two hands hold
+ * it), each STANDOFF out of its face. Which face is cheapest the distance does not tell (on the 12 kg box the top won
+ * by 0.3 mm and sent the hand through the edge: QA 121, the +X face 42), so repair compiles them all (repair.js).
  */
-function otherFace(out, id, f) {
+function otherFaces(out, id, f) {
 	const { sk, scene } = out.ctx, s = out.frames[f - (out.f0 ?? 0)]?.s, pose = objectPoseAt(out, id, f), rest = restOf(scene, id);
 	const part = scene.objects[partsOf(scene, id)[0]] ?? scene.objects[id];
-	if (!s || !pose || !part?.half) return null;
+	if (!s || !pose || !part?.half) return [];
 	const toLocal = p => apply(T(pose.R), sub(p, pose.pos)), c = apply(T(rest.R), sub(add(part.pos, apply(part.R, [0, part.half[1], 0])), rest.pos));
 	const palm = toLocal(scale(add(s.P[sk.index.RightHand], s.P[sk.index.RightHandMiddle1]), 0.5)), shoulder = toLocal(s.P[sk.index.LeftArm]);
 	const faces = [0, 1, 2].flatMap(i => [-1, 1].map(sg => { const p = c.slice(); p[i] += sg * part.half[i]; return { p, i, sg }; })).filter(x => !(x.i === 1 && x.sg < 0));
 	const palmFace = faces.reduce((m, x) => (Math.abs(palm[x.i] - x.p[x.i]) < Math.abs(palm[m.i] - m.p[m.i]) ? x : m));
-	const best = faces.filter(x => x !== palmFace).reduce((m, x) => (len(sub(x.p, shoulder)) < len(sub(m.p, shoulder)) ? x : m));
-	return best.p.map(x => Math.round(x * 1000) / 1000);
+	const off = x => x.p.map((v, i) => Math.round((i === x.i ? v + x.sg * STANDOFF : v) * 1000) / 1000);
+	return faces.filter(x => x !== palmFace).map(x => ({ x, d: len(sub(x.p, shoulder)) })).sort((a, b) => a.d - b.d).slice(0, FACES).map(({ x }) => off(x));
 }
 
 export const loadHints = {
@@ -114,12 +120,13 @@ export const loadHints = {
 		const k = side === "left" ? "l" : "r", other = k === "r" ? "left" : "right", [grab] = spanOf(X.out, o), kg = massOf(X.spec, X.out.ctx.scene, id);
 		const plain = { cause: `objects.${id} (${kg.toFixed(1)} kg)`, hint: `${id} weighs ${kg.toFixed(1)} kg: ${g.worst.toFixed(0)} N m on the ${side} arm at f${g.worstFrame} (one hand holds ${ONE_HAND}); put the ${other} hand on it too (a reachGrip on an object anchor on ${id} from f${grab}), or carry it closer to the body` };
 		if (k !== "r") return plain;
-		const local = otherFace(X.out, id, Math.max(grab, Math.min(g.worstFrame, spanOf(X.out, o)[1])));
-		if (!local) return plain;
+		const faces = otherFaces(X.out, id, Math.max(grab, Math.min(g.worstFrame, spanOf(X.out, o)[1])));
+		if (!faces.length) return plain;
 		const name = `${id}Other`;
 		// a big face takes the flat palm against it (a power grip's thumb would go into the box)
-		const anchor = { kind: "object", object: id, local, grasp: "palm" };
-		return { ...plain, fix: { ops: user => [user.anchors ? { op: "add", path: `/anchors/${name}`, value: anchor } : { op: "add", path: "/anchors", value: { [name]: anchor } },
-			{ op: "add", path: "/use/-", value: { skill: "reachGrip", f0: Math.max(0, grab - REACH), args: { anchor: name, side: "l", reach: Math.min(REACH, grab) || 1, hold: Math.max(1, spanOf(X.out, o)[1] - grab), release: 1 } } }] } };
+		const ops = local => user => { const anchor = { kind: "object", object: id, local, grasp: "palm" };
+			return [user.anchors ? { op: "add", path: `/anchors/${name}`, value: anchor } : { op: "add", path: "/anchors", value: { [name]: anchor } },
+				{ op: "add", path: "/use/-", value: { skill: "reachGrip", f0: Math.max(0, grab - REACH), args: { anchor: name, side: "l", reach: Math.min(REACH, grab) || 1, hold: Math.max(1, spanOf(X.out, o)[1] - grab), release: 1 } } }]; };
+		return { ...plain, fix: { ops: ops(faces[0]), candidates: faces.map(ops) } };
 	},
 };

package/src/motion3/qa/hints-contact.js

@@ -96,10 +96,22 @@ function probes(X, f, nm) {
 	return Object.entries(diag.props?.[nm.slice(5)] ?? {}).filter(([k, p]) => Array.isArray(p) && k !== "origin").map(([, p]) => p);
 }
 
+/** The most a hand's reachGrip world anchor rises over a scene box's top it went into (#819: past ~3.5 cm the fingers miss the thing). */
+const GRIP_LIFT = 0.035;
+/** A hand whose reachGrip world anchor sits too low over a scene box's top: that anchor rises by what the hit lacks. */
+function gripLift(X, g, part, id, need) {
+	const f = g.worstFrame, k = sideOf(part), box = X.out.objectsAt(X.rel(f))[id], d = X.hand(k, f);
+	const grip = d.anchor && X.keys(d.ch).some(key => / reachGrip$/.test(key.src));
+	if (!/^hand_[lr]$/.test(part) || !box || X.spec.objects?.[id] || !grip || X.spec.anchors?.[d.anchor]?.kind !== "world" || !(need > 0 && need <= GRIP_LIFT)) return null;
+	return deepest(X, f, part, box).n[1] > 0.5 ? moveHint(X, part, f, [0, need, 0], ` (over ${id}'s top)`) : null;
+}
+
 export const contactHints = {
 	COLLIDE(X, g) {
 		const [, part, id] = /^(\S+) x (.+)$/.exec(g.subject) ?? [];
 		if (/^foot_[lr]$/.test(part ?? "")) return footHint(X, g, part, id);
+		const lift = gripLift(X, g, part, id, g.worst - g.limit + MARGIN);
+		if (lift) return lift;
 		const r = boxHint(X, g, part, id, g.worst - g.limit + MARGIN);
 		if (r && /^(hand|farm)_/.test(part) && !X.spec.fix?.penetration && g.worst - g.limit <= 0.05) {
 			r.hint += "; or fix.penetration: 0.02 pushes shallow hand hits out";

package/src/motion3/qa/patch.js

@@ -7,6 +7,8 @@
 //   { path: "/anchors/cupHandle/p", delta: [dx, dy, dz] }     move a spec value by delta
 //   { channel: "root", f, delta, hold: true }                  move the body that stands at f
 //   { ops: userSpec => [{ op, path, value }] }                 the operations for the agent's spec (a second hand: load.js)
+//     + candidates: [ops, ...]                                 other ways to the same end, which compile repair alone can
+//                                                              price: g.candidates (non-enumerable, never in the output)
 // Each becomes g.patch = [{ op, path, value }] against opts.userSpec (the spec as the agent sent
 // it, use[] not expanded): a user key that sets the channel within f +-2 -> replace
 // /keys/<i>/set/<ch> (a delta: with the agent's keys next to it that hold the same value, so a held
@@ -177,8 +179,9 @@ export function attachPatches(groups, { X, userSpec } = {}) {
 	for (const g of groups) {
 		if (!g.fix) continue;
 		try {
-			const patch = patchOf(g.fix, X, userSpec);
+			const patch = patchOf(g.fix, X, userSpec), more = patch && (g.fix.candidates ?? []).map(ops => patchOf({ ops }, X, userSpec)).filter(Boolean);
 			if (patch) g.patch = patch;
+			if (more?.length > 1) Object.defineProperty(g, "candidates", { value: more, enumerable: false, configurable: true });
 		} catch {
 			// a fix the context cannot place (no frame, no key table) gets no patch
 		}

package/src/motion3/qa/verdict.js

@@ -2,7 +2,8 @@
 // (hint-check.js) offers a patch by. Better means all of
 //   less       the summed severity (severity.js) drops
 //   goals      no more goals fail, and every goal that held still holds
-//   problems   no more issue groups than before
+//   problems   no more issue groups than before, unless a HARD group is gone and every new group is SMALL: a second
+//              hand that ends a LOAD may leave a forearm grazing the box, which the next repair round can finish
 //   trade      what got worse (a new group, or a group whose severity rose) costs at most half of what got better
 // Logs: a hint patch applied as sent made the take worse 49% of the time, and repair moved the root and broke the arms;
 // a lower sum alone let a change through that traded one failure for several new ones.
@@ -13,6 +14,9 @@ const sevOf = qa => groupsOf(qa).reduce((sum, g) => sum + (g.severity ?? 0), 0);
 const heldOf = qa => (qa?.goals ?? []).filter(g => g.ok).map(g => g.name);
 const failedOf = qa => (qa?.goals ?? []).filter(g => !g.ok).length;
 const TRADE = 0.5;
+// failures the take cannot keep (a hand that cannot hold its load), and the severity (severity.js) a new group may have
+// for a change that ends one to pass with more groups: 5 is a few frames just past a limit, never a held failure
+const HARD = new Set(["LOAD"]), SMALL = 5;
 const r2 = x => Math.round(x * 100) / 100;
 
 /** The group severities by key (severity.js groupKey). */
@@ -35,9 +39,10 @@ export function compareQa(next, base) {
 	worse.sort((x, y) => y.severity[1] - y.severity[0] - (x.severity[1] - x.severity[0]));
 	const sev = [r2(sevOf(base)), r2(sevOf(next))], problems = [groupsOf(base).length, groupsOf(next).length];
 	const lost = heldOf(base).filter(n => !heldOf(next).includes(n));
+	const ends = groupsOf(base).some(g => HARD.has(g.kind) && !b.has(groupKey(g))) && [...b].every(([k, v]) => a.has(k) || v <= SMALL);
 	const why = !(sevOf(next) < sevOf(base) - 1e-9) ? `summed severity ${sev[0]} -> ${sev[1]}`
 		: failedOf(next) > failedOf(base) || lost.length ? `goal ${lost.length ? `"${lost[0]}" no longer holds` : "failures rose"}`
-			: problems[1] > problems[0] ? `problems ${problems[0]} -> ${problems[1]}`
+			: problems[1] > problems[0] && !ends ? `problems ${problems[0]} -> ${problems[1]}`
 				: rise > TRADE * drop + 1e-9 ? `${worse[0]?.key} got worse (${worse[0]?.severity.join(" -> ")})` : "";
 	return { better: !why, why, sev, problems, worse: worse.slice(0, 3) };
 }