cozyclay 2.1.0 → 3.0.0

package/src/motion/waypoints.js

@@ -0,0 +1,76 @@
+import { isKo } from "../locale.js";
+
+// Root path pins: the limits keep an authored path a person could walk, and a
+// capsule figure that rides the path moves at a believable pace.
+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
+});
+
+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: isKo ? `핀 사이에는 최소 ${PATH_LIMITS.minPinGapFrames}프레임(${(PATH_LIMITS.minPinGapFrames / fps).toFixed(1)}초)이 필요해요 — ${last.frame + PATH_LIMITS.minPinGapFrames}프레임 이후로 이동해 주세요` : `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: isKo ? `${speed.toFixed(1)} m/s는 사람이 움직이기엔 너무 빨라요(최대 ${PATH_LIMITS.speedMaxMps}) — ${last.frame + neededFrames}프레임 이후에 핀을 찍거나 더 가까운 곳을 눌러 주세요` : `${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: isKo ? `${speed.toFixed(2)} m/s는 자연스럽게 걷기엔 너무 느려요(최소 ${PATH_LIMITS.speedMinMps}) — 대신 약 ${walkFrame}프레임에 핀을 찍거나 최소 ${neededDist} m 이상 떨어진 곳을 눌러 주세요` : `${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(isKo ? `이전 구간보다 속도가 ${ratio.toFixed(1)}배 달라요 — 걸음 변화가 눈에 보일 수 있어요` : `${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(isKo ? `${dt.toFixed(1)}초 동안 ${Math.round((turn * 180) / Math.PI)}° 회전은 걷는 동선치고 너무 급해요 — 프레임이나 거리를 더 주세요` : `${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 };
+}

package/src/motion3/beats.js

@@ -0,0 +1,83 @@
+// C11. What a beats contact sheet shows and what a trace plots, read from one compile of the
+// installed take (pipeline.js compileSpec: out, qa, timeline, the expanded spec). Pure; see
+// docs/motion-api-v3.1.md C11. Frames are absolute timeline frames (a whole compile has f0 = 0).
+import { refPoint, refDistance } from "./refs.js";
+
+const NEAR = 3, MAX_SERIES = 6;
+export const TRACE_COLORS = ["#d1495b", "#2e86ab", "#edae49", "#66a182", "#a06cd5", "#f28f3b"];
+const round3 = v => Math.round(v * 1000) / 1000;
+
+/** Grab and release frames: the timeline's events (lane C), then the spec.objects grab/release
+ * fields (C3), so a take still shows them when the timeline lists no event. */
+export function grabReleases(timeline = [], objects = {}) {
+	const rows = [];
+	for (const entry of timeline) for (const e of entry.events ?? []) if (e.event === "grab" || e.event === "release") rows.push({ f: e.f, why: `${e.event} ${e.object}` });
+	for (const [id, o] of Object.entries(objects ?? {})) for (const event of ["grab", "release"]) if (Number.isFinite(o?.[event])) rows.push({ f: o[event], why: `${event} ${id}` });
+	return rows.sort((a, b) => a.f - b.f);
+}
+
+/**
+ * Up to `count` frames inside [lo, hi], in this order: grab and release frames, beat starts
+ * (timeline f[0]), the worstFrame of the top 2 QA groups (qa.groups is ranked), then even fill:
+ * the `even` frames, then any frame, each time the one farthest from the frames picked so far.
+ * A frame within +-3 of a pick is dropped. Deterministic; answers { frames, picks: [{ f, why }] },
+ * ascending. With nothing to read it answers the even frames.
+ */
+export function beatFrames({ range: [lo, hi], even = [], timeline = [], groups = [], objects = {}, count = 6 }) {
+	const picks = [], gap = f => picks.reduce((d, p) => Math.min(d, Math.abs(p.f - f)), Infinity);
+	const offer = (f, why) => {
+		if (!Number.isFinite(f)) return;
+		f = Math.round(f);
+		if (picks.length < count && f >= lo && f <= hi && gap(f) > NEAR) picks.push({ f, why });
+	};
+	for (const row of grabReleases(timeline, objects)) offer(row.f, row.why);
+	for (const entry of timeline) offer(entry.f?.[0], `start ${entry.beat}`);
+	for (const g of groups.slice(0, 2)) offer(g.worstFrame, `worst ${g.kind} ${String(g.subject).split(": ")[0]}`);
+	const every = Array.from({ length: Math.max(0, hi - lo + 1) }, (_, i) => lo + i);
+	for (const pool of [even.filter(f => f >= lo && f <= hi), every]) {
+		while (picks.length < count) {
+			let best = null, far = NEAR;
+			for (const f of pool) { const d = gap(f); if (d > far) { best = f; far = d; } }
+			if (best === null) break;
+			picks.push({ f: best, why: "even" });
+		}
+	}
+	picks.sort((a, b) => a.f - b.f);
+	return { frames: picks.map(p => p.f), picks };
+}
+
+/** What a trace plots: both hand heights, the distance of every `near` goal and every distance
+ * probe the spec carries, and each carried object's prop origin to the object's surface. */
+function traceDefs(spec = {}) {
+	const defs = [
+		{ name: "hand_l.y", at: (out, f) => refPoint(out, f, "joint:LeftHand")?.[1] },
+		{ name: "hand_r.y", at: (out, f) => refPoint(out, f, "joint:RightHand")?.[1] },
+	];
+	const pair = (name, [a, b]) => defs.push({ name, at: (out, f) => refDistance(out, f, a, b) });
+	(spec.goals ?? []).forEach((g, i) => { if (Array.isArray(g?.near)) pair(`near ${g.name ?? `goals[${i}]`}`, g.near); });
+	(spec.probes ?? []).forEach((p, i) => { if (Array.isArray(p?.distance)) pair(p.name ?? `probes[${i}]`, p.distance); });
+	for (const [id, o] of Object.entries(spec.objects ?? {})) if (typeof o?.prop === "string") pair(`${o.prop} to ${id}`, [`prop:${o.prop}.origin`, `object:${id}`]);
+	return defs.slice(0, MAX_SERIES);
+}
+
+/**
+ * Series over absolute frames lo..hi (clamped to the compiled frames): { name, color, unit,
+ * min, minAt, max, maxAt, values } with values[i] the value at frame lo + i, or null. A series
+ * with no value anywhere is left out.
+ */
+export function traceSeries(out, spec, [lo, hi]) {
+	const f0 = out.f0 ?? 0, last = Math.min(hi, f0 + out.frames.length - 1), first = Math.max(lo, f0), series = [];
+	for (const def of traceDefs(spec)) {
+		const values = [];
+		let min = Infinity, minAt = null, max = -Infinity, maxAt = null;
+		for (let f = first; f <= last; f++) {
+			const raw = def.at(out, f), v = Number.isFinite(raw) ? round3(raw) : null;
+			values.push(v);
+			if (v === null) continue;
+			if (v < min) { min = v; minAt = f; }
+			if (v > max) { max = v; maxAt = f; }
+		}
+		if (minAt !== null) series.push({ name: def.name, color: TRACE_COLORS[series.length], unit: "m", min, minAt, max, maxAt, values });
+	}
+	return { range: [first, last], series };
+}

package/src/motion3/body.js

@@ -0,0 +1,158 @@
+// The body a limb must stay out of, fitted from the rig's skin (tools/motion3/extract-body.mjs):
+// a signed distance grid per skinned bone in that bone's bind frame (the bone carries it rigidly;
+// outside positive, metres) and, for the limbs, the skin radius along the bone. A limb collides as
+// spheres on its bone axis (limbProbes); bodyDistance is the nearest skin of every other bone but
+// the limb's own neighbours (SKIP), so an arm reads the torso, the head, the legs and the other arm.
+import yBody from "./rigs/y-bot-tpose-body.json" with { type: "json" };
+import xBody from "./rigs/x-bot-tpose-body.json" with { type: "json" };
+import { add, sub, scale, apply, T, len, dot, clamp } from "./compiler/math.js";
+
+const BODIES = { "y-bot-tpose": yBody, "x-bot-tpose": xBody };
+/** Distance read outside a grid: far enough that no probe counts it as touching. */
+const FAR = 0.1;
+const cache = new Map();
+
+function decode(text) {
+	const bytes = typeof Buffer !== "undefined" ? Buffer.from(text, "base64") : Uint8Array.from(atob(text), c => c.charCodeAt(0));
+	return new Int8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+/** The neighbours a limb bone may touch without colliding: itself, its parent, its children, and for
+ * an upper arm the collarbone and chest it hangs from (only near the shoulder: see limbProbes). */
+function skipOf(sk, b) {
+	const out = new Set([b, sk.parent[b], ...sk.children[b]]);
+	if (/^(Left|Right)Arm$/.test(sk.names[b])) out.add(sk.parent[sk.parent[b]]);
+	if (/^(Left|Right)UpLeg$/.test(sk.names[b])) out.add(sk.index.Spine);
+	return out;
+}
+
+/** The fitted body of skeleton sk, or null for a rig without one. */
+export function bodyFor(sk) {
+	const fit = BODIES[sk.model];
+	if (!fit) return null;
+	if (cache.has(sk.model)) return cache.get(sk.model);
+	const grids = Object.entries(fit.grids).map(([name, g]) => {
+		const half = g.dims.map(d => ((d - 1) * fit.step) / 2), centre = g.min.map((m, k) => m + half[k]);
+		return { b: sk.index[name], min: g.min, dims: g.dims, data: decode(g.data), centre, reach: len(half) };
+	});
+	const radii = Object.fromEntries(Object.entries(fit.radii).map(([name, r]) => [sk.index[name], r]));
+	const body = { step: fit.step, grids, radii, skip: new Map(Object.keys(radii).map(b => [+b, skipOf(sk, +b)])) };
+	cache.set(sk.model, body);
+	return body;
+}
+
+/** Trilinear signed distance (m) of a point in grid g's bone frame. */
+function sample(body, g, q) {
+	const [nx, ny, nz] = g.dims, step = body.step;
+	const fx = (q[0] - g.min[0]) / step, fy = (q[1] - g.min[1]) / step, fz = (q[2] - g.min[2]) / step;
+	if (fx < 0 || fy < 0 || fz < 0 || fx > nx - 1 || fy > ny - 1 || fz > nz - 1) return FAR;
+	const x = Math.min(nx - 2, Math.floor(fx)), y = Math.min(ny - 2, Math.floor(fy)), z = Math.min(nz - 2, Math.floor(fz));
+	const u = fx - x, v = fy - y, w = fz - z, at = (i, j, k) => g.data[((x + i) * ny + y + j) * nz + z + k];
+	const c00 = at(0, 0, 0) * (1 - u) + at(1, 0, 0) * u, c01 = at(0, 0, 1) * (1 - u) + at(1, 0, 1) * u;
+	const c10 = at(0, 1, 0) * (1 - u) + at(1, 1, 0) * u, c11 = at(0, 1, 1) * (1 - u) + at(1, 1, 1) * u;
+	return ((c00 * (1 - v) + c10 * v) * (1 - w) + (c01 * (1 - v) + c11 * v) * w) / 1000;
+}
+
+/** Each grid's centre in the world at state s (cached per state: a planner asks thousands of points of one pose). */
+const centres = new WeakMap();
+function centresAt(body, s) {
+	let c = centres.get(s);
+	if (!c) { c = body.grids.map(g => add(s.P[g.b], apply(s.R[g.b], g.centre))); centres.set(s, c); }
+	return c;
+}
+
+/** Signed distance (m) from p to the skin of every bone not in `skip`, with the bone it came from. */
+export function bodyDistance(body, s, p, skip = null) {
+	let best = FAR, bone = -1;
+	const c = centresAt(body, s);
+	body.grids.forEach((g, i) => {
+		if (skip?.has(g.b) || len(sub(p, c[i])) - g.reach > best) return;
+		const d = sample(body, g, apply(T(s.R[g.b]), sub(p, s.P[g.b])));
+		if (d < best) { best = d; bone = g.b; }
+	});
+	return { d: best, bone };
+}
+
+/** Unit direction out of the skin at p (central differences of bodyDistance). */
+export function bodyNormal(body, s, p, skip = null, h = 0.01) {
+	const g = [0, 1, 2].map(k => {
+		const e = [0, 0, 0]; e[k] = h;
+		return bodyDistance(body, s, add(p, e), skip).d - bodyDistance(body, s, sub(p, e), skip).d;
+	});
+	const l = len(g);
+	return l > 1e-9 ? scale(g, 1 / l) : null;
+}
+
+/** Spheres { p, r, t } on limb bone b's axis (to its first child), from the fitted skin radius. Near an
+ * upper arm's shoulder (its armpit half: arm and chest skin are one there) or a thigh's hip the trunk is
+ * its neighbour, so those stations are left out. */
+const rootOf = name => (/^(Left|Right)Arm$/.test(name) ? 0.5 : /^(Left|Right)UpLeg$/.test(name) ? 0.3 : 0);
+/** Where limb bone b's axis ends: its child joint, for a hand the middle finger's knuckle (the first
+ * child is a thumb or a ring finger, rig by rig). */
+export const axisEnd = (sk, b) => (/Hand$/.test(sk.names[b]) ? sk.index[sk.names[b].replace(/Hand$/, "HandMiddle1")] : sk.children[b][0]);
+function limbProbes(body, sk, s, b) {
+	const prof = body.radii[b], child = axisEnd(sk, b);
+	if (!prof || child === undefined) return [];
+	const A = s.P[b], axis = sub(s.P[child], A), root = rootOf(sk.names[b]);
+	return prof.filter(([t]) => t >= root).map(([t, r]) => ({ p: add(A, scale(axis, t)), r, t }));
+}
+
+/** The trunk runs Hips-Spine-Spine1-Spine2-Neck: a trunk bone's axis goes to its trunk child, a limb's to axisEnd. */
+const TRUNK = /^(Spine\d?|Neck|Head)$/;
+const axisOf = (sk, b) => sk.children[b].find(j => TRUNK.test(sk.names[j])) ?? axisEnd(sk, b);
+
+/**
+ * Point p moved out of the body (bones not in `skip`) until its skin distance is at least `clear`, along
+ * the line from the axis of the bone it is in: deep inside, the skin's normal turns with every millimetre,
+ * the way out from the bone does not, so a target sliding through a thigh slides out of it smoothly.
+ * The distance along that line is found by bisection. p itself when it is clear already.
+ */
+const OUT_MAX = 0.25;
+export function keepOut(body, sk, s, p, clear, skip = null) {
+	const hit = bodyDistance(body, s, p, skip);
+	if (hit.d >= clear || hit.bone < 0) return p;
+	const A = s.P[hit.bone], end = axisOf(sk, hit.bone), B = end === undefined ? A : s.P[end], ab = sub(B, A);
+	const t = dot(ab, ab) > 1e-9 ? clamp(dot(sub(p, A), ab) / dot(ab, ab), 0, 1) : 0, off = sub(p, add(A, scale(ab, t)));
+	const dir = len(off) > 1e-4 ? scale(off, 1 / len(off)) : bodyNormal(body, s, p, skip);
+	if (!dir) return p;
+	// clear of the bone it is in (another bone on the way out is the next call's: one bone at a time stays bounded)
+	const only = new Set(body.grids.map(g => g.b).filter(b => b !== hit.bone)), clearAt = k => bodyDistance(body, s, add(p, scale(dir, k)), only).d >= clear;
+	let lo = 0, hi = 0.02;
+	while (!clearAt(hi) && hi < OUT_MAX) { lo = hi; hi = Math.min(OUT_MAX, hi * 2); }
+	for (let i = 0; i < 10; i++) { const mid = (lo + hi) / 2; if (clearAt(mid)) hi = mid; else lo = mid; }
+	return add(p, scale(dir, hi));
+}
+
+/** How far (m) a wrist target stays off the skin (the hand's radius at the wrist, and a little). */
+export const HAND_CLEAR = 0.03;
+/** What a wrist target keeps out of: the body but the arms (they move with it) and the head and neck (a hand
+ * comes to the mouth or the face on purpose: QA's BODY and FACE report what goes too deep). null without a body. */
+export function wristBody(sk) {
+	const body = bodyFor(sk);
+	return body && { body, skip: new Set(sk.names.map((n, b) => (/(Arm|ForeArm|Hand|Neck|Head.*)$/.test(n) ? b : -1)).filter(b => b >= 0)) };
+}
+
+/** How deep (m) limb bone b goes into the rest of the body were its axis A-B (its own pose may differ:
+ * a planner trying an elbow), 0 when clear. */
+export function segmentDepth(body, sk, s, b, A, B) {
+	let worst = 0;
+	const root = rootOf(sk.names[b]);
+	for (const [t, r] of body.radii[b] ?? []) {
+		if (t < root) continue;
+		const { d, bone } = bodyDistance(body, s, add(A, scale(sub(B, A), t)), body.skip.get(b));
+		if (bone >= 0) worst = Math.max(worst, r - d);
+	}
+	return worst;
+}
+
+/** How far (m) limb bone b's skin goes into the rest of the body at state s (0 when clear), where, and into which bone. */
+export function limbDepth(body, sk, s, b) {
+	let worst = { depth: 0, p: null, into: -1 };
+	for (const probe of limbProbes(body, sk, s, b)) {
+		const { d, bone } = bodyDistance(body, s, probe.p, body.skip.get(b));
+		const depth = probe.r - d;
+		if (bone >= 0 && depth > worst.depth) worst = { depth, p: probe.p, into: bone, r: probe.r };
+	}
+	return worst;
+}
+

package/src/motion3/bones.js

@@ -0,0 +1,47 @@
+// Bone names as the agent writes them -> the rig's bone. Tried in order: the exact name, the
+// name in any case ("hips", "lefthand"), the name without a "mixamorig:" prefix, then aliases
+// ("pelvis" -> Hips, "hand_l" / "l_hand" / "left hand" -> LeftHand, "thigh_r" -> RightUpLeg).
+// Nothing found: a "did you mean" suggestion. Callers that hand the name on to code that needs
+// the exact name (validate-common.js boneOk, sk.index) use the answered `bone`.
+import { didYouMean } from "./compiler/vocab.js";
+
+// Unsided aliases (lower case, no separators) -> the rig's name.
+const ALIAS = { pelvis: "Hips", hip: "Hips", hips: "Hips", root: "Hips", chest: "Spine2", upperchest: "Spine2", torso: "Spine1", belly: "Spine",
+	abdomen: "Spine", neck: "Neck", head: "Head" };
+// Sided part aliases -> the part after Left/Right.
+const PART = { hand: "Hand", wrist: "Hand", foot: "Foot", ankle: "Foot", toe: "ToeBase", toes: "ToeBase", ball: "ToeBase", arm: "Arm", upperarm: "Arm",
+	forearm: "ForeArm", lowerarm: "ForeArm", elbow: "ForeArm", shoulder: "Shoulder", clavicle: "Shoulder", thigh: "UpLeg", upleg: "UpLeg",
+	upperleg: "UpLeg", leg: "Leg", lowerleg: "Leg", shin: "Leg", calf: "Leg", knee: "Leg" };
+const SIDE = { l: "Left", left: "Left", r: "Right", right: "Right" };
+
+const squash = s => s.toLowerCase().replace(/[\s_.-]+/g, "");
+
+function caseless(sk, name) {
+	const want = name.toLowerCase();
+	return sk.names.find(n => n.toLowerCase() === want) ?? null;
+}
+
+function alias(sk, name) {
+	const flat = squash(name);
+	if (ALIAS[flat]) return caseless(sk, ALIAS[flat]);
+	const low = name.toLowerCase().trim();
+	const pre = /^(l|r|left|right)[\s_.-]+(.+)$/.exec(low) ?? /^(left|right)(.+)$/.exec(low);
+	const post = /^(.+?)[\s_.-]+(l|r|left|right)$/.exec(low) ?? /^(.+?)(left|right)$/.exec(low);
+	const [side, part] = pre ? [pre[1], pre[2]] : post ? [post[2], post[1]] : [];
+	if (!side) return null;
+	return caseless(sk, `${SIDE[side]}${PART[squash(part)] ?? squash(part)}`);
+}
+
+/**
+ * @param {{ index: Record<string, number>, names: string[] }} sk  the rig (rigs/index.js skeletonFor)
+ * @param {string} name
+ * @returns {{ bone: string | null, hint: string }} bone = the rig's own name, or null; hint = the
+ *   suffix for an error message when bone is null ('; did you mean "LeftHand"?' or "").
+ */
+export function resolveBone(sk, name) {
+	if (typeof name !== "string" || !name) return { bone: null, hint: "" };
+	if (sk.index[name] !== undefined) return { bone: name, hint: "" };
+	const bare = name.replace(/^mixamorig\d*:/i, "");
+	const bone = caseless(sk, name) ?? caseless(sk, bare) ?? alias(sk, bare);
+	return bone ? { bone, hint: "" } : { bone: null, hint: didYouMean(bare, sk.names) };
+}

package/src/motion3/carried.js

@@ -0,0 +1,47 @@
+// Scene objects a hand carries: spec.objects[id] = { prop, grab?, release?, at?, along?, visible? }
+// puts the record (a body, or a group root) on prop `prop` (spec.props). `at` is the record's base
+// along the palm axes [d, l, n] from the prop origin, `along` the palm direction its +Y (a
+// cylinder's length) takes, and `visible` a channel that shows the record while it is above 0.5
+// (a step key in the pocket). Without at/along a grabbed record keeps the transform it had
+// against the palm at the grab frame (object-pose.js). Also the rigid-pose algebra and the hinge
+// pose the compiler, the take and QA share.
+import { palmAxes } from "./compiler/limbs.js";
+import { SIDES } from "./compiler/pose.js";
+import { add, scale, norm, sub, dot, cross, apply, mul, T, axisRot, I3 } from "./compiler/math.js";
+
+export const isCarried = o => typeof o?.prop === "string";
+/** A follow entry { follow: <ref>, offset?, aim?, visible?, level? } (C16, follow.js): the record rides a point of the body. */
+export const isFollow = o => !isCarried(o) && o?.follow !== undefined;
+/** A switch entry { visible?, level? } (C15): no prop, follow, hinge, keys or fall field (C17), so it moves nothing; it shows, hides or dims its record. */
+export const isSwitch = o => !!o && typeof o === "object" && !Array.isArray(o) && ["prop", "follow", "pivot", "axis", "channel", "keys", "fall"].every(k => o[k] === undefined);
+/** An entry that moves its record (a carry, a follow or a hinge), as opposed to a switch. */
+export const movesRecord = o => !!o && typeof o === "object" && !isSwitch(o);
+
+/** Mean of the prop's origin joints on pose s (the point the hand holds the prop by). */
+export function propOrigin(sk, spec, s, o) {
+	const prop = spec.props[o.prop];
+	return scale(prop.origin.map(b => s.P[sk.index[b]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / prop.origin.length);
+}
+
+/** World { pos, R } of a carried record on pose s (at/along offset, PR #14). */
+export function carriedPose(sk, spec, s, o) {
+	const ax = palmAxes(sk, s, SIDES[spec.props[o.prop].hand]), origin = propOrigin(sk, spec, s, o);
+	const palm = v => add(scale(ax.d, v[0]), add(scale(ax.l, v[1]), scale(ax.n, v[2])));
+	const y = norm(palm(o.along ?? [0, 0, 1]));
+	let x = sub(ax.d, scale(y, dot(ax.d, y)));
+	if (Math.hypot(...x) < 1e-6) x = sub(ax.l, scale(y, dot(ax.l, y)));
+	x = norm(x);
+	const z = cross(x, y);
+	return { pos: add(origin, palm(o.at ?? [0, 0, 0])), R: [[x[0], y[0], z[0]], [x[1], y[1], z[1]], [x[2], y[2], z[2]]] };
+}
+
+/** a * b for rigid poses { pos, R }. */
+export const compose = (a, b) => ({ pos: add(a.pos, apply(a.R, b.pos)), R: mul(a.R, b.R) });
+/** a^-1 * b: b in a's frame. */
+export const relative = (a, b) => ({ pos: apply(T(a.R), sub(b.pos, a.pos)), R: mul(T(a.R), b.R) });
+
+/** A record at `rest` turned by hinge { pivot, axis, channel } at frame f of the baked channels. */
+export function hingePose(hinge, rest, baked, f) {
+	const angle = baked[hinge.channel]?.[f] ?? 0, R = axisRot(hinge.axis ?? [0, 1, 0], angle);
+	return { pos: add(hinge.pivot, apply(R, sub(rest.pos, hinge.pivot))), R: mul(R, rest.R ?? I3()), angle };
+}

package/src/motion3/compile-job.js

@@ -0,0 +1,75 @@
+// One motion compile as a job of plain data, the same in the compile worker (compile-worker.js) and on
+// the calling thread (commands/motion3-compile.js, where no worker runs: Node, tests): the rig by model
+// name, the motion scene (scene.js motionScene of the editor's objects: boxes only), the spec as sent, and
+// what to do with it (probes, checks, lenient, repair, bake). The answer is plain data and typed arrays
+// only (the compiler's out holds closures), so it crosses a worker boundary: QA, observations, the stored
+// spec, and the baked take when asked.
+// A refusal is an Error with a code (INVALID_ARGUMENT, MOTION_SPEC_INVALID turned into it), which the
+// client turns back into the Studio's protocol error.
+import { compileSpec, liftRequest } from "./pipeline.js";
+import { repairSpec } from "./repair.js";
+import { bakeTake } from "./take.js";
+import { skeletonFor } from "./rigs/index.js";
+
+const TIMELINE_FPS = 24;
+const refuse = (code, message) => { throw Object.assign(new Error(message), { code }); };
+
+/** Runs `run`, turning a MOTION_SPEC_INVALID error into INVALID_ARGUMENT with the exact message. */
+function asArgument(run) {
+	try {
+		return run();
+	} catch (error) {
+		if (/^MOTION_SPEC_INVALID/.test(error.message)) refuse("INVALID_ARGUMENT", error.message.replace(/^MOTION_SPEC_INVALID:\s*/, ""));
+		throw error;
+	}
+}
+
+/**
+ * The same plain data as fresh literals. Objects that came through a structured clone (a worker message) make
+ * the compiler's hot loops ~60% slower in V8 (their shapes); a copy built from literals runs at full speed and
+ * keeps every value exactly (unlike a JSON round trip: -0, NaN, Infinity).
+ */
+const fresh = value => (Array.isArray(value) ? value.map(fresh) : value && typeof value === "object" && !ArrayBuffer.isView(value)
+	? Object.fromEntries(Object.keys(value).map(k => [k, fresh(value[k])])) : value);
+
+/**
+ * runCompileJob({ model, scene, spec, probes?, checks?, lenient?, repair?, bake? }) -> { stored, qa, observations,
+ * used, fixed, search, timeline, probes?, notes?, ms (+ repair: its wall ms), frameCount, label, repair?, take? }
+ * bake: { position, yaw, prompt? } bakes the final result's take (prompt: given, else the final spec's label).
+ */
+export function runCompileJob({ model, scene, spec: asked, probes: sentProbes, checks, lenient, repair, bake }) {
+	const sk = skeletonFor(model);
+	const opts = { ...(checks ? { checks } : {}), ...(lenient ? { lenient: true } : {}) };
+	// spec.probes and bare moved ids are lifted before fps is filled in, so the specId stays the spec's own
+	const once = s => {
+		const { spec, probes } = liftRequest(s, sentProbes);
+		if (spec?.fps !== undefined && spec.fps !== TIMELINE_FPS) refuse("INVALID_ARGUMENT", `spec.fps must be ${TIMELINE_FPS}, the timeline rate.`);
+		const sent = { fps: TIMELINE_FPS, ...spec };
+		const r = asArgument(() => compileSpec(sent, { sk, scene }, { ...opts, probes }));
+		return { ...r, stored: r.spec === sent ? spec : r.spec };
+	};
+	const t0 = performance.now(), fixed = repair ? repairSpec(asked, repair, once) : { spec: asked, result: once(asked) };
+	// ms.repair: the whole repair's wall time, so a sweep that repairs every variant shows what it costs
+	const r = fixed.result, label = fixed.spec?.label ?? null, ms = fixed.repair ? { ...r.ms, repair: Math.round(performance.now() - t0) } : r.ms;
+	const take = bake ? bakeTake(sk, r.out, { position: bake.position, yaw: bake.yaw }, { spec: r.stored, prompt: ("prompt" in bake ? bake.prompt : label) ?? "" }) : undefined;
+	return { stored: r.stored, qa: r.qa, observations: r.observations, used: r.used, fixed: r.fixed, search: r.search, timeline: r.timeline,
+		...(r.probes ? { probes: r.probes } : {}), ...(r.notes ? { notes: r.notes } : {}), ms, frameCount: r.out.frameCount, label,
+		...(fixed.repair ? { repair: fixed.repair } : {}), ...(take ? { take } : {}) };
+}
+
+/** The ArrayBuffers under a job answer's typed arrays (each once), to transfer instead of copy. */
+function buffersOf(value, found = new Set()) {
+	if (ArrayBuffer.isView(value)) found.add(value.buffer);
+	else if (value && typeof value === "object") for (const v of Object.values(value)) buffersOf(v, found);
+	return [...found];
+}
+
+/** The worker's answer to { id, job }: { message: { id, value }, transfer } or { message: { id, error: { message, code, name } }, transfer: [] }. */
+export function answerOf({ id, job }) {
+	try {
+		const value = runCompileJob(fresh(job));
+		return { message: { id, value }, transfer: buffersOf(value) };
+	} catch (error) {
+		return { message: { id, error: { message: String(error?.message ?? error), code: error?.code ?? null, name: error?.name ?? "Error" } }, transfer: [] };
+	}
+}

package/src/motion3/compile-worker.js

@@ -0,0 +1,10 @@
+// The motion compile worker: runs compile jobs (compile-job.js) off the editor's main thread, one at a time
+// in arrival order, and answers each { id } with { id, value } (typed arrays transferred) or { id, error }.
+// On the main thread the compiler runs about 4x slower than here (measured: 6.2 s against 1.5 s for a
+// 240-frame carry) and blocks the viewport and the agent panel for the whole compile.
+import { answerOf } from "./compile-job.js";
+
+self.onmessage = ({ data }) => {
+	const { message, transfer } = answerOf(data);
+	self.postMessage(message, transfer);
+};

package/src/motion3/compiler/anchors.js

@@ -0,0 +1,105 @@
+// Hand-target anchors and hand-held props for the motion3 compiler.
+//
+// spec.anchors = { name: anchor }, an anchor being one of
+//   { kind: "world",    p: [x,y,z] }                        fixed world point (m)
+//   { kind: "body",     p: [x,y,z] }                        root-relative, rotated by root yaw
+//   { kind: "bone",     bone: "LeftLeg", offset: [x,y,z] }  world offset from a bone joint
+//   { kind: "segment",  from: "LeftUpLeg", to: "LeftLeg", t: 0.4, offset: [x,y,z], reach: "l" }
+//                       point along a segment; with reach, slides toward `from` until the arm reaches
+//   { kind: "object",   object: "Car_Door_L", local: [x,y,z] }  point fixed to a scene object or group where it is at
+//                       that frame (hinged, carried, following; object-pose.js objectPoseAt), in its own axes
+//   { kind: "landmark", name: "mouth" }                     measured face landmark on the Head bone
+//   { kind: "prop",     prop: "cig", point: "tip", offset: [x,y,z] }  a point on a prop held by the other hand
+// spec.props = { name: { hand: "r", origin: ["RightHandIndex2", "RightHandMiddle2"],
+//                        points: { name: [d, l, n] } } }   offsets along the palm axes (m)
+import { add, sub, scale, len, apply, ry } from "./math.js";
+import { bonePoint } from "./skeleton.js";
+import { palmAxes } from "./limbs.js";
+import { SIDES } from "./pose.js";
+import { HAND_CLEAR, keepOut } from "../body.js";
+import { groupsOf } from "../scene.js";
+
+function armReach(sk, k) {
+	const side = SIDES[k], P = sk.restWorldPos, I = sk.index;
+	return len(sub(P[I[`${side}ForeArm`]], P[I[`${side}Arm`]])) + len(sub(P[I[`${side}Hand`]], P[I[`${side}ForeArm`]]));
+}
+
+/** Resolve a named anchor to a world point for the current (partial) frame state. */
+/** Anchors placed off the root (a pocket): with fix.self (ctx.keepOut, compile.js) a point the pose put inside
+ * the skin resolves onto it, HAND_CLEAR off, for the hand and for every check alike. A bone's or a segment's
+ * anchor is the spec's own place on that limb (a hand resting on a thigh) and stays. */
+const ON_BODY = new Set(["body"]);
+/** side: the hand ("l" | "r") this point is a target for while the compiler solves it; none for a reader of a solved frame. */
+export function resolveAnchor(ctx, name, s, diag, c, side) {
+	const a = ctx.spec.anchors?.[name];
+	if (!a) throw new Error(`MOTION_SPEC_INVALID: unknown anchor "${name}"`);
+	const p = anchorPoint(ctx, a, name, s, diag, c, side), skin = ON_BODY.has(a.kind) && ctx.keepOut;
+	return skin ? keepOut(skin.body, ctx.sk, s, keepOut(skin.body, ctx.sk, s, p, HAND_CLEAR, skin.skip), HAND_CLEAR, skin.skip) : p;
+}
+
+// pose.js solves the right arm, then the left
+const ARMS = ["r", "l"], HAND = { l: "left", r: "right" };
+
+/**
+ * The pose { pos, R } an object anchor's `local` is in at frame diag.frame: where the object is then (ctx.objectPose,
+ * the pose refs and probes read). A hand cannot aim at what rides on it: the hand that carries the object keeps the
+ * scene pose, where it took it. While the right arm is solved the left is not, so the right hand cannot aim at what
+ * the left carries (refused).
+ */
+export function objectFrame(ctx, a, name, { s, diag, c }, side) {
+	const f = diag.frame, still = () => ctx.restingAt?.(a.object, f) ?? ctx.objectsAt(f)[a.object] ?? groupsOf(ctx.scene)[a.object];
+	const hand = ctx.objectPose && f !== undefined ? ctx.objectHand(a.object, f) : null;
+	if (side && hand && ARMS.indexOf(hand) > ARMS.indexOf(side)) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" is on "${a.object}", which the ${HAND[hand]} hand holds at f${f}; the right arm is solved before the left, so the right hand cannot follow it. Carry "${a.object}" in the right hand (a right-hand prop) and put the left hand on it, or give the right hand another anchor`);
+	const pose = !ctx.objectPose || f === undefined || hand === side ? still() : nested(ctx, name, a.object, f, () => ctx.objectPose(a.object, f, { s, diag, c }));
+	if (!pose) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" names unknown object "${a.object}"`);
+	return pose;
+}
+
+// Reading an object may solve another frame (a keyed carry's grab offset, object-keys.js), whose hands read objects
+// again; legitimate reads nest a few deep, so a deeper chain is a loop and is refused instead of overflowing the stack.
+const MAX_NEST = 16;
+function nested(ctx, name, object, f, read) {
+	if ((ctx.nest ?? 0) >= MAX_NEST) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" on "${object}" at f${f} reads a pose that needs this frame solved again (an anchor and carry loop); anchor the hand on a point that does not ride on the hand it moves`);
+	ctx.nest = (ctx.nest ?? 0) + 1;
+	try { return read(); } finally { ctx.nest--; }
+}
+
+function anchorPoint(ctx, a, name, s, diag, c, side) {
+	const { sk } = ctx, I = sk.index;
+	switch (a.kind) {
+		case "world": return a.p.slice();
+		case "body": return add(c.root ?? s.P[I.Hips], apply(ry(c.yaw ?? 0), a.p));
+		case "bone": return add(s.P[I[a.bone]], a.offset ?? [0, 0, 0]);
+		case "segment": {
+			const A = s.P[I[a.from]], B = s.P[I[a.to]], off = a.offset ?? [0, 0, 0];
+			const at = t => add(add(A, scale(sub(B, A), t)), off);
+			if (!a.reach) return at(a.t ?? 0.5);
+			const sh = s.P[I[`${SIDES[a.reach]}Arm`]], r = 0.95 * armReach(sk, a.reach);
+			for (let t = a.t ?? 0.45; t >= (a.tMin ?? 0.15); t -= 0.01) if (len(sub(at(t), sh)) <= r) return at(t);
+			return at(a.tMin ?? 0.15);
+		}
+		case "object": { const o = objectFrame(ctx, a, name, { s, diag, c }, side); return add(o.pos, apply(o.R, a.local ?? [0, 0, 0])); }
+		case "landmark": return bonePoint(s, I.Head, sk.landmarks[a.name] ?? (() => { throw new Error(`MOTION_SPEC_INVALID: unknown landmark "${a.name}"`); })());
+		case "prop": {
+			const p = diag.props?.[a.prop]?.[a.point];
+			if (!p) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" needs prop ${a.prop}.${a.point}, which is held by an arm solved later`);
+			return add(p, a.offset ?? [0, 0, 0]);
+		}
+		default: throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" has unknown kind "${a.kind}"`);
+	}
+}
+
+/** Points of every prop held by hand k, in world space, written to diag.props. */
+export function measureProps(ctx, k, s, diag) {
+	const { sk } = ctx;
+	for (const [name, prop] of Object.entries(ctx.spec.props ?? {})) {
+		if (prop.hand !== k) continue;
+		const ax = palmAxes(sk, s, SIDES[k]);
+		const origin = scale(prop.origin.map(b => s.P[sk.index[b]]).reduce((acc, p) => add(acc, p), [0, 0, 0]), 1 / prop.origin.length);
+		const pts = {};
+		for (const [pn, [d, l, n]] of Object.entries(prop.points ?? {})) pts[pn] = add(origin, add(scale(ax.d, d), add(scale(ax.l, l), scale(ax.n, n))));
+		pts.origin = origin;
+		pts.axes = ax;
+		(diag.props ??= {})[name] = pts;
+	}
+}