cozyclay 1.9.0 → 2.0.0

package/src/ardy/ik-drag.js

@@ -0,0 +1,101 @@
+import { createIkState, ikBakeKeyframe, ikTouch } from "./ik.js";
+
+/**
+ * Per-drag bookkeeping for manual IK drags over a loaded motion.
+ *
+ * A drag keys ONLY the parts it wrote, as DELTA keys over the raw clip pose at
+ * the drag frame. Keying every part ever tracked (the old behaviour) planted an
+ * absolute key for untouched parts too, which spiked them off the clip on the
+ * drag frame (bind-translation reset + absolute slerp on the ramp).
+ */
+
+/** The record for the drag in progress. IkHandles has no drag-start callback,
+ * so a record opens on the first solve and closes on drag end; a record left
+ * on another frame (a click-sized drag that never ended) is stale and resets. */
+export function ikDragRecord(current, frame) {
+	return current && current.frame === frame ? current : { frame, ids: new Set() };
+}
+
+/** Mark `id` as written by this drag and touch it into the live layer. */
+export function ikDragTouch(ikState, record, id) {
+	ikTouch(ikState, id);
+	record?.ids.add(id);
+}
+
+/** Run `write` and return the chain ids whose bone locals it changed — for
+ * solvers like applyBodyContact that only report "something moved". */
+export function chainsChangedBy(chains, write) {
+	const before = new Map();
+	for (const [id, chain] of chains) {
+		before.set(id, chain.bones.map((bone) => [bone.quaternion.clone(), bone.position.clone()]));
+	}
+	write();
+	const changed = [];
+	for (const [id, chain] of chains) {
+		const saved = before.get(id);
+		if (chain.bones.some((bone, index) => !bone.quaternion.equals(saved[index][0]) || !bone.position.equals(saved[index][1]))) changed.push(id);
+	}
+	return changed;
+}
+
+/**
+ * Read the RAW clip locals of `ids` at the current frame without disturbing the
+ * live pose: snapshot every node under `rig`, let `applyRaw(rig)` pose the clip
+ * alone (no correction layer), read chain b0..b2 quaternions and FK joint
+ * quaternion + position, then put every node back.
+ */
+export function captureRawBase(rig, chains, fkJoints, ids, applyRaw) {
+	const saved = [];
+	rig.traverse((node) => saved.push([node, node.position.clone(), node.quaternion.clone(), node.scale.clone()]));
+	const baseQuats = new Map();
+	const basePositions = new Map();
+	try {
+		applyRaw(rig);
+		for (const id of ids) {
+			const chain = chains?.get(id);
+			const joint = fkJoints?.get(id);
+			if (chain) baseQuats.set(id, chain.bones.map((bone) => bone.quaternion.clone()));
+			else if (joint) {
+				baseQuats.set(id, [joint.bone.quaternion.clone()]);
+				basePositions.set(id, joint.bone.position.clone());
+			}
+		}
+	} finally {
+		for (const [node, position, quaternion, scale] of saved) {
+			node.position.copy(position);
+			node.quaternion.copy(quaternion);
+			node.scale.copy(scale);
+		}
+		rig.updateMatrixWorld(true);
+	}
+	return { baseQuats, basePositions };
+}
+
+/**
+ * Bake the key entry (Map trackId → key) a drag leaves at `frame`, for exactly
+ * `ids`. With `applyRaw` (a motion is loaded) every entry is a delta key over
+ * the raw clip: chains carry baseQ; FK joints carry baseQ + basePos, and a
+ * joint whose rotation matches the clip is stored translation-only, the same
+ * shape ikBakeKeyframe gives based hips keys. Without `applyRaw` the entry is
+ * the plain absolute key. Returns null when nothing was keyed.
+ */
+export function bakeIkDragKey(chains, fkJoints, frame, ids, applyRaw = null) {
+	const list = [...ids];
+	if (!list.length) return null;
+	const rig = chains?.values().next().value?.rig;
+	const base = applyRaw && rig ? captureRawBase(rig, chains, fkJoints, list, applyRaw) : null;
+	const scratch = createIkState();
+	ikBakeKeyframe(chains, scratch, frame, fkJoints, list, null, base?.baseQuats ?? null);
+	const entry = scratch.keys.get(frame);
+	if (!entry || !base) return entry ?? null;
+	for (const [id, key] of entry) {
+		if (chains.has(id) || !fkJoints?.has(id)) continue;
+		const baseQ = base.baseQuats.get(id)?.[0];
+		const basePos = base.basePositions.get(id);
+		if (!baseQ || !basePos || !key.p) continue;
+		key.basePos = basePos;
+		if (key.q?.[0] && key.q[0].angleTo(baseQ) > 1e-7) key.baseQ = [baseQ];
+		else key.q = null;
+	}
+	return entry;
+}

package/src/ardy/ik-key-json.js

@@ -0,0 +1,43 @@
+import * as THREE from "three";
+
+/**
+ * One IK track key in the JSON form character.setIkKey takes
+ * (src/studio-actions.js ikTrackKey) and back: quaternions as {x,y,z,w},
+ * positions as {x,y,z}. Optional fields are written only when the key has
+ * them, so a key without a stored `blend` stays one without it.
+ */
+export function ikTrackKeyJson(key) {
+	const quaternion = (q) => ({ x: q.x, y: q.y, z: q.z, w: q.w });
+	const vector = (p) => ({ x: p.x, y: p.y, z: p.z });
+	return {
+		...(key.q ? { q: key.q.map(quaternion) } : {}),
+		...(key.p ? { p: vector(key.p) } : {}),
+		...(key.baseQ ? { baseQ: key.baseQ.map(quaternion) } : {}),
+		...(key.basePos ? { basePos: vector(key.basePos) } : {}),
+		...(key.chainP ? { chainP: key.chainP.map(vector) } : {}),
+		...(key.keepTranslations ? { keepTranslations: true } : {}),
+		...(key.blend != null ? { blend: key.blend } : {}),
+		...(key.pin != null ? { pin: key.pin } : {}),
+	};
+}
+
+/** A baked key entry (Map trackId → key) as character.setIkKey's `tracks`. */
+export function ikKeyJson(entry) {
+	return Object.fromEntries([...entry].map(([track, key]) => [track, ikTrackKeyJson(key)]));
+}
+
+/** The IK state's key for one track of character.setIkKey's `tracks`. */
+export function ikTrackKeyFromJson(key) {
+	const quaternion = (q) => new THREE.Quaternion(q.x, q.y, q.z, q.w).normalize();
+	const vector = (p) => new THREE.Vector3(p.x, p.y, p.z);
+	return {
+		q: key.q?.map(quaternion) ?? null,
+		p: key.p ? vector(key.p) : null,
+		...(key.baseQ ? { baseQ: key.baseQ.map(quaternion) } : {}),
+		...(key.basePos ? { basePos: vector(key.basePos) } : {}),
+		...(key.chainP ? { chainP: key.chainP.map(vector) } : {}),
+		...(key.keepTranslations ? { keepTranslations: true } : {}),
+		...(key.blend != null ? { blend: key.blend } : {}),
+		...(key.pin != null ? { pin: key.pin } : {}),
+	};
+}

package/src/ardy/ik.js

@@ -32,6 +32,29 @@ const CONTACT_RADIUS_FALLBACK = 0.01;
 const CONTACT_HEIGHT_MAX = 0.25;
 const contactRadiusCache = new WeakMap();
 const contactHeightCache = new WeakMap();
+// Normalised once: the per-vertex loops below used to re-run the
+// normalizeBoneName regex 16 times per vertex, which was most of the cost of
+// measuring a rig (#413).
+const CONTACT_TARGETS = CONTACT_JOINTS.map((name) => [name, normalizeBoneName(`mixamorig${name}`)]);
+const contactJointFor = (normalized) => {
+	if (!normalized) return undefined;
+	for (const [name, target] of CONTACT_TARGETS) {
+		if (normalized === target || normalized.endsWith(target) || target.endsWith(normalized)) return name;
+	}
+	return undefined;
+};
+
+/** Copy one rig's measured contact radii/heights onto another rig that shares
+ * its bind pose (a skeleton clone). The measurement reads bind-pose geometry
+ * only, so the numbers are identical and re-scanning every skinned vertex per
+ * clone is pure waste: studioBounds clones the rig per query (#413). */
+export function shareContactMeasurements(from, to) {
+	if (!from || !to || from === to) return;
+	const radii = contactRadiusCache.get(from);
+	const heights = contactHeightCache.get(from);
+	if (radii && !contactRadiusCache.has(to)) contactRadiusCache.set(to, radii);
+	if (heights && !contactHeightCache.has(to)) contactHeightCache.set(to, heights);
+}
 
 function pointSegmentDistance(point, start, end) {
 	const segment = end.clone().sub(start);
@@ -259,11 +282,7 @@ export function measureContactRadii(rig) {
 				}
 			}
 			if (dominantWeight <= 0.4) continue;
-			const normalized = names[dominant];
-			const name = CONTACT_JOINTS.find((candidate) => {
-				const target = normalizeBoneName(`mixamorig${candidate}`);
-				return normalized === target || normalized.endsWith(target) || target.endsWith(normalized);
-			});
+			const name = contactJointFor(names[dominant]);
 			const segment = segments.get(name);
 			if (!segment) continue;
 			if (bindPose) bindVertexPosition(mesh, index, vertex);
@@ -327,10 +346,7 @@ export function measureContactHeights(rig) {
 				if (weight > dominantWeight) { dominantWeight = weight; dominant = indices.getComponent(index, slot); }
 			}
 			if (dominantWeight <= 0.4 || !names[dominant]) continue;
-			const name = CONTACT_JOINTS.find((candidate) => {
-				const target = normalizeBoneName(`mixamorig${candidate}`);
-				return names[dominant] === target || names[dominant].endsWith(target) || target.endsWith(names[dominant]);
-			});
+			const name = contactJointFor(names[dominant]);
 			const point = points.get(name);
 			if (!point) continue;
 			if (bindPose) bindVertexPosition(mesh, index, vertex);
@@ -513,16 +529,21 @@ export function resolveIkRig(rig) {
  * root→effector reach with a soft clamp: past the cap the effector approaches
  * it asymptotically and never exceeds it, so a locked foot cannot straighten
  * the leg past the extension the source pose actually had.
+ *
+ * `exactHinge` makes the one-step claim hold for a BENT chain too: without it
+ * the continuity hinge keeps an along-line component and a solve from a bent
+ * pose lands short of a reachable target, converging only over repeated calls.
  */
-export function solveIk(chain, targetWorld, { maxExtension = null, softening = 0.01 } = {}) {
-	restoreChainPositions(chain);
-	const { bones, lengths, poleLocal, rig } = chain;
+export function solveIk(chain, targetWorld, { maxExtension = null, softening = 0.01, exactHinge = false } = {}) {
+	// Playback owns translations. Measure this frame's lengths rather than
+	// resetting to bind, which turns a small target move into length compensation.
+	const { bones, poleLocal, rig } = chain;
 	const [b0, b1, b2] = bones;
 	const p0 = b0.getWorldPosition(new THREE.Vector3());
 	const p1cur = b1.getWorldPosition(new THREE.Vector3());
 	const t = targetWorld.clone();
-	const l0 = lengths[0];
-	const l1 = lengths[1];
+	const l0 = p0.distanceTo(p1cur);
+	const l1 = p1cur.distanceTo(b2.getWorldPosition(new THREE.Vector3()));
 	let d = p0.distanceTo(t);
 
 	const dir = t.clone().sub(p0);
@@ -577,8 +598,18 @@ export function solveIk(chain, targetWorld, { maxExtension = null, softening = 0
 	const isBent = seg0.dot(seg1) < 0.999;
 	let bend;
 	if (isBent) {
-		// Continuity: reuse the elbow's current offset from the line.
+		// Legacy continuity: reuse the elbow's current offset from the NEW line.
+		// fix-collisions and its fixtures are tuned on this result, but when the
+		// line rotates past a near-straight elbow the offset changes sign and
+		// the joint reverse-bends.
 		bend = p1cur.clone().sub(linePoint);
+		// exactHinge keeps the chain's CURRENT hinge axis a = norm(seg0 x seg1)
+		// and bends in the plane it spans with dir: bend = dir x a, which is
+		// perpendicular to dir, so p1 stays on the l0 sphere. The solved
+		// thigh' x shin' = off*d*(a - dir(a.dir)), whose dot with a is
+		// off*d*(1 - (a.dir)^2) >= 0, so the bend side cannot flip. When the
+		// target lies along a, bend degenerates and the pole fallback runs.
+		if (exactHinge) bend = dir.clone().cross(seg0.clone().cross(seg1).normalize());
 	}
 	if (!bend || bend.lengthSq() < 1e-8) {
 		// Straight chain — no side to continue; use the pole hint.
@@ -684,8 +715,7 @@ export function solveHipsTranslateToFloor(joint, worldDelta, startLocalPos, floo
 }
 
 export function solveMidJoint(chain, midTargetWorld) {
-	restoreChainPositions(chain);
-	const { bones, lengths } = chain;
+	const { bones } = chain;
 	const [b0, b1, b2] = bones;
 	const p0 = b0.getWorldPosition(new THREE.Vector3());
 	const p1cur = b1.getWorldPosition(new THREE.Vector3());
@@ -694,12 +724,12 @@ export function solveMidJoint(chain, midTargetWorld) {
 	const dir = midTargetWorld.clone().sub(p0);
 	if (dir.lengthSq() < 1e-12) dir.copy(p1cur).sub(p0);
 	dir.normalize();
-	const p1 = p0.clone().addScaledVector(dir, lengths[0]);
+	const p1 = p0.clone().addScaledVector(dir, p0.distanceTo(p1cur));
 	// Forearm keeps its current world direction; the wrist/ankle follows.
 	const foreDir = p2cur.clone().sub(p1cur);
 	if (foreDir.lengthSq() < 1e-12) foreDir.copy(dir);
 	foreDir.normalize();
-	const p2 = p1.clone().addScaledVector(foreDir, lengths[1]);
+	const p2 = p1.clone().addScaledVector(foreDir, p1cur.distanceTo(p2cur));
 	aimChain(bones, [p0, p1, p2]);
 	return p1; // the clamped position the caller should snap the handle to
 }
@@ -839,7 +869,9 @@ export function ikRestore(rig, snapshot, fkJoints) {
  * (b0, b1, b2) for chains, the single bone for FK joints — and the hips' LOCAL
  * POSITION when the body root was moved. Entries are uniform
  * { q: [...quats], p: localPos | null, basePos? }. Local values are
- * character-position independent, so keys need no re-anchoring ever.
+ * character-position independent, so keys need no re-anchoring ever. New chain
+ * keys keep clip translations. Absolute keys also capture chainP; delta keys
+ * need it only when an earlier layer changed translations at this frame.
  *
  * `onlyIds` (Set or array) bakes EXACTLY those ids instead of the whole tracked
  * set, and touches them into `tracked` on the way. Without it a fix to a leg at
@@ -906,6 +938,16 @@ export function ikBakeKeyframe(rig, ikState, frame, fkJoints, onlyIds = null, ba
 		if (!q && !p) continue;
 		if (!entry) ikState.keys.set(frame, (entry = new Map()));
 		const key = { q, p };
+		if (chain) {
+			const clip = chainClipPositions.get(chain);
+			// A rotation-only correction must not freeze the keyed frame's bone
+			// lengths onto its neighbours. Preserve explicit translations only
+			// for absolute authoring or an edit over a translation-changing key.
+			if (!baseQ || (clip?.frame === frame && chain.bones.some((bone, i) => !bone.position.equals(clip.positions[i])))) {
+				key.chainP = chain.bones.map((bone) => bone.position.clone());
+			}
+			key.keepTranslations = true;
+		}
 		if (basePos) key.basePos = basePos;
 		if (baseQ && q) key.baseQ = baseQ;
 		entry.set(id, key);
@@ -1020,25 +1062,32 @@ export function ikKeyframes(ikState) {
  * `blendWindow` > 0 turns the layer into a LOCAL correction (used when a
  * generated motion plays underneath): the correction holds full strength
  * across each ISLAND of keys and eases to zero over that many frames outside
- * it (see correctionWeight), blending against whatever pose is already on the
+ * it, or over an edge key's own `blend` when it stores one (see
+ * correctionWeight), blending against whatever pose is already on the
  * bone (the motion). With the default 0 the keys hold forever (constant
  * extrapolation), the no-motion authoring behaviour.
  */
 const deltaPos = new THREE.Vector3();
 const identityQuat = new THREE.Quaternion();
 const easedDelta = new THREE.Quaternion();
+// Raw locals under the layer, used when a drag re-keys a legacy bind-space
+// correction. Solvers no longer translate, but that existing layer might.
+const chainClipPositions = new WeakMap();
 
 export function ikEvaluate(rig, ikState, frame, fkJoints, blendWindow = 0) {
 	if (!rig) return;
+	for (const chain of rig.values()) {
+		chainClipPositions.set(chain, { frame, positions: chain.bones.map((bone) => bone.position.clone()) });
+	}
 	for (const id of ikState.tracked) {
-		const sampled = sampleChain(ikState.keys, id, frame);
-		if (!sampled) continue;
 		const chain = rig.get(id);
+		const sampled = sampleChain(ikState.keys, id, frame, chain);
+		if (!sampled) continue;
 		const joint = fkJoints?.get(id);
 		const w = blendWindow > 0 ? correctionWeight(ikState.keys, id, frame, blendWindow) : 1;
 		if (w <= 0) continue;
 		if (chain) {
-			if (sampled.chainP) chain.bones.forEach((bone, i) => { if (sampled.chainP[i]) bone.position.lerp(sampled.chainP[i], w); });
+			if (sampled.chainP) chain.bones.forEach((bone, i) => { if (sampled.chainP[i]) bone.position.lerp(sampled.chainP[i], w * (sampled.chainPWeight ?? 1)); });
 			// DELTA blend for chain rotations, the mirror of basePos for the hips
 			// and for exactly the same reason. Easing a bone toward the key's
 			// ABSOLUTE rotation makes the smear proportional to how different the
@@ -1052,10 +1101,9 @@ export function ikEvaluate(rig, ikState, frame, fkJoints, blendWindow = 0) {
 			// which is the only thing the key ever claimed.
 			const deltas = blendWindow > 0 ? sampled.deltaQ : null;
 			if (deltas) {
-				// Translations stay on the CLIP until the correction has full
-				// authority. See restoreChainPositions for why this is a step and
-				// not a ramp.
-				if (w >= 1 && !sampled.keepTranslations) restoreChainPositions(chain, 1);
+				// Ease the translations with the rotations: switching to bind only
+				// at w = 1 tears the otherwise continuous correction at island edges.
+				if (!sampled.keepTranslations) restoreChainPositions(chain, w);
 				for (let index = 0; index < chain.bones.length && index < deltas.length; index += 1) {
 					if (!deltas[index]) continue;
 					easedDelta.copy(deltas[index]);
@@ -1112,30 +1160,15 @@ export function ikEvaluate(rig, ikState, frame, fkJoints, blendWindow = 0) {
 }
 
 /**
- * ARDY playback positions mapped joints independently. Once IK authors a
- * chain's rotations, those generated translations no longer describe the
- * same FK pose and can visually separate the limb. Return the edited chain
- * to its Mixamo bind translations before applying IK rotations so parent
- * rotation and fixed segment lengths own all descendants.
- *
- * WHY THE DELTA PATH CALLS THIS ONLY AT FULL WEIGHT. The bind restore is not a
- * small adjustment — on a generated clip the per-bone translations sit ~19 mm
- * off bind — and, unlike a rotation, it cannot be expressed as a delta: the
- * authored pose is defined AT bind translations (solveIk resets them before it
- * aims, and the chain's segment lengths were measured there), so any partial
- * value is a pose nobody authored. Ramping it by `weight` therefore injects up
- * to 16 mm of segment-length change into frames whose only claim on the layer is
- * a fractional rotation delta — several times the correction itself, and enough
- * on its own to blow a 1 cm budget.
- *
- * So: a frame the correction fully owns (a key, or an unkeyed frame inside a key
- * island) gets bind translations, because it must reproduce the authored pose. A
- * frame on the ease ramp keeps the CLIP's translations untouched and receives
- * only the eased rotation delta. The cost is a step of up to that ~19 mm at each
- * island edge instead of a ramp spread over the whole window; the benefit is
- * that every frame outside an island deviates from the clip by the correction
- * and nothing else. Removing the step outright means solving in clip-translation
- * space, which is a change to solveIk's contract and to every drag path with it.
+ * Legacy keys were solved at bind translations and must still replay there.
+ * New correction keys keep clip translations; explicit poses carry chainP.
+ * On a legacy key's ease ramp, interpolate the ENTIRE local transform:
+ * p = clipP + (bindP - clipP) * weight,
+ * alongside the eased rotation delta. This keeps both endpoints exact and is
+ * continuous at full weight; withholding the translation until then made a
+ * 1 cm correction jump 50.5 mm on a chain whose locals were 2 cm off bind.
+ * Partial weights deliberately interpolate segment lengths too, just as the
+ * absolute-key path does. They are transition poses, not fresh IK solves.
  */
 function restoreChainPositions(chain, weight = 1) {
 	if (!chain?.bindPositions) return;
@@ -1150,39 +1183,48 @@ function restoreChainPositions(chain, weight = 1) {
 
 /**
  * A track's key ISLANDS: runs of keys close enough together to be one
- * correction, as [firstFrame, lastFrame] pairs in ascending order. Two
- * consecutive keys belong to the same island while the gap between them is no
- * wider than `blendWindow`; a wider gap starts a new island.
+ * correction, as [firstFrame, lastFrame, firstBlend, lastBlend] in ascending
+ * order. Two consecutive keys belong to the same island while the gap between
+ * them is no wider than the larger of their two blend ranges; a wider gap
+ * starts a new island.
  *
- * The window is the right ruler because it is exactly how far a correction is
- * allowed to reach: keys closer together than that overlap anyway, and keys
- * further apart are, by the layer's own definition, separate local fixes with
- * clip in between.
+ * A key's blend range is its own `blend` (frames, stored by a Pose fix drag
+ * made with a wider or narrower correction range) or, for every key without
+ * one, `blendWindow`. The range is the right ruler because it is exactly how
+ * far a correction is allowed to reach: keys closer together than that overlap
+ * anyway, and keys further apart are, by the layer's own definition, separate
+ * local fixes with clip in between. The larger of the pair decides because the
+ * wider key already reaches its neighbour.
  */
 function trackIslands(keys, trackId, blendWindow) {
 	const frames = [];
-	for (const [f, entry] of keys) if (entry.has(trackId)) frames.push(f);
+	for (const [f, entry] of keys) {
+		const key = entry.get(trackId);
+		if (key) frames.push([f, key.blend ?? blendWindow]);
+	}
 	if (!frames.length) return [];
-	frames.sort((a, b) => a - b);
+	frames.sort((a, b) => a[0] - b[0]);
 	const islands = [];
-	let first = frames[0];
-	let prev = frames[0];
+	let [first, firstBlend] = frames[0];
+	let [prev, prevBlend] = frames[0];
 	for (let index = 1; index < frames.length; index += 1) {
-		const f = frames[index];
-		if (f - prev > blendWindow) {
-			islands.push([first, prev]);
+		const [f, blend] = frames[index];
+		if (f - prev > Math.max(prevBlend, blend)) {
+			islands.push([first, prev, firstBlend, prevBlend]);
 			first = f;
+			firstBlend = blend;
 		}
 		prev = f;
+		prevBlend = blend;
 	}
-	islands.push([first, prev]);
+	islands.push([first, prev, firstBlend, prevBlend]);
 	return islands;
 }
 
 /**
  * Correction strength at `frame` for one track: 1 on a key and anywhere inside
- * a key ISLAND, easing 1 → 0 across `blendWindow` frames outward from the
- * nearest island edge, 0 beyond every island.
+ * a key ISLAND, easing 1 → 0 outward from each island edge across that edge
+ * key's blend range (its `blend`, else `blendWindow`), 0 beyond every island.
  *
  * This used to be "1 everywhere between the track's first and last key", which
  * quietly made every sparse correction a whole-clip rewrite: two collision
@@ -1197,13 +1239,12 @@ function trackIslands(keys, trackId, blendWindow) {
  * boundary pins, a fully baked pose — is one island, so full-strength playback
  * of authored ranges is unchanged too.
  */
-function correctionWeight(keys, trackId, frame, blendWindow) {
+export function correctionWeight(keys, trackId, frame, blendWindow) {
 	const islands = trackIslands(keys, trackId, blendWindow);
 	let best = 0;
-	for (const [first, last] of islands) {
+	for (const [first, last, firstBlend, lastBlend] of islands) {
 		if (frame >= first && frame <= last) return 1;
-		const distance = frame < first ? first - frame : frame - last;
-		const weight = 1 - distance / blendWindow;
+		const weight = frame < first ? 1 - (first - frame) / firstBlend : 1 - (frame - last) / lastBlend;
 		if (weight > best) best = weight;
 	}
 	return Math.max(0, best);
@@ -1231,7 +1272,7 @@ function withDeltas(entry) {
 	return entry?.baseQ ? { ...entry, deltaQ: keyDeltas(entry) } : entry;
 }
 
-function sampleChain(keys, trackId, frame) {
+function sampleChain(keys, trackId, frame, chain) {
 	let prevFrame = null;
 	let nextFrame = null;
 	for (const f of keys.keys()) {
@@ -1247,9 +1288,14 @@ function sampleChain(keys, trackId, frame) {
 	const t = (frame - prevFrame) / (nextFrame - prevFrame);
 	const deltasA = keyDeltas(a);
 	const deltasB = keyDeltas(b);
+	// Missing chainP means raw clip for a new key, bind for a legacy key.
+	// A mixed pair must ease between those policies, not switch at an endpoint.
+	const positionsA = a.chainP ?? (a.keepTranslations ? null : chain?.bindPositions);
+	const positionsB = b.chainP ?? (b.keepTranslations ? null : chain?.bindPositions);
 	return {
-		keepTranslations: a.keepTranslations === true && b.keepTranslations === true,
-		chainP: a.chainP && b.chainP ? a.chainP.map((p, i) => p.clone().lerp(b.chainP[i], t)) : null,
+		keepTranslations: Boolean(chain) || (a.keepTranslations === true && b.keepTranslations === true),
+		chainP: positionsA && positionsB ? positionsA.map((p, i) => p.clone().lerp(positionsB[i], t)) : (positionsA ?? positionsB),
+		chainPWeight: positionsA && positionsB ? 1 : (positionsA ? 1 - t : t),
 		// Between two based keys the DELTAS interpolate, not the absolute
 		// rotations and their bases separately: each key's delta is a statement
 		// about its own frame's clip pose, and interpolating those statements is

package/src/ardy/physics-panel.css

@@ -1,3 +1,4 @@
+@layer legacy {
 .physics-review { border-top: 1px solid var(--border, #40444c); margin-top: 12px; padding-top: 12px; }
 .physics-review h4 { margin: 0 0 8px; font-size: 13px; }
 .physics-review h4 small { font-weight: 400; opacity: .7; }
@@ -17,3 +18,4 @@
 .physics-review th:first-child, .physics-review td:first-child { text-align: left; }
 .physics-list { max-height: 170px; overflow: auto; }
 .physics-warning { padding: 8px; border: 1px solid #cc924e; border-radius: 5px; font-size: 11px; margin-top: 8px; }
+}

package/src/ardy/physics-panel.jsx

@@ -1,5 +1,6 @@
-import React, { useState, useSyncExternalStore } from "react";
+import React, { useEffect, useState, useSyncExternalStore } from "react";
 import { SUPPORT_SITES } from "./physics-review.js";
+import { useMotionCommands } from '../domains/motion.js';
 import "./physics-panel.css";
 
 // Only the progress panel subscribes. Publishing a percentage must not
@@ -12,6 +13,7 @@ export function createPhysicsProgress() {
 }
 
 export function PhysicsPanel({ ko, disabled, running, progress: progressStore, preview, show, options, frame, frames, onOptions, onRun, onShow, onApply, onCancel, onFrame }) {
+	const { run } = useMotionCommands();
 	const progress = useSyncExternalStore(progressStore.subscribe, progressStore.getSnapshot);
 	const [site, setSite] = useState("leftFoot");
 	const [start, setStart] = useState(0), [end, setEnd] = useState(0), [mode, setMode] = useState("plant");
@@ -24,8 +26,18 @@ export function PhysicsPanel({ ko, disabled, running, progress: progressStore, p
 	};
 	const cm = (x) => `${(x * 100).toFixed(2)} cm`;
 	const warning = (r) => ({ unsupported: ko("Unexplained body support", "몸을 지탱하는 접촉 미확인"), floor: ko("Floor penetration", "바닥 관통"), float: ko("Contact floats", "접지점 뜸"), slide: ko("Contact drift", "접지점 밀림"), "knee-pop": ko("Knee speed jump", "무릎 튐"), "knee-acceleration": ko("Knee acceleration increased", "무릎 가속도 증가"), "root-acceleration": ko("Root acceleration increased", "골반 가속도 증가"), replay: ko("Playback mismatch", "재생 불일치") }[r] ?? r);
-	return <section className="physics-review" data-testid="physics-panel" aria-label="AutoPhysics">
-		<h4>AutoPhysics <small>{ko("review before applying", "확인 후 적용")}</small></h4>
+	useEffect(() => {
+		if (!preview) return undefined;
+		const onKeyDown = (event) => {
+			if (event.metaKey || event.ctrlKey || event.altKey) return;
+			if (event.key === "Escape") { event.preventDefault(); onCancel?.(); }
+			if (event.key === "Enter") { event.preventDefault(); onApply?.(); }
+		};
+		window.addEventListener("keydown", onKeyDown);
+		return () => window.removeEventListener("keydown", onKeyDown);
+	}, [preview, onApply, onCancel]);
+	return <section className="physics-review" data-testid="physics-panel" aria-label={ko("Physics cleanup", "물리 정리")}>
+		<h4>{ko("Physics cleanup", "물리 정리")} <small>{ko("review before applying", "확인 후 적용")}</small></h4>
 		<p className="inspector-hint">{ko("Floor-support hypotheses → force + moment check → pelvis + limbs. Flight is preserved; uncertain support stays flagged. Original stays unchanged until Apply.", "바닥 지지 후보 → 힘·회전 검사 → 골반·팔다리를 보정합니다. 비행은 보존하고, 불명확한 지지는 표시해요. 적용 전까지 원본은 바뀌지 않아요.")}</p>
 		<fieldset disabled={disabled || running}>
 			<label>{ko("Correction strength", "보정 강도")} <output>{Math.round(options.strength * 100)}%</output>
@@ -44,7 +56,7 @@ export function PhysicsPanel({ ko, disabled, running, progress: progressStore, p
 				<button data-testid="physics-protect" className="btn full" onClick={() => set({ protectedFrames: [...new Set([...options.protectedFrames, frame])].sort((a, b) => a - b) })}>{ko(`Protect pose at frame ${frame}`, `${frame}프레임 포즈 보호`)}</button>
 				{options.protectedFrames.map((f) => <div key={f} className="physics-row"><button className="btn" onClick={() => onFrame(f)}>{ko("Protected", "보호")} F{f}</button><button className="btn" aria-label={ko("Unprotect pose", "포즈 보호 해제")} onClick={() => set({ protectedFrames: options.protectedFrames.filter((p) => p !== f) })}>×</button></div>)}
 			</details>
-			<button data-testid="physics-analyse" className="btn full primary" onClick={onRun}>{running ? ko(`Analysing ${progress}%`, `분석 중 ${progress}%`) : ko("Analyse & preview", "분석 · 미리보기")}</button>
+			<button data-testid="physics-analyse" className="btn full primary" onClick={() => run('motion.autoPhysics', { ...options, apply: false })}>{running ? ko(`Analysing ${progress}%`, `분석 중 ${progress}%`) : ko("Analyse & preview", "분석 · 미리보기")}</button>
 		</fieldset>
 		{running && <progress max="100" value={progress} aria-label={ko("Analysis progress", "분석 진행률")} />}
 		{preview && <div data-testid="physics-results">
@@ -70,7 +82,7 @@ export function PhysicsPanel({ ko, disabled, running, progress: progressStore, p
 				{!!preview.skippedAir?.length && <p>{ko(`${preview.skippedAir.length} flight spans skipped`, `공중 ${preview.skippedAir.length}구간 보류`)}</p>}
 				{!!preview.contacts.rejected.length && <button className="btn full" onClick={() => onFrame(preview.contacts.rejected[0].start)}>{ko(`${preview.contacts.rejected.length} moving support intervals rejected`, `움직이는 접지 ${preview.contacts.rejected.length}구간 제외`)}</button>}
 			</div>
-			<div className="physics-actions"><button data-testid="physics-cancel" className="btn" onClick={onCancel}>{ko("Cancel", "취소")}</button><button data-testid="physics-apply" className="btn primary" disabled={!preview.changedFrames.length || preview.strength === 0} onClick={onApply}>{ko("Apply", "적용")}</button></div>
+			<div className="physics-actions"><button data-testid="physics-cancel" className="btn" onClick={onCancel}>{ko("Cancel", "취소")}</button><button data-testid="physics-apply" className="btn primary" disabled={!preview.changedFrames.length || preview.strength === 0} onClick={() => run('motion.applyPhysics')}>{ko("Apply", "적용")}</button></div><small className="pose-keyhint">{ko("Enter applies · Esc cancels", "Enter 적용 · Esc 취소")}</small>
 		</div>}
 	</section>;
 }

package/src/ardy/platform-fit-panel.css

@@ -0,0 +1,64 @@
+@layer legacy {
+/* Inspector scale: 4 px spacing, 13 px section headings, shared flat buttons.
+   Success matches the existing completed-guide marker; warning/error use theme tokens. */
+.platform-fit {
+	--platform-fit-space: 4px;
+	--platform-fit-heading-size: 13px;
+	--platform-fit-rule: 1px;
+	--platform-fit-success: #65c18c;
+	min-width: 0;
+	border-top: var(--platform-fit-rule) solid var(--line2);
+	margin-top: calc(var(--platform-fit-space) * 3);
+	padding-top: calc(var(--platform-fit-space) * 3);
+}
+
+.platform-fit.auto-fix-card {
+	margin-top: 0;
+	padding-top: calc(var(--platform-fit-space) * 3);
+	border-top: var(--platform-fit-rule) solid var(--line2);
+}
+.platform-fit h4 {
+	margin: 0;
+	font-size: var(--platform-fit-heading-size);
+}
+.platform-fit progress { width: 100%; accent-color: var(--accent); }
+.platform-fit-results {
+	display: grid;
+	gap: var(--platform-fit-space);
+	margin: calc(var(--platform-fit-space) * 2) 0 0;
+	padding: 0;
+	list-style: none;
+	max-height: calc(var(--platform-fit-space) * 48);
+	overflow: auto;
+}
+.platform-fit .platform-fit-step {
+	display: grid;
+	grid-template-columns: calc(var(--platform-fit-space) * 2) minmax(0, 1fr);
+	align-items: start;
+	gap: calc(var(--platform-fit-space) * 2);
+	width: 100%;
+	min-width: 0;
+	height: auto;
+	margin: 0;
+	padding: calc(var(--platform-fit-space) * 2);
+	text-align: left;
+	white-space: normal;
+	font-variant-numeric: tabular-nums;
+}
+.platform-fit-step[data-status="ok"] { --platform-fit-status: var(--platform-fit-success); }
+.platform-fit-step[data-status="tooHigh"] { --platform-fit-status: var(--range-pin-warning); }
+.platform-fit-step[data-status="wall"] { --platform-fit-status: var(--danger); }
+.platform-fit-chip {
+	width: calc(var(--platform-fit-space) * 2);
+	height: calc(var(--platform-fit-space) * 2);
+	margin-top: var(--platform-fit-space);
+	border-radius: var(--radius);
+	background: var(--platform-fit-status);
+}
+.platform-fit-step .inspector-hint {
+	display: block;
+	margin: var(--platform-fit-space) 0 0;
+	font-weight: normal;
+}
+
+}