cozyclay 1.0.0

package/src/ardy/to-cskel27.js

@@ -0,0 +1,205 @@
+/**
+ * CozyClayPoseV1 -> the two npz arrays cclay_constrained_generate.load_poses
+ * reads (local_rot_mats 27x3x3, posed_joints 27x3; the generator then runs its
+ * own FK, consulting only posed_joints[0] as the root).
+ *
+ * The 19 joints CozyClay authors map through each bone's armature-space rest
+ * rotation Rb (cskel27-rest.json): L = Rb @ basis @ Rb^T. The other 8 joints
+ * get identity, i.e. "at ARDY rest" — CozyClay does not author them and must
+ * not invent them; `filled_identity` says which joints that happened for and
+ * why, so callers can report it rather than guess.
+ *
+ * Proportions are never hardcoded: bone offsets come from the reference frame
+ * of the same base clip the pose will constrain (mirroring
+ * motion_constraints.derive_bone_offsets), and the root rides on that frame's
+ * own root. If ARDY ever reproportions cskel27, the clip proportions stay
+ * correct by construction.
+ */
+
+import { COZYCLAY_BONES, CSKEL27_JOINTS } from "./cskel27.js";
+import { CSKEL27_NEUTRAL } from "./cskel27-neutral.js";
+import {
+	basisQuaternionToLocalRotation,
+	deriveBoneOffsets,
+	forwardKinematics,
+} from "./convert.js";
+
+// Tolerance on |norm - 1| for pose quaternions, and on orthonormality /
+// determinant for emitted matrices. Float32-serialized source data is off by
+// ~1e-7 at worst, so 1e-6 is comfortably above input noise while still
+// catching real corruption.
+const UNIT_TOLERANCE = 1e-6;
+
+const IDENTITY = [
+	[1, 0, 0],
+	[0, 1, 0],
+	[0, 0, 1],
+];
+
+const CANONICAL_ROOT_Y = -Math.min(...CSKEL27_NEUTRAL.map((joint) => joint[1]));
+
+/** Floor-aligned CoreSkeleton27 reference used when no clip reference is
+ * supplied. A generated motion is not a skeleton definition: borrowing its
+ * frame-zero root made a rolling clip lower every authored pose by 10 cm.
+ * The neutral skeleton is stable, deterministic, and keeps both toes at Y=0. */
+export function canonicalCskel27Reference() {
+	return {
+		local_rot_mats: CSKEL27_JOINTS.map(() => IDENTITY.map((row) => row.slice())),
+		posed_joints: CSKEL27_NEUTRAL.map(([x, y, z]) => [x, y + CANONICAL_ROOT_Y, z]),
+	};
+}
+
+function isFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+function determinant3(m) {
+	return (
+		m[0][0] * (m[1][1] * m[2][2] - m[1][2] * m[2][1]) -
+		m[0][1] * (m[1][0] * m[2][2] - m[1][2] * m[2][0]) +
+		m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0])
+	);
+}
+
+function requireUnitQuaternion(q, bone) {
+	if (!Array.isArray(q) || q.length !== 4 || !q.every(isFiniteNumber)) {
+		throw new Error(
+			`poseToCskel27: bone "${bone}" is not a [w, x, y, z] quaternion of four finite numbers`
+		);
+	}
+	const norm = Math.hypot(q[0], q[1], q[2], q[3]);
+	if (Math.abs(norm - 1) > UNIT_TOLERANCE) {
+		throw new Error(
+			`poseToCskel27: bone "${bone}" is not a unit quaternion (norm ${norm})`
+		);
+	}
+}
+
+// A matrix must stay inside the rotation group: rows orthonormal (unit
+// length, pairwise orthogonal) and right-handed.
+function requireRotationMatrix(m, label) {
+	for (let i = 0; i < 3; i += 1) {
+		const row = m[i];
+		const normSq = row[0] * row[0] + row[1] * row[1] + row[2] * row[2];
+		if (Math.abs(normSq - 1) > UNIT_TOLERANCE) {
+			throw new Error(
+				`poseToCskel27: ${label} is not orthonormal (row ${i} has squared length ${normSq})`
+			);
+		}
+		for (let j = i + 1; j < 3; j += 1) {
+			const other = m[j];
+			const dot = row[0] * other[0] + row[1] * other[1] + row[2] * other[2];
+			if (Math.abs(dot) > UNIT_TOLERANCE) {
+				throw new Error(
+					`poseToCskel27: ${label} is not orthonormal (rows ${i} and ${j} dot to ${dot})`
+				);
+			}
+		}
+	}
+	const det = determinant3(m);
+	if (Math.abs(det - 1) > UNIT_TOLERANCE) {
+		throw new Error(`poseToCskel27: ${label} has determinant ${det}, not +1`);
+	}
+}
+
+/**
+ * Convert a CozyClayPoseV1 into the frame arrays the ARDY generator expects.
+ * `rest` is the parsed public/ardy/cskel27-rest.json, `reference` a parsed
+ * ardy.frame.v1 fixture from the base motion the pose will constrain.
+ * Returns { local_rot_mats, posed_joints, filled_identity }.
+ */
+export function poseToCskel27({ pose, rest, reference }) {
+	if (!pose || typeof pose !== "object") {
+		throw new Error(
+			`poseToCskel27: pose is ${pose === null ? "null" : typeof pose}, expected an object`
+		);
+	}
+	if (pose.schema !== "cozyclay.pose.v1") {
+		throw new Error(
+			`poseToCskel27: unsupported pose schema ${JSON.stringify(pose.schema)} — expected "cozyclay.pose.v1"`
+		);
+	}
+	if (!pose.bones || typeof pose.bones !== "object" || Array.isArray(pose.bones)) {
+		throw new Error("poseToCskel27: pose.bones must be an object keyed by mixamo bone name");
+	}
+	if (pose.root !== undefined) {
+		if (!Array.isArray(pose.root) || pose.root.length !== 3 || !pose.root.every(isFiniteNumber)) {
+			throw new Error("poseToCskel27: pose.root must be [x, y, z] finite metres when present");
+		}
+	}
+
+	// Every joint CozyClay authors must be present and a unit quaternion.
+	for (const bone of COZYCLAY_BONES) {
+		if (!(bone in pose.bones)) {
+			throw new Error(`poseToCskel27: pose.bones is missing "${bone}"`);
+		}
+		requireUnitQuaternion(pose.bones[bone], bone);
+	}
+
+	if (!rest || !Array.isArray(rest.joints)) {
+		throw new Error("poseToCskel27: rest must be parsed cskel27-rest.json with a joints array");
+	}
+	const restByJoint = new Map();
+	for (const entry of rest.joints) {
+		if (!entry || typeof entry.name !== "string") {
+			throw new Error("poseToCskel27: rest.joints entries must carry a string name");
+		}
+		if (entry.rest !== null) {
+			if (
+				!Array.isArray(entry.rest) ||
+				entry.rest.length !== 3 ||
+				!entry.rest.every(
+					(row) => Array.isArray(row) && row.length === 3 && row.every(isFiniteNumber)
+				)
+			) {
+				throw new Error(
+					`poseToCskel27: rest for "${entry.name}" is neither null nor a 3x3 finite matrix`
+				);
+			}
+		}
+		restByJoint.set(entry.name, entry.rest);
+	}
+
+	const authored = new Set(COZYCLAY_BONES);
+	const local_rot_mats = new Array(CSKEL27_JOINTS.length);
+	const filled_identity = [];
+	for (let index = 0; index < CSKEL27_JOINTS.length; index += 1) {
+		const name = CSKEL27_JOINTS[index];
+		const rb = restByJoint.get(name);
+		if (authored.has(name) && rb !== null && rb !== undefined) {
+			// L = Rb @ basis @ Rb^T; basisQuaternionToLocalRotation is the
+			// quatToMat + basisToLocal composition from convert.js.
+			local_rot_mats[index] = basisQuaternionToLocalRotation(pose.bones[name], rb);
+		} else {
+			// Fresh identity per joint so callers can never alias a shared
+			// constant by mutating one row.
+			local_rot_mats[index] = IDENTITY.map((row) => row.slice());
+			filled_identity.push({
+				joint: name,
+				reason: authored.has(name) ? "no rest rotation" : "not authored",
+			});
+		}
+	}
+
+	// Every emitted matrix must be a real rotation.
+	for (let index = 0; index < CSKEL27_JOINTS.length; index += 1) {
+		requireRotationMatrix(
+			local_rot_mats[index],
+			`${CSKEL27_JOINTS[index]} (local_rot_mats[${index}])`
+		);
+	}
+
+	// A reference may still supply different skeleton proportions, but its
+	// frame-zero root is never copied. Placement is authored explicitly in
+	// pose.root; otherwise the canonical floor-aligned neutral root is used.
+	// This decouples body shape from whichever motion happened to be selected.
+	const skeleton = reference ?? canonicalCskel27Reference();
+	if (!Array.isArray(skeleton.posed_joints) || !Array.isArray(skeleton.local_rot_mats)) {
+		throw new Error("poseToCskel27: reference must carry posed_joints and local_rot_mats");
+	}
+	const offsets = deriveBoneOffsets(skeleton.posed_joints, skeleton.local_rot_mats);
+	const canonicalRoot = canonicalCskel27Reference().posed_joints[0];
+	const posed_joints = forwardKinematics(local_rot_mats, offsets, pose.root ?? canonicalRoot);
+
+	return { local_rot_mats, posed_joints, filled_identity };
+}

package/src/ardy/waypoints.js

@@ -0,0 +1,364 @@
+const cleanZero = (value) => (Object.is(value, -0) || Math.abs(value) < 1e-9 ? 0 : value);
+
+/**
+ * ARDY root constraints live in the actor's clip-local coordinates. CozyClay's
+ * plan uses scene-world coordinates and rotates Subject 1 as a scene object, so
+ * both translation and actor yaw must be removed before generation. Playback
+ * applies the exact inverse transform when it places the generated root.
+ */
+export function toArdyWaypoints(waypoints, actorRotationDeg = 0) {
+	if (!waypoints.length) return [];
+	const origin = waypoints[0];
+	const yaw = (actorRotationDeg * Math.PI) / 180;
+	const cos = Math.cos(yaw);
+	const sin = Math.sin(yaw);
+	return waypoints.map((waypoint) => {
+		const worldX = waypoint.x - origin.x;
+		const worldZ = waypoint.z - origin.z;
+		return {
+			frame: waypoint.frame,
+			x: cleanZero(cos * worldX - sin * worldZ),
+			z: cleanZero(sin * worldX + cos * worldZ),
+			heading: waypoint.heading ?? null,
+		};
+	});
+}
+/**
+ * Densify an authored root path for ARDY motion generation: rebase to
+ * clip-local coordinates exactly like toArdyWaypoints, interpolate on the
+ * authored polyline, and emit one sample roughly every `spacing` frames
+ * (capped at maxPoints). Authored frames are always kept, the first
+ * sample is always frame 0, and frames are strictly ascending without
+ * duplicates. The spacing is deliberately loose: a sample every 2-3
+ * frames rails the root so hard the model gives up its gait cadence and
+ * ice-skates; ~0.4 s between position pins leaves room for real steps
+ * while the interpolated headings still steer the facing.
+ * Each sample heading is the path tangent (central difference between
+ * neighbors; adjacent-segment direction at the ends), carried forward
+ * through stalls shorter than 1e-6 and 0 when the whole path is
+ * stationary; headings are always finite numbers in [-2π, 2π].
+ */
+export function densifyArdyWaypoints(waypoints, actorRotationDeg = 0, maxPoints = 32, spacing = 8) {
+	if (waypoints.length < 2) return [];
+	const local = toArdyWaypoints(waypoints, actorRotationDeg);
+
+	// Authored frames and positions, deduplicated: these are the
+	// interpolation endpoints every sample set must contain.
+	const authored = [];
+	for (const point of local) {
+		if (authored.length === 0 || authored[authored.length - 1].frame !== point.frame) {
+			authored.push({ frame: point.frame, x: point.x, z: point.z });
+		}
+	}
+	if (authored.length === 1) {
+		return [{ frame: authored[0].frame, x: authored[0].x, z: authored[0].z, heading: 0 }];
+	}
+
+	const denseCount = authored[authored.length - 1].frame - authored[0].frame + 1;
+	const limit = Math.max(0, Math.floor(maxPoints));
+	const gapSpacing = Math.max(1, Math.floor(spacing));
+	// One filler per started `spacing` chunk beyond the first, per gap.
+	let spacingExtra = 0;
+	for (let i = 0; i < authored.length - 1; i += 1) {
+		spacingExtra += Math.max(0, Math.ceil((authored[i + 1].frame - authored[i].frame) / gapSpacing) - 1);
+	}
+	const extra = Math.max(0, Math.min(limit, denseCount, authored.length + spacingExtra) - authored.length);
+
+	// Distribute the extra samples across the gaps between authored frames
+	// in proportion to gap length (largest remainder), so spacing stays
+	// uniform while authored frames are always kept.
+	const gaps = [];
+	for (let i = 0; i < authored.length - 1; i += 1) {
+		gaps.push(authored[i + 1].frame - authored[i].frame);
+	}
+	const gapSizes = gaps.map(() => 0);
+	if (extra > 0) {
+		const total = gaps.reduce((sum, size) => sum + size, 0);
+		const raw = gaps.map((size) => (extra * size) / total);
+		const base = raw.map((value) => Math.floor(value));
+		const order = raw
+			.map((value, i) => [value - base[i], i])
+			.sort((a, b) => b[0] - a[0]);
+		let used = base.reduce((sum, value) => sum + value, 0);
+		for (const [, i] of order) {
+			if (used >= extra) break;
+			const add = Math.min(extra - used, gaps[i] - 1 - base[i]);
+			base[i] += add;
+			used += add;
+		}
+		for (let i = 0; i < gaps.length; i += 1) gapSizes[i] = base[i];
+	}
+
+	// Sample frames: authored frames plus evenly spaced integer fillers.
+	const frames = [];
+	for (let i = 0; i < authored.length; i += 1) {
+		if (i > 0) {
+			const count = gapSizes[i - 1];
+			if (count > 0) {
+				const step = gaps[i - 1] / (count + 1);
+				for (let j = 0; j < count; j += 1) {
+					frames.push(authored[i - 1].frame + Math.round((j + 1) * step));
+				}
+			}
+		}
+		frames.push(authored[i].frame);
+	}
+
+	// C1 resampling: cubic Hermite through the authored pins, with each pin's
+	// velocity as the finite-difference average of its two segment velocities
+	// (one-sided at the ends). A C0 polyline pins an instantaneous direction
+	// flip at every interior waypoint — and, when authored frames imply
+	// different paces, an instantaneous speed jump — which the generator can
+	// only satisfy by braking and pivoting on the pin: the hitch you see as
+	// the root crosses waypoint 2. Hermite keeps authored pins exact, keeps a
+	// uniform straight path exactly linear, and turns corners into arcs where
+	// both travel direction and speed ramp continuously. (A near-180° reversal
+	// will swing wide of the pin — that wide swing is the C1 answer to an
+	// about-face, not an error.)
+	const segmentVelocity = (a, b) => ({
+		x: (b.x - a.x) / (b.frame - a.frame),
+		z: (b.z - a.z) / (b.frame - a.frame),
+	});
+	const stalledSegment = (a, b) => (b.x - a.x) * (b.x - a.x) + (b.z - a.z) * (b.z - a.z) < 1e-12;
+	const velocity = authored.map((point, i) => {
+		const prev = authored[i - 1];
+		const next = authored[i + 1];
+		// A knot beside a stall comes to a full stop: leaking a neighbour's
+		// velocity into a hold would make the "stationary" span drift, and a
+		// walker entering a hold decelerates to zero anyway.
+		if (!prev) return stalledSegment(point, next) ? { x: 0, z: 0 } : segmentVelocity(point, next);
+		if (!next) return stalledSegment(prev, point) ? { x: 0, z: 0 } : segmentVelocity(prev, point);
+		if (stalledSegment(prev, point) || stalledSegment(point, next)) return { x: 0, z: 0 };
+		const before = segmentVelocity(prev, point);
+		const after = segmentVelocity(point, next);
+		return { x: (before.x + after.x) / 2, z: (before.z + after.z) / 2 };
+	});
+	const samples = [];
+	let seg = 0;
+	for (const frame of frames) {
+		while (frame > authored[seg + 1].frame) seg += 1;
+		const start = authored[seg];
+		const end = authored[seg + 1];
+		const span = end.frame - start.frame;
+		const t = (frame - start.frame) / span;
+		const h00 = (1 + 2 * t) * (1 - t) * (1 - t);
+		const h10 = t * (1 - t) * (1 - t);
+		const h01 = t * t * (3 - 2 * t);
+		const h11 = t * t * (t - 1);
+		const v0 = velocity[seg];
+		const v1 = velocity[seg + 1];
+		samples.push({
+			frame,
+			x: cleanZero(h00 * start.x + h10 * span * v0.x + h01 * end.x + h11 * span * v1.x),
+			z: cleanZero(h00 * start.z + h10 * span * v0.z + h01 * end.z + h11 * span * v1.z),
+			heading: 0,
+		});
+	}
+
+	// Path-tangent headings. Interior samples use the central difference
+	// between neighbors, the ends use their adjacent segment; displacements
+	// under 1e-6 (stalls) carry the previous heading, 0 when stationary.
+	// Sign convention measured against the deployed generator, not assumed.
+	// With the path aligned so heading[0] = 0 matches the model's forced
+	// frame-0 facing, the generated hips reproduce the SENT angle exactly
+	// (a probe sending mirrored headings walked the second segment facing
+	// +77.7° while travelling at −77.7°). Earlier mirror-looking results
+	// came from clips whose frame-0 facing conflicted with heading[0] and
+	// corrupted the whole track. Model heading = atan2(dx, dz) of the
+	// facing/travel direction; 0 faces +Z.
+	let previousHeading = 0;
+	for (let i = 0; i < samples.length; i += 1) {
+		let dx = 0;
+		let dz = 0;
+		if (samples.length > 1) {
+			if (i === 0) {
+				dx = samples[1].x - samples[0].x;
+				dz = samples[1].z - samples[0].z;
+			} else if (i === samples.length - 1) {
+				dx = samples[i].x - samples[i - 1].x;
+				dz = samples[i].z - samples[i - 1].z;
+			} else {
+				dx = samples[i + 1].x - samples[i - 1].x;
+				dz = samples[i + 1].z - samples[i - 1].z;
+			}
+		}
+		if (dx * dx + dz * dz >= 1e-12) previousHeading = Math.atan2(dx, dz);
+		samples[i].heading = cleanZero(previousHeading);
+	}
+	return samples;
+}
+/**
+ * Align an authored root path for ARDY generation: compute the clip-local
+ * first travel tangent (first non-zero authored displacement, squared
+ * length >= 1e-12) and fold it into the total rotation so the densified
+ * path starts with heading 0, the model's forced frame-0 +Z facing. The
+ * returned rotationDeg is the scene->clip total rotation; handing it to
+ * toSceneRootOffset at playback restores scene coordinates exactly.
+ */
+export function alignArdyPath(waypoints, actorRotationDeg = 0, maxPoints = 32) {
+	if (waypoints.length < 2) return { waypoints: [], rotationDeg: actorRotationDeg };
+	// Fold the first *sampled* travel direction into the rotation, not the
+	// authored chord: the C1 resampler bends inside the first segment, so only
+	// the dense samples know the true first step. Rotation is rigid, so
+	// densifying again with the folded rotation rotates those samples exactly
+	// and heading[0] lands on 0 by construction.
+	const probe = densifyArdyWaypoints(waypoints, actorRotationDeg, maxPoints);
+	let phi = 0;
+	for (let i = 0; i < probe.length - 1; i += 1) {
+		const dx = probe[i + 1].x - probe[i].x;
+		const dz = probe[i + 1].z - probe[i].z;
+		if (dx * dx + dz * dz >= 1e-12) {
+			phi = Math.atan2(dx, dz);
+			break;
+		}
+	}
+	const rotationDeg = actorRotationDeg + (phi * 180) / Math.PI;
+	return {
+		waypoints: densifyArdyWaypoints(waypoints, rotationDeg, maxPoints),
+		rotationDeg,
+	};
+}
+
+/** Rotate an ARDY clip-local root offset back into CozyClay scene space. */
+export function toSceneRootOffset(x, z, actorRotationDeg = 0) {
+	const yaw = (actorRotationDeg * Math.PI) / 180;
+	const cos = Math.cos(yaw);
+	const sin = Math.sin(yaw);
+	return {
+		x: cleanZero(cos * x + sin * z),
+		z: cleanZero(-sin * x + cos * z),
+	};
+}
+
+/**
+ * A full-body pose also constrains the root. On a root path it must share the
+ * frame-zero origin; otherwise the two constraints can pull the clip apart.
+ */
+export function poseConstraintFrame(requestedFrame, clipFrames, hasRootPath) {
+	if (hasRootPath) return 0;
+	return Math.max(0, Math.min(Math.round(requestedFrame) || 0, clipFrames - 1));
+}
+
+/* ---------------------------------------------------- path limits ------ */
+
+// What the generator can actually express, learned the hard way: waypoints
+// are inpainting observations ARDY cannot refuse, so a request outside the
+// training distribution collapses into foot-sliding instead of erroring.
+// These limits keep authored paths inside that distribution.
+export const PATH_LIMITS = Object.freeze({
+	speedMinMps: 0.5, // below this, "walking" cannot cycle a gait — feet slide
+	speedMaxMps: 3.0, // above this is out of the locomotion band entirely
+	holdEpsM: 0.05, // a displacement this small is a deliberate hold, any duration
+	minPinGapFrames: 8, // authored pins closer than this over-rail the root
+	speedRatioWarn: 2, // adjacent legs differing more than 2x force a gait change
+	turnRateWarnDegPerS: 120, // sharper turns need wider arcs than the path gives
+	tailMaxS: 2, // unconstrained tail after the last pin inherits its history
+	clipMaxS: 10, // ARDY's trained window; one-shot constrained calls cannot exceed it
+});
+
+const NATURAL_WALK_MPS = 1.4;
+
+/**
+ * Judge the segment a candidate pin would create after `last`. Returns
+ * { ok, error?, warnings: [] } — `error` blocks the placement and always
+ * names the fix (a workable frame or distance), `warnings` accompany a
+ * placement that is legal but will read oddly.
+ * @param {{frame:number,x:number,z:number}} last      the previous pin (or the frame-0 start)
+ * @param {{frame:number,x:number,z:number}} candidate the pin being authored
+ * @param {number} fps
+ * @param {{frame:number,x:number,z:number}|null} prev the pin before `last`, for ratio/turn warnings
+ */
+export function judgeNextWaypoint(last, candidate, fps, prev = null) {
+	const gap = candidate.frame - last.frame;
+	if (gap < PATH_LIMITS.minPinGapFrames) {
+		return {
+			ok: false,
+			error: `pins need at least ${PATH_LIMITS.minPinGapFrames} frames between them (${(PATH_LIMITS.minPinGapFrames / fps).toFixed(1)} s) — scrub past frame ${last.frame + PATH_LIMITS.minPinGapFrames}`,
+			warnings: [],
+		};
+	}
+	const dist = Math.hypot(candidate.x - last.x, candidate.z - last.z);
+	if (dist <= PATH_LIMITS.holdEpsM) return { ok: true, warnings: [] }; // a hold: legal at any length
+	const dt = gap / fps;
+	const speed = dist / dt;
+	if (speed > PATH_LIMITS.speedMaxMps) {
+		const neededFrames = Math.ceil((dist / PATH_LIMITS.speedMaxMps) * fps);
+		return {
+			ok: false,
+			error: `${speed.toFixed(1)} m/s is faster than anyone moves (max ${PATH_LIMITS.speedMaxMps}) — pin frame ${last.frame + neededFrames} or later, or click closer`,
+			warnings: [],
+		};
+	}
+	if (speed < PATH_LIMITS.speedMinMps) {
+		const walkFrame = last.frame + Math.max(PATH_LIMITS.minPinGapFrames, Math.round((dist / NATURAL_WALK_MPS) * fps));
+		const neededDist = (PATH_LIMITS.speedMinMps * dt).toFixed(1);
+		return {
+			ok: false,
+			error: `${speed.toFixed(2)} m/s is below a sustainable walk (min ${PATH_LIMITS.speedMinMps}) — pin frame ~${walkFrame} instead, or click at least ${neededDist} m away`,
+			warnings: [],
+		};
+	}
+	const warnings = [];
+	if (prev) {
+		const prevDist = Math.hypot(last.x - prev.x, last.z - prev.z);
+		if (prevDist > PATH_LIMITS.holdEpsM) {
+			const prevSpeed = prevDist / ((last.frame - prev.frame) / fps);
+			const ratio = Math.max(speed, prevSpeed) / Math.max(Math.min(speed, prevSpeed), 1e-6);
+			if (ratio > PATH_LIMITS.speedRatioWarn) {
+				warnings.push(`${ratio.toFixed(1)}x speed change from the previous leg — expect a visible gait shift`);
+			}
+			const before = Math.atan2(last.x - prev.x, last.z - prev.z);
+			const after = Math.atan2(candidate.x - last.x, candidate.z - last.z);
+			let turn = Math.abs(after - before);
+			if (turn > Math.PI) turn = 2 * Math.PI - turn;
+			const turnRate = (turn * 180) / Math.PI / dt;
+			if (turnRate > PATH_LIMITS.turnRateWarnDegPerS) {
+				warnings.push(`${Math.round((turn * 180) / Math.PI)}° turn in ${dt.toFixed(1)} s is sharper than a walking arc — give it more frames or distance`);
+			}
+		}
+	}
+	return { ok: true, warnings };
+}
+
+/**
+ * Re-judge a whole authored path (frame-0 start included) before generation:
+ * placement-time checks can be invalidated later by removing a middle pin.
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function judgeAuthoredPath(rootPath, fps, clipFrames, { chained = false } = {}) {
+	const errors = [];
+	const warnings = [];
+	const ordered = [...rootPath].sort((a, b) => a.frame - b.frame);
+	for (let i = 1; i < ordered.length; i += 1) {
+		const verdict = judgeNextWaypoint(ordered[i - 1], ordered[i], fps, i >= 2 ? ordered[i - 2] : null);
+		if (!verdict.ok) errors.push(`leg ${i} (frame ${ordered[i - 1].frame}->${ordered[i].frame}): ${verdict.error}`);
+		else for (const warning of verdict.warnings) warnings.push(`leg ${i}: ${warning}`);
+	}
+	// The trained window binds ONE model call. A chained rollout (a prompt
+	// schedule) makes a call per block, so the whole clip may exceed it —
+	// each block is capped separately by the bridge and the box generator.
+	if (!chained && clipFrames / fps > PATH_LIMITS.clipMaxS) {
+		errors.push(
+			`a root path generates the whole clip in one model call, and ARDY's trained window is ${PATH_LIMITS.clipMaxS} s — shorten the clip to ${PATH_LIMITS.clipMaxS} s, or split the prompt into blocks so the path rides a chained rollout`,
+		);
+	}
+	const tail = (clipFrames - 1 - (ordered[ordered.length - 1]?.frame ?? 0)) / fps;
+	if (ordered.length > 1 && tail > PATH_LIMITS.tailMaxS) {
+		warnings.push(
+			`${tail.toFixed(1)} s of clip remain after the last pin — the unconstrained tail continues whatever the path ends in`,
+		);
+	}
+	return { errors, warnings };
+}
+
+/** Place a newly-authored keyframe where it is immediately visible and draggable. */
+export function defaultWaypointPosition(waypoints, subject) {
+	if (!waypoints.length) return { x: subject.x, z: subject.z };
+	const last = waypoints[waypoints.length - 1];
+	if (waypoints.length > 1) {
+		const previous = waypoints[waypoints.length - 2];
+		return { x: last.x + (last.x - previous.x), z: last.z + (last.z - previous.z) };
+	}
+	const yaw = (subject.rot * Math.PI) / 180;
+	return { x: last.x + Math.sin(yaw), z: last.z + Math.cos(yaw) };
+}