cozyclay 1.0.0

package/src/ardy/client.js

@@ -0,0 +1,140 @@
+/**
+ * Browser-side client for the ARDY dev sidecar (tools/ardy/bridge.mjs).
+ *
+ * The sidecar is an OPTIONAL dev companion: it listens on 127.0.0.1:5181 and
+ * Vite proxies /ardy to it during development only. The production build is
+ * a static SPA with no server at all, so every function here treats a missing
+ * sidecar as an expected state and reports it as data — never as a thrown
+ * error — so the UI can degrade to a hint instead of crashing.
+ */
+
+const JSON_HEADERS = { "Content-Type": "application/json" };
+
+// Bounded wait so a hung proxy or a slow-but-alive bridge cannot wedge the
+// panel behind a spinner forever. Long enough to not mislabel a healthy
+// bridge that answers in a couple of seconds, short enough to keep the
+// no-sidecar state snappy.
+const PROBE_TIMEOUT_MS = 5000;
+
+/**
+ * Prefer the sidecar's {"reason": "..."} error body; fall back to `fallback`
+ * when the body is not JSON (e.g. the dev proxy's own error page).
+ */
+async function reasonOf(res, fallback) {
+	try {
+		const payload = await res.json();
+		if (payload && typeof payload.reason === "string" && payload.reason) return payload.reason;
+	} catch {
+		// non-JSON error body — keep the caller's fallback
+	}
+	return fallback;
+}
+
+/**
+ * Probe the sidecar once. Resolves to { ok:true, host, encoder, device } on a
+ * healthy 200, otherwise { ok:false, reason }. Never rejects: the most common
+ * failure (no sidecar running) is a UI state, not a crash.
+ */
+export async function checkBridge() {
+	try {
+		const res = await fetch("/ardy/health", { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+		if (!res.ok) {
+			return { ok: false, reason: await reasonOf(res, `bridge unhealthy (HTTP ${res.status})`) };
+		}
+		const payload = await res.json();
+		return {
+			ok: true,
+			host: payload.host,
+			encoder: payload.encoder,
+			device: payload.device,
+		};
+	} catch (err) {
+		return { ok: false, reason: err?.message || "bridge unreachable" };
+	}
+}
+
+/**
+ * List base motions the box reported. Returns [] when the sidecar is down —
+ * the caller renders an empty state, it does not crash.
+ */
+export async function listBases() {
+	try {
+		const res = await fetch("/ardy/bases", { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+		if (!res.ok) return [];
+		const payload = await res.json();
+		return payload && Array.isArray(payload.bases) ? payload.bases : [];
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * POST a generation and stream the ndjson answer.
+ *
+ * The response is read incrementally with a streaming reader and every parsed
+ * line is handed to `onEvent(event)`. Lines may be split at any byte — text is
+ * buffered until the trailing newline arrives, so a JSON object broken across
+ * two chunks is still delivered as one event.
+ *
+ * Resolves with the terminal `done` event ({event, output, bytes}); rejects on
+ * a terminal `error` event, a malformed line, a non-200 response, or an
+ * aborted signal (the AbortError propagates so callers can tell cancellation
+ * apart from failure). `signal` is optional.
+ */
+export async function generate(body, onEvent, { signal } = {}) {
+	const res = await fetch("/ardy/generate", {
+		method: "POST",
+		headers: JSON_HEADERS,
+		body: JSON.stringify(body),
+		signal,
+	});
+	if (!res.ok) {
+		throw new Error(await reasonOf(res, `generate failed (HTTP ${res.status})`));
+	}
+	if (!res.body) throw new Error("generate: response has no body stream");
+
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		// Drain complete lines only; a chunk may end mid-line, in which case
+		// the remainder stays in the buffer until its newline arrives.
+		let nl = buffer.indexOf("\n");
+		while (nl !== -1) {
+			const terminal = applyLine(buffer.slice(0, nl).trim());
+			buffer = buffer.slice(nl + 1);
+			if (terminal) return terminal;
+			nl = buffer.indexOf("\n");
+		}
+	}
+	// Flush the decoder so a multi-byte char split by the final chunk boundary
+	// is complete, then treat a non-empty tail as one last line: the contract
+	// does not promise a trailing newline on the terminal event.
+	buffer += decoder.decode();
+	if (buffer.trim()) {
+		const terminal = applyLine(buffer.trim());
+		if (terminal) return terminal;
+	}
+	throw new Error("generate: stream ended without a done or error event");
+
+	/** Parse one ndjson line; returns the done event, throws on error/bad line. */
+	function applyLine(line) {
+		let event;
+		try {
+			event = JSON.parse(line);
+		} catch (err) {
+			throw new Error(`generate: bad ndjson line: ${err.message}`);
+		}
+		onEvent(event);
+		if (event.event === "error") {
+			throw new Error(
+				typeof event.message === "string" && event.message ? event.message : "generate: generator reported an error",
+			);
+		}
+		if (event.event === "done") return event;
+		return null;
+	}
+}

package/src/ardy/convert.js

@@ -0,0 +1,313 @@
+/**
+ * Pure, framework-free math for the CozyClay -> ARDY pose bridge.
+ * JS twin of /Users/yun/CozyClay/blender-addon/cclay/motion_constraints.py,
+ * with the small matrix/quaternion helpers mirrored from
+ * /Users/yun/CozyClay/blender-addon/cclay/motion_retarget.py so the math is
+ * not re-derived (keep the two files in lockstep when the Python changes).
+ *
+ * Matrices are row-major 3x3 nested arrays, quaternions are w-first
+ * [w, x, y, z] (Blender/motion_constraints order, NOT three.js [x, y, z, w]).
+ * The math contract, from PoseTrackBuilder.step in motion_retarget.py:
+ *
+ *     basis = Rb^T @ L @ Rb          (ARDY local rotation L -> Blender basis)
+ *     L     = Rb @ basis @ Rb^T      (inverse, this module)
+ *
+ * where Rb is the target bone's armature-space rest rotation (3x3). Every
+ * function is total: shape mismatches raise a clear Error instead of leaking
+ * NaN. No file IO, no three.js, no UI — pure functions over plain arrays.
+ */
+
+import { CSKEL27_PARENTS } from "./cskel27.js";
+
+// Quaternion norm below which a rotation matrix cannot be built. Mirrors
+// motion_retarget._QUATERNION_NORM_EPSILON so the inverse path rejects the
+// same degenerate inputs the forward path would have produced.
+const QUATERNION_NORM_EPSILON = 1e-12;
+
+function isFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+function requireQuat(q, label) {
+	if (!Array.isArray(q) || q.length !== 4 || !q.every(isFiniteNumber)) {
+		throw new Error(`${label} must be a [w, x, y, z] quaternion of four finite numbers`);
+	}
+	return q;
+}
+
+function requireMat3(m, label) {
+	if (
+		!Array.isArray(m) ||
+		m.length !== 3 ||
+		!m.every(
+			(row) => Array.isArray(row) && row.length === 3 && row.every(isFiniteNumber)
+		)
+	) {
+		throw new Error(`${label} must be a row-major 3x3 matrix of finite numbers`);
+	}
+	return m;
+}
+
+function requireVec3(v, label) {
+	if (!Array.isArray(v) || v.length !== 3 || !v.every(isFiniteNumber)) {
+		throw new Error(`${label} must be an [x, y, z] vector of three finite numbers`);
+	}
+	return v;
+}
+
+function requireJointMatrices(values, label) {
+	if (!Array.isArray(values) || values.length !== CSKEL27_PARENTS.length) {
+		throw new Error(
+			`${label} must hold ${CSKEL27_PARENTS.length} entries (one per cskel27 joint)`
+		);
+	}
+	values.forEach((m, index) => requireMat3(m, `${label}[${index}]`));
+	return values;
+}
+
+function requireJointVectors(values, label) {
+	if (!Array.isArray(values) || values.length !== CSKEL27_PARENTS.length) {
+		throw new Error(
+			`${label} must hold ${CSKEL27_PARENTS.length} entries (one per cskel27 joint)`
+		);
+	}
+	values.forEach((v, index) => requireVec3(v, `${label}[${index}]`));
+	return values;
+}
+
+// Joint indices ordered so every parent precedes its children. Mirrors
+// motion_constraints._topological_order.
+function topologicalOrder() {
+	const placed = new Set();
+	const order = [];
+	CSKEL27_PARENTS.forEach((parent, index) => {
+		if (parent === null) {
+			placed.add(index);
+			order.push(index);
+		}
+	});
+	order.sort((a, b) => a - b);
+	while (order.length < CSKEL27_PARENTS.length) {
+		let progressed = false;
+		for (let index = 0; index < CSKEL27_PARENTS.length; index += 1) {
+			if (!placed.has(index) && placed.has(CSKEL27_PARENTS[index])) {
+				order.push(index);
+				placed.add(index);
+				progressed = true;
+			}
+		}
+		if (!progressed) {
+			throw new Error("cskel27 parent table is not a tree");
+		}
+	}
+	return order;
+}
+
+const CSKEL27_TOPOLOGICAL_ORDER = topologicalOrder();
+
+/** Row-major 3x3 matrix product a @ b (motion_retarget._mat_mul). */
+export function matMul(a, b) {
+	requireMat3(a, "matMul(a, b): a");
+	requireMat3(b, "matMul(a, b): b");
+	return [
+		[
+			a[0][0] * b[0][0] + a[0][1] * b[1][0] + a[0][2] * b[2][0],
+			a[0][0] * b[0][1] + a[0][1] * b[1][1] + a[0][2] * b[2][1],
+			a[0][0] * b[0][2] + a[0][1] * b[1][2] + a[0][2] * b[2][2],
+		],
+		[
+			a[1][0] * b[0][0] + a[1][1] * b[1][0] + a[1][2] * b[2][0],
+			a[1][0] * b[0][1] + a[1][1] * b[1][1] + a[1][2] * b[2][1],
+			a[1][0] * b[0][2] + a[1][1] * b[1][2] + a[1][2] * b[2][2],
+		],
+		[
+			a[2][0] * b[0][0] + a[2][1] * b[1][0] + a[2][2] * b[2][0],
+			a[2][0] * b[0][1] + a[2][1] * b[1][1] + a[2][2] * b[2][1],
+			a[2][0] * b[0][2] + a[2][1] * b[1][2] + a[2][2] * b[2][2],
+		],
+	];
+}
+
+/** Row-major 3x3 transpose (motion_retarget._mat_transpose). */
+export function matTranspose(m) {
+	requireMat3(m, "matTranspose(m): m");
+	return [
+		[m[0][0], m[1][0], m[2][0]],
+		[m[0][1], m[1][1], m[2][1]],
+		[m[0][2], m[1][2], m[2][2]],
+	];
+}
+
+// Row-major 3x3 matrix times column vector (motion_retarget._mat_vec).
+function matVec(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],
+	];
+}
+
+/**
+ * Normalized [w, x, y, z] -> row-major 3x3 rotation matrix.
+ * Twin of motion_constraints._quat_to_mat (which is the inverse of
+ * motion_retarget._mat_to_quat). A zero-length or non-finite quaternion is
+ * rejected explicitly rather than producing a garbage matrix.
+ */
+export function quatToMat(q) {
+	const [wRaw, xRaw, yRaw, zRaw] = requireQuat(q, "quatToMat(q): q");
+	const normSq = wRaw * wRaw + xRaw * xRaw + yRaw * yRaw + zRaw * zRaw;
+	if (!Number.isFinite(normSq) || normSq <= QUATERNION_NORM_EPSILON) {
+		throw new Error("quatToMat(q): quaternion is zero-length and cannot represent a rotation");
+	}
+	const inverseNorm = 1 / Math.sqrt(normSq);
+	const w = wRaw * inverseNorm;
+	const x = xRaw * inverseNorm;
+	const y = yRaw * inverseNorm;
+	const z = zRaw * inverseNorm;
+	// Standard quaternion -> rotation matrix (right-handed, row-major).
+	return [
+		[1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
+		[2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
+		[2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
+	];
+}
+
+/**
+ * Row-major 3x3 rotation matrix -> normalized [w, x, y, z].
+ * Twin of motion_retarget._mat_to_quat (Shepperd's method). A non-finite or
+ * degenerate matrix raises instead of returning a garbage quaternion.
+ */
+export function matToQuat(m) {
+	requireMat3(m, "matToQuat(m): m");
+	let quat;
+	const trace = m[0][0] + m[1][1] + m[2][2];
+	if (trace > 0) {
+		const s = Math.sqrt(trace + 1) * 2;
+		quat = [0.25 * s, (m[2][1] - m[1][2]) / s, (m[0][2] - m[2][0]) / s, (m[1][0] - m[0][1]) / s];
+	} else if (m[0][0] > m[1][1] && m[0][0] > m[2][2]) {
+		const s = Math.sqrt(1 + m[0][0] - m[1][1] - m[2][2]) * 2;
+		quat = [(m[2][1] - m[1][2]) / s, 0.25 * s, (m[0][1] + m[1][0]) / s, (m[0][2] + m[2][0]) / s];
+	} else if (m[1][1] > m[2][2]) {
+		const s = Math.sqrt(1 + m[1][1] - m[0][0] - m[2][2]) * 2;
+		quat = [(m[0][2] - m[2][0]) / s, (m[0][1] + m[1][0]) / s, 0.25 * s, (m[1][2] + m[2][1]) / s];
+	} else {
+		const s = Math.sqrt(1 + m[2][2] - m[0][0] - m[1][1]) * 2;
+		quat = [(m[1][0] - m[0][1]) / s, (m[0][2] + m[2][0]) / s, (m[1][2] + m[2][1]) / s, 0.25 * s];
+	}
+	const squaredNorm = quat.reduce((sum, component) => sum + component * component, 0);
+	if (!Number.isFinite(squaredNorm) || squaredNorm <= QUATERNION_NORM_EPSILON) {
+		throw new Error("matToQuat(m): matrix is degenerate and cannot represent a rotation");
+	}
+	const inverseNorm = 1 / Math.sqrt(squaredNorm);
+	const normalized = quat.map((component) => component * inverseNorm);
+	if (!normalized.every(isFiniteNumber)) {
+		throw new Error("matToQuat(m): matrix is degenerate and cannot represent a rotation");
+	}
+	return normalized;
+}
+
+/**
+ * ARDY local rotation L -> Blender pose basis: basis = Rb^T @ L @ Rb.
+ * (the forward direction of the PoseTrackBuilder.step contract).
+ */
+export function localToBasis(L, Rb) {
+	const local = requireMat3(L, "localToBasis(L, Rb): L");
+	const rest = requireMat3(Rb, "localToBasis(L, Rb): Rb");
+	const restT = matTranspose(rest);
+	return matMul(restT, matMul(local, rest));
+}
+
+/**
+ * Blender pose basis -> ARDY local rotation L: L = Rb @ basis @ Rb^T.
+ * (the inverse of the PoseTrackBuilder.step contract).
+ */
+export function basisToLocal(basis, Rb) {
+	const b = requireMat3(basis, "basisToLocal(basis, Rb): basis");
+	const rest = requireMat3(Rb, "basisToLocal(basis, Rb): Rb");
+	const restT = matTranspose(rest);
+	return matMul(rest, matMul(b, restT));
+}
+
+/**
+ * Blender pose-bone quaternion (normalized [w, x, y, z]) -> ARDY local
+ * rotation L, given the bone's armature-space rest rotation Rb.
+ * Twin of motion_constraints.basis_quaternion_to_local_rotation:
+ * basis = quatToMat(quat); L = Rb @ basis @ Rb^T.
+ */
+export function basisQuaternionToLocalRotation(quatWFirst, restRotation) {
+	const basis = quatToMat(quatWFirst);
+	return basisToLocal(basis, restRotation);
+}
+
+/**
+ * Accumulate per-joint local rotations into global ones down the tree.
+ * Twin of motion_constraints.global_rotations. Returns 27 fresh matrices in
+ * cskel27 index order.
+ */
+export function globalRotations(localRotations) {
+	const locals = requireJointMatrices(localRotations, "globalRotations(localRotations)");
+	const out = new Array(CSKEL27_PARENTS.length);
+	for (const index of CSKEL27_TOPOLOGICAL_ORDER) {
+		const parent = CSKEL27_PARENTS[index];
+		out[index] =
+			parent === null
+				? locals[index].map((row) => row.slice())
+				: matMul(out[parent], locals[index]);
+	}
+	return out;
+}
+
+/**
+ * Constant bone vectors, each expressed in its parent's global frame, derived
+ * from one posed frame: offset = R_parent^T @ (child - parent).
+ * Twin of motion_constraints.derive_bone_offsets (argument order swapped: JS
+ * call sites pass the source positions first). Deriving them from the clip
+ * rather than hardcoding a rest skeleton keeps this correct if ARDY ever
+ * reproportions cskel27.
+ */
+export function deriveBoneOffsets(jointPositions, localRotations) {
+	const positions = requireJointVectors(jointPositions, "deriveBoneOffsets(jointPositions, ...)");
+	const rotations = globalRotations(localRotations);
+	const offsets = new Array(CSKEL27_PARENTS.length);
+	for (let index = 0; index < offsets.length; index += 1) {
+		offsets[index] = [0, 0, 0];
+	}
+	for (const index of CSKEL27_TOPOLOGICAL_ORDER) {
+		const parent = CSKEL27_PARENTS[index];
+		if (parent === null) continue;
+		const delta = [
+			positions[index][0] - positions[parent][0],
+			positions[index][1] - positions[parent][1],
+			positions[index][2] - positions[parent][2],
+		];
+		offsets[index] = matVec(matTranspose(rotations[parent]), delta);
+	}
+	return offsets;
+}
+
+/**
+ * Joint positions in npz space for one posed frame: the mapping that answers
+ * "where does the ARDY skeleton put this joint when posed like these
+ * rotations". Twin of motion_constraints.forward_kinematics. `rootPosition`
+ * defaults to the npz origin when the caller only needs relative pose.
+ */
+export function forwardKinematics(localRotations, boneOffsets, rootPosition = [0, 0, 0]) {
+	const rotations = globalRotations(localRotations);
+	requireJointVectors(boneOffsets, "forwardKinematics(...): boneOffsets");
+	const root = requireVec3(rootPosition, "forwardKinematics(...): rootPosition");
+	const positions = new Array(CSKEL27_PARENTS.length);
+	for (const index of CSKEL27_TOPOLOGICAL_ORDER) {
+		const parent = CSKEL27_PARENTS[index];
+		if (parent === null) {
+			positions[index] = root.slice();
+			continue;
+		}
+		const moved = matVec(rotations[parent], boneOffsets[index]);
+		positions[index] = [
+			positions[parent][0] + moved[0],
+			positions[parent][1] + moved[1],
+			positions[parent][2] + moved[2],
+		];
+	}
+	return positions;
+}

package/src/ardy/cskel27-neutral.js

@@ -0,0 +1,39 @@
+/**
+ * CoreSkeleton27 neutral-pose joint positions (metres, Y-up), exported
+ * verbatim from the box (`CoreSkeleton27().neutral_joints`, ~/ardy) — the
+ * same reference the viser demo's Mixamo avatar uses as ardy_bind_positions
+ * in compute_bone_transforms. Index order == CSKEL27_JOINTS. The hips sit
+ * at the origin and the lowest joint (toes) at y = -0.9544128.
+ *
+ * Positional skinning needs this: a bone's bind offset is measured
+ * against the ARDY neutral joint, not against the rig's own rest pose.
+ */
+export const CSKEL27_NEUTRAL = [
+	[0.0, 0.0, 0.0], // Hips
+	[0.0, 0.0709891, -0.0473261], // Spine
+	[0.0, 0.1642033, -0.0637623], // Spine1
+	[0.0, 0.2584953, -0.0720118], // Spine2
+	[0.0, 0.3531475, -0.0720119], // Spine3
+	[0.0, 0.6016096, -0.0365176], // Neck
+	[0.0, 0.7297793, -0.0139179], // Head
+	[-0.0319949, 0.5259196, -0.0186873], // RightShoulder
+	[-0.1909029, 0.5259195, -0.0186873], // RightArm
+	[-0.4863389, 0.5259194, -0.0186873], // RightForeArm
+	[-0.7189909, 0.5259193, -0.0186873], // RightHand
+	[-0.7886024, 0.5259193, -0.0186873], // RightHandEnd
+	[-0.7468355, 0.5073563, 0.0277204], // RightHandThumb1
+	[0.0319949, 0.5259196, -0.0186873], // LeftShoulder
+	[0.1909029, 0.5259196, -0.0186873], // LeftArm
+	[0.4863389, 0.5259196, -0.0186873], // LeftForeArm
+	[0.7189909, 0.5259196, -0.0186873], // LeftHand
+	[0.7886024, 0.5259196, -0.0186873], // LeftHandEnd
+	[0.7468355, 0.5073565, 0.0277204], // LeftHandThumb1
+	[-0.0949182, -0.0277289, 0.0], // RightUpLeg
+	[-0.0949182, -0.4398469, 0.0], // RightLeg
+	[-0.0949182, -0.8959379, 0.0], // RightFoot
+	[-0.0949182, -0.9544128, 0.1606583], // RightToeBase
+	[0.0949182, -0.0277289, 0.0], // LeftUpLeg
+	[0.0949182, -0.4398469, 0.0], // LeftLeg
+	[0.0949182, -0.8959379, 0.0], // LeftFoot
+	[0.0949182, -0.9544128, 0.1606583], // LeftToeBase
+];

package/src/ardy/cskel27.js

@@ -0,0 +1,68 @@
+/**
+ * cskel27 joint order and parent hierarchy, transcribed verbatim from the
+ * ARDY reference implementation:
+ *   - CSKEL27_JOINTS mirrors `motion_retarget.CSKEL27_JOINTS`
+ *     (/Users/yun/CozyClay/blender-addon/cclay/motion_retarget.py)
+ *   - CSKEL27_PARENTS mirrors `motion_constraints._PARENT_BY_NAME` /
+ *     `CSKEL27_PARENTS` (/Users/yun/CozyClay/blender-addon/cclay/motion_constraints.py)
+ *
+ * Index in CSKEL27_JOINTS == joint index in the npz arrays
+ * (local_rot_mats[:, i], posed_joints[:, i]). motion_retarget deliberately
+ * carries no hierarchy (it is rotation-only); the parent table was verified
+ * numerically in the Python repo (deriving offsets from one frame and running
+ * FK across every other frame reproduces the npz's own posed_joints to
+ * ~2.8e-07, float32 serialization noise) — a wrong parent moves that error to
+ * whole npz units immediately, so this table must stay exact.
+ */
+
+/** The 27 ARDY core-skeleton joints in index order. */
+export const CSKEL27_JOINTS = [
+	"Hips", "Spine", "Spine1", "Spine2", "Spine3", "Neck", "Head",
+	"RightShoulder", "RightArm", "RightForeArm", "RightHand",
+	"RightHandEnd", "RightHandThumb1",
+	"LeftShoulder", "LeftArm", "LeftForeArm", "LeftHand",
+	"LeftHandEnd", "LeftHandThumb1",
+	"RightUpLeg", "RightLeg", "RightFoot", "RightToeBase",
+	"LeftUpLeg", "LeftLeg", "LeftFoot", "LeftToeBase",
+];
+
+const JOINT_INDEX = Object.fromEntries(
+	CSKEL27_JOINTS.map((name, index) => [name, index])
+);
+
+// Parent per joint by name, transcribed verbatim from
+// motion_constraints._PARENT_BY_NAME. The root (Hips) has no parent.
+const PARENT_BY_NAME = {
+	"Hips": null,
+	"Spine": "Hips", "Spine1": "Spine", "Spine2": "Spine1", "Spine3": "Spine2",
+	"Neck": "Spine3", "Head": "Neck",
+	"RightShoulder": "Spine3", "RightArm": "RightShoulder",
+	"RightForeArm": "RightArm", "RightHand": "RightForeArm",
+	"RightHandEnd": "RightHand", "RightHandThumb1": "RightHand",
+	"LeftShoulder": "Spine3", "LeftArm": "LeftShoulder",
+	"LeftForeArm": "LeftArm", "LeftHand": "LeftForeArm",
+	"LeftHandEnd": "LeftHand", "LeftHandThumb1": "LeftHand",
+	"RightUpLeg": "Hips", "RightLeg": "RightUpLeg",
+	"RightFoot": "RightLeg", "RightToeBase": "RightFoot",
+	"LeftUpLeg": "Hips", "LeftLeg": "LeftUpLeg",
+	"LeftFoot": "LeftLeg", "LeftToeBase": "LeftFoot",
+};
+
+/** Parent joint index per cskel27 index; the root (Hips) is null. */
+export const CSKEL27_PARENTS = CSKEL27_JOINTS.map(
+	(name) => (PARENT_BY_NAME[name] === null ? null : JOINT_INDEX[PARENT_BY_NAME[name]])
+);
+
+/** The 19 joints CozyClay edits (src/poses.js POSE_BONES), as cskel27 names. */
+export const COZYCLAY_BONES = [
+	"Hips", "Spine", "Spine1", "Neck", "Head",
+	"LeftShoulder", "RightShoulder", "LeftArm", "RightArm",
+	"LeftForeArm", "RightForeArm", "LeftHand", "RightHand",
+	"LeftUpLeg", "RightUpLeg", "LeftLeg", "RightLeg",
+	"LeftFoot", "RightFoot",
+];
+
+/** CozyClay bone name -> cskel27 joint index. */
+export const COZYCLAY_TO_CSKEL27 = Object.fromEntries(
+	COZYCLAY_BONES.map((name) => [name, JOINT_INDEX[name]])
+);