cozyclay 1.2.0 → 1.3.0

package/src/ardy/cskel27.js

@@ -62,7 +62,12 @@ export const COZYCLAY_BONES = [
 	"LeftFoot", "RightFoot",
 ];
 
-/** CozyClay bone name -> cskel27 joint index. */
+/** CozyClay/Mixamo bone name -> playback-equivalent cskel27 joint index.
+ * Core has one more torso segment, so its first animated spine joint is
+ * Spine1 and the Mixamo chest lands on Spine2. */
 export const COZYCLAY_TO_CSKEL27 = Object.fromEntries(
-	COZYCLAY_BONES.map((name) => [name, JOINT_INDEX[name]])
+	COZYCLAY_BONES.map((name) => [
+		name,
+		JOINT_INDEX[name === "Spine" ? "Spine1" : name === "Spine1" ? "Spine2" : name],
+	])
 );

package/src/ardy/ik.js

@@ -20,20 +20,20 @@ import { normalizeBoneName } from "../poses.js";
 /** The four IK chain handles, mapped to the timeline lanes of the same
  * names. */
 export const IK_TRACKS = [
-	{ id: "leftHand", label: "Left Hand", kind: "arm", side: "Left" },
-	{ id: "rightHand", label: "Right Hand", kind: "arm", side: "Right" },
-	{ id: "leftFoot", label: "Left Foot", kind: "leg", side: "Left" },
-	{ id: "rightFoot", label: "Right Foot", kind: "leg", side: "Right" },
+	{ id: "leftHand", label: "Left Hand", kind: "arm", side: "Left", visibilityDepth: 0.14 },
+	{ id: "rightHand", label: "Right Hand", kind: "arm", side: "Right", visibilityDepth: 0.14 },
+	{ id: "leftFoot", label: "Left Foot", kind: "leg", side: "Left", visibilityDepth: 0.14 },
+	{ id: "rightFoot", label: "Right Foot", kind: "leg", side: "Right", visibilityDepth: 0.14 },
 ];
 
 /** Mid-joint position handles: dragging repositions the elbow/knee with
  * BOTH ends pinned (shoulder+wrist / hip+ankle) — the classic mid-chain
  * handle. `chain` links to the IK chain whose bones it edits. */
 export const MID_TRACKS = [
-	{ id: "leftElbow", label: "Left Elbow", chain: "leftHand" },
-	{ id: "rightElbow", label: "Right Elbow", chain: "rightHand" },
-	{ id: "leftKnee", label: "Left Knee", chain: "leftFoot" },
-	{ id: "rightKnee", label: "Right Knee", chain: "rightFoot" },
+	{ id: "leftElbow", label: "Left Elbow", chain: "leftHand", visibilityDepth: 0.12 },
+	{ id: "rightElbow", label: "Right Elbow", chain: "rightHand", visibilityDepth: 0.12 },
+	{ id: "leftKnee", label: "Left Knee", chain: "leftFoot", visibilityDepth: 0.12 },
+	{ id: "rightKnee", label: "Right Knee", chain: "rightFoot", visibilityDepth: 0.12 },
 ];
 
 /** FK swing handles: dragging swings the part toward the pointer (rotation
@@ -42,15 +42,25 @@ export const MID_TRACKS = [
  * follow the FK PoseHandles coding: torso yellow, head purple, arms orange,
  * legs blue. */
 export const FK_TRACKS = [
-	{ id: "hips", label: "Hips", bone: "mixamorigHips", child: "mixamorigSpine", color: "#ffd23d" },
-	{ id: "spine", label: "Spine", bone: "mixamorigSpine", child: "mixamorigSpine1", color: "#ffd23d" },
-	{ id: "chest", label: "Chest", bone: "mixamorigSpine1", child: "mixamorigSpine2", color: "#ffd23d" },
-	{ id: "neck", label: "Neck", bone: "mixamorigNeck", child: "mixamorigHead", color: "#b98cff" },
-	{ id: "head", label: "Head", bone: "mixamorigHead", child: null, color: "#b98cff" },
-	{ id: "leftShoulder", label: "Left Shoulder", bone: "mixamorigLeftShoulder", child: "mixamorigLeftArm", color: "#ff8a3d" },
-	{ id: "rightShoulder", label: "Right Shoulder", bone: "mixamorigRightShoulder", child: "mixamorigRightArm", color: "#ff8a3d" },
+	{ id: "hips", label: "Hips", bone: "mixamorigHips", child: "mixamorigSpine", color: "#ffd23d", group: "torso", visibilityDepth: 0.34 },
+	{ id: "spine", label: "Spine", bone: "mixamorigSpine", child: "mixamorigSpine1", color: "#ffd23d", group: "torso", visibilityDepth: 0.32 },
+	{ id: "chest", label: "Chest", bone: "mixamorigSpine1", child: "mixamorigSpine2", color: "#ffd23d", group: "torso", visibilityDepth: 0.3 },
+	{ id: "neck", label: "Neck", bone: "mixamorigNeck", child: "mixamorigHead", color: "#b98cff", group: "head", visibilityDepth: 0.2 },
+	{ id: "head", label: "Head", bone: "mixamorigHead", child: null, color: "#b98cff", group: "head", visibilityDepth: 0.24 },
+	{ id: "leftShoulder", label: "Left Shoulder", bone: "mixamorigLeftShoulder", child: "mixamorigLeftArm", color: "#ff8a3d", group: "shoulder", visibilityDepth: 0.2 },
+	{ id: "rightShoulder", label: "Right Shoulder", bone: "mixamorigRightShoulder", child: "mixamorigRightArm", color: "#ff8a3d", group: "shoulder", visibilityDepth: 0.2 },
 ];
 
+/** Whether a control centre is close enough to the first visible surface.
+ * Centreline controls (torso/head) intentionally have larger allowances than
+ * side-specific limbs, so front-facing body controls remain available while
+ * the far shoulder/arm/leg is rejected. */
+export function ikControlIsExposed(targetDistance, blockerDistance, visibilityDepth) {
+	if (!Number.isFinite(targetDistance) || targetDistance <= 0) return false;
+	if (!Number.isFinite(blockerDistance)) return true;
+	return targetDistance - blockerDistance <= visibilityDepth;
+}
+
 /** Bone chains per handle, root → effector. Mixamo spelling; the matcher
  * accepts the `mixamorig:` prefix and prefix-less rigs. Shoulder stays out of
  * the arm chain — clavicle rotation swings the whole shoulder mass and reads

package/src/ardy/npz.js

@@ -32,6 +32,12 @@ const FPS_MAX = 240; // matches CozyClay motion_retarget.FPS_BOUNDS
 // Same tolerance motion_retarget uses for squared row/column norms, pairwise
 // dots, and determinant; float32 serialization noise sits far below 1e-3.
 const ROTATION_MATRIX_TOLERANCE = 1e-3;
+// Bounds on the stature a take may ask the character to take on. The estimate
+// is a ratio of leg lengths measured off a video, so a bad detection must
+// never be able to produce a giant or a gnome; the clamp lives next to the
+// decode because that is where the number enters the app.
+export const CHARACTER_SCALE_MIN = 0.6;
+export const CHARACTER_SCALE_MAX = 1.5;
 
 const ZIP_EOCD_SIG = 0x06054b50;
 const ZIP_CENTRAL_SIG = 0x02014b50;
@@ -345,6 +351,25 @@ function scalarIntOf(parsed, label) {
 	return value;
 }
 
+/** scalar float value (person_scale); returns Number. An integer member is
+ *  accepted too, so a writer that stored a whole-number scale still reads. */
+function scalarFloatOf(parsed, label) {
+	if (parsed.kind === "i" || parsed.kind === "u") return scalarIntOf(parsed, label);
+	if (parsed.kind !== "f") {
+		throw new NpzError(`${label} must be a float scalar, got descr kind '${parsed.kind}'`);
+	}
+	if (parsed.shape.length > 1 || (parsed.shape.length === 1 && parsed.shape[0] !== 1)) {
+		throw new NpzError(`${label} must be a scalar (shape () or (1,)), got shape (${parsed.shape.join(", ")})`);
+	}
+	const view = new DataView(parsed.data.buffer, parsed.data.byteOffset, parsed.data.byteLength);
+	let value;
+	if (parsed.itemsize === 4) value = view.getFloat32(0, parsed.littleEndian);
+	else if (parsed.itemsize === 8) value = view.getFloat64(0, parsed.littleEndian);
+	else throw new NpzError(`${label} has unsupported float itemsize ${parsed.itemsize}`);
+	if (!Number.isFinite(value)) throw new NpzError(`${label} is not a finite number`);
+	return value;
+}
+
 /** Validate one 3x3 matrix: finite, orthonormal rows/columns, det +1. */
 function checkRotationMatrix(rows, frame, joint) {
 	const columns = [
@@ -383,12 +408,19 @@ function checkRotationMatrix(rows, frame, joint) {
 /**
  * Decode an ARDY motion npz from raw bytes.
  *
- * Returns { frames, fps, rotMats, rootPos, posedJoints } with `rotMats` a
+ * Returns { frames, fps, personScale, rotMats, rootPos, posedJoints } with `rotMats` a
  * Float32Array of frames*27*9 row-major 3x3 matrices (cskel27 joint order),
  * `rootPos` a Float32Array of frames*3 (x, y, z) ARDY-world root positions,
  * and `posedJoints` a Float32Array of frames*27*3 ARDY-world joint
  * positions (the positional-skinning reference — playback.js drives bone
  * positions straight from it). Throws NpzError on anything malformed.
+ *
+ * `personScale` is the filmed performer's stature relative to the canonical
+ * body, carried by the optional `person_scale` member. The extraction divided
+ * the root translation by it, so applying the frames without applying the
+ * scale exaggerates every stride — the two must move together. An archive
+ * without the member (an ARDY-generated take, or one written before the
+ * member existed) reports 1: canonical body, unscaled travel.
  */
 export async function decodeMotionNpz(bytes) {
 	if (bytes.byteLength > MAX_ARCHIVE_BYTES) {
@@ -401,9 +433,12 @@ export async function decodeMotionNpz(bytes) {
 	const names = ["local_rot_mats.npy", "root_positions.npy", "fps.npy", "posed_joints.npy"];
 	const missing = names.filter((n) => !entries.has(n));
 	if (missing.length) throw new NpzError(`motion npz is missing members: ${missing.join(", ")}`);
+	// person_scale is optional: only a filmed take has a performer to measure,
+	// and archives predating the member are still valid motions.
+	const read = [...names, ...(entries.has("person_scale.npy") ? ["person_scale.npy"] : [])];
 
 	const members = {};
-	for (const name of names) {
+	for (const name of read) {
 		const entry = entries.get(name);
 		if (entry.uncompSize > MAX_MEMBER_BYTES) {
 			throw new NpzError(`motion npz member ${name} decompresses to ${entry.uncompSize} bytes, over the ${MAX_MEMBER_BYTES} byte cap`);
@@ -449,6 +484,13 @@ export async function decodeMotionNpz(bytes) {
 	if (fps < FPS_MIN || fps > FPS_MAX) {
 		throw new NpzError(`motion fps ${fps} is outside ${FPS_MIN}..${FPS_MAX}`);
 	}
+	let personScale = 1;
+	if (members["person_scale.npy"]) {
+		personScale = scalarFloatOf(parseNpyMember(members["person_scale.npy"], "person_scale"), "person_scale");
+		// A stored zero or negative would mirror the trajectory or collapse the
+		// body; that is corrupt data, not a scale to clamp into range.
+		if (!(personScale > 0)) throw new NpzError(`motion person_scale ${personScale} must be positive`);
+	}
 
 	const rotMats = float32Of(rotParsed, "local_rot_mats");
 	const rootPos = float32Of(posParsed, "root_positions");
@@ -482,7 +524,26 @@ export async function decodeMotionNpz(bytes) {
 		if (!Number.isFinite(posedJoints[i])) throw new NpzError(`motion npz posed_joints contains a non-finite value at index ${i}`);
 	}
 
-	return { frames, fps, rotMats, rootPos, posedJoints };
+	return { frames, fps, personScale, rotMats, rootPos, posedJoints };
+}
+
+/**
+ * The character scale a decoded take implies, clamped to the sane stature
+ * band. THE INVARIANT: a take's root travel was authored against this scale,
+ * so every path that applies a motion must apply this too — leaving them apart
+ * is what makes a filmed stride overshoot and the feet slide.
+ *
+ * `fallback` is for a take whose npz predates the member but whose scale
+ * arrived some other way (the extraction response). No scale anywhere means
+ * canonical: 1.
+ */
+export function characterScaleFor(motion, fallback = 1) {
+	const raw = Number.isFinite(motion?.personScale) && motion.personScale > 0
+		? motion.personScale
+		: Number.isFinite(fallback) && fallback > 0
+			? fallback
+			: 1;
+	return Math.max(CHARACTER_SCALE_MIN, Math.min(CHARACTER_SCALE_MAX, raw));
 }
 
 /**

package/src/ardy/playback.js

@@ -35,6 +35,8 @@
  * HandEnd leaves drive no bone — their motion folds into the mapped joints'
  * global transforms, and HeadTop_End/Toe_End/finger bones simply follow
  * their parents). Bones the map does not touch keep their bind transforms.
+ * Shoulder and arm chains keep their Mixamo bind translations and consume
+ * ARDY rotations only, avoiding clavicle shear between incongruent rigs.
  */
 
 import * as THREE from "three";
@@ -76,6 +78,18 @@ const SKINNING_MAP = CSKEL27_JOINTS.map((name) => {
 	}
 });
 
+// CoreSkeleton27 and the Mixamo bots are not congruent around the clavicles:
+// their neutral shoulder directions differ by about 30 degrees. Positional
+// skinning therefore moves the arm root away from the direction encoded by
+// the parent bone's rotation and visibly shears the shoulder. Keep the
+// Mixamo arm chains' authored local translations and retarget rotations only;
+// the rest of the body still uses ARDY positional skinning for root motion
+// and foot placement.
+const HIERARCHY_PRESERVED_JOINTS = new Set([
+	"RightShoulder", "RightArm", "RightForeArm",
+	"LeftShoulder", "LeftArm", "LeftForeArm",
+]);
+
 const ARDY_NEUTRAL_MIN_Y = -0.9544128; // toe depth under the hips-origin neutral pose
 
 /* No finger forcing: ARDY's cskel27 stops at the wrist, and the fingers
@@ -160,6 +174,7 @@ function prepOf(rig) {
 	const bindPos = new Array(CSKEL27_JOINTS.length).fill(null);
 	const bindQuat = new Array(CSKEL27_JOINTS.length).fill(null);
 	const bindScale = new Array(CSKEL27_JOINTS.length).fill(null);
+	const bindLocalPos = new Array(CSKEL27_JOINTS.length).fill(null);
 	const parentBindWorld = new Array(CSKEL27_JOINTS.length).fill(null);
 	for (let j = 0; j < CSKEL27_JOINTS.length; j += 1) {
 		const mixamoName = SKINNING_MAP[j];
@@ -171,6 +186,7 @@ function prepOf(rig) {
 		bindPos[j] = new THREE.Vector3().setFromMatrixPosition(world);
 		bindQuat[j] = new THREE.Quaternion().setFromRotationMatrix(world);
 		bindScale[j] = bone.scale.clone();
+		bindLocalPos[j] = bone.position.clone();
 		parentBindWorld[j] = worldByNode.get(bone.parent) ?? new THREE.Matrix4();
 	}
 
@@ -228,7 +244,17 @@ function prepOf(rig) {
 		}
 	}
 
-	prep = { bones, bindQuat, bindScale, parentBindWorld, chainParent, chainRel, scale, offsets };
+	prep = {
+		bones,
+		bindQuat,
+		bindScale,
+		bindLocalPos,
+		parentBindWorld,
+		chainParent,
+		chainRel,
+		scale,
+		offsets,
+	};
 	rigPreps.set(rig, prep);
 	return prep;
 }
@@ -373,6 +399,10 @@ export function applyMotionFrame(rig, motion, frame) {
 			mParentInv.copy(prep.parentBindWorld[j]);
 		}
 
+		if (HIERARCHY_PRESERVED_JOINTS.has(CSKEL27_JOINTS[j])) {
+			vWorld.copy(prep.bindLocalPos[j]).applyMatrix4(mParentInv);
+		}
+
 		mWorld.compose(vWorld, qWorld, prep.bindScale[j]);
 		desiredWorld[j] = mWorld.clone();
 		mLocal.copy(mParentInv).invert().multiply(mWorld);

package/src/ardy/prompt-clips.js

@@ -1,6 +1,11 @@
-/** Move one prompt clip on the fixed ARDY block grid without changing its
+/** Move one prompt clip on the fixed prompt-block grid without changing its
  * duration. Overlaps are rejected because segment generation needs one prompt
- * per frame range; gaps remain valid and inherit the main prompt. */
+ * per frame range; gaps remain valid and inherit the main prompt.
+ *
+ * Clock-agnostic: `blockFrames` is the caller's grid, and App.jsx always
+ * passes ARDY_PROMPT_HORIZON_FRAMES (2 s on the 24 fps timeline clock = 48).
+ * The 40 default is only the bare-call fallback and means nothing on the
+ * wire — nothing here ever reaches the bridge unconverted. */
 export function movePromptClipFrames(clips, id, rawStartFrame, blockFrames = 40) {
 	const target = clips.find((clip) => clip.id === id);
 	if (!target) return clips;

package/src/ardy/retime.js

@@ -0,0 +1,211 @@
+// retime.js — duration-preserving resample of a decoded motion between frame
+// clocks. ARDY Core generates on its trained 20 fps clock, filmed takes arrive
+// at 30 or 60; the app timeline runs the production 24 fps one. A 20 fps take
+// counted against a 24 fps reference reads 1.2× fast, so inbound takes are
+// resampled here: rotations slerp between neighbouring source frames, the root
+// lerps, frame 0 stays identical, and the clip's length in seconds does not
+// move — only how densely it is sampled.
+//
+// World joint positions are NOT interpolated. A slerped rotation walks the arc
+// between two frames while a lerped position cuts the chord, so the two used to
+// disagree at every blended frame — and since most 24 fps frames land between
+// source frames, that disagreement was phase-locked to the resample (a 6 Hz
+// pulse from 30 fps, alternating frames from 60). Playback drives bone.position
+// straight from posedJoints, so on screen the shin visibly shortened by up to
+// 2.6 cm and sprang back: the trembling feet. Positions are regenerated by
+// forward kinematics from the retimed rotations instead, which makes constant
+// bone length a property of the output rather than a hope.
+
+import { CSKEL27_JOINTS } from "./cskel27.js";
+import { deriveBoneOffsets, forwardKinematics, matToQuat, quatToMat } from "./convert.js";
+import { canonicalCskel27Reference } from "./to-cskel27.js";
+
+/** w-first quaternion slerp with hemisphere correction; falls back to a
+ *  normalised lerp when the arc is too small for a stable sine. Shared with
+ *  the bridge's BVH conversion (torso stabilization, root-spin repair). */
+export function slerpQuat(a, b, t) {
+	let dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+	const sign = dot < 0 ? -1 : 1;
+	dot *= sign;
+	let wa;
+	let wb;
+	if (dot > 0.9995) {
+		wa = 1 - t;
+		wb = t;
+	} else {
+		const theta = Math.acos(Math.min(1, dot));
+		const sinTheta = Math.sin(theta);
+		wa = Math.sin((1 - t) * theta) / sinTheta;
+		wb = Math.sin(t * theta) / sinTheta;
+	}
+	const out = [
+		a[0] * wa + b[0] * sign * wb,
+		a[1] * wa + b[1] * sign * wb,
+		a[2] * wa + b[2] * sign * wb,
+		a[3] * wa + b[3] * sign * wb,
+	];
+	const norm = Math.hypot(...out);
+	return out.map((component) => component / norm);
+}
+
+function readMat(flat, offset) {
+	return [
+		[flat[offset], flat[offset + 1], flat[offset + 2]],
+		[flat[offset + 3], flat[offset + 4], flat[offset + 5]],
+		[flat[offset + 6], flat[offset + 7], flat[offset + 8]],
+	];
+}
+
+function writeMat(flat, offset, m) {
+	flat[offset] = m[0][0]; flat[offset + 1] = m[0][1]; flat[offset + 2] = m[0][2];
+	flat[offset + 3] = m[1][0]; flat[offset + 4] = m[1][1]; flat[offset + 5] = m[1][2];
+	flat[offset + 6] = m[2][0]; flat[offset + 7] = m[2][1]; flat[offset + 8] = m[2][2];
+}
+
+const JOINTS = CSKEL27_JOINTS.length;
+
+// Bone lengths are a property of the skeleton, not of the frame, so the offsets
+// are derived once for the module rather than per take or per frame. Same
+// pairing the BVH bridge uses (tools/ardy/bvh-cskel27.mjs): the canonical
+// cskel27 reference, not a clip's frame zero, so a take whose first frame is
+// noisy cannot smear its noise across the whole clip's proportions.
+const BONE_OFFSETS = (() => {
+	const skeleton = canonicalCskel27Reference();
+	return deriveBoneOffsets(skeleton.posed_joints, skeleton.local_rot_mats);
+})();
+
+// Above this (in npz metres) a take's own posedJoints are not the forward
+// kinematics of its own rotations, so regenerating them would move the take
+// rather than repair it. Measured across every take in tools/ardy/out — filmed
+// extractions and ARDY-generated clips alike — the residual is at most 1e-6 m,
+// pure float32 serialization noise, so 1e-4 m sits 100x above the honest floor
+// and far below any disagreement worth calling one.
+const FK_CONSISTENCY_TOLERANCE = 1e-4;
+
+// The 27 local rotations of one frame, as the nested matrices convert.js takes.
+function readLocals(flat, frame) {
+	const locals = new Array(JOINTS);
+	for (let j = 0; j < JOINTS; j += 1) locals[j] = readMat(flat, (frame * JOINTS + j) * 9);
+	return locals;
+}
+
+/**
+ * Does this take's posedJoints already agree with FK of its own rotations?
+ * Sampled rather than exhaustive: an inconsistent take is inconsistent by
+ * construction (wrong proportions, hand-authored positions, a legacy writer),
+ * not on one unlucky frame, and the check must not cost a second FK sweep.
+ */
+function posedJointsFollowRotations(motion) {
+	const step = Math.max(1, Math.floor(motion.frames / 16));
+	for (let f = 0; f < motion.frames; f += step) {
+		const positions = forwardKinematics(
+			readLocals(motion.rotMats, f),
+			BONE_OFFSETS,
+			[motion.rootPos[f * 3], motion.rootPos[f * 3 + 1], motion.rootPos[f * 3 + 2]]
+		);
+		for (let j = 0; j < JOINTS; j += 1) {
+			const p = (f * JOINTS + j) * 3;
+			const dx = positions[j][0] - motion.posedJoints[p];
+			const dy = positions[j][1] - motion.posedJoints[p + 1];
+			const dz = positions[j][2] - motion.posedJoints[p + 2];
+			if (Math.hypot(dx, dy, dz) > FK_CONSISTENCY_TOLERANCE) return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * Resample `{ frames, fps, rotMats, rootPos, posedJoints, ... }` onto
+ * `targetFps`. Every other field rides through untouched (`personScale`
+ * included — changing the sampling clock does not change how big the filmed
+ * performer was), except a present `anchorFrame`, which is rescaled onto the
+ * new clock. Same-rate input is
+ * returned as-is — retiming is never a copy for its own sake.
+ *
+ * `posedJoints` comes out of forward kinematics on the retimed rotations, so
+ * every bone keeps its length exactly. The one exception is a take whose own
+ * posedJoints do not already follow its own rotations: there the positions are
+ * the authority and FK would move the take rather than repair it, so those
+ * lerp between source frames as before. Nothing in tools/ardy/out is such a
+ * take; the branch exists so a legacy or hand-built one is not rewritten.
+ */
+export function retimeMotion(motion, targetFps) {
+	if (!motion || !Number.isFinite(motion.fps) || motion.fps <= 0) {
+		throw new Error("retimeMotion: motion.fps must be a positive finite number");
+	}
+	if (!Number.isFinite(targetFps) || targetFps <= 0) {
+		throw new Error("retimeMotion: targetFps must be a positive finite number");
+	}
+	if (motion.fps === targetFps) return motion;
+	const srcFrames = motion.frames;
+	if (!Number.isInteger(srcFrames) || srcFrames < 1) {
+		throw new Error("retimeMotion: motion.frames must be a positive integer");
+	}
+	const ratio = targetFps / motion.fps;
+	const frames = Math.max(1, Math.round(srcFrames * ratio));
+	const rotMats = new Float32Array(frames * JOINTS * 9);
+	const rootPos = new Float32Array(frames * 3);
+	const posedJoints = new Float32Array(frames * JOINTS * 3);
+	const regenerate = posedJointsFollowRotations(motion);
+
+	for (let f = 0; f < frames; f += 1) {
+		const s = f / ratio;
+		const i0 = Math.min(Math.floor(s), srcFrames - 1);
+		const i1 = Math.min(i0 + 1, srcFrames - 1);
+		const t = Math.min(Math.max(s - i0, 0), 1);
+		const exact = t === 0 || i0 === i1;
+
+		for (let j = 0; j < JOINTS; j += 1) {
+			const src0 = (i0 * JOINTS + j) * 9;
+			const dst = (f * JOINTS + j) * 9;
+			if (exact) {
+				for (let k = 0; k < 9; k += 1) rotMats[dst + k] = motion.rotMats[src0 + k];
+			} else {
+				const src1 = (i1 * JOINTS + j) * 9;
+				const q = slerpQuat(
+					matToQuat(readMat(motion.rotMats, src0)),
+					matToQuat(readMat(motion.rotMats, src1)),
+					t
+				);
+				writeMat(rotMats, dst, quatToMat(q));
+			}
+		}
+		for (let axis = 0; axis < 3; axis += 1) {
+			rootPos[f * 3 + axis] =
+				motion.rootPos[i0 * 3 + axis] * (1 - t) + motion.rootPos[i1 * 3 + axis] * t;
+		}
+
+		if (regenerate) {
+			// The root is the only position left in the interpolation; every joint
+			// below it is placed rigidly off the retimed rotations, which is what
+			// keeps bone lengths out of the blend entirely.
+			const positions = forwardKinematics(readLocals(rotMats, f), BONE_OFFSETS, [
+				rootPos[f * 3],
+				rootPos[f * 3 + 1],
+				rootPos[f * 3 + 2],
+			]);
+			for (let j = 0; j < JOINTS; j += 1) {
+				const pd = (f * JOINTS + j) * 3;
+				posedJoints[pd] = positions[j][0];
+				posedJoints[pd + 1] = positions[j][1];
+				posedJoints[pd + 2] = positions[j][2];
+			}
+		} else {
+			for (let j = 0; j < JOINTS; j += 1) {
+				const p0 = (i0 * JOINTS + j) * 3;
+				const p1 = (i1 * JOINTS + j) * 3;
+				const pd = (f * JOINTS + j) * 3;
+				for (let axis = 0; axis < 3; axis += 1) {
+					posedJoints[pd + axis] =
+						motion.posedJoints[p0 + axis] * (1 - t) + motion.posedJoints[p1 + axis] * t;
+				}
+			}
+		}
+	}
+
+	const retimed = { ...motion, frames, fps: targetFps, rotMats, rootPos, posedJoints };
+	if (Number.isFinite(motion.anchorFrame)) {
+		retimed.anchorFrame = Math.min(frames - 1, Math.round(motion.anchorFrame * ratio));
+	}
+	return retimed;
+}

package/src/ardy/timeline-coordinates.js

@@ -16,6 +16,19 @@ export function promptMoveStartFrame(startFrame, startClientX, clientX, laneWidt
 	return startFrame + (clientX - startClientX) * framesPerPixel;
 }
 
+/** Half a second at 24 fps: a shorter take is a pose, not a motion. */
+export const TRIM_MIN_FRAMES = 12;
+
+/** Clamp one trim-handle drag of the loaded take into a legal in/out range.
+ * `preview` is the range the gesture currently shows, `frame` the frame under
+ * the pointer and `max` the take's last displayed frame. The opposite edge
+ * never moves, and the remaining take never drops below `minFrames`. */
+export function motionTrimRange(edge, frame, preview, max, minFrames = TRIM_MIN_FRAMES) {
+	return edge === "start"
+		? { ...preview, start: Math.max(0, Math.min(frame, preview.end - minFrames)) }
+		: { ...preview, end: Math.min(max, Math.max(frame, preview.start + minFrames)) };
+}
+
 /** Optional Shot blocks use their own explicit inclusive range. Gaps remain
  * visible free-camera time instead of being inferred from the next card. */
 export function shotBlockGeometry(shots, index, frameCount, displayFrameCount = frameCount) {