cozyclay 2.1.0 → 3.0.0

package/tools/kimodo/compare-seam.mjs

@@ -1,108 +0,0 @@
-/**
- * compare-seam.mjs — measure what a multi-segment take does AT THE SEAM,
- * comparably across backends that run at different frame rates.
- *
- * ARDY-Core runs at 20 fps and Kimodo-SOMA at 30, so a per-FRAME root
- * displacement means different things in each file and cannot be compared
- * directly — every figure here is per SECOND.
- *
- * Two different failures are reported because they are not the same thing:
- *   - a STALL: root speed collapsing toward zero at the boundary, which is the
- *     "the motion stops between the two prompts" symptom.
- *   - a JUMP: a one-frame teleport, which is a discontinuity rather than a stall.
- */
-
-import { readNpz } from "./read-npz.mjs";
-
-/** Root speed per frame, in m/s. */
-export function rootSpeeds(rootPos, frames, fps) {
-	const speeds = [];
-	for (let frame = 1; frame < frames; frame += 1) {
-		const a = frame * 3;
-		const b = (frame - 1) * 3;
-		speeds.push(
-			Math.hypot(rootPos[a] - rootPos[b], rootPos[a + 1] - rootPos[b + 1], rootPos[a + 2] - rootPos[b + 2]) * fps
-		);
-	}
-	return speeds;
-}
-
-/**
- * @param {Float32Array} rootPos flat [frames*3]
- * @param {number} boundaryFrame first frame of the second segment
- * @param {number} windowS how far either side of the seam to look
- */
-export function seamReport(rootPos, frames, fps, boundaryFrame, windowS = 0.25) {
-	const speeds = rootSpeeds(rootPos, frames, fps);
-	const half = Math.max(1, Math.round(windowS * fps));
-	// speeds[i] is the step from frame i to i+1.
-	const seamIndex = boundaryFrame - 1;
-	const from = Math.max(0, seamIndex - half);
-	const to = Math.min(speeds.length - 1, seamIndex + half);
-
-	const window = speeds.slice(from, to + 1);
-	const outsideBefore = speeds.slice(Math.max(0, from - half), from);
-	const outsideAfter = speeds.slice(to + 1, Math.min(speeds.length, to + 1 + half));
-	const surrounding = [...outsideBefore, ...outsideAfter];
-
-	const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0);
-	const cruise = mean(surrounding);
-	const seamMin = window.length ? Math.min(...window) : 0;
-	const seamMax = window.length ? Math.max(...window) : 0;
-
-	return {
-		fps,
-		frames,
-		boundaryFrame,
-		seam_speed_at_boundary_mps: speeds[seamIndex] ?? null,
-		seam_min_speed_mps: seamMin,
-		seam_max_speed_mps: seamMax,
-		cruise_speed_mps: cruise,
-		// 1.0 = the seam keeps the surrounding pace; 0.0 = a dead stop.
-		stall_ratio: cruise > 0 ? seamMin / cruise : null,
-		overall_max_speed_mps: Math.max(...speeds),
-		overall_mean_speed_mps: mean(speeds),
-	};
-}
-
-function loadRoot(path) {
-	const members = readNpz(path);
-	const root = members.root_positions ?? members.smooth_root_pos;
-	if (!root) throw new Error(`${path}: no root_positions member`);
-	const frames = root.shape[0];
-	return { rootPos: root.data, frames };
-}
-
-// Only act as a CLI when executed directly; seam-batch.mjs imports seamReport.
-const invokedDirectly = process.argv[1] && process.argv[1].endsWith("compare-seam.mjs");
-const [, , ...args] = process.argv;
-if (!invokedDirectly) {
-	// imported as a library
-} else if (args.length % 3 !== 0 || args.length === 0) {
-	console.error('usage: compare-seam.mjs <label> <npz> <fps> [<label> <npz> <fps> ...]');
-	process.exit(2);
-}
-
-if (invokedDirectly) {
-	const rows = [];
-	for (let index = 0; index < args.length; index += 3) {
-		const label = args[index];
-		const path = args[index + 1];
-		const fps = Number(args[index + 2]);
-		const { rootPos, frames } = loadRoot(path);
-		// Both takes here are two equal-length segments, so the seam is the middle.
-		const report = seamReport(rootPos, frames, fps, Math.round(frames / 2));
-		rows.push({ label, ...report });
-	}
-
-	for (const row of rows) {
-		console.log(`\n=== ${row.label} ===`);
-		console.log(`  ${row.frames} frames @ ${row.fps} fps  (seam at frame ${row.boundaryFrame})`);
-		console.log(`  cruise speed around seam : ${row.cruise_speed_mps.toFixed(3)} m/s`);
-		console.log(`  slowest speed at seam    : ${row.seam_min_speed_mps.toFixed(3)} m/s`);
-		console.log(`  STALL RATIO              : ${row.stall_ratio.toFixed(3)}   (1.0 = no stall, 0.0 = dead stop)`);
-		console.log(`  fastest speed at seam    : ${row.seam_max_speed_mps.toFixed(3)} m/s`);
-		console.log(`  overall max / mean       : ${row.overall_max_speed_mps.toFixed(3)} / ${row.overall_mean_speed_mps.toFixed(3)} m/s`);
-	}
-	console.log("");
-}

package/tools/kimodo/constraints.mjs

@@ -1,244 +0,0 @@
-/**
- * constraints.mjs — CozyClay's authored root path → Kimodo's `--constraints` JSON.
- *
- * Two coordinate translations happen here, and both are silent-bug shaped, so
- * each is pinned by test/verify-kimodo-waypoints.mjs:
- *
- * 1. FRAME SPACE. CozyClay authors waypoints against the app's clip, which runs
- *    at ARDY's 20 fps (src/App.jsx ARDY_FPS). Kimodo generates at 30 and the
- *    take is retimed back down afterwards, so a constraint frame must be scaled
- *    onto the GENERATION clock or the path lands at 2/3 of the intended time.
- *
- * 2. ORIGIN. Kimodo canonicalises training motion so the smoothed root starts at
- *    XZ (0,0) on frame 0, and the docs require constraints to be authored
- *    against that canonical origin. CozyClay waypoints are absolute world
- *    metres, so the whole path is translated by its own first waypoint. Feeding
- *    absolute coordinates straight in would ask the character to teleport to its
- *    world position on frame 0.
- *
- * 3. SEGMENT SPACE. Kimodo generates each prompt segment separately. For every
- *    segment after the first it shifts that segment's constraints to the origin
- *    (translate_2d(observed_motion, -last_smooth_root_2d)), generates, then adds
- *    last_smooth_root_2d back — where last_smooth_root_2d is the segment's
- *    ACTUAL GENERATED start. `crop_move` only re-indexes frames; it never moves
- *    smooth_root_2d. So a constraint in segment N must be a DISPLACEMENT FROM
- *    THAT SEGMENT'S START, and an absolute whole-clip target lands there as a
- *    doubled offset that yanks the root at the boundary.
- *
- *    This was isolated by measurement on a real 2-segment take, not inferred:
- *      no waypoints                  -> boundary jump 0.105 m
- *      waypoints inside segment 1    -> boundary jump 0.084 m
- *      absolute waypoints in seg 2   -> boundary jump 2.353 m
- *    A first attempt that re-anchored each segment onto its own first waypoint
- *    was measured WORSE still (4.48 m, waypoint error 3.55 m) because it
- *    discarded the displacement the author actually asked for.
- *
- * `global_root_heading` is a [cos, sin] direction PAIR per constrained frame,
- * NOT a radian — passing radians through would be accepted as a number pair and
- * silently steer the character wrong, so heading is converted, never forwarded.
- */
-
-export const ROOT2D_TYPE = "root2d";
-
-function requireFinite(value, label) {
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		throw new Error(`buildRoot2dConstraints: ${label} must be a finite number, got ${JSON.stringify(value)}`);
-	}
-	return value;
-}
-
-/**
- * @param {Array<{frame:number,x:number,z:number,heading:number|null}>} waypoints
- * @param {{appFps:number, genFps:number, genFrames:number, segmentBoundaries?:number[],
- *          segmentStarts?:number[], transitionFrames?:number}} options
- *   `segmentBoundaries` are APP-space frames where a new prompt segment begins
- *   (excluding 0). Omit or pass [] for a single-segment take.
- *   `segmentStarts` are the same boundaries already in GENERATION space, used
- *   to keep constraints clear of each segment's transition window.
- * @returns {Array<object>} Kimodo constraint entries (empty when nothing is constrained)
- */
-export function buildRoot2dConstraints(
-	waypoints,
-	{ appFps, genFps, genFrames, segmentBoundaries = [], segmentStarts = [], transitionFrames = 5, densifyStride = 0 } = {}
-) {
-	if (!Number.isInteger(densifyStride) || densifyStride < 0) {
-		throw new Error(`buildRoot2dConstraints: densifyStride must be a non-negative integer, got ${JSON.stringify(densifyStride)}`);
-	}
-	if (!waypoints || waypoints.length === 0) return [];
-	if (!Array.isArray(waypoints)) {
-		throw new Error("buildRoot2dConstraints: waypoints must be an array");
-	}
-	requireFinite(appFps, "appFps");
-	requireFinite(genFps, "genFps");
-	requireFinite(genFrames, "genFrames");
-	if (genFrames < 1) throw new Error(`buildRoot2dConstraints: genFrames must be >= 1, got ${genFrames}`);
-
-	const scale = genFps / appFps;
-	const lastFrame = Math.round(genFrames) - 1;
-
-	// Validate and normalise in author order first, so a bad path is refused
-	// before any of it is translated.
-	let previousFrame = -1;
-	const normalised = waypoints.map((waypoint, index) => {
-		if (!waypoint || typeof waypoint !== "object") {
-			throw new Error(`buildRoot2dConstraints: waypoints[${index}] must be an object`);
-		}
-		const frame = waypoint.frame;
-		if (!Number.isInteger(frame) || frame < 0) {
-			throw new Error(
-				`buildRoot2dConstraints: waypoints[${index}].frame must be a non-negative integer, got ${JSON.stringify(frame)}`
-			);
-		}
-		if (frame <= previousFrame) {
-			throw new Error(
-				`buildRoot2dConstraints: waypoint frames must be strictly ascending; waypoints[${index}].frame ${frame} follows ${previousFrame}`
-			);
-		}
-		previousFrame = frame;
-		const x = requireFinite(waypoint.x, `waypoints[${index}].x`);
-		const z = requireFinite(waypoint.z, `waypoints[${index}].z`);
-		const heading = waypoint.heading;
-		if (heading !== null && heading !== undefined) {
-			requireFinite(heading, `waypoints[${index}].heading`);
-		}
-		// A frame past the generated clip is CLAMPED rather than dropped: the
-		// author asked for the path to end there, and Kimodo rejects an index
-		// outside the clip, so the honest reading is "as late as possible".
-		const genFrame = Math.min(lastFrame, Math.max(0, Math.round(frame * scale)));
-		return { genFrame, x, z, heading: heading ?? null };
-	});
-
-	// Two authored frames can round onto one generation frame (a downscale, or
-	// waypoints one app-frame apart). Duplicate frame_indices would constrain a
-	// single frame to two different targets, so the LAST author wins — matching
-	// "the most recent instruction for that moment".
-	const byFrame = new Map();
-	for (const entry of normalised) byFrame.set(entry.genFrame, entry);
-	const points = [...byFrame.values()].sort((a, b) => a.genFrame - b.genFrame);
-
-	// The AUTHORED polyline, frozen before any nudge or densification mutates
-	// `points`: every later interpolation samples what the author drew, never a
-	// constraint that has already been moved for Kimodo's benefit.
-	const authored = points.map((point) => ({ ...point }));
-
-	// Where does the authored path sit when each segment BEGINS? That position is
-	// the origin Kimodo will re-zero this segment to, so every constraint inside
-	// the segment is emitted as a displacement from it. The path is sampled
-	// (linearly, matching a straight walk between pins) rather than snapped to a
-	// waypoint, because a segment need not start on one.
-	const genBoundaries = [...new Set(segmentBoundaries.map((frame) => Math.round(frame * scale)))].sort(
-		(a, b) => a - b
-	);
-	const sampleAt = (genFrame) => {
-		if (genFrame <= authored[0].genFrame) return authored[0];
-		const last = authored[authored.length - 1];
-		if (genFrame >= last.genFrame) return last;
-		for (let index = 1; index < authored.length; index += 1) {
-			const a = authored[index - 1];
-			const b = authored[index];
-			if (genFrame <= b.genFrame) {
-				const span = b.genFrame - a.genFrame;
-				const t = span === 0 ? 0 : (genFrame - a.genFrame) / span;
-				return { x: a.x + (b.x - a.x) * t, z: a.z + (b.z - a.z) * t };
-			}
-		}
-		return last;
-	};
-	const segmentStartOf = (genFrame) => {
-		let start = 0;
-		for (const boundary of genBoundaries) if (genFrame >= boundary) start = boundary;
-		return start;
-	};
-	const originCache = new Map();
-	const originFor = (genFrame) => {
-		const start = segmentStartOf(genFrame);
-		if (!originCache.has(start)) originCache.set(start, start === 0 ? points[0] : sampleAt(start));
-		return originCache.get(start);
-	};
-
-	// Keep constraints out of each segment's TRANSITION WINDOW. For every segment
-	// after the first, Kimodo builds its own FullBody + EndEffector constraints
-	// over that segment's first `num_transition_frames` from the previous
-	// segment's tail. A root2d constraint in the same window disagrees with them
-	// and the root teleports at the seam: measured 2.353 m with the constraint on
-	// the boundary against 0.400 m ten frames later, same path and seed.
-	//
-	// Only the TIMING moves; the authored position is preserved exactly, because
-	// dropping the constraint would silently discard what the author asked for.
-	if (segmentStarts.length > 0 && points.length > 0) {
-		const windows = [...new Set(segmentStarts.map((frame) => Math.round(frame)))].sort((a, b) => a - b);
-		for (const point of points) {
-			for (const start of windows) {
-				if (point.genFrame >= start && point.genFrame < start + transitionFrames) {
-					point.genFrame = Math.min(lastFrame, start + transitionFrames);
-				}
-			}
-		}
-		// A nudge can land on a frame another waypoint already owns, and duplicate
-		// indices would constrain one frame twice; the later author wins, matching
-		// the dedupe above.
-		const deduped = new Map();
-		for (const point of points) deduped.set(point.genFrame, point);
-		points.length = 0;
-		points.push(...[...deduped.values()].sort((a, b) => a.genFrame - b.genFrame));
-	}
-
-	// DENSIFICATION — the seam fix. Kimodo generates each prompt segment
-	// separately and crops constraints with a half-open [start, end): a waypoint
-	// ON a boundary belongs entirely to the segment that starts there, so the
-	// segment BEFORE it never learns the path exists, ends wherever it likes, and
-	// the root teleports at the seam (measured 2.353 m) to satisfy the constraint
-	// one frame later. Laying interpolated samples of the authored polyline every
-	// `densifyStride` generation frames tells every segment where the path goes,
-	// so each one arrives at its boundary already in place. Samples stay strictly
-	// inside [first, last] authored frames (constraining past the path's end
-	// would invent motion) and out of every transition window (Kimodo owns those
-	// frames with its own constraints; see the nudge above).
-	if (densifyStride > 0 && points.length >= 2) {
-		const windows = [...new Set(segmentStarts.map((frame) => Math.round(frame)))];
-		const inWindow = (frame) => windows.some((start) => frame >= start && frame < start + transitionFrames);
-		const taken = new Set(points.map((point) => point.genFrame));
-		const first = authored[0].genFrame;
-		const last = authored[authored.length - 1].genFrame;
-		for (let frame = first + densifyStride; frame < last; frame += densifyStride) {
-			if (taken.has(frame) || inWindow(frame)) continue;
-			const { x, z } = sampleAt(frame);
-			points.push({ genFrame: frame, x, z, heading: null });
-			taken.add(frame);
-		}
-		points.sort((a, b) => a.genFrame - b.genFrame);
-	}
-
-	const anyHeading = points.some((point) => point.heading !== null);
-
-	// A lone waypoint at the origin carries no displacement and no heading, so
-	// it constrains nothing; emitting it would hand Kimodo a degenerate entry.
-	if (points.length === 1 && !anyHeading) return [];
-
-	const entry = {
-		type: ROOT2D_TYPE,
-		frame_indices: points.map((point) => point.genFrame),
-		smooth_root_2d: points.map((point) => {
-			const origin = originFor(point.genFrame);
-			return [point.x - origin.x, point.z - origin.z];
-		}),
-	};
-
-	if (anyHeading) {
-		// Every constrained frame needs a pair so the array stays index-aligned
-		// with frame_indices. An unauthored heading borrows the next authored
-		// one (falling back to the previous), which keeps the character facing
-		// along the path it is about to follow rather than snapping at the
-		// first authored pin.
-		const resolved = points.map((point) => point.heading);
-		for (let index = resolved.length - 1; index >= 0; index -= 1) {
-			if (resolved[index] === null) resolved[index] = resolved[index + 1] ?? null;
-		}
-		for (let index = 0; index < resolved.length; index += 1) {
-			if (resolved[index] === null) resolved[index] = resolved[index - 1] ?? 0;
-		}
-		entry.global_root_heading = resolved.map((radians) => [Math.cos(radians), Math.sin(radians)]);
-	}
-
-	return [entry];
-}

package/tools/kimodo/edit.mjs

@@ -1,259 +0,0 @@
-/**
- * edit.mjs — regenerate one span of an existing take with Kimodo.
- *
- * ARDY does this by feeding the surrounding motion in as autoregressive
- * history. Kimodo has no history input, so the same intent is expressed with the
- * constraint protocol it does have: the span is regenerated as part of a whole
- * clip that is PINNED to the original take on both sides of the edit, and only
- * the edited span is kept.
- *
- *   frames <  start   anchored to the source  -> the take rejoins what came before
- *   frames in [start,end)  free, except the author's own IK keyframes
- *   frames >= end     anchored to the source  -> the take rejoins what comes after
- *
- * Anchors are ordinary `fullbody` constraints built by pose-constraints.mjs, the
- * same ones pose pinning uses and which measured 0.00 deg tracking, so the joins
- * are as tight as a pinned pose rather than a blend.
- *
- * The result is spliced back with replaceMotionSegment: everything outside the
- * edited range is copied from the source byte for byte, because the author
- * changed one span and expects the rest of their take untouched.
- *
- * ROUND 2 (contract C5) — THE AUTHOR'S KEYS MAY BE EFFECTOR-SCOPED
- * ---------------------------------------------------------------
- * A `fullbody` key freezes all 77 joints at that frame. For an ANCHOR that is the
- * point: the frame is context we want held exactly. For the author's own key it is
- * the bug C5 exists to remove — dragging one hand should move the arm, not weld
- * the legs, the spine and the head to a pose the user never authored.
- *
- * So planEditConstraints splits the two kinds of frame:
- *
- *   anchors            -> ALWAYS fullbody, in every mode
- *   author keyframes   -> end-effector constraints IFF every edited track in the
- *                         manifest maps to a limb chain, else fullbody
- *
- * "EVERY track" is the condition, not "any": the manifest's tracks describe ONE
- * authored pose per frame, and an edit that also moved the spine or the head has
- * no effector to carry those bones — emitting hand constraints for it would
- * silently drop half the user's edit. Mixed or non-effector track lists therefore
- * keep round 1's behaviour wholesale, and the chosen mode is REPORTED
- * (`constraintMode`) rather than inferred, so the wrapper can log which pinning a
- * take actually got.
- *
- * A CAVEAT WORTH REPEATING AT THE SWITCH (effector-constraints.mjs states it in
- * full): an EE constraint still pins root XZ, root height and heading at its
- * frames — Kimodo's EndEffectorConstraintSet appends them unconditionally and has
- * no flag to disable it. On an edit that is harmless by construction: every pose
- * here is either read back out of the source take or authored on top of it, so
- * the pinned root is the take's own root at that frame. It is NOT a free root.
- */
-
-import { readFileSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
-import { buildEffectorConstraints, effectorTypeForTrack } from "./effector-constraints.mjs";
-import { buildFullBodyConstraints } from "./pose-constraints.mjs";
-import { readNpz } from "./read-npz.mjs";
-
-/** How many source frames to pin on each side when the caller asks for context. */
-const ANCHOR_SAMPLES = 3;
-
-/**
- * Read the bridge's edit-manifest.json into a resolved plan.
- * Paths inside it are relative to the manifest, which is what the bridge writes.
- */
-export function parseEditManifest(manifestPath) {
-	const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
-	const base = dirname(resolve(manifestPath));
-
-	if (!Number.isInteger(raw.start_frame) || raw.start_frame < 0) {
-		throw new Error(`parseEditManifest: start_frame must be a non-negative integer, got ${JSON.stringify(raw.start_frame)}`);
-	}
-	if (!Number.isInteger(raw.end_frame)) {
-		throw new Error(`parseEditManifest: end_frame must be an integer, got ${JSON.stringify(raw.end_frame)}`);
-	}
-	if (raw.end_frame <= raw.start_frame) {
-		throw new Error(`parseEditManifest: range ${raw.start_frame}..${raw.end_frame} is empty or inverted`);
-	}
-	if (!Array.isArray(raw.edits) || raw.edits.length === 0) {
-		throw new Error("parseEditManifest: edits must be a non-empty array");
-	}
-
-	let previous = -1;
-	const edits = raw.edits.map((entry, index) => {
-		if (!entry || typeof entry !== "object") {
-			throw new Error(`parseEditManifest: edits[${index}] must be an object`);
-		}
-		if (!Number.isInteger(entry.frame)) {
-			throw new Error(`parseEditManifest: edits[${index}].frame must be an integer`);
-		}
-		if (entry.frame < raw.start_frame || entry.frame >= raw.end_frame) {
-			throw new Error(
-				`parseEditManifest: edits[${index}].frame ${entry.frame} is outside the edited range ${raw.start_frame}..${raw.end_frame}`
-			);
-		}
-		if (entry.frame <= previous) {
-			throw new Error(
-				`parseEditManifest: edit frames must be strictly ascending; edits[${index}].frame ${entry.frame} follows ${previous}`
-			);
-		}
-		previous = entry.frame;
-		if (typeof entry.pose_path !== "string" || !entry.pose_path) {
-			throw new Error(`parseEditManifest: edits[${index}].pose_path is required`);
-		}
-		return {
-			frame: entry.frame,
-			tracks: Array.isArray(entry.tracks) ? entry.tracks : [],
-			posePath: isAbsolute(entry.pose_path) ? entry.pose_path : resolve(base, entry.pose_path),
-		};
-	});
-
-	return { startFrame: raw.start_frame, endFrame: raw.end_frame, edits };
-}
-
-/** One frame of a cclay motion npz as the {local_rot_mats, posed_joints} a pose wants. */
-function frameAsPose(members, frame) {
-	const rot = members.local_rot_mats;
-	const pos = members.posed_joints;
-	const joints = rot.shape.at(-3);
-	if (joints !== 27) throw new Error(`planEditConstraints: source motion has ${joints} joints, expected 27`);
-	const local_rot_mats = [];
-	const posed_joints = [];
-	for (let j = 0; j < 27; j += 1) {
-		const b = (frame * 27 + j) * 9;
-		local_rot_mats.push([
-			[rot.data[b], rot.data[b + 1], rot.data[b + 2]],
-			[rot.data[b + 3], rot.data[b + 4], rot.data[b + 5]],
-			[rot.data[b + 6], rot.data[b + 7], rot.data[b + 8]],
-		]);
-		const p = (frame * 27 + j) * 3;
-		posed_joints.push([pos.data[p], pos.data[p + 1], pos.data[p + 2]]);
-	}
-	return { local_rot_mats, posed_joints };
-}
-
-/** A cclay pose npz (single keyframe) as the same shape. */
-function poseFromNpz(path) {
-	const members = readNpz(path);
-	for (const key of ["local_rot_mats", "posed_joints"]) {
-		if (!members[key]) throw new Error(`planEditConstraints: pose npz ${path} is missing ${key}`);
-	}
-	return frameAsPose(members, 0);
-}
-
-/**
- * Build the constraint set for an edit: the author's keyframes inside the range,
- * plus source anchors on both sides so the regenerated span rejoins the take.
- *
- * `poses` are the same pins in APP frame space, which is what generateOnBox
- * takes; `constraints` is the already-scaled Kimodo form, used by the tests and
- * for reporting how many frames ended up pinned.
- *
- * @returns {{constraints:Array<object>, poses:Array<object>, startFrame:number, endFrame:number, sourceFrames:number, fps:number}}
- */
-export function planEditConstraints({ sourcePath, manifestPath, contextBefore = 0, contextAfter = 0, genFps = 30, appFps = 24 }) {
-	const manifest = parseEditManifest(manifestPath);
-	const source = readNpz(sourcePath);
-	if (!source.local_rot_mats || !source.posed_joints) {
-		throw new Error(`planEditConstraints: ${sourcePath} is not a cclay motion npz`);
-	}
-	const sourceFrames = source.local_rot_mats.shape[0];
-	const fps = source.fps ? Math.round(source.fps.data[0]) : appFps;
-	if (manifest.endFrame > sourceFrames) {
-		throw new Error(
-			`planEditConstraints: edited range ends at ${manifest.endFrame} but the source has ${sourceFrames} frames`
-		);
-	}
-
-	// Anchor frames: the last few source frames before the range and the first
-	// few at/after it. Sampling several rather than one gives the model a
-	// direction to rejoin on, not just a point.
-	const anchors = [];
-	if (contextBefore > 0) {
-		const from = Math.max(0, manifest.startFrame - contextBefore);
-		const step = Math.max(1, Math.floor((manifest.startFrame - from) / ANCHOR_SAMPLES) || 1);
-		for (let f = from; f < manifest.startFrame; f += step) anchors.push(f);
-	}
-	if (contextAfter > 0) {
-		const to = Math.min(sourceFrames - 1, manifest.endFrame + contextAfter - 1);
-		const step = Math.max(1, Math.floor((to - manifest.endFrame) / ANCHOR_SAMPLES) || 1);
-		for (let f = manifest.endFrame; f <= to; f += step) anchors.push(f);
-	}
-
-	// Author keyframes win over an anchor on the same frame: the whole point of
-	// the edit is that those frames changed. `kind` rides along because round 2
-	// constrains the two differently — and this map is what GUARANTEES a frame can
-	// never carry both an anchor and an author key, i.e. never both a fullbody
-	// anchor and an EE edit.
-	const byFrame = new Map();
-	for (const frame of anchors) {
-		if (frame < 0 || frame >= sourceFrames) continue;
-		byFrame.set(frame, { frame, kind: "anchor", pose: frameAsPose(source, frame) });
-	}
-	for (const edit of manifest.edits) {
-		byFrame.set(edit.frame, { frame: edit.frame, kind: "edit", pose: poseFromNpz(edit.posePath) });
-	}
-	const poses = [...byFrame.values()].sort((a, b) => a.frame - b.frame);
-
-	// C5's switch, decided from the MANIFEST rather than from the surviving poses:
-	// an author key that lost its slot to app->gen frame rounding still describes
-	// what the user edited. EVERY edited track must map to a limb chain (see the
-	// header); an edit that names no tracks at all cannot claim one, so it is
-	// fullbody.
-	const editedTracks = [];
-	let allEffector = manifest.edits.length > 0;
-	for (const edit of manifest.edits) {
-		if (edit.tracks.length === 0) allEffector = false;
-		for (const track of edit.tracks) {
-			if (effectorTypeForTrack(track) === null) allEffector = false;
-			if (!editedTracks.includes(track)) editedTracks.push(track);
-		}
-	}
-	const constraintMode = allEffector ? "effector" : "fullbody";
-
-	// The clip Kimodo generates runs at genFps; the manifest speaks in app frames.
-	// ONE scaling pass over the merged, sorted list, so the gen-frame dedup stays
-	// SHARED: two source frames that round onto the same generation frame keep the
-	// earlier one whatever kind it is, and an anchor and an author key can never
-	// both survive onto one frame in two different constraint entries.
-	const scale = genFps / appFps;
-	const genFrames = Math.max(1, Math.round(sourceFrames * scale));
-	const scaled = [];
-	const seen = new Set();
-	for (const entry of poses) {
-		const genFrame = Math.min(genFrames - 1, Math.max(0, Math.round(entry.frame * scale)));
-		if (seen.has(genFrame)) continue;
-		seen.add(genFrame);
-		scaled.push({ frame: genFrame, kind: entry.kind, pose: entry.pose });
-	}
-
-	// fullbody mode is round 1 unchanged: ONE entry over every frame, anchors and
-	// author keys alike. Effector mode splits them — the anchors stay fullbody
-	// (they are context to hold exactly), the author's keys become one entry per
-	// distinct effector chain, over the edited frames only.
-	let constraints;
-	if (constraintMode === "effector") {
-		const anchorPoses = scaled.filter((entry) => entry.kind === "anchor");
-		const editPoses = scaled.filter((entry) => entry.kind === "edit");
-		constraints = [
-			...buildFullBodyConstraints(anchorPoses, { genFrames }),
-			...buildEffectorConstraints(editPoses, { genFrames, tracks: editedTracks }),
-		];
-	} else {
-		constraints = buildFullBodyConstraints(scaled, { genFrames });
-	}
-
-	return {
-		constraints,
-		// Which pinning the AUTHOR's keyframes got ("effector" | "fullbody"), and
-		// the tracks that decided it. Reported rather than re-derived downstream:
-		// run-edit-on-box logs it and the tests assert it.
-		constraintMode,
-		editedTracks,
-		poses,
-		startFrame: manifest.startFrame,
-		endFrame: manifest.endFrame,
-		sourceFrames,
-		fps,
-		genFrames,
-	};
-}