cozyclay 1.2.0 → 1.3.0

package/tools/ardy/bvh-cskel27.mjs

@@ -0,0 +1,1209 @@
+/**
+ * bvh-cskel27.mjs — SAM-3D-Body's Mixamo BVH → the exact motion arrays the
+ * npz decoder consumes ({ frames, fps, rotMats, rootPos, posedJoints }).
+ *
+ * Both skeletons rest in the same T-pose convention (Y-up, spine +Y, left
+ * arm +X — verified against CSKEL27_NEUTRAL and the BVH template generator),
+ * so a BVH world rotation IS the cskel27 global rotation for the matching
+ * joint, and each cskel27 local is recovered as parentGlobalᵀ · global.
+ * Joints cskel27 has and the BVH does not (Spine3, the Hand ends) borrow the
+ * nearest BVH ancestor's world rotation, which makes their local rotation
+ * identity — the same "not authored" rule poseToCskel27 applies.
+ *
+ * Joint positions are re-grown with FK over the CANONICAL cskel27 skeleton:
+ * the take must move CozyClay's body, not drag SAM's per-clip bone lengths
+ * into the scene. The root trajectory is scaled by the leg-length ratio and
+ * floor-shifted so the clip's lowest foot sample touches Y=0.
+ */
+
+import { CSKEL27_JOINTS, CSKEL27_PARENTS } from "../../src/ardy/cskel27.js";
+import { deriveBoneOffsets, forwardKinematics, globalRotations, matMul, matToQuat, matTranspose, quatToMat } from "../../src/ardy/convert.js";
+import { canonicalCskel27Reference } from "../../src/ardy/to-cskel27.js";
+import { slerpQuat } from "../../src/ardy/retime.js";
+
+const CM_TO_M = 0.01;
+
+// ---------------------------------------------------------------------------
+// EVERY temporal constant in this file is a DURATION, resolved to frames
+// against the clip's own fps at runtime. It used to be a mix, and the frame
+// counts were a measured bug: SAM extractions arrive at whatever rate the
+// footage ran at — the two fixtures are 30 fps, the user's real capture is
+// 60 — and a constant written as N FRAMES covers half the time at 60 fps, so
+// it filters half as hard exactly where the per-frame input noise is twice as
+// dense (foot wobble measured 3.4 cm on the 60 fps take against 0.6 cm on the
+// 30 fps fixtures). Before the conversion, feeding this module a 60 fps
+// rendering of the SAME motion produced 1.8x the time-normalized ankle jitter
+// and 1.7x the knee jerk of the 30 fps one, and dropped grounding 86.6 → 81.4 %.
+// Every duration below is written as <30 fps frames>/30 so that 30 fps
+// reproduces exactly the numbers each comment was measured at.
+// ---------------------------------------------------------------------------
+
+// Stabilization, ported from the proven Blender retarget script the old
+// ingest pipeline used (sam3d-retarget-shadow.py):
+//  - SPIN: SAM's BVH occasionally winds the root nearly 360° in a few frames
+//    when yaw crosses ±180; detected by root angular SPEED (deg/s — as a
+//    per-frame threshold the same physical spin reads half as fast at 60 fps
+//    and the repair silently stops firing) and bridged with one shortest-path
+//    slerp, corrected on EVERY joint so local articulation survives.
+//  - TORSO: mild zero-lag three-frame slerp on the trunk only; hands and
+//    arms stay untouched so punch timing and impact speed survive.
+//  - LEGS: the same slerp, harder, on both leg chains — see LEG_BLEND.
+const SPIN_DEG_PER_S = 25 * 30; // = 25°/frame at 30 fps
+const TORSO_BLEND = 0.2;
+const TORSO_JOINTS = ["Hips", "Spine", "Spine1", "Spine2", "Neck", "Head"].map((n) => `mixamorig:${n}`);
+// The leg chains get the SAME zero-lag 3-frame slerp, at double strength. This
+// is the single largest measured lever on foot tremble: SAM estimates the legs
+// frame-independently and they are the joints a fixed camera sees worst
+// (self-occlusion behind the torso on every guard-up stance), so their
+// per-frame rotation noise is what the ankle — and then the whole grounding
+// stack downstream — has to fight. On its own it takes ankle accel RMS
+// 2.32 → 1.71 cm and toe 2.53 → 1.83 on boxing-offline (2.29 → 1.65 / 2.50 →
+// 1.78 on shadow17); take it back out of the finished stack and the ankle
+// returns to 2.35. It costs almost nothing in motion: the 95th percentile
+// ankle speed falls 318 → 303 cm/s, so the footwork is smoothed, not killed.
+// Arms are still deliberately NOT smoothed: a punch is a two-frame
+// acceleration into an impact, and blending it with its neighbours is exactly
+// what softens the landing the animation exists to show. A foot has no such
+// event — it plants and it swings — so the same filter costs it nothing.
+const LEG_BLEND = 0.4;
+const LEG_JOINTS = ["LeftUpLeg", "LeftLeg", "LeftFoot", "LeftToeBase", "RightUpLeg", "RightLeg", "RightFoot", "RightToeBase"]
+	.map((n) => `mixamorig:${n}`);
+// Neighbour span of that slerp: ±1 frame at 30 fps. Widening the span instead
+// of repeating the pass would be wrong — a stride-2 three-tap filter has unity
+// gain at Nyquist, so at 60 fps it would leave the every-other-frame noise
+// (the dominant term) completely untouched. Repeating a ±1-frame pass keeps
+// the stopband and matches the 30 fps kernel in TIME (see smoothingPasses).
+const TORSO_SMOOTH_HALF_S = 1 / 30;
+const ROOT_XZ_SMOOTH_HALF_S = 2 / 30; // root translation jitter is camera noise, not gait (5-frame window at 30 fps)
+// Grounding: the ground line PINS the SUPPORT sole to zero (the fixed-camera
+// scope makes "wherever the planted sole lands" the floor by definition),
+// with a jump permit so fast+tall+brief excursions of BOTH feet keep their
+// measured air (see 4c). The version this replaces read the floor off the
+// merely LOWEST foot, which is the SWING leg most of the time — measured on
+// both fixtures that foot is horizontally still on 6–13 % of frames and runs
+// 0.7 m/s median — so its per-frame estimation error went straight into body
+// height and the hip popped at each of the ~3 support changes per second.
+// On top of the line: per-foot contact RUNS with hysteresis, then a 2-bone
+// leg IK that pins each planted ankle in XZ. Occlusion errors (a forward bend
+// hides the legs and SAM floats or sinks them by ±25 cm) are bridged by XZ
+// consistency: a foot that leaves "contact" but reappears at the same spot
+// never actually moved, so the gap is pinned too — while a real jump either
+// travels or lifts past the bridge ceiling and keeps its air. Whatever still
+// ends up under the floor is corrected in the LEG rather than in the body
+// (4f), because that is where the error is.
+// SUPPORT — is this foot on the floor at all? Deliberately generous: a foot
+// that pivots, drags or rocks while it carries weight is still the floor
+// witness, and the boxer's slower ankle never drops below 0.43 m/s anyway.
+// The three together put at least one foot in support on 82 % of frames; a
+// strict reading leaves the ground line nothing to stand on for half the clip.
+const SUPPORT_BAND_M = 0.16; // ankle within this of its own rolling low...
+const SUPPORT_RISE_MPS = 1.0; // ...not climbing or dropping like a swing leg...
+const SUPPORT_MIN_RUN_S = 4 / 30; // ...and holding for at least this long (0.13 s)
+// Baseline of the vertical-speed central difference the two gates above read.
+// A ±2-FRAME difference measures 0.13 s at 30 fps but 0.07 s at 60, where
+// SAM's per-frame estimation noise (ankle accel RMS ~2.4 cm) has not yet
+// averaged out — the gate would then be reading noise rather than movement and
+// reject planted feet. Per-frame deltas are mostly that noise; this baseline is
+// long enough to read the actual movement underneath it.
+const SPEED_DIFF_HALF_S = 2 / 30;
+// The hand-over. REF_MARGIN_M is what makes the reference sticky: it takes a
+// real weight shift to move the floor onto the other foot, not the 3.6 cm
+// median disagreement between the two feet's soles. Reference changes fall
+// from 3.0/s (reading whichever foot is lowest) to 1.2/s.
+const REF_MARGIN_M = 0.05; // the other foot must be in support AND this much lower to take over
+const TRANSFER_BLEND_HALF_S = 3 / 30; // hand-over cross-fade (7-frame window at 30 fps), box-smoothed twice → an S-ramp with no corner
+const FLOOR_SAG_M = 0.02; // how far the stance line may sit above the lowest sole
+// CONTACT — is this foot ALSO nailed to one spot? This gate feeds the XZ foot
+// LOCK, which teleports the ankle onto a single point, so it must stay strict:
+// widening it to cover footwork (a 14 cm band / 12 cm wander patch) made the
+// lock fire on 41 % of frames and drag ankles up to 18 cm — legs visibly
+// flying. The ground line does NOT depend on this track (it reads `support`
+// above), so strictness here costs nothing but a little residual foot slide.
+// Stillness is still judged over the RUN rather than per frame: 1 cm of SAM's
+// per-frame XZ noise already reads as 0.3 m/s.
+const CONTACT_BAND_M = 0.06; // ankle within this of its own rolling low (two-sided: a below-floor dip is an ERROR, not a contact)
+const CONTACT_SETTLE_MPS = 0.6; // ...not dropping or rising like a swing leg...
+const CONTACT_WANDER_M = 0.03; // ...and never leaving one patch of floor for the whole run
+const CONTACT_MIN_RUN_S = 3 / 30; // shortest accepted contact / bridged flicker gap (0.1 s)
+const BRIDGE_MAX_GAP_S = 0.8; // occlusion gaps longer than this are believed instead
+const BRIDGE_MAX_XZ_M = 0.12; // the foot must reappear this close to where it left
+const BRIDGE_MAX_LIFT_M = 0.25; // ankle lift above this reads as a real jump, never bridged
+const LOCK_BLEND_S = 4 / 30; // IK ramp at each contact-run edge (0.13 s)
+// A plant that would have to be dragged further than this was never a plant —
+// the run passed the wander gate but the lock point still lands far from where
+// this frame's ankle actually is (occlusion bridging can extend a run across
+// exactly such a stretch). Snapping the leg there is worse than the slide the
+// lock exists to remove, so the correction is skipped instead of ramped.
+const LOCK_MAX_PULL_M = 0.04;
+// Jump permit — the only measured air the foot-pinned ground line believes.
+// SAM's depth-drift floats are SLOW (the worst on the boxing clip climb
+// ~20 cm over a second-plus); a real hop is FAST and BRIEF. An excursion of
+// the lowest sole must clear all three gates to keep its air.
+const AIR_EPS_M = 0.05; // candidate air: lowest sole this far above its local floor
+const JUMP_MIN_PEAK_M = 0.15; // must peak at least this high...
+const JUMP_MIN_RISE_MPS = 0.7; // ...climbing at least this fast...
+const JUMP_MAX_AIR_S = 0.9; // ...and land within ballistic time, or it is drift
+// Ground-line smoothing: sole jitter must not shake the root. Short on
+// purpose — every centimetre the smoothed line drifts off the measured sole is
+// a centimetre 4f has to take back out of a leg, and past a few frames that
+// correction costs more than the smoothing saves (hip jerk RMS 0.58 cm at a
+// 5-frame window, 0.90 at 13). Re-swept: 5 frames was still too long. Roughly
+// HALF the floor penetration the 4f guard has to repair was manufactured here
+// — on exactly the frames the guard fires, the smoothed line sat +0.61 cm
+// above the measured sole — and a 3-frame window beats a 5-frame one on knee
+// jerk (3.44 vs 3.68°), grounding (87.2 vs 86.6 %) and hover (1.64 vs 1.86 cm)
+// while the hip cost the longer window was bought for is 0.01 cm. In the
+// finished stack it matters more than that: with the shaped guard in front of
+// it, putting the window back to 5 frames costs 2.1 points of grounding
+// (86.2 → 84.1 %) for 0.004 cm of hip.
+const PIN_SMOOTH_HALF_S = 1 / 30; // 3-frame window at 30 fps
+// The 4f penetration guard's correction is SHAPED over this half-window before
+// it is applied. Raw, the guard fired on 228/514 frames (44 %), switching on
+// and off 6.8 times a second in bursts of median length 3 frames, and the
+// correction's own second difference was 1.10 cm RMS — it fixed the sole and
+// injected a per-frame tremble into the leg doing it. ±2 frames at 30 fps is
+// the shortest window that spans that median burst.
+const GUARD_SHAPE_HALF_S = 2 / 30;
+// "Near the floor" is always measured against a LOCAL low, never a global
+// constant, because SAM's vertical drift moves the apparent ground by tens of
+// cm across a clip. Half a second is long enough to contain a whole step and
+// short enough that the drift inside it is small. Already a duration before
+// this file's constants were converted; named here so the block is complete.
+const LOCAL_LOW_HALF_S = 0.5;
+
+/** Frames covering `seconds` at `fps`, never fewer than `min` — a run length,
+ *  a blend ramp or a central-difference baseline of zero frames is not an
+ *  algorithm, so a slow clip degrades to the tightest meaningful setting
+ *  rather than to a no-op. */
+function framesFor(seconds, fps, min = 1) {
+	return Math.max(min, Math.round(seconds * fps));
+}
+
+/** Odd, centred moving-average window covering ±`halfSeconds` — the smoothers
+ *  below all read `Math.floor(window / 2)` on each side, so the window has to
+ *  be built from the half-width to stay symmetric at any rate. */
+function windowFor(halfSeconds, fps) {
+	return 2 * framesFor(halfSeconds, fps) + 1;
+}
+
+/** How many passes of the three-frame slerp reproduce ONE pass at 30 fps.
+ *  A three-tap smoother's spread grows as sqrt(passes) FRAMES, i.e.
+ *  sqrt(passes)/fps seconds, so holding the duration fixed costs
+ *  (halfSeconds * fps)² passes — 1 at 30 fps, 4 at 60. */
+function smoothingPasses(halfSeconds, fps) {
+	return Math.max(1, Math.round((halfSeconds * fps) ** 2));
+}
+
+// cskel27 joint -> BVH joint (mixamorig: prefix added at lookup). Identity
+// mapping except the joints the BVH does not carry.
+const BVH_SOURCE = Object.fromEntries(CSKEL27_JOINTS.map((name) => [name, name]));
+BVH_SOURCE.Spine3 = "Spine2";
+BVH_SOURCE.LeftHandEnd = "LeftHand";
+BVH_SOURCE.RightHandEnd = "RightHand";
+
+/** Minimal BVH reader: hierarchy (names, parents, offsets, channels) and the
+ *  motion table. Throws with a named reason on anything malformed. */
+export function parseBvh(text) {
+	if (typeof text !== "string" || !text.includes("HIERARCHY")) throw new Error("bvh-malformed");
+	const tokens = text.slice(text.indexOf("HIERARCHY")).split(/\s+/);
+	let cursor = 0;
+	const next = () => tokens[cursor++];
+	const peek = () => tokens[cursor];
+	const joints = [];
+	const stack = [];
+
+	if (next() !== "HIERARCHY") throw new Error("bvh-malformed");
+	while (cursor < tokens.length) {
+		const token = next();
+		if (token === "ROOT" || token === "JOINT") {
+			const name = next();
+			const joint = { name, parent: stack.length ? stack[stack.length - 1] : -1, offset: [0, 0, 0], channels: [] };
+			joints.push(joint);
+			if (next() !== "{") throw new Error("bvh-malformed");
+			stack.push(joints.length - 1);
+		} else if (token === "OFFSET") {
+			const target = stack[stack.length - 1];
+			const offset = [Number(next()), Number(next()), Number(next())];
+			if (!offset.every(Number.isFinite)) throw new Error("bvh-malformed");
+			if (target !== undefined && joints[target].endPending) joints[target].end = offset;
+			else if (target !== undefined) joints[target].offset = offset;
+		} else if (token === "CHANNELS") {
+			const count = Number(next());
+			const channels = [];
+			for (let i = 0; i < count; i += 1) channels.push(next());
+			joints[stack[stack.length - 1]].channels = channels;
+		} else if (token === "End") {
+			next(); // "Site"
+			if (next() !== "{") throw new Error("bvh-malformed");
+			joints[stack[stack.length - 1]].endPending = true;
+		} else if (token === "}") {
+			const top = stack[stack.length - 1];
+			if (top !== undefined && joints[top].endPending) joints[top].endPending = false;
+			else stack.pop();
+			if (stack.length === 0 && peek() === "MOTION") break;
+		} else if (token === "MOTION") {
+			break;
+		}
+	}
+	if (next() !== "MOTION" && tokens[cursor - 1] !== "MOTION") {
+		// the while-loop may have consumed MOTION already via peek/break
+	}
+	// Align cursor to just after "MOTION".
+	while (tokens[cursor - 1] !== "MOTION") {
+		if (cursor >= tokens.length) throw new Error("bvh-malformed");
+		cursor += 1;
+	}
+	if (next() !== "Frames:") throw new Error("bvh-malformed");
+	const frames = Number(next());
+	if (next() !== "Frame" || next() !== "Time:") throw new Error("bvh-malformed");
+	const frameTimeS = Number(next());
+	if (!Number.isInteger(frames) || frames < 1 || !(frameTimeS > 0)) throw new Error("bvh-malformed");
+	const channelTotal = joints.reduce((sum, joint) => sum + joint.channels.length, 0);
+	const values = new Float64Array(frames * channelTotal);
+	for (let i = 0; i < values.length; i += 1) {
+		const value = Number(next());
+		if (!Number.isFinite(value)) throw new Error("bvh-motion-truncated");
+		values[i] = value;
+	}
+	return { joints, frames, frameTimeS, channelTotal, values };
+}
+
+function rotX(deg) {
+	const r = (deg * Math.PI) / 180;
+	const c = Math.cos(r);
+	const s = Math.sin(r);
+	return [[1, 0, 0], [0, c, -s], [0, s, c]];
+}
+function rotY(deg) {
+	const r = (deg * Math.PI) / 180;
+	const c = Math.cos(r);
+	const s = Math.sin(r);
+	return [[c, 0, s], [0, 1, 0], [-s, 0, c]];
+}
+function rotZ(deg) {
+	const r = (deg * Math.PI) / 180;
+	const c = Math.cos(r);
+	const s = Math.sin(r);
+	return [[c, -s, 0], [s, c, 0], [0, 0, 1]];
+}
+const ROTATORS = { Xrotation: rotX, Yrotation: rotY, Zrotation: rotZ };
+
+/** Convert a parsed Mixamo BVH into cskel27 motion arrays. */
+export function bvhToCskel27Motion(bvh) {
+	const { joints, frames, frameTimeS, channelTotal, values } = bvh;
+	const bvhIndex = new Map(joints.map((joint, index) => [joint.name, index]));
+	const sourceIndex = CSKEL27_JOINTS.map((name) => {
+		const source = `mixamorig:${BVH_SOURCE[name]}`;
+		if (!bvhIndex.has(source)) throw new Error(`bvh-missing-joint:${source}`);
+		return bvhIndex.get(source);
+	});
+	const channelStart = [];
+	let running = 0;
+	for (const joint of joints) {
+		channelStart.push(running);
+		running += joint.channels.length;
+	}
+
+	const jointCount = CSKEL27_JOINTS.length;
+	const fps = Math.round(1 / frameTimeS);
+	// Every duration in the constants block, resolved against THIS clip's rate.
+	// Nothing below this line may be written as a frame count.
+	const spinDegPerFrame = SPIN_DEG_PER_S / fps;
+	const torsoPasses = smoothingPasses(TORSO_SMOOTH_HALF_S, fps);
+	const rootXzWindow = windowFor(ROOT_XZ_SMOOTH_HALF_S, fps);
+	const supportMinRun = framesFor(SUPPORT_MIN_RUN_S, fps);
+	const contactMinRun = framesFor(CONTACT_MIN_RUN_S, fps);
+	const speedDiffHalf = framesFor(SPEED_DIFF_HALF_S, fps);
+	const transferBlendWindow = windowFor(TRANSFER_BLEND_HALF_S, fps);
+	const pinSmoothWindow = windowFor(PIN_SMOOTH_HALF_S, fps);
+	const lockBlendFrames = framesFor(LOCK_BLEND_S, fps);
+	const guardShapeHalf = framesFor(GUARD_SHAPE_HALF_S, fps);
+	const localLowHalf = framesFor(LOCAL_LOW_HALF_S, fps);
+	const rotMats = new Float32Array(frames * jointCount * 9);
+	const rootPos = new Float32Array(frames * 3);
+	const posedJoints = new Float32Array(frames * jointCount * 3);
+
+	const skeleton = canonicalCskel27Reference();
+	const offsets = deriveBoneOffsets(skeleton.posed_joints, skeleton.local_rot_mats);
+
+	// Scale the root trajectory to CozyClay's body: SAM writes per-clip bone
+	// lengths, and a 92 cm-legged skeleton's hip path on a 88 cm-legged body
+	// floats or sinks. Ratio of hip-to-ankle chain lengths, both skeletons.
+	const canonicalLeg = chainLength(skeleton.posed_joints, ["LeftUpLeg", "LeftLeg", "LeftFoot"]);
+	const bvhLeg =
+		(magnitude(joints[bvhIndex.get("mixamorig:LeftLeg")].offset) +
+			magnitude(joints[bvhIndex.get("mixamorig:LeftFoot")].offset)) * CM_TO_M;
+	const rootScale = bvhLeg > 1e-6 ? canonicalLeg / bvhLeg : 1;
+
+	const IDENTITY = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+	const rootChannels = joints[0].channels;
+
+	// Pass 1 — BVH world rotations for every joint on every frame: local
+	// eulers composed in listed channel order, chained down the hierarchy.
+	const worldsByFrame = new Array(frames);
+	for (let f = 0; f < frames; f += 1) {
+		const base = f * channelTotal;
+		const worlds = new Array(joints.length);
+		for (let j = 0; j < joints.length; j += 1) {
+			const joint = joints[j];
+			let local = IDENTITY;
+			const start = base + channelStart[j];
+			for (let c = 0; c < joint.channels.length; c += 1) {
+				const rotate = ROTATORS[joint.channels[c]];
+				if (!rotate) continue; // position channels are read separately
+				local = matMul(local, rotate(values[start + c]));
+			}
+			worlds[j] = joint.parent < 0 ? local : matMul(worlds[joint.parent], local);
+		}
+		worldsByFrame[f] = worlds;
+		// Root position: the position channels, cm → m, scaled.
+		const start = base + channelStart[0];
+		for (let c = 0; c < rootChannels.length; c += 1) {
+			if (rootChannels[c] === "Xposition") rootPos[f * 3] = values[start + c] * CM_TO_M * rootScale;
+			else if (rootChannels[c] === "Yposition") rootPos[f * 3 + 1] = values[start + c] * CM_TO_M * rootScale;
+			else if (rootChannels[c] === "Zposition") rootPos[f * 3 + 2] = values[start + c] * CM_TO_M * rootScale;
+		}
+	}
+	// Frame-0 root in RAW metres (unscaled, untouched by any later pass):
+	// every person extracted from the same clip shares this camera space, so
+	// the difference between two takes' rawRootStart is their real-world
+	// relative placement in the scene.
+	const rawRootStart = [rootPos[0] / rootScale, rootPos[1] / rootScale, rootPos[2] / rootScale];
+
+	// Pass 2 — repair root spins, then stabilize the torso and the legs (see
+	// header). The two joint sets are disjoint and each pass snapshots its own
+	// input, so the order between them does not change the result.
+	repairRootSpins(worldsByFrame, bvhIndex.get("mixamorig:Hips"), spinDegPerFrame);
+	const bvhIndices = (names) => names.map((name) => bvhIndex.get(name)).filter((i) => i !== undefined);
+	stabilizeChain(worldsByFrame, bvhIndices(TORSO_JOINTS), TORSO_BLEND, torsoPasses);
+	stabilizeChain(worldsByFrame, bvhIndices(LEG_JOINTS), LEG_BLEND, torsoPasses);
+
+	// The BVH's own sole heights, via FK over ITS skeleton. SAM's offline
+	// foot-contact pass already leveled the ground relationship in that
+	// space (median lowest sole ≈ 2 cm); re-growing the pose on CozyClay's
+	// canonical proportions would shift it (a crouched leg of different
+	// thigh/shin ratio lands its foot at a different height), so the raw
+	// sole track is carried over as the reference to restore.
+	const rawSoleScaled = new Float64Array(frames);
+	{
+		const soleJoints = ["LeftFoot", "RightFoot", "LeftToeBase", "RightToeBase"]
+			.map((name) => bvhIndex.get(`mixamorig:${name}`))
+			.filter((index) => index !== undefined);
+		const positions = new Array(joints.length);
+		for (let f = 0; f < frames; f += 1) {
+			const worlds = worldsByFrame[f];
+			positions[0] = [rootPos[f * 3] / (CM_TO_M * rootScale), rootPos[f * 3 + 1] / (CM_TO_M * rootScale), rootPos[f * 3 + 2] / (CM_TO_M * rootScale)];
+			for (let j = 1; j < joints.length; j += 1) {
+				const parent = joints[j].parent;
+				const rotated = matVec3(worlds[parent], joints[j].offset);
+				positions[j] = [
+					positions[parent][0] + rotated[0],
+					positions[parent][1] + rotated[1],
+					positions[parent][2] + rotated[2],
+				];
+			}
+			let low = Infinity;
+			for (const j of soleJoints) low = Math.min(low, positions[j][1]);
+			rawSoleScaled[f] = low * CM_TO_M * rootScale;
+		}
+	}
+
+	// Root translation: camera-space jitter is noise, not gait — X/Z ride a
+	// short centred average.
+	smoothTrack(rootPos, frames, 0, rootXzWindow);
+	smoothTrack(rootPos, frames, 2, rootXzWindow);
+
+	// Pass 3 — cskel27 locals: parentGlobalᵀ · global along the cskel27 chain.
+	for (let f = 0; f < frames; f += 1) {
+		const worlds = worldsByFrame[f];
+		for (let j = 0; j < jointCount; j += 1) {
+			const global = worlds[sourceIndex[j]];
+			const parent = CSKEL27_PARENTS[j];
+			const local = parent === null ? global : matMul(matTranspose(worlds[sourceIndex[parent]]), global);
+			const o = (f * jointCount + j) * 9;
+			rotMats[o] = local[0][0]; rotMats[o + 1] = local[0][1]; rotMats[o + 2] = local[0][2];
+			rotMats[o + 3] = local[1][0]; rotMats[o + 4] = local[1][1]; rotMats[o + 5] = local[1][2];
+			rotMats[o + 6] = local[2][0]; rotMats[o + 7] = local[2][1]; rotMats[o + 8] = local[2][2];
+		}
+	}
+
+	// Pass 4 — grounding and foot lock (see the constants block), then one
+	// global shift so the lowest contact sits exactly on Y=0.
+	const readLocals = (f) => {
+		const frameLocals = new Array(jointCount);
+		for (let j = 0; j < jointCount; j += 1) {
+			const o = (f * jointCount + j) * 9;
+			frameLocals[j] = [
+				[rotMats[o], rotMats[o + 1], rotMats[o + 2]],
+				[rotMats[o + 3], rotMats[o + 4], rotMats[o + 5]],
+				[rotMats[o + 6], rotMats[o + 7], rotMats[o + 8]],
+			];
+		}
+		return frameLocals;
+	};
+	const rootAt = (f) => [rootPos[f * 3], rootPos[f * 3 + 1], rootPos[f * 3 + 2]];
+	const writeLocal = (f, j, m) => {
+		const o = (f * jointCount + j) * 9;
+		rotMats[o] = m[0][0]; rotMats[o + 1] = m[0][1]; rotMats[o + 2] = m[0][2];
+		rotMats[o + 3] = m[1][0]; rotMats[o + 4] = m[1][1]; rotMats[o + 5] = m[1][2];
+		rotMats[o + 6] = m[2][0]; rotMats[o + 7] = m[2][1]; rotMats[o + 8] = m[2][2];
+	};
+	const J = (name) => CSKEL27_JOINTS.indexOf(name);
+	const feet = ["LeftToeBase", "RightToeBase", "LeftFoot", "RightFoot"].map(J);
+	const legs = [
+		{ hip: J("LeftUpLeg"), knee: J("LeftLeg"), ankle: J("LeftFoot") },
+		{ hip: J("RightUpLeg"), knee: J("RightLeg"), ankle: J("RightFoot") },
+	];
+	const hipsIdx = J("Hips");
+
+	// 4a) ankle and sole tracks from a first FK sweep — and the proportion
+	// correction: with the SAME joint angles, a crouched leg of different
+	// thigh/shin ratio lands its sole at a different height, which reads as
+	// a constant hover on a fighter who never fully straightens. The root is
+	// re-seated per frame so the canonical body's lowest sole reproduces the
+	// (scaled) sole height SAM's own leveled skeleton had.
+	const toes = [J("LeftToeBase"), J("RightToeBase")];
+	const ankle = [new Float64Array(frames * 3), new Float64Array(frames * 3)];
+	const kneeY = [new Float64Array(frames), new Float64Array(frames)];
+	const lowestSole = new Float64Array(frames * 2);
+	for (let f = 0; f < frames; f += 1) {
+		let positions = forwardKinematics(readLocals(f), offsets, rootAt(f));
+		const canonSole = Math.min(
+			positions[legs[0].ankle][1], positions[toes[0]][1],
+			positions[legs[1].ankle][1], positions[toes[1]][1]
+		);
+		const reseat = rawSoleScaled[f] - canonSole;
+		if (Math.abs(reseat) > 1e-9) {
+			rootPos[f * 3 + 1] += reseat;
+			positions = forwardKinematics(readLocals(f), offsets, rootAt(f));
+		}
+		for (let s = 0; s < 2; s += 1) {
+			ankle[s][f * 3] = positions[legs[s].ankle][0];
+			ankle[s][f * 3 + 1] = positions[legs[s].ankle][1];
+			ankle[s][f * 3 + 2] = positions[legs[s].ankle][2];
+			kneeY[s][f] = positions[legs[s].knee][1];
+			lowestSole[f * 2 + s] = Math.min(positions[legs[s].ankle][1], positions[toes[s]][1]);
+		}
+	}
+
+	// 4b) per-foot stance evidence, in two nested strengths, because the two
+	// consumers want different things. Both are measured against that foot's
+	// LOCAL low, not a global constant: SAM's vertical drift moves the apparent
+	// ground by tens of cm across a clip, so "near the floor" can only mean
+	// "near where this foot bottoms out around now".
+	//  - SUPPORT (4c, the ground line) only has to know which foot is ON the
+	//    floor. A boxer's lead foot pivots and drags while it carries his
+	//    weight; it is still the floor witness, so support does NOT gate on
+	//    horizontal speed — only on being low and vertically settled.
+	//  - CONTACT (4e, the XZ foot lock) additionally needs the foot to STAY in
+	//    one place, since the lock nails it there. That is judged over the RUN
+	//    (see splitByXzWander), not per frame: 1 cm of SAM's per-frame XZ noise
+	//    already reads as 0.3 m/s over a ±2-frame baseline, so an instantaneous
+	//    speed gate tight enough to reject a real step also rejects every
+	//    jittery-but-planted foot — which is exactly how the old single
+	//    detector ended up firing on 4 % of foot-frames, leaving both the
+	//    ground line and the lock with nothing to hold on to.
+	const support = [new Array(frames).fill(false), new Array(frames).fill(false)];
+	const realContact = [new Array(frames).fill(false), new Array(frames).fill(false)];
+	const lockContact = [new Array(frames).fill(false), new Array(frames).fill(false)];
+	const settleLimit = CONTACT_SETTLE_MPS / fps;
+	const riseLimit = SUPPORT_RISE_MPS / fps;
+	const lowHalf = localLowHalf;
+	for (let s = 0; s < 2; s += 1) {
+		for (let f = 0; f < frames; f += 1) {
+			// Central difference over SPEED_DIFF_HALF_S (±2 frames at 30 fps):
+			// per-frame deltas are mostly estimation noise (ankle accel RMS
+			// ~2.4 cm), a 0.13 s baseline reads the actual movement underneath
+			// it. The result is a per-FRAME delta, which is what riseLimit and
+			// settleLimit are (m/s ÷ fps), so both sides scale together.
+			const before = Math.max(0, f - speedDiffHalf);
+			const after = Math.min(frames - 1, f + speedDiffHalf);
+			const span = Math.max(1, after - before);
+			const dy = (ankle[s][after * 3 + 1] - ankle[s][before * 3 + 1]) / span;
+			let localLow = Infinity;
+			for (let k = Math.max(0, f - lowHalf); k <= Math.min(frames - 1, f + lowHalf); k += 1) {
+				localLow = Math.min(localLow, ankle[s][k * 3 + 1]);
+			}
+			const above = ankle[s][f * 3 + 1] - localLow;
+			const belowKnee = ankle[s][f * 3 + 1] < kneeY[s][f] - 0.05;
+			support[s][f] = above < SUPPORT_BAND_M && Math.abs(dy) < riseLimit && belowKnee;
+			realContact[s][f] = above < CONTACT_BAND_M && Math.abs(dy) < settleLimit && belowKnee;
+		}
+		// Run cleaning IS the hysteresis: below supportMinRun neither a
+		// flicker of evidence starts a stance nor a flicker of noise ends one,
+		// so the ground reference cannot chatter between feet frame by frame.
+		cleanRuns(support[s], supportMinRun);
+		cleanRuns(realContact[s], contactMinRun);
+		// ...then the lockable half of the evidence: keep only the stretches
+		// the ankle spends inside one CONTACT_WANDER_M patch of floor. This is
+		// what separates "planted, estimated noisily" from "stepping".
+		splitByXzWander(realContact[s], ankle[s], CONTACT_WANDER_M, contactMinRun);
+	}
+
+	// 4c) the measured ground line: STANCE PINNING with a jump permit. The
+	// scope is fixed-camera footage, so wherever a planted sole lands IS the
+	// ground — pinning it to zero kills SAM's vertical drift outright. (The
+	// rolling-quantile line two revisions back still floated up to 23 cm
+	// whenever a window went majority-dip.) What the floor is read FROM is the
+	// SUPPORT foot, not whichever foot is lowest: measured on both fixtures
+	// the lowest foot is horizontally still on 6–13 % of frames and runs
+	// 0.7 m/s median — it is usually the SWING leg, so every swing-leg
+	// estimation error went straight into body height and the hip popped ~1 cm
+	// (5.5 cm worst) at each of the ~3 support changes per second.
+	// The only measured air that survives is a PERMITTED jump: a fast, tall,
+	// brief excursion of the lowest sole above its local floor — the three
+	// gates that separate a real hop from a slow depth-drift float or a
+	// bend-occlusion lift. Over permitted air the ground interpolates takeoff
+	// level → landing level, so the arc keeps its measured height.
+	const soleAt = new Float64Array(frames); // physical lowest sole: jump gates and the sag clamp
+	const soleSide = [new Float64Array(frames), new Float64Array(frames)];
+	for (let f = 0; f < frames; f += 1) {
+		soleSide[0][f] = lowestSole[f * 2];
+		soleSide[1][f] = lowestSole[f * 2 + 1];
+		soleAt[f] = Math.min(soleSide[0][f], soleSide[1][f]);
+	}
+	const airHalf = localLowHalf;
+	const localFloor = new Float64Array(frames);
+	for (let f = 0; f < frames; f += 1) {
+		let low = Infinity;
+		for (let k = Math.max(0, f - airHalf); k <= Math.min(frames - 1, f + airHalf); k += 1) low = Math.min(low, soleAt[k]);
+		localFloor[f] = low;
+	}
+	const airborne = new Array(frames).fill(false);
+	const candidate = new Array(frames).fill(false);
+	for (let f = 0; f < frames; f += 1) candidate[f] = soleAt[f] - localFloor[f] > AIR_EPS_M;
+	const maxAirFrames = Math.round(JUMP_MAX_AIR_S * fps);
+	const airRuns = [];
+	for (const run of contactRuns(candidate)) {
+		let peak = 0;
+		let rise = 0;
+		for (let f = run.start; f <= run.end; f += 1) {
+			peak = Math.max(peak, soleAt[f] - localFloor[f]);
+			// The takeoff-speed gate reads the same SPEED_DIFF_HALF_S baseline
+			// as the stance gates: over ±1 frame at 60 fps a real hop and a
+			// noisy plant are indistinguishable.
+			const before = Math.max(0, f - speedDiffHalf);
+			const after = Math.min(frames - 1, f + speedDiffHalf);
+			rise = Math.max(rise, ((soleAt[after] - soleAt[before]) / Math.max(1, after - before)) * fps);
+		}
+		if (peak >= JUMP_MIN_PEAK_M && rise >= JUMP_MIN_RISE_MPS && run.end - run.start + 1 <= maxAirFrames) {
+			for (let f = run.start; f <= run.end; f += 1) airborne[f] = true;
+			airRuns.push({ ...run, peak });
+		}
+	}
+	// Which foot the floor is read from, frame by frame — a STICKY choice, so
+	// that a stance the detector reports on both feet (double support runs 53 %
+	// of this footage) does not hand the reference back and forth on whichever
+	// sole the estimator happened to place a millimetre lower this frame. The
+	// reference moves only when the foot holding it loses support outright, or
+	// when the other foot is both in support and REF_MARGIN_M lower — a real
+	// weight shift. With no evidence on either foot (flight, or footwork the
+	// detector missed) the last reference is simply held; the jump permit below
+	// owns those stretches.
+	const refSide = new Int8Array(frames);
+	{
+		let side = soleSide[0][0] <= soleSide[1][0] ? 0 : 1;
+		for (let f = 0; f < frames; f += 1) {
+			const other = 1 - side;
+			if (support[other][f] && (!support[side][f] || soleSide[other][f] < soleSide[side][f] - REF_MARGIN_M)) side = other;
+			refSide[f] = side;
+		}
+	}
+	// A support TRANSFER must never step. The two soles disagree by 3.6 cm
+	// median — estimation error, not a floor that moved — so switching source
+	// instantly dumps that whole gap into one frame of body height. Cross-fade
+	// the two sole tracks instead: the 0/1 side track box-smoothed TWICE, so
+	// the hand-over is an S-ramp with no corner at either end of it.
+	const rightShare = new Float64Array(frames);
+	for (let f = 0; f < frames; f += 1) rightShare[f] = refSide[f];
+	smoothArray(rightShare, transferBlendWindow);
+	smoothArray(rightShare, transferBlendWindow);
+	const ground = new Float64Array(frames);
+	for (let f = 0; f < frames; f += 1) {
+		ground[f] = soleSide[0][f] * (1 - rightShare[f]) + soleSide[1][f] * rightShare[f];
+	}
+	// Permitted air: the floor does not move while nobody is standing on it,
+	// so the line interpolates takeoff → landing and the hop keeps its arc.
+	for (const run of contactRuns(airborne)) {
+		const i0 = run.start - 1;
+		const i1 = run.end + 1;
+		const y0 = i0 >= 0 ? ground[i0] : i1 < frames ? ground[i1] : localFloor[run.start];
+		const y1 = i1 < frames ? ground[i1] : y0;
+		for (let f = run.start; f <= run.end; f += 1) {
+			ground[f] = y0 + ((y1 - y0) * (f - i0)) / (i1 - i0);
+		}
+	}
+	// Sag clamp: the stance line may sit at most FLOOR_SAG_M above the lowest
+	// sole. Without it a foot the detector calls "swinging" while it is in
+	// fact a few cm below the support foot would be driven under Y=0, and 4f's
+	// per-frame penetration guard would hoist that single frame — trading the
+	// pop we are removing for an identical one. Above permitted air the clamp
+	// is inert (the soles are far above the line by construction).
+	for (let f = 0; f < frames; f += 1) ground[f] = Math.min(ground[f], soleAt[f] + FLOOR_SAG_M);
+	smoothArray(ground, pinSmoothWindow);
+
+	if (process.env.BVH_GROUND_DEBUG) {
+		const pctOf = (n) => `${((n / frames) * 100).toFixed(0)}%`;
+		const trueCount = (track) => track.filter(Boolean).length;
+		let either = 0;
+		let switches = 0;
+		for (let f = 0; f < frames; f += 1) {
+			if (support[0][f] || support[1][f]) either += 1;
+			if (f > 0 && refSide[f] !== refSide[f - 1]) switches += 1;
+		}
+		const contacts = trueCount(realContact[0]) + trueCount(realContact[1]);
+		const jumps = airRuns.map((r) => `f${r.start}..${r.end}@${(r.peak * 100).toFixed(0)}cm`).join(" ") || "none";
+		console.error(`[stance] support L=${pctOf(trueCount(support[0]))} R=${pctOf(trueCount(support[1]))} either=${pctOf(either)}; lockable contact ${contacts}/${frames * 2} (${((contacts / (frames * 2)) * 100).toFixed(0)}%); reference hand-overs ${switches} (${(switches / (frames / fps)).toFixed(1)}/s)`);
+		console.error(`[ground] range=[${Math.min(...ground).toFixed(2)}..${Math.max(...ground).toFixed(2)}] jumps: ${jumps}`);
+	}
+
+	// 4d) level the root by subtracting the ground line.
+	for (let f = 0; f < frames; f += 1) {
+		rootPos[f * 3 + 1] -= ground[f];
+		ankle[0][f * 3 + 1] -= ground[f];
+		ankle[1][f * 3 + 1] -= ground[f];
+	}
+	const anchors = realContact[0].filter(Boolean).length + realContact[1].filter(Boolean).length;
+
+	// XZ bridging runs in LEVELED space, where the planted-ankle level is a
+	// constant again (the median over real contacts).
+	const leveledPlant = [];
+	for (let s = 0; s < 2; s += 1) {
+		for (let f = 0; f < frames; f += 1) if (realContact[s][f]) leveledPlant.push(ankle[s][f * 3 + 1]);
+	}
+	leveledPlant.sort((a, b) => a - b);
+	const plantY = leveledPlant[Math.floor(leveledPlant.length / 2)] ?? 0;
+	for (let s = 0; s < 2; s += 1) {
+		for (let f = 0; f < frames; f += 1) lockContact[s][f] = realContact[s][f];
+		bridgeOcclusionGaps(lockContact[s], ankle[s], plantY, fps);
+	}
+
+	// How far the lock actually dragged an ankle sideways, the metric that
+	// separates "removed a slide" from "threw the leg across the floor".
+	let lockPullMax = 0;
+	// 4e) foot lock: hold each contact run's ankle at its median planted spot
+	// via 2-bone leg IK, ramped over the run edges. Positions are re-read
+	// after leveling so the lock lives in the leveled space.
+	if (anchors > 0) {
+		for (let f = 0; f < frames; f += 1) {
+			const positions = forwardKinematics(readLocals(f), offsets, rootAt(f));
+			for (let s = 0; s < 2; s += 1) {
+				ankle[s][f * 3] = positions[legs[s].ankle][0];
+				ankle[s][f * 3 + 1] = positions[legs[s].ankle][1];
+				ankle[s][f * 3 + 2] = positions[legs[s].ankle][2];
+			}
+		}
+		for (let s = 0; s < 2; s += 1) {
+			for (const run of contactRuns(lockContact[s])) {
+				const lock = runLockPoint(run, realContact[s], ankle[s]);
+				if (!lock) continue;
+				for (let f = run.start; f <= run.end; f += 1) {
+					const edge = Math.min(f - run.start + 1, run.end - f + 1);
+					const weight = Math.min(1, edge / (lockBlendFrames + 1));
+					const locals = readLocals(f);
+					const worlds = globalRotations(locals);
+					const positions = forwardKinematics(locals, offsets, rootAt(f));
+					const current = positions[legs[s].ankle];
+					const pull = Math.hypot(lock[0] - current[0], lock[2] - current[2]);
+					if (pull > LOCK_MAX_PULL_M) continue;
+					lockPullMax = Math.max(lockPullMax, pull * weight);
+					const target = [
+						current[0] + (lock[0] - current[0]) * weight,
+						current[1] + (lock[1] - current[1]) * weight,
+						current[2] + (lock[2] - current[2]) * weight,
+					];
+					const solved = solveLegIk(positions, worlds, legs[s], hipsIdx, target);
+					if (!solved) continue;
+					writeLocal(f, legs[s].hip, solved.hipLocal);
+					writeLocal(f, legs[s].knee, solved.kneeLocal);
+					writeLocal(f, legs[s].ankle, solved.ankleLocal);
+				}
+			}
+		}
+	}
+
+	// 4f) final FK, then the vertical placement. The reference is a robust
+	// touch level (the 10th percentile of per-frame lowest soles) — NOT the
+	// clip's global minimum: one residual estimation dip below the floor
+	// would otherwise hoist the entire clip by its depth. What still pokes
+	// through afterwards is caught by a one-sided guard (lifting a sunken
+	// frame never squashes a jump; only chasing feet upward does).
+	const lowestAt = new Float64Array(frames);
+	for (let f = 0; f < frames; f += 1) {
+		const positions = forwardKinematics(readLocals(f), offsets, rootAt(f));
+		for (let j = 0; j < jointCount; j += 1) {
+			const p = (f * jointCount + j) * 3;
+			posedJoints[p] = positions[j][0];
+			posedJoints[p + 1] = positions[j][1];
+			posedJoints[p + 2] = positions[j][2];
+		}
+		let low = Infinity;
+		for (const j of feet) low = Math.min(low, posedJoints[(f * jointCount + j) * 3 + 1]);
+		lowestAt[f] = low;
+	}
+	// The ground line already brought touch-downs to ≈0; the last shift only
+	// centres the touch CLUSTER on zero. A low percentile would land just
+	// above the residual error dips instead and hoist the clip by their
+	// depth — the exact 7 cm hover this replaced.
+	const touchValues = [...lowestAt].filter((value) => value < 0.05).sort((a, b) => a - b);
+	const sortedLowest = [...lowestAt].sort((a, b) => a - b);
+	const shift = touchValues.length > frames * 0.05
+		? touchValues[Math.floor(touchValues.length / 2)]
+		: sortedLowest[Math.floor(sortedLowest.length * 0.1)] ?? 0;
+	if (Number.isFinite(shift) && Math.abs(shift) > 1e-6) {
+		for (let f = 0; f < frames; f += 1) {
+			rootPos[f * 3 + 1] -= shift;
+			lowestAt[f] -= shift;
+			for (let j = 0; j < jointCount; j += 1) posedJoints[(f * jointCount + j) * 3 + 1] -= shift;
+		}
+	}
+	// A sole under the floor is a LEG error, not a body error: the ground line
+	// stands on the SUPPORT foot, so what pokes through is the other leg's
+	// per-frame estimate. Hoisting the whole body for it — the only thing this
+	// guard used to do — wrote every one of those errors into hip height, on
+	// 44 % of frames, 1.8 cm mean and 6 cm worst, and that rectified track was
+	// measurably the largest single source of hip jitter in the take (hip jerk
+	// RMS fell from 1.17 to 0.80 cm with the guard simply switched off).
+	// So: lift the offending FOOT with the same 2-bone leg IK, where the error
+	// actually is, and the hips never feel it. The body lift stays underneath
+	// as the backstop for whatever the leg cannot reach — a leg already
+	// straight has nowhere left to go — so nothing ever ends up below Y=0.
+	//
+	// The correction is SHAPED in time before it is applied, per leg. Raw, it
+	// is a per-frame quantity computed from a per-frame estimate: it fired on
+	// 44 % of frames in bursts of median length 3, switching on and off 6.8
+	// times a second, and its own second difference was 1.10 cm RMS — so while
+	// it fixed the sole it wrote that tremble straight into the knee. Shaping:
+	//   deficit → running MAX over ±guardShapeHalf → moving average over the
+	//   same half-window.
+	// The DILATION BEFORE THE BLUR is what makes this safe: after the max,
+	// every sample the average sees within ±guardShapeHalf of frame f is
+	// already ≥ the raw deficit at f, so their mean is too — the smoothed
+	// correction is pointwise ≥ the raw deficit everywhere and no floor
+	// penetration can be reintroduced by the smoothing, which is the only
+	// reason it is allowed to touch this correction at all. (Blurring the raw
+	// deficit alone would halve the correction at the tip of every spike,
+	// which is exactly where the sole is deepest under the floor.)
+	// What this buys is measured in the leg's ANGLES, which is where the raw
+	// guard's damage was: knee angle jerk 3.04 → 2.63°/frame² and the worst
+	// single-frame knee change 16.2 → 14.5° on boxing-offline. The ankle's own
+	// accel barely moves (1.70 → 1.72 cm) — the guard was never displacing the
+	// foot much, it was chattering the joints that carry it. The cost is that
+	// frames NEAR a penetration are lifted slightly above the floor: grounding
+	// 87.2 → 86.2 %, which is most of why PIN_SMOOTH_HALF_S was re-swept.
+	const legLift = { frames: 0, sum: 0, max: 0 };
+	const bodyLift = { frames: 0, sum: 0, max: 0 };
+	const soleOfLeg = (f, s) => Math.min(
+		posedJoints[(f * jointCount + legs[s].ankle) * 3 + 1],
+		posedJoints[(f * jointCount + toes[s]) * 3 + 1]
+	);
+	const correction = [0, 1].map((s) => {
+		const deficit = new Float64Array(frames);
+		for (let f = 0; f < frames; f += 1) deficit[f] = Math.max(0, -soleOfLeg(f, s));
+		return shapeFloorCorrection(deficit, guardShapeHalf);
+	});
+	for (let f = 0; f < frames; f += 1) {
+		let lifted = false;
+		for (let s = 0; s < 2; s += 1) {
+			const lift = correction[s][f];
+			if (lift <= 1e-6) continue;
+			const locals = readLocals(f);
+			const positions = forwardKinematics(locals, offsets, rootAt(f));
+			const current = positions[legs[s].ankle];
+			const solved = solveLegIk(positions, globalRotations(locals), legs[s], hipsIdx, [current[0], current[1] + lift, current[2]]);
+			if (!solved) continue;
+			writeLocal(f, legs[s].hip, solved.hipLocal);
+			writeLocal(f, legs[s].knee, solved.kneeLocal);
+			writeLocal(f, legs[s].ankle, solved.ankleLocal);
+			lifted = true;
+			legLift.sum += lift;
+			legLift.max = Math.max(legLift.max, lift);
+		}
+		if (lifted) {
+			legLift.frames += 1;
+			const positions = forwardKinematics(readLocals(f), offsets, rootAt(f));
+			let low = Infinity;
+			for (let j = 0; j < jointCount; j += 1) {
+				const p = (f * jointCount + j) * 3;
+				posedJoints[p] = positions[j][0];
+				posedJoints[p + 1] = positions[j][1];
+				posedJoints[p + 2] = positions[j][2];
+			}
+			for (const j of feet) low = Math.min(low, posedJoints[(f * jointCount + j) * 3 + 1]);
+			lowestAt[f] = low;
+		}
+		const residual = -lowestAt[f];
+		if (residual <= 1e-6) continue;
+		bodyLift.frames += 1;
+		bodyLift.sum += residual;
+		bodyLift.max = Math.max(bodyLift.max, residual);
+		rootPos[f * 3 + 1] += residual;
+		lowestAt[f] += residual;
+		for (let j = 0; j < jointCount; j += 1) posedJoints[(f * jointCount + j) * 3 + 1] += residual;
+	}
+	if (process.env.BVH_GROUND_DEBUG) {
+		const report = (label, lift) =>
+			`${label} ${lift.frames}/${frames} (${((lift.frames / frames) * 100).toFixed(0)}%) mean ${((lift.sum / Math.max(1, lift.frames)) * 100).toFixed(2)}cm max ${(lift.max * 100).toFixed(2)}cm`;
+		console.error(`[guard] ${report("leg lifts", legLift)}; ${report("body lifts", bodyLift)}`);
+	}
+
+	// How large the FILMED person is relative to CozyClay's canonical body
+	// (leg-chain ratio). The take itself stays canonical; the app may scale
+	// the rendered character by this so the performer's real stature reads.
+	const personScale = rootScale > 1e-6 ? 1 / rootScale : 1;
+
+	return { frames, fps, rotMats, rootPos, posedJoints, personScale, rawRootStart, lockPullMax };
+}
+
+/** Angle in degrees between two rotation matrices, via the quat dot. */
+function angleBetweenDeg(a, b) {
+	const qa = matToQuat(a);
+	const qb = matToQuat(b);
+	const dot = Math.min(1, Math.abs(qa[0] * qb[0] + qa[1] * qb[1] + qa[2] * qb[2] + qa[3] * qb[3]));
+	return (2 * Math.acos(dot) * 180) / Math.PI;
+}
+
+/** Bridge intervals where the root spins impossibly fast with one shortest
+ *  path between the sound frames on either side, applying the correction to
+ *  EVERY joint so local articulation is preserved (the old retarget script's
+ *  repair, generalized from its hand-measured frame range). */
+function repairRootSpins(worldsByFrame, hipsIndex, degPerFrame) {
+	const frames = worldsByFrame.length;
+	if (hipsIndex === undefined || frames < 3) return;
+	const fast = new Array(frames).fill(false);
+	for (let f = 1; f < frames; f += 1) {
+		fast[f] = angleBetweenDeg(worldsByFrame[f - 1][hipsIndex], worldsByFrame[f][hipsIndex]) > degPerFrame;
+	}
+	let f = 1;
+	while (f < frames) {
+		if (!fast[f]) {
+			f += 1;
+			continue;
+		}
+		let end = f;
+		while (end + 1 < frames && fast[end + 1]) end += 1;
+		const before = f - 1;
+		const after = end + 1;
+		if (before >= 0 && after < frames) {
+			const qa = matToQuat(worldsByFrame[before][hipsIndex]);
+			const qb = matToQuat(worldsByFrame[after][hipsIndex]);
+			for (let inner = f; inner <= end; inner += 1) {
+				const repaired = quatToMat(slerpQuat(qa, qb, (inner - before) / (after - before)));
+				const correction = matMul(repaired, matTranspose(worldsByFrame[inner][hipsIndex]));
+				const worlds = worldsByFrame[inner];
+				for (let j = 0; j < worlds.length; j += 1) worlds[j] = matMul(correction, worlds[j]);
+			}
+		}
+		f = end + 1;
+	}
+}
+
+/** Zero-lag three-frame stabilization: each world rotation on the chain slides
+ *  `blend` of the way toward its immediate neighbours' midpoint, `passes`
+ *  times. Used on the torso (0.2) and both legs (0.4); the ARMS are never
+ *  passed in — see LEG_BLEND for why the same filter that costs a foot nothing
+ *  would blunt a punch. The neighbour span stays ±1 frame at every rate and
+ *  the DURATION is carried by the pass count, because a stride-N three-tap
+ *  filter passes Nyquist untouched (LEG/TORSO_SMOOTH_HALF_S). */
+function stabilizeChain(worldsByFrame, chainIndices, blend, passes) {
+	const frames = worldsByFrame.length;
+	if (frames < 3 || chainIndices.length === 0) return;
+	for (let pass = 0; pass < passes; pass += 1) {
+		for (const j of chainIndices) {
+			const original = worldsByFrame.map((worlds) => matToQuat(worlds[j]));
+			for (let f = 1; f < frames - 1; f += 1) {
+				const mid = slerpQuat(original[f - 1], original[f + 1], 0.5);
+				worldsByFrame[f][j] = quatToMat(slerpQuat(original[f], mid, blend));
+			}
+		}
+	}
+}
+
+/**
+ * Shape a per-frame floor-penetration correction so that applying it does not
+ * itself shake the leg: running MAX over ±half (dilation), then a centred
+ * moving average over the same ±half. Returns a new track.
+ *
+ * SAFETY INVARIANT — the result is pointwise >= the input, so a correction
+ * shaped this way can never reintroduce penetration the raw one removed. Every
+ * sample the average sees at frame f is dilated[k] for some |k - f| <= half,
+ * and dilated[k] >= source[f] because f is inside k's own ±half window; a mean
+ * of values all >= source[f] is >= source[f]. (Blurring the raw deficit
+ * without the dilation would instead halve the correction at the tip of every
+ * spike, which is exactly where the sole is deepest under the floor.)
+ * Exported so the invariant is tested directly rather than inferred.
+ */
+export function shapeFloorCorrection(source, half) {
+	const frames = source.length;
+	const dilated = new Float64Array(frames);
+	for (let f = 0; f < frames; f += 1) {
+		let peak = 0;
+		for (let k = Math.max(0, f - half); k <= Math.min(frames - 1, f + half); k += 1) peak = Math.max(peak, source[k]);
+		dilated[f] = peak;
+	}
+	const blurred = new Float64Array(frames);
+	for (let f = 0; f < frames; f += 1) {
+		let sum = 0;
+		let count = 0;
+		for (let k = Math.max(0, f - half); k <= Math.min(frames - 1, f + half); k += 1) {
+			sum += dilated[k];
+			count += 1;
+		}
+		blurred[f] = sum / count;
+	}
+	return blurred;
+}
+
+/** In-place centred moving average of a plain array, boundary-clamped. */
+function smoothArray(values, window) {
+	const half = Math.floor(window / 2);
+	const source = Float64Array.from(values);
+	for (let f = 0; f < values.length; f += 1) {
+		let sum = 0;
+		let count = 0;
+		for (let k = Math.max(0, f - half); k <= Math.min(values.length - 1, f + half); k += 1) {
+			sum += source[k];
+			count += 1;
+		}
+		values[f] = sum / count;
+	}
+}
+
+/** Erode contact runs shorter than minRun, then bridge gaps shorter than
+ *  minRun — single-frame flicker neither starts nor breaks a plant. */
+function cleanRuns(track, minRun) {
+	const frames = track.length;
+	for (let f = 0; f < frames; ) {
+		if (!track[f]) { f += 1; continue; }
+		let g = f;
+		while (g < frames && track[g]) g += 1;
+		if (g - f < minRun) for (let k = f; k < g; k += 1) track[k] = false;
+		f = g;
+	}
+	for (let f = 0; f < frames; ) {
+		if (track[f]) { f += 1; continue; }
+		let g = f;
+		while (g < frames && !track[g]) g += 1;
+		if (f > 0 && g < frames && g - f < minRun) for (let k = f; k < g; k += 1) track[k] = true;
+		f = g;
+	}
+}
+
+/** Cut a candidate contact track down to the stretches during which the ankle
+ *  never leaves a `maxWander`-wide patch of floor, dropping what is then
+ *  shorter than minRun. Net wander over a run is immune to the per-frame XZ
+ *  noise that defeats an instantaneous speed gate, and still rejects a foot
+ *  that is actually travelling — a step's bounding box blows past the patch
+ *  within a few frames, so the run is closed exactly where the foot left. */
+function splitByXzWander(track, anklePositions, maxWander, minRun) {
+	const kept = new Array(track.length).fill(false);
+	for (const run of contactRuns(track)) {
+		let start = run.start;
+		let minX = Infinity;
+		let maxX = -Infinity;
+		let minZ = Infinity;
+		let maxZ = -Infinity;
+		for (let f = run.start; f <= run.end; f += 1) {
+			const x = anklePositions[f * 3];
+			const z = anklePositions[f * 3 + 2];
+			const spanX = Math.max(maxX, x) - Math.min(minX, x);
+			const spanZ = Math.max(maxZ, z) - Math.min(minZ, z);
+			if (f > start && Math.hypot(spanX, spanZ) > maxWander) {
+				if (f - start >= minRun) for (let k = start; k < f; k += 1) kept[k] = true;
+				start = f;
+				minX = maxX = x;
+				minZ = maxZ = z;
+				continue;
+			}
+			minX = Math.min(minX, x); maxX = Math.max(maxX, x);
+			minZ = Math.min(minZ, z); maxZ = Math.max(maxZ, z);
+		}
+		if (run.end - start + 1 >= minRun) for (let k = start; k <= run.end; k += 1) kept[k] = true;
+	}
+	for (let f = 0; f < track.length; f += 1) track[f] = kept[f];
+}
+
+/** Contiguous true runs of a boolean track as { start, end } (inclusive). */
+function contactRuns(track) {
+	const runs = [];
+	for (let f = 0; f < track.length; ) {
+		if (!track[f]) { f += 1; continue; }
+		let g = f;
+		while (g < track.length && track[g]) g += 1;
+		runs.push({ start: f, end: g - 1 });
+		f = g;
+	}
+	return runs;
+}
+
+/** Merge contact runs across short occlusion gaps: the foot left "contact"
+ *  but reappears at (nearly) the same spot without ever lifting past the
+ *  jump ceiling — so it never actually moved, and the gap is an estimation
+ *  error to be pinned, not air to be preserved. */
+export function bridgeOcclusionGaps(track, anklePositions, floorY, fps) {
+	const maxGap = Math.round(BRIDGE_MAX_GAP_S * fps);
+	const runs = contactRuns(track);
+	for (let i = 0; i + 1 < runs.length; i += 1) {
+		const a = runs[i];
+		const b = runs[i + 1];
+		const gap = b.start - a.end - 1;
+		if (gap <= 0 || gap > maxGap) continue;
+		const dx = anklePositions[b.start * 3] - anklePositions[a.end * 3];
+		const dz = anklePositions[b.start * 3 + 2] - anklePositions[a.end * 3 + 2];
+		if (Math.hypot(dx, dz) > BRIDGE_MAX_XZ_M) continue;
+		let maxLift = -Infinity;
+		for (let f = a.end + 1; f < b.start; f += 1) maxLift = Math.max(maxLift, anklePositions[f * 3 + 1] - floorY);
+		if (maxLift > BRIDGE_MAX_LIFT_M) continue; // a real jump keeps its air
+		for (let f = a.end + 1; f < b.start; f += 1) track[f] = true;
+	}
+}
+
+/** Where a contact run pins its ankle: the median planted position over the
+ *  run's REAL contact frames (bridged frames are the error being repaired). */
+function runLockPoint(run, realTrack, anklePositions) {
+	const xs = [];
+	const ys = [];
+	const zs = [];
+	for (let f = run.start; f <= run.end; f += 1) {
+		if (!realTrack[f]) continue;
+		xs.push(anklePositions[f * 3]);
+		ys.push(anklePositions[f * 3 + 1]);
+		zs.push(anklePositions[f * 3 + 2]);
+	}
+	if (xs.length === 0) return null;
+	const median = (values) => values.sort((a, b) => a - b)[Math.floor(values.length / 2)];
+	return [median(xs), median(ys), median(zs)];
+}
+
+function v3sub(a, b) { return [a[0] - b[0], a[1] - b[1], a[2] - b[2]]; }
+function v3add(a, b) { return [a[0] + b[0], a[1] + b[1], a[2] + b[2]]; }
+function v3scale(v, k) { return [v[0] * k, v[1] * k, v[2] * k]; }
+function v3dot(a, b) { return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]; }
+function v3cross(a, b) {
+	return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function v3len(v) { return Math.hypot(v[0], v[1], v[2]); }
+function matVec3(m, v) {
+	return [
+		m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+		m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+		m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
+	];
+}
+
+/** Shortest rotation matrix taking direction u onto direction v (Rodrigues). */
+function rotationBetween(u, v) {
+	const lu = v3len(u);
+	const lv = v3len(v);
+	if (lu < 1e-9 || lv < 1e-9) return null;
+	const a = v3scale(u, 1 / lu);
+	const b = v3scale(v, 1 / lv);
+	const c = v3cross(a, b);
+	const d = v3dot(a, b);
+	const s2 = v3dot(c, c);
+	if (s2 < 1e-14) {
+		if (d > 0) return [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+		// opposite: 180 deg about any axis perpendicular to a
+		let axis = v3cross(a, [1, 0, 0]);
+		if (v3len(axis) < 1e-6) axis = v3cross(a, [0, 1, 0]);
+		const n = v3scale(axis, 1 / v3len(axis));
+		return [
+			[2 * n[0] * n[0] - 1, 2 * n[0] * n[1], 2 * n[0] * n[2]],
+			[2 * n[0] * n[1], 2 * n[1] * n[1] - 1, 2 * n[1] * n[2]],
+			[2 * n[0] * n[2], 2 * n[1] * n[2], 2 * n[2] * n[2] - 1],
+		];
+	}
+	const K = [
+		[0, -c[2], c[1]],
+		[c[2], 0, -c[0]],
+		[-c[1], c[0], 0],
+	];
+	const k = (1 - d) / s2;
+	const KK = matMul(K, K);
+	return [
+		[1 + K[0][0] + KK[0][0] * k, K[0][1] + KK[0][1] * k, K[0][2] + KK[0][2] * k],
+		[K[1][0] + KK[1][0] * k, 1 + K[1][1] + KK[1][1] * k, K[1][2] + KK[1][2] * k],
+		[K[2][0] + KK[2][0] * k, K[2][1] + KK[2][1] * k, 1 + K[2][2] + KK[2][2] * k],
+	];
+}
+
+/**
+ * Analytic 2-bone leg IK (research 11 §2: "hold the ankle world position and
+ * re-solve the two-bone leg chain"). Re-aims hip and knee so the ankle
+ * reaches `target`, keeps the knee's current bend plane, and leaves the
+ * foot's WORLD orientation untouched — a planted foot must not roll because
+ * the leg above it moved. Returns the new cskel27 LOCAL matrices, or null
+ * when the chain is degenerate.
+ */
+function solveLegIk(positions, worlds, leg, hipsIdx, target) {
+	const H = positions[leg.hip];
+	const K = positions[leg.knee];
+	const A = positions[leg.ankle];
+	const L1 = v3len(v3sub(K, H));
+	const L2 = v3len(v3sub(A, K));
+	if (L1 < 1e-4 || L2 < 1e-4) return null;
+	let d = v3len(v3sub(target, H));
+	const eps = 1e-3;
+	d = Math.max(Math.abs(L1 - L2) + eps, Math.min(L1 + L2 - eps, d));
+	if (d < 1e-4) return null;
+	const dir = v3scale(v3sub(target, H), 1 / v3len(v3sub(target, H)));
+	// Preserve the current bend plane: the knee keeps pointing the way it
+	// already points, projected off the new hip→ankle axis.
+	const hk = v3sub(K, H);
+	let bend = v3sub(hk, v3scale(dir, v3dot(hk, dir)));
+	if (v3len(bend) < 1e-6) {
+		bend = v3sub(matVec3(worlds[leg.hip], [0, 0, 1]), v3scale(dir, v3dot(matVec3(worlds[leg.hip], [0, 0, 1]), dir)));
+		if (v3len(bend) < 1e-6) return null;
+	}
+	bend = v3scale(bend, 1 / v3len(bend));
+	const a1 = (L1 * L1 - L2 * L2 + d * d) / (2 * d);
+	const h = Math.sqrt(Math.max(0, L1 * L1 - a1 * a1));
+	const newKnee = v3add(H, v3add(v3scale(dir, a1), v3scale(bend, h)));
+	const clampedTarget = v3add(H, v3scale(dir, d));
+
+	const hipDelta = rotationBetween(v3sub(K, H), v3sub(newKnee, H));
+	if (!hipDelta) return null;
+	const ankleAfterHip = v3add(newKnee, matVec3(hipDelta, v3sub(A, K)));
+	const kneeDelta = rotationBetween(v3sub(ankleAfterHip, newKnee), v3sub(clampedTarget, newKnee));
+	if (!kneeDelta) return null;
+
+	const hipGlobal = matMul(hipDelta, worlds[leg.hip]);
+	const kneeGlobal = matMul(kneeDelta, matMul(hipDelta, worlds[leg.knee]));
+	return {
+		hipLocal: matMul(matTranspose(worlds[hipsIdx]), hipGlobal),
+		kneeLocal: matMul(matTranspose(hipGlobal), kneeGlobal),
+		// the foot keeps its ORIGINAL world orientation under the new knee
+		ankleLocal: matMul(matTranspose(kneeGlobal), worlds[leg.ankle]),
+	};
+}
+
+/** Centred moving average over one interleaved component of a stride-3 track. */
+function smoothTrack(track, frames, component, window) {
+	const half = Math.floor(window / 2);
+	const source = new Float64Array(frames);
+	for (let f = 0; f < frames; f += 1) source[f] = track[f * 3 + component];
+	for (let f = 0; f < frames; f += 1) {
+		let sum = 0;
+		let count = 0;
+		for (let k = Math.max(0, f - half); k <= Math.min(frames - 1, f + half); k += 1) {
+			sum += source[k];
+			count += 1;
+		}
+		track[f * 3 + component] = sum / count;
+	}
+}
+
+
+function magnitude(v) {
+	return Math.hypot(v[0], v[1], v[2]);
+}
+
+function chainLength(positions, names) {
+	let total = 0;
+	for (let i = 1; i < names.length; i += 1) {
+		const a = positions[CSKEL27_JOINTS.indexOf(names[i - 1])];
+		const b = positions[CSKEL27_JOINTS.indexOf(names[i])];
+		total += Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+	}
+	return total;
+}