cozyclay 3.1.6 → 3.2.1

package/src/finger-handles.jsx

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

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/center-of-mass.js

@@ -1,20 +1,14 @@
 import * as THREE from "three";
 import { findBone } from "./ik.js";
+import { SEGMENT_FRACTIONS } from "../motion3/qa/com.js";
 
 // Body segment masses and the centre of mass of a posed Mixamo rig. Read-only:
 // motion verification and the support diagnostics measure with it.
 
 /**
- * Segment mass fractions of total body mass, from Dempster's cadaver study
- * (Dempster, W.T., "Space Requirements of the Seated Operator", WADC TR
- * 55-159, 1955), in the tabulation popularised by Winter, "Biomechanics and
- * Motor Control of Human Movement". The trunk (0.497) is split into pelvis
- * (0.142) and thorax+abdomen (0.355); distal pairs are merged because their
- * combined centroid still lands near the segment midpoint and Mixamo's hand
- * and toe bones are too short to place reliably:
- *
- *   head+neck 0.081 · trunk 0.497 · upper arm 0.028 · forearm 0.016 +
- *   hand 0.006 = 0.022 · thigh 0.100 · shank 0.0465 + foot 0.0145 = 0.061
+ * Segment mass fractions of total body mass (Dempster, via Winter), on Mixamo
+ * bone names. The table itself lives with motion3 QA (motion3/qa/com.js
+ * SEGMENT_FRACTIONS), which measures balance on the same segments.
  *
  * Each entry names the two Mixamo bones whose MIDPOINT carries the fraction.
  * Dempster's true centres of mass sit ~43% down each segment rather than at
@@ -24,19 +18,7 @@ import { findBone } from "./ik.js";
  *
  * The fractions sum to 1, so the weighted average below is a true CoM.
  */
-export const SEGMENT_MASSES = [
-	{ id: "pelvis", start: "mixamorigHips", end: "mixamorigSpine1", mass: 0.142 },
-	{ id: "torso", start: "mixamorigSpine1", end: "mixamorigNeck", mass: 0.355 },
-	{ id: "head", start: "mixamorigNeck", end: "mixamorigHead", mass: 0.081 },
-	{ id: "leftUpperArm", start: "mixamorigLeftArm", end: "mixamorigLeftForeArm", mass: 0.028 },
-	{ id: "leftForeArmHand", start: "mixamorigLeftForeArm", end: "mixamorigLeftHand", mass: 0.022 },
-	{ id: "rightUpperArm", start: "mixamorigRightArm", end: "mixamorigRightForeArm", mass: 0.028 },
-	{ id: "rightForeArmHand", start: "mixamorigRightForeArm", end: "mixamorigRightHand", mass: 0.022 },
-	{ id: "leftThigh", start: "mixamorigLeftUpLeg", end: "mixamorigLeftLeg", mass: 0.100 },
-	{ id: "leftShankFoot", start: "mixamorigLeftLeg", end: "mixamorigLeftFoot", mass: 0.061 },
-	{ id: "rightThigh", start: "mixamorigRightUpLeg", end: "mixamorigRightLeg", mass: 0.100 },
-	{ id: "rightShankFoot", start: "mixamorigRightLeg", end: "mixamorigRightFoot", mass: 0.061 },
-];
+export const SEGMENT_MASSES = SEGMENT_FRACTIONS.map(({ id, start, end, mass }) => ({ id, start: `mixamorig${start}`, end: `mixamorig${end}`, mass }));
 
 /**
  * World-space centre of mass of the rig's CURRENT pose: the mass-weighted

package/src/motion/contact-project.js

@@ -0,0 +1,143 @@
+import * as THREE from "three";
+import { closestPointsSegmentSegment } from "./fix-collisions.js";
+
+/**
+ * Contact projection for a Studio IK drag: the dragged target is moved out of
+ * the OTHER characters' capsules before the chain solves toward it, so a hand
+ * pushed into someone's chest stops on the chest instead of going through.
+ *
+ * One-sided by design: the blockers never move (the other character is never
+ * pushed; what they do is their own take). Fixed pass count, fixed order
+ * (probe capsules in the order given, blockers in the order given, the first
+ * deepest pair wins a tie), no clock, no randomness: the same target, the same
+ * blockers and the same `lastGood` give the same result.
+ *
+ * KEEP THE SIDE. The plain escape normal (probe point minus blocker point)
+ * flips once a deep target crosses the blocker's axis and then pushes the hand
+ * out of the BACK of the body. The escape keeps the side the hand came from:
+ * when the normal points away from `lastGood` (the last clean target of this
+ * drag), the push goes toward `lastGood` instead. Of the escape rules tried in
+ * the research prototype this was the only one that never tunnelled.
+ */
+
+const EPS = 1e-9;
+
+/** Push distance along unit `dir` that takes point `w` (relative to the
+ * blocker point) to distance `reach` from it: the far root of |w + t dir| = reach. */
+function exitDistance(w, dir, reach) {
+	const along = w.dot(dir);
+	const inside = w.lengthSq() - reach * reach;
+	return -along + Math.sqrt(Math.max(0, along * along - inside));
+}
+
+/**
+ * @param {object} options
+ * @param {Array<{id:string,a:THREE.Vector3,b:THREE.Vector3,radius:number}>} options.blockers
+ *   the other characters' capsules, built once per drag; never moved
+ * @param {number|((probeId:string, blockerId:string) => number|null)} [options.allow]
+ *   depth (m) a probe may go into a blocker: a number for every pair, or a
+ *   lookup (null = 0) for an intended touch (spec.checks.allow person entries)
+ * @param {number} [options.margin]  how far outside the surface a pushed target lands
+ * @param {number} [options.passes] fixed number of probe/push passes
+ * @param {number} [options.maxSteps] cap on the sweep's substeps per event
+ */
+export function createContactProjector({ blockers = [], allow = 0, margin = 0.004, passes = 4, maxSteps = 32 } = {}) {
+	// sweep spacing: no substep longer than the thinnest blocker's radius
+	const thinnest = Math.max(0.005, Math.min(...blockers.map((b) => b.radius)));
+	const allowed = typeof allow === "function" ? (p, b) => Math.max(0, allow(p, b) ?? 0) : () => Math.max(0, allow ?? 0);
+	const onProbe = new THREE.Vector3(), onBlocker = new THREE.Vector3(), w = new THREE.Vector3(), dir = new THREE.Vector3(), side = new THREE.Vector3();
+	const best = { depth: 0, reach: 0, probe: new THREE.Vector3(), blocker: new THREE.Vector3() };
+
+	/** The deepest probe/blocker pair past its allowance, written into `best`; false when none. */
+	function deepest(capsules) {
+		best.depth = 0;
+		for (const capsule of capsules) {
+			for (const blocker of blockers) {
+				const reach = capsule.radius + blocker.radius - allowed(capsule.id, blocker.id);
+				const dist = Math.sqrt(closestPointsSegmentSegment(capsule.a, capsule.b, blocker.a, blocker.b, onProbe, onBlocker));
+				if (reach - dist <= best.depth) continue;
+				best.depth = reach - dist;
+				best.reach = reach;
+				best.probe.copy(onProbe);
+				best.blocker.copy(onBlocker);
+			}
+		}
+		return best.depth > 0;
+	}
+
+	/**
+	 * SWEEP. A clean endpoint is not enough: one pointer event can carry the
+	 * limb clean across a thin blocker (a forearm, a hand). Walk from the
+	 * handle as displayed (`from.at`) to the target in equal substeps no
+	 * longer than the thinnest blocker's radius (at most `maxSteps`; a longer
+	 * jump gets longer substeps) and stop at the first substep that touches
+	 * after a clean one. Returns that substep (the keep-the-side push then runs
+	 * there, with the clean substep before it as the side), `{ at: null }`
+	 * when the target is clean and so was the way there, or null when the path
+	 * never got clean (the limb as displayed is in contact, e.g. the drag
+	 * opened touching, and a start in contact only stops once clean).
+	 *
+	 * The start is judged on the limb AS DISPLAYED (`from.capsules`), not by
+	 * solving toward lastGood again: the drag's solve does not land its handle
+	 * on the target in one call, so a second solve toward the same clean
+	 * target moves the limb on, into the blocker it had stopped short of, and
+	 * the whole crossing then read as a start in contact allowed to leave.
+	 */
+	function firstTouch(target, probe, from) {
+		const steps = Math.min(maxSteps, Math.max(1, Math.ceil(from.at.distanceTo(target) / thinnest)));
+		let wasClean = !deepest(from.capsules);
+		const clean = from.at.clone();
+		for (let k = 1; k <= steps; k++) {
+			const at = k === steps ? target.clone() : from.at.clone().lerp(target, k / steps);
+			if (!deepest(probe(at))) {
+				wasClean = true;
+				clean.copy(at);
+			} else if (wasClean) return { at, clean };
+		}
+		return wasClean ? { at: null, clean } : null;
+	}
+
+	/**
+	 * Move `target` out of the blockers.
+	 * @param {THREE.Vector3} target  the dragged point (not mutated)
+	 * @param {(candidate:THREE.Vector3) => Array<{id:string,a:THREE.Vector3,b:THREE.Vector3,radius:number}>} probe
+	 *   the dragged limb's capsules when its handle sits at `candidate`
+	 * @param {THREE.Vector3|null} lastGood  the last clean target of this drag (the side to keep)
+	 * @param {{at:THREE.Vector3, capsules:Array}|null} [from]  the handle and the limb's
+	 *   capsules as displayed when the event began: where the sweep starts
+	 *   (default: lastGood, with the limb probed there)
+	 * @returns {{ target: THREE.Vector3, contact: boolean, depth: number }}
+	 *   `contact` = a push happened; `depth` = what is left after the last pass (0 = clean)
+	 */
+	function project(target, probe, lastGood = null, from = null) {
+		let out = target.clone();
+		let contact = false;
+		if (!blockers.length) return { target: out, contact, depth: 0 };
+		const hit = lastGood ? firstTouch(out, probe, from ?? { at: lastGood, capsules: probe(lastGood) }) : null;
+		if (hit && !hit.at) return { target: out, contact, depth: 0 };
+		if (hit) out = hit.at;
+		const keep = hit?.clean ?? lastGood;
+		for (let pass = 0; pass < passes; pass++) {
+			if (!deepest(probe(out))) return { target: out, contact, depth: 0 };
+			contact = true;
+			w.subVectors(best.probe, best.blocker);
+			dir.copy(w);
+			if (keep) {
+				side.subVectors(keep, best.blocker);
+				// a normal pointing away from the side the hand came from is the
+				// far side of the body: escape toward lastGood instead
+				if (side.lengthSq() > EPS && (dir.lengthSq() <= EPS || dir.dot(side) < 0)) dir.copy(side);
+			}
+			if (dir.lengthSq() <= EPS) dir.set(0, 1, 0);
+			dir.normalize();
+			out.addScaledVector(dir, exitDistance(w, dir, best.reach + margin));
+		}
+		const left = deepest(probe(out)) ? best.depth : 0;
+		// the passes did not get the probed (displayed) limb out: fall back to
+		// the last clean substep of the sweep, on the near side
+		if (left > 0 && hit) return { target: hit.clean.clone(), contact: true, depth: 0 };
+		return { target: out, contact, depth: left };
+	}
+
+	return { 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 },
+};