cozyclay 1.10.0 → 2.0.2

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

@@ -529,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);
@@ -593,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.
@@ -700,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());
@@ -710,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
 }
@@ -855,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
@@ -922,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);
@@ -1036,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
@@ -1068,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]);
@@ -1128,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;
@@ -1166,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
@@ -1213,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);
@@ -1247,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()) {
@@ -1263,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;
+}
+
+}

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

@@ -0,0 +1,40 @@
+import React, { useEffect, useSyncExternalStore } from "react";
+import "../panels/pose.css";
+
+const FOOT_NAMES = { leftFoot: ["Left foot", "왼발"], rightFoot: ["Right foot", "오른발"] };
+function stepLabel(step, ko) {
+	if (step.status === "wall") return `${ko("Wall", "벽")} · F${step.start}`;
+	const [en, kr] = FOOT_NAMES[step.foot] ?? [step.foot, step.foot];
+	const amount = step.lift !== 0 ? step.lift : step.rise;
+	return `${ko(en, kr)} F${step.start}–F${step.end} · ${amount >= 0 ? "+" : ""}${Math.round(amount * 100)}cm`;
+}
+
+export function PlatformFitPanel({ ko, disabled, running, progress: progressStore, last, applied, onRun, onApply, onCancel, onRemove, onFrame }) {
+	const progress = useSyncExternalStore(progressStore.subscribe, progressStore.getSnapshot);
+	const preview = Boolean(last && !applied && last.candidate);
+	const steps = last?.steps?.filter((step) => step.lift !== 0 || step.status !== "ok") ?? [];
+	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="platform-fit auto-fix-card pose-section" data-testid="platform-fit-panel" aria-label={ko("Fit to platforms", "발판에 맞추기")}>
+		<div className="auto-fix-card-head"><h4>{ko("Fit to platforms", "발판에 맞추기")}</h4><p className="inspector-hint">{ko("Raise feet and body to platforms in the path.", "경로의 발판에 맞춰 발과 몸을 올립니다.")}</p></div>
+		<button type="button" data-testid="platform-fit-run" className="btn full primary" disabled={disabled || running || preview} onClick={onRun}>{running ? ko(`Fitting ${progress}%`, `맞추는 중 ${progress}%`) : ko("Run", "실행")}</button>
+		{running && <progress max="100" value={progress} aria-label={ko("Platform fit progress", "발판 맞춤 진행률")} />}
+		{preview && <div className="pose-preview" data-testid="platform-fit-preview">
+			<strong className="pose-preview-title">{ko("Preview", "미리보기")}</strong>
+			<span className="pose-preview-summary">{ko(`${last.summary.lifted} steps lifted · ${steps.length} result${steps.length === 1 ? "" : "s"}`, `${last.summary.lifted}개 단계 상승 · 결과 ${steps.length}개`)}</span>
+			<ul className="pose-results">{steps.slice(0, 5).map((step) => <li key={step.id} data-status={step.status}><button type="button" className="btn ghost small" onClick={() => onFrame(step.start)}>{stepLabel(step, ko)}</button></li>)}</ul>
+			<div className="pose-actions"><button data-testid="platform-fit-cancel" type="button" className="btn" onClick={onCancel}>{ko("Cancel", "취소")}</button><button data-testid="platform-fit-apply" type="button" className="btn primary" disabled={!last.changedFrames?.length || steps.some((step) => step.status === "wall" && step.lift === 0)} onClick={onApply}>{ko("Apply", "적용")}</button></div>
+			<span className="pose-keyhint">{ko("Enter applies · Esc cancels", "Enter 적용 · Esc 취소")}</span>
+		</div>}
+		{applied && <button type="button" data-testid="platform-fit-remove" className="btn full" disabled={disabled || running} onClick={onRemove}>{ko("Remove platform fit", "발판 맞춤 제거")}</button>}
+		{last && !preview && <div data-testid="platform-fit-results" className="auto-fix-result"><ul className="platform-fit-results">{steps.slice(0, 5).map((step) => <li key={step.id}><button type="button" className="btn platform-fit-step" data-status={step.status} onClick={() => onFrame(step.start)}>{stepLabel(step, ko)}</button></li>)}</ul>{steps.length === 0 && <p className="inspector-hint">{ko("No platforms in the path.", "경로에 발판이 없어요.")}</p>}</div>}
+	</section>;
+}