cozyclay 2.1.0 → 3.0.0

package/src/motion3/search.js

@@ -0,0 +1,117 @@
+// Open parameters: any number in a spec (generator params, key channel values or vector
+// components, anchor offsets, skill args) may be written as { range: [lo, hi] } (or
+// { search: [lo, hi] }, + int: true). motion.compile then searches the values deterministically:
+// the midpoint first, a grid (one parameter) or a Halton set (several), then a shrinking pattern
+// search around the best, at most spec.search.budget (default 32, max 64) compiles, stopping at
+// the first value with QA 0. Each trial compiles only the frames the parameters can change.
+import { compileMotion } from "./compiler/compile.js";
+import { bakeChannels, flowOptions } from "./compiler/channels.js";
+import { expandGenerators } from "./compiler/walk.js";
+import { runMotionQa } from "./qa/index.js";
+import { weightOf } from "./qa/severity.js";
+
+const INT_FIELDS = new Set(["f", "f0", "steps", "period", "swing", "until", "reach", "hold", "release"]);
+const isOpen = v => v && typeof v === "object" && !Array.isArray(v) && (v.range ?? v.search) !== undefined && Object.keys(v).every(k => ["range", "search", "int"].includes(k));
+const pathText = path => path.reduce((s, p) => (typeof p === "number" ? `${s}[${p}]` : s ? `${s}.${p}` : p), "");
+
+/** Every { range } in the spec: [{ path, lo, hi, int }]. */
+export function findParams(spec) {
+	const out = [];
+	const walk = (v, path) => {
+		if (isOpen(v)) {
+			const r = v.range ?? v.search;
+			if (!(Array.isArray(r) && r.length === 2 && r.every(Number.isFinite) && r[0] < r[1])) throw new Error(`MOTION_SPEC_INVALID: ${pathText(path)} range must be [lo, hi] with lo < hi, got ${JSON.stringify(r)}`);
+			out.push({ path, lo: r[0], hi: r[1], int: v.int ?? INT_FIELDS.has(path[path.length - 1]) });
+			return;
+		}
+		if (Array.isArray(v)) v.forEach((x, i) => walk(x, [...path, i]));
+		else if (v && typeof v === "object") for (const [k, x] of Object.entries(v)) walk(x, [...path, k]);
+	};
+	for (const [k, v] of Object.entries(spec ?? {})) if (!["schema", "fps", "frames", "search"].includes(k)) walk(v, [k]);
+	return out;
+}
+
+const snap = (p, x) => { const v = Math.min(p.hi, Math.max(p.lo, x)); return p.int ? Math.round(v) : Math.round(v * 1e4) / 1e4; };
+
+function resolveParams(spec, params, values) {
+	const s = structuredClone(spec);
+	params.forEach((p, i) => { let o = s; for (const k of p.path.slice(0, -1)) o = o[k]; o[p.path[p.path.length - 1]] = values[i]; });
+	return s;
+}
+
+/** QA groups -> one number: the sum of their severities (qa/severity.js, unrounded). */
+const costOf = qa => qa.groups.reduce((c, g) => c + weightOf(g), 0);
+
+/** Frames a parameter can change (baked channels differ between its ends), or null for all. */
+function dirtyWindow(spec, params, mid, prepare, sk) {
+	const expand = values => prepare(resolveParams(spec, params, values));
+	const base = expand(mid), parts = s => JSON.stringify({ ...s, keys: undefined, generators: undefined });
+	const bake = s => bakeChannels(expandGenerators(s, sk), s.frames, flowOptions(s.flow));
+	const b0 = bake(base);
+	let a = Infinity, b = -Infinity;
+	for (let i = 0; i < params.length; i++) for (const end of [params[i].lo, params[i].hi]) {
+		const s = expand(mid.map((v, j) => (j === i ? snap(params[i], end) : v)));
+		if (parts(s) !== parts(base)) return null;
+		const b1 = bake(s);
+		for (const ch of new Set([...Object.keys(b0), ...Object.keys(b1)])) {
+			const x = b0[ch], y = b1[ch];
+			for (let f = 0; f < spec.frames; f++) if (JSON.stringify(x?.[f]) !== JSON.stringify(y?.[f])) { a = Math.min(a, f); b = Math.max(b, f); }
+		}
+	}
+	return a > b ? null : [Math.max(0, a - 8), Math.min(spec.frames - 1, b + 8)];
+}
+
+/** Halton point i (1-based) in [0, 1]^k. */
+const PRIMES = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29];
+const halton = (i, k) => Array.from({ length: k }, (_, d) => { let f = 1, r = 0, n = i; const p = PRIMES[d % PRIMES.length]; while (n > 0) { f /= p; r += f * (n % p); n = Math.floor(n / p); } return r; });
+
+/**
+ * prepare(spec) -> expanded + validated plain spec (pipeline.js). Returns the spec with the
+ * chosen values and a report { values: { path: value }, evals, cost (0 = clean), window, ms }.
+ */
+export function searchParams(spec, params, { sk, scene }, prepare) {
+	const t0 = performance.now(), budget = Math.max(1, Math.min(64, Math.round(spec.search?.budget ?? 32)));
+	const mid = params.map(p => snap(p, (p.lo + p.hi) / 2));
+	const window = dirtyWindow(spec, params, mid, prepare, sk);
+	const cache = new Map();
+	let evals = 0, best = null;
+	const evaluate = values => {
+		const key = values.join(",");
+		if (cache.has(key)) return cache.get(key);
+		if (evals >= budget) return Infinity;
+		evals++;
+		let cost;
+		try {
+			const exp = prepare(resolveParams(spec, params, values));
+			cost = costOf(runMotionQa(sk, compileMotion({ fps: 24, ...exp }, { sk, scene }, { window }), exp, { explain: false }));
+		} catch (error) {
+			if (!/MOTION_SPEC_INVALID/.test(error.message)) throw error;
+			cost = 1e9;
+		}
+		cache.set(key, cost);
+		if (!best || cost < best.cost) best = { values, cost };
+		return cost;
+	};
+	const done = () => best?.cost === 0 || evals >= budget;
+	const at = u => params.map((p, d) => snap(p, p.lo + (p.hi - p.lo) * u[d]));
+	evaluate(mid);
+	// coarse pass: a 9-point grid from the middle outward (one parameter) or Halton points
+	const coarse = params.length === 1 ? [4, 3, 5, 2, 6, 1, 7, 0, 8].map(i => [i / 8]) : Array.from({ length: Math.min(budget >> 1, 8 * params.length) }, (_, i) => halton(i + 1, params.length));
+	for (const u of coarse) { if (done()) break; evaluate(at(u)); }
+	// pattern search around the best, halving the step
+	let step = params.map(p => (p.hi - p.lo) / 8);
+	while (!done() && step.some((s, d) => s > (params[d].int ? 0.5 : (params[d].hi - params[d].lo) * 1e-3))) {
+		let moved = false;
+		for (let d = 0; d < params.length && !done(); d++) for (const sg of [-1, 1]) {
+			const v = best.values.slice(); v[d] = snap(params[d], v[d] + sg * step[d]);
+			const before = best.cost;
+			evaluate(v);
+			if (best.cost < before) moved = true;
+		}
+		if (!moved) step = step.map(s => s / 2);
+	}
+	return {
+		spec: resolveParams(spec, params, best.values),
+		search: { values: Object.fromEntries(params.map((p, i) => [pathText(p.path), best.values[i]])), evals, cost: Math.round(best.cost * 100) / 100, window, ms: Math.round(performance.now() - t0) },
+	};
+}

package/src/motion3/second-hand.js

@@ -0,0 +1,112 @@
+// The second hand on a held object (C14, lane K8). While keys lead a carry the right hand holds
+// (object-keys.js), a left hand anchored to that prop (w_<anchor>_l on a kind "prop" anchor of
+// the same prop, with or without a fit) turns with the object too. The wrist stays where the
+// anchor puts it (with a fit, the palm stays where the fit puts it). The hand takes the holding
+// hand's grip mirrored across the plane of the object's axis and the holding fingers (the object's
+// +Y runs through the left palm frame as through the right one, knuckles in line), turned about
+// the axis to the roll its arm holds most easily (planned over the frames, object-keys.js and
+// hold-plan.js). The arm follows as for the holding hand (compiler/hold.js): the elbow swivels
+// about the shoulder-wrist axis (lane N1; it stayed in the plane the anchor's IK gave it, and the
+// default pole, down and back, bent a left arm reaching across the chest into the torso), the
+// forearm and the wrist turn. Each roll is scored by the wrist's strain at the best of POLES poles,
+// plus CLEAR per squared centimetre the upper arm, the forearm or the hand goes into the torso
+// capsules (the BODY check's), and DEEP per squared centimetre the hand goes past what QA allows a
+// hand: into the torso past the BODY allowance, into the holding hand past the SELF one (lane Q1:
+// at CLEAR alone, session 4db5d447 put the hand 0.9 cm into torso_lo at f35 to save 1 of strain,
+// QA BODY). The elbow's path is planned like the holding elbow's. The hold
+// eases in with the keys' weight times the anchor weight, and a grip the arm cannot hold fades out.
+// Only a hand solved after the holding hand can follow it (pose.js solves the right arm first), so
+// the second hand is the left.
+import { palmAxes } from "./compiler/limbs.js";
+import { SIDES } from "./compiler/pose.js";
+import { add, sub, scale, norm, dot, cross, mul, T, apply, axisRot, len, clamp } from "./compiler/math.js";
+import { landscape, ELBOW_REST } from "./compiler/arm-orient.js";
+import { bendPlane } from "./compiler/hold.js";
+import { CAPSULES } from "./qa/geometry.js";
+import { QA_LIMITS } from "./qa/checks.js";
+import { bodyFor, segmentDepth } from "./body.js";
+
+const ROLLS = 36, TEMP = 0.05, PULL = 0.3, EASY = 3, SLACK = 10, POLES = 36, CLEAR = 1, DEEP = 100;
+const TORSO = CAPSULES.filter(c => c[0].startsWith("torso")), RADIUS = Object.fromEntries(CAPSULES.map(c => [c[0], c[3]]));
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];
+const col = (R, i) => [R[0][i], R[1][i], R[2][i]];
+
+/** The distance between segments p1-q1 and p2-q2 (closest points, clamped to both). */
+function segSeg(p1, q1, p2, q2) {
+	const d1 = sub(q1, p1), d2 = sub(q2, p2), r = sub(p1, p2), a = dot(d1, d1), e = dot(d2, d2), f = dot(d2, r);
+	if (a < 1e-12 || e < 1e-12) return len(r);
+	const c = dot(d1, r), b = dot(d1, d2), den = a * e - b * b;
+	let t = den > 1e-12 ? clamp((b * f - c * e) / den, 0, 1) : 0, u = (b * t + f) / e;
+	if (u < 0) { u = 0; t = clamp(-c / a, 0, 1); } else if (u > 1) { u = 1; t = clamp((b - c) / a, 0, 1); }
+	return len(sub(add(p1, scale(d1, t)), add(p2, scale(d2, u))));
+}
+
+/** The palm frame of `side` on pose s: the finger middles, axes d, l, n as columns. */
+function palmFrame(sk, s, side) {
+	const I = sk.index, ax = palmAxes(sk, s, side);
+	return { pos: scale(add(s.P[I[`${side}HandIndex2`]], s.P[I[`${side}HandMiddle2`]]), 0.5), R: cols(ax.d, ax.l, ax.n) };
+}
+
+/**
+ * The left hand's grip on carry `id` at this frame, or null when the left hand is not anchored to
+ * its prop: s is the pose with the holding hand done and the left arm on its plain target, c the
+ * frame's channels, axis the object's +Y as drawn. The grip is the holding hand's mirrored (knuckles
+ * in line), turned `roll` radians about the axis; arm(roll) is the left arm holding it: at(th) ->
+ * { pv, elbow, cost } for the elbow th radians about the shoulder-wrist axis from its plane (the
+ * swivel landscape plus the torso price) and best { th, pole, cost }; cost(roll) is best's cost
+ * (pulled lightly toward the mirror), point(roll) the end of the hand that moves (the palm with the
+ * wrist pinned, the wrist with the palm pinned), softmin() the easiest roll.
+ */
+export function secondGrip(sk, spec, id, s, c, axis) {
+	const o = spec.objects[id];
+	if (spec.props[o.prop].hand !== "r") return null;
+	const weight = Object.entries(spec.anchors ?? {}).reduce((sum, [name, a]) => sum + (a.kind === "prop" && a.prop === o.prop ? Math.max(0, c[`w_${name}_l`] ?? 0) : 0), 0);
+	if (!(weight > 1e-4)) return null;
+	// the mirror of the holding palm frame across the plane of the axis and the holding fingers
+	const R = palmFrame(sk, s, SIDES.r).R, d = col(R, 0), p = norm(cross(axis, sub(d, scale(axis, dot(d, axis))))), mirror = v => sub(v, scale(p, 2 * dot(v, p)));
+	const base = cols(mirror(d), mirror(col(R, 1)), scale(mirror(col(R, 2)), -1));
+	const left = palmFrame(sk, s, SIDES.l), I = sk.index, h = I.LeftHand, wrist = s.P[h], local = mul(T(s.R[h]), left.R), localP = apply(T(s.R[h]), sub(left.pos, wrist));
+	// with a fit the palm (its effector) stays where the fit put it, else the wrist stays on the anchor
+	const pin = (spec.fits ?? []).some(x => x.side === "l" && spec.anchors?.[x.anchor]?.kind === "prop" && spec.anchors[x.anchor].prop === o.prop && c[`w_${x.anchor}_l`] > 1e-4) ? "palm" : "wrist";
+	const rolled = r => mul(axisRot(axis, r * 180 / Math.PI), base), hand = r => mul(rolled(r), T(local));
+	const point = r => (pin === "wrist" ? add(wrist, apply(hand(r), localP)) : sub(left.pos, apply(hand(r), localP)));
+	// the wrist for a roll, the knuckles off it, and how deep a segment goes into the torso (m)
+	const wristAt = r => (pin === "wrist" ? wrist : point(r)), knuckle = apply(T(s.R[h]), sub(s.P[I.LeftHandMiddle3], wrist)), S = s.P[I.LeftArm], plane = bendPlane(sk, s, SIDES.l);
+	// on the fitted skin when the rig has one and spec.fix.self is on (body.js, as QA's BODY measures it), else on the torso capsules
+	const skin = spec.fix === false || spec.fix?.self === false ? null : bodyFor(sk), BONE = { uarm_l: I.LeftArm, farm_l: I.LeftForeArm, hand_l: I.LeftHand };
+	const into = (a, b, part) => (skin ? segmentDepth(skin, sk, s, BONE[part], a, b) : Math.max(0, ...TORSO.map(([, ta, tb, rt]) => RADIUS[part] + rt - segSeg(a, b, s.P[I[ta]], s.P[I[tb]]))));
+	const arms = new Map();
+	const arm = r => {
+		if (arms.has(r)) return arms.get(r);
+		const W = wristAt(r), land = landscape(sk, s, SIDES.l, hand(r), W, plane, ELBOW_REST);
+		const at = th => { const q = land.at(th); return { pv: q.pv, elbow: q.elbow, cost: q.cost + CLEAR * ((100 * into(S, q.elbow, "uarm_l")) ** 2 + (100 * into(q.elbow, W, "farm_l")) ** 2) }; };
+		let best = { th: 0, cost: Infinity };
+		for (let i = 0; i < POLES; i++) { const th = (2 * Math.PI * i) / POLES - Math.PI, v = at(th).cost; if (v < best.cost) best = { th, cost: v }; }
+		const K = add(W, apply(hand(r), knuckle)), deep = into(W, K, "hand_l"), past = Math.max(0, deep - QA_LIMITS.body);
+		// the holding hand is done: how far this hand's capsule goes into it (QA SELF "hands overlap")
+		const touch = 2 * RADIUS.hand_l - segSeg(W, K, s.P[I.RightHand], s.P[I.RightHandMiddle3]), over = Math.max(0, touch - QA_LIMITS.hands);
+		const fixed = CLEAR * ((100 * deep) ** 2 + (100 * land.miss) ** 2) + (past > 0 ? DEEP * (100 * past) ** 2 : 0) + (over > 0 ? DEEP * (100 * over) ** 2 : 0);
+		const a = { at, best: { th: best.th, pole: at(best.th).pv, cost: best.cost + fixed } };
+		arms.set(r, a);
+		return a;
+	};
+	const cost = r => arm(r).best.cost + PULL * (1 - Math.cos(r));
+	const softmin = () => {
+		const all = Array.from({ length: ROLLS }, (_, i) => { const r = (2 * Math.PI * i) / ROLLS - Math.PI; return [r, cost(r)]; }), low = Math.min(...all.map(x => x[1]));
+		const m = all.reduce((acc, [r, v]) => { const e = Math.exp(-(v - low) / TEMP); return [acc[0] + e * Math.cos(r), acc[1] + e * Math.sin(r)]; }, [0, 0]);
+		return Math.atan2(m[1], m[0]);
+	};
+	return { id, weight, pin, at: left.pos, rolled, arm, cost, point, softmin, measure: s2 => palmFrame(sk, s2, SIDES.l) };
+}
+
+/** How much of a grip at `roll` the arm can take: 1 while its cost is under EASY, fading by SLACK past it. */
+export const gripGate = (grip, roll) => Math.exp(-Math.max(0, grip.cost(roll) - EASY) / SLACK);
+
+/**
+ * The hold ({ w, palm, measure, pole, pin, second } for compiler/hold.js) of a grip at `roll`
+ * radians with the elbow toward `pole` (a world direction), w the keys' lead weight, gate the
+ * planned gripGate: a grip the arm cannot hold fades out, so the hand stays nearer where the plain
+ * arm put it instead of turning to a limit and flipping there.
+ */
+export const secondHold = (grip, w, roll, gate, pole) => ({ w: w * Math.min(1, grip.weight) * gate, second: grip.id, pin: grip.pin,
+	pole, palm: { pos: grip.at, R: grip.rolled(roll) }, measure: grip.measure });

package/src/motion3/skills/basic.js

@@ -0,0 +1,82 @@
+// Basic skills: stand, walk, reach-and-grip. Each reads the channel state the earlier keys
+// leave at its f0 and returns keys plus whatever anchors, props, fits and checks it needs.
+import { add, apply, ry } from "../compiler/math.js";
+import { walk } from "../compiler/walk.js";
+import { keyBook, skillError } from "./book.js";
+import { walkEnd } from "./info.js";
+
+/** standIdle({ at: [x, z], heading = 0, until }): a neutral standing pose, arms down (FK). */
+export function standIdle(ctx) {
+	const { sk, args, state } = ctx, I = sk.index, P = sk.restWorldPos, ank = P[I.LeftFoot][1];
+	const h = args.heading ?? state.yaw ?? 0, base = args.at ?? (state.root ? [state.root[0], state.root[2]] : null);
+	if (!base) skillError(ctx.tag, "needs args.at: [x, z] (no root is keyed before f0)");
+	const c = [base[0], 0, base[base.length - 1]], R = ry(h), foot = v => { const p = add(c, apply(R, v)); p[1] = ank; return p; };
+	const set = { root: [c[0], P[I.Hips][1] - 0.01, c[2]], yaw: h, pitch: 0, roll: 0, spine_yaw: 0, spine_pitch: 0, spine_roll: 0, head_yaw: 0, head_pitch: 0,
+		foot_l: foot([0.09, 0, -0.03]), foot_r: foot([-0.09, 0, 0.03]), fyaw_l: h, fyaw_r: h, fpitch_l: 0, fpitch_r: 0, knee_l: [0.05, 0, 1], knee_r: [-0.05, 0, 1],
+		armw_l: 0, armw_r: 0, aswing_l: 0, aswing_r: 0, abend_l: 0, abend_r: 0, arm_hang: 1 };
+	const keys = [{ f: ctx.f0, set }];
+	if (args.until !== undefined) keys.push({ f: args.until, set: structuredClone(set) });
+	return { keys, end: args.until ?? ctx.f0 };
+}
+
+/**
+ * walkTo({ to: [x, z] } | { heading: h | [h0, h1] }, steps, step = 0.5, turnDistance, ...): the
+ * walk generator from the pose at f0. With `to` the heading turns toward the point and the step
+ * count covers the distance. Ends 16 + steps * period + 18 frames after f0, feet together; a
+ * take that ends after the last step holds that pose to its end. The steps keep a natural rhythm
+ * (compiler/gait-rhythm.js); vary: 0 makes every step the same.
+ */
+export function walkTo(ctx) {
+	const { args, state } = ctx;
+	if (!state.foot_l || !state.foot_r || !state.root) skillError(ctx.tag, "needs a standing pose keyed before f0 (use standIdle or another skill first)");
+	const gen = { type: "walk", f0: ctx.f0, ...args };
+	delete gen.to; delete gen.arrive;
+	const h0 = state.yaw ?? 0, step = args.step ?? 0.5, first = args.firstStep ?? 0.4;
+	if (args.to) {
+		const c0 = [(state.foot_l[0] + state.foot_r[0]) / 2, (state.foot_l[2] + state.foot_r[2]) / 2];
+		const dx = args.to[0] - c0[0], dz = args.to[args.to.length - 1] - c0[1], d = Math.hypot(dx, dz);
+		let h1 = Math.atan2(dx, dz) * 180 / Math.PI;
+		while (h1 - h0 > 180) h1 -= 360;
+		while (h1 - h0 < -180) h1 += 360;
+		gen.heading = args.heading ?? [h0, h1];
+		gen.steps = args.steps ?? Math.max(2, 2 + Math.round((d - first) / step));
+	}
+	if (typeof gen.heading === "number") gen.heading = [h0, gen.heading];
+	const keys = walk(gen, ctx.keys, ctx.sk, ctx.tag), end = walkEnd(gen), last = ctx.frames - 1;
+	// the settle after the last step only holds the pose: a take that ends in it ends the walk there
+	if (end > last && Math.max(...keys.filter(k => k.f < end).map(k => k.f)) <= last) return { keys: keys.filter(k => k.f <= last), end: last, cut: `settle cut at f${last} (hold to the end)` };
+	return { keys, end };
+}
+
+/**
+ * reachGrip({ anchor, side, reach = 20, hold = 22, release = 12, elbow, fingers = "grip",
+ * define, orient = true }): the hand goes to the anchor (defined elsewhere, or by `define`) over
+ * `reach` frames with the fingers closing, holds, and lets go. Adds a fit of the fingertips on the
+ * anchor (on a body it also turns the hand into a grip, compiler/grip.js; orient: false leaves the
+ * hand's turn alone) and a contact check. A take that ends during the release holds the grip to its end.
+ */
+export function reachGrip(ctx) {
+	const { args, state } = ctx, k = args.side, name = args.anchor;
+	if (k !== "l" && k !== "r") skillError(ctx.tag, `args.side must be "l" or "r", got ${JSON.stringify(k)}`);
+	if (typeof name !== "string" || /_[lr]$/.test(name)) skillError(ctx.tag, "args.anchor must name an anchor (not ending in _l/_r)");
+	const reach = args.reach ?? 20, hold = args.hold ?? 22, release = args.release ?? 12, preset = args.fingers ?? "grip";
+	const w = `w_${name}_${k}`, fg = `fingers_${k}`, armw = `armw_${k}`, el = `elbow_${k}`, wasFk = !(state[armw] > 0.5);
+	// a take that ends after the hold but before the hand lets go cuts the release: the grip holds to the last frame
+	const last = ctx.frames - 1, cut = ctx.f0 + reach + hold <= last && ctx.f0 + reach + hold + release > last;
+	for (const [c, v] of [[w, 0], [fg, { [preset]: 0 }], [armw, 0]]) if (state[c] === undefined) state[c] = v;
+	const b = keyBook(state, ctx.f0);
+	b.hold(0, w, fg, armw, el);
+	b.at(reach, { [w]: 1, [fg]: { ...state[fg], [preset]: 1 }, [armw]: 1, ...(args.elbow ? { [el]: args.elbow } : {}) });
+	b.hold(reach + hold, w, fg, armw, el);
+	if (!cut) b.at(reach + hold + release, { [w]: 0, [fg]: { ...state[fg], [preset]: 0 }, ...(wasFk ? { [armw]: 0 } : {}) });
+	const S = k === "l" ? "Left" : "Right", prop = `${name}Grip`;
+	const def = args.define ? { [name]: args.define } : {};
+	const obj = args.define?.kind === "object" ? args.define.object : ctx.anchors?.[name]?.kind === "object" ? ctx.anchors[name].object : null;
+	return {
+		keys: b.keys, end: cut ? last : ctx.f0 + reach + hold + release, ...(cut ? { cut: `release cut at f${last} (hold to the end)` } : {}), anchors: def,
+		props: { [prop]: { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: [0, 0, 0] } } },
+		fits: [{ side: k, anchor: name, effector: { prop, point: "fingers" }, ...(args.orient === false ? { orient: false } : {}) }],
+		checks: { contacts: [{ name: `fingers on ${name}`, point: `prop:${prop}.fingers`, target: `anchor:${name}`, tol: 0.04, when: w }],
+			allow: obj ? [{ part: "hand", object: obj, depth: 0.04 }] : [] },
+	};
+}

package/src/motion3/skills/book.js

@@ -0,0 +1,76 @@
+// Skill plumbing: a key book that tracks the channel state while a skill writes keys, and the
+// placement of choreography written in a template frame (e.g. a car's own frame, driver side
+// on +X) into the scene: translate, turn by a yaw, and mirror left/right for the other side.
+import { add, apply, ry } from "../compiler/math.js";
+
+const SIDE_SWAP = { _l: "_r", _r: "_l" };
+const NEGATE_ON_MIRROR = /^(yaw|roll|spine_yaw|spine_roll|head_yaw|head_roll|fyaw_[lr]|wtwist_[lr]|wflex_[lr])$/;
+const POINT = /^(root|foot_[lr]|hand_[lr])$/, POLE = /^(knee|elbow)_[lr]$/, YAW = /^(yaw|fyaw_[lr])$/;
+
+const clone = v => (v && typeof v === "object" ? structuredClone(v) : v);
+export const swapSide = name => name.replace(/_(l|r)$/, m => SIDE_SWAP[m]).replace(/^(Left|Right)/, m => (m === "Left" ? "Right" : "Left"));
+
+/**
+ * A frame: { origin: [x,y,z], yaw (deg), mirror (bool), negate: Set of extra channels (hinge
+ * angles) to negate, names: { anchor: mirroredAnchor } }. Template points p map to
+ * origin + ry(yaw)(mirror ? [-x, y, z] : p).
+ */
+export const identityFrame = () => ({ origin: [0, 0, 0], yaw: 0, mirror: false, negate: new Set(), names: {} });
+
+const placePoint = (fr, p) => add(fr.origin, apply(ry(fr.yaw), fr.mirror ? [-p[0], p[1], p[2]] : p));
+export const placeDir = (fr, v) => (fr.mirror ? [-v[0], v[1], v[2]] : v.slice());
+
+/** A channel name in the placed frame (sides swap and anchor names rename when mirrored). */
+export function placeChannel(fr, ch) {
+	if (!fr.mirror) return ch;
+	const w = /^w_(.+)_([lr])$/.exec(ch);
+	if (w) return `w_${fr.names[w[1]] ?? w[1]}_${w[2] === "l" ? "r" : "l"}`;
+	return /_[lr]$/.test(ch) ? swapSide(ch) : ch;
+}
+
+function placeSet(fr, set) {
+	const out = {};
+	for (const [ch, v0] of Object.entries(set)) {
+		let v = clone(v0);
+		if (POINT.test(ch)) v = placePoint(fr, v);
+		else if (POLE.test(ch)) v = placeDir(fr, v);
+		else if (typeof v === "number") {
+			if (fr.mirror && (NEGATE_ON_MIRROR.test(ch) || fr.negate.has(ch))) v = -v;
+			if (YAW.test(ch)) v += fr.yaw;
+		}
+		out[placeChannel(fr, ch)] = v;
+	}
+	return out;
+}
+
+/**
+ * Keys relative to f0 (book.at(12, ...) writes frame f0 + 12). `at` and `step` take template
+ * values and place them; `hold` re-keys the current (already placed) values.
+ */
+export function keyBook(state, f0 = 0, fr = identityFrame()) {
+	const keys = [], name = ch => placeChannel(fr, ch);
+	return {
+		state, keys, frame: fr,
+		at(f, set) { const placed = placeSet(fr, set); Object.assign(state, clone(placed)); keys.push({ f: f0 + f, set: placed }); },
+		hold(f, ...names) { keys.push({ f: f0 + f, set: Object.fromEntries(names.filter(n => state[name(n)] !== undefined).map(n => [name(n), clone(state[name(n)])])) }); },
+		step(f, ch, value) {
+			const n = name(ch);
+			keys.push({ f: f0 + f - 1, set: { [n]: state[n] } });
+			state[n] = value;
+			keys.push({ f: f0 + f, set: { [n]: value }, step: [n] });
+		},
+	};
+}
+
+/** Throws the skill's own MOTION_SPEC_INVALID message. */
+export const skillError = (tag, msg) => { throw new Error(`MOTION_SPEC_INVALID: ${tag}: ${msg}`); };
+
+/** Scene box by id or a skill error naming the arg. */
+export function sceneBox(ctx, arg, id) {
+	const box = ctx.scene?.objects?.[id];
+	if (!box) skillError(ctx.tag, `args.${arg} "${id}" is not a scene object`);
+	return box;
+}
+
+/** Yaw (deg) of a box's rotation matrix about +Y. */
+export const yawOf = R => Math.atan2(R[0][2], R[2][2]) * 180 / Math.PI;

package/src/motion3/skills/car.js

@@ -0,0 +1,145 @@
+// Car skills, extracted from the car-exit fixture (test/motion3/fixtures/exitcar-scene.mjs).
+// The choreography is written in the template car's frame: the car centred on the origin facing
+// +Z, its driver door on +X, seat base at y 0.4. The skills place it from the scene: the seat
+// gives the car's position and yaw, the door gives the hinge, side "r" mirrors everything.
+// Tuned on the X Bot: seated heights are the template's, standing heights follow the rig.
+import { add, sub, apply, ry } from "../compiler/math.js";
+import { keyBook, identityFrame, placeChannel, placeDir, sceneBox, skillError, yawOf, swapSide } from "./book.js";
+
+const SEAT_REF = [0.54, 0.4, -0.075], FLOOR = 0.4, X_HIPS = 1.0427487182617188;
+const SIDES = new Set(["l", "r"]);
+
+/** Seat, door and handle ids from args ({ car: "Car" } fills the template's names). */
+function carIds(args, side = "l") {
+	const car = args.car;
+	return {
+		seat: args.seat ?? (car && `${car}_Seat_Driver`), seatBack: args.seatBack ?? (car && `${car}_Seat_Driver_Back`),
+		door: args.door ?? (car && `${car}_Door_${side.toUpperCase()}`), handle: args.handle ?? (car && `${car}_Door_Handle`),
+		wheel: args.wheel ?? (car && `${car}_Steering_Wheel`),
+	};
+}
+
+/** The template-to-scene frame for a car whose driver seat is `seat`. */
+function carFrame(ctx, seat, side) {
+	const box = sceneBox(ctx, "seat", seat);
+	if (Math.abs(box.pos[1] - FLOOR) > 0.05) skillError(ctx.tag, `seat "${seat}" stands at y ${box.pos[1]}; the car skills are tuned for a seat base at y ${FLOOR} (a car on the ground)`);
+	const fr = identityFrame();
+	fr.yaw = yawOf(box.R); fr.mirror = side === "r";
+	const o = sub(box.pos, apply(ry(fr.yaw), fr.mirror ? [-SEAT_REF[0], SEAT_REF[1], SEAT_REF[2]] : SEAT_REF));
+	fr.origin = [o[0], 0, o[2]];
+	fr.names = { lthigh: "rthigh", rthigh: "lthigh" };
+	return fr;
+}
+
+/** The hands on the thighs, pushing to stand up; letting go as the thighs turn under them, the palms and forearms
+ * sweep a few centimetres into them for a few frames (the open case of fix/self.js: it moves wrists, not palms);
+ * the hands, both on the thighs over knees close together, touch. */
+const THIGH_CONTACT = [["hand", "thigh*", 0.07], ["farm", "thigh*", 0.07], ["hand", "hips", 0.07], ["farm", "hips", 0.07], ["hand_l", "hand_r", 0.035]]
+	.map(([part, object, depth]) => ({ part, object, depth }));
+
+const rigHeights = sk => ({ A: sk.restWorldPos[sk.index.LeftFoot][1], H: y => y + (sk.restWorldPos[sk.index.Hips][1] - X_HIPS) });
+
+/** sitInSeat({ car | seat (+ seatBack, wheel), offset = [0, 0.17, 0.02], floor }): seated, hands forward at the wheel. */
+export function sitInSeat(ctx) {
+	const { args, sk } = ctx, ids = carIds(args), box = sceneBox(ctx, "seat", ids.seat), { A } = rigHeights(sk);
+	const Y = yawOf(box.R), turn = v => apply(ry(Y), v), off = args.offset ?? [0, 0.17, 0.02], floor = args.floor ?? box.pos[1];
+	const root = add(add(box.pos, apply(box.R, [0, 2 * box.half[1], 0])), turn(off));
+	const foot = x => { const p = add(root, turn([x, 0, 0.452])); p[1] = floor + A; return p; };
+	const hand = x => add(root, turn([x, 0.348, 0.324]));
+	const set = {
+		root, yaw: Y, pitch: 0, spine_pitch: -12, spine_yaw: 0, spine_roll: 0, head_yaw: 0, head_pitch: 10,
+		foot_l: foot(0.17), foot_r: foot(-0.17), fyaw_l: Y, fyaw_r: Y, fpitch_l: 0, fpitch_r: 0, knee_l: [0.15, 0.2, 1], knee_r: [-0.15, 0.2, 1],
+		armw_l: 1, armw_r: 1, hand_l: hand(0.22), hand_r: hand(-0.22), elbow_l: [0.6, -1, -0.3], elbow_r: [-0.6, -1, -0.3],
+		aswing_l: 0, aswing_r: 0, abend_l: 0, abend_r: 0, wtwist_l: 0, wtwist_r: 0, wflex_l: 0, wflex_r: 0,
+	};
+	const allow = [{ part: "torso_lo", object: ids.seat, depth: 0.04 }, { part: "hips", object: ids.seat, depth: 0.04 }, { part: "thigh", object: ids.seat, depth: 0.045 }];
+	if (ids.seatBack && ctx.scene.objects[ids.seatBack]) allow.push({ part: "torso", object: ids.seatBack, depth: 0.03 });
+	if (ids.wheel && ctx.scene.objects[ids.wheel]) allow.push({ part: "hand", object: ids.wheel, depth: 0.05 });
+	return { keys: [{ f: ctx.f0, set }], checks: { supports: [{ object: ids.seat, part: "hips", tol: 0.04 }], allow }, end: ctx.f0 };
+}
+
+/**
+ * exitCar({ car | seat+door+handle, side = "l", channel = "door" }): reach the inner handle, pull
+ * and push the door, let it swing open, swivel, legs out, stand up with the hands on the thighs,
+ * two steps away; ends at f0 + 246 standing on a walk start stance heading car yaw + 125.
+ */
+export function exitCar(ctx) {
+	const side = ctx.args.side ?? "l";
+	if (!SIDES.has(side)) skillError(ctx.tag, `args.side must be "l" or "r", got ${JSON.stringify(side)}`);
+	const ids = carIds(ctx.args, side), fr = carFrame(ctx, ids.seat, side), ch = ctx.args.channel ?? "door";
+	for (const [arg, id] of [["door", ids.door], ["handle", ids.handle]]) sceneBox(ctx, arg, id);
+	fr.negate.add(ch);
+	const defaults = { [ch]: 0, w_handle_l: 0, w_lthigh_l: 0, w_rthigh_r: 0, fingers_l: { grip: 0, fist: 0 } };
+	const k = keyBook(ctx.state, ctx.f0, fr), fresh = {};
+	for (const [c, v] of Object.entries(defaults)) if (ctx.state[placeChannel(fr, c)] === undefined) fresh[c] = v;
+	if (Object.keys(fresh).length) k.at(0, fresh);
+	choreography(k, ch, rigHeights(ctx.sk));
+	const door = ctx.scene.objects[ids.door], hx = (fr.mirror ? -1 : 1) * door.half[0];
+	const hinge = { pivot: add(door.pos, apply(door.R, [hx, 0, door.half[2]])), axis: [0, 1, 0], channel: ch };
+	const L = s => (fr.mirror ? swapSide(s) : s), n = s => (fr.mirror ? { lthigh: "rthigh", rthigh: "lthigh" }[s] ?? s : s);
+	const seg = (S, reach) => ({ kind: "segment", from: L(`${S}UpLeg`), to: L(`${S}Leg`), t: 0.45, tMin: 0.15, offset: [0, 0.07, 0], reach: fr.mirror ? (reach === "l" ? "r" : "l") : reach });
+	const hand = fr.mirror ? "r" : "l";
+	return {
+		keys: k.keys,
+		objects: { [ids.door]: hinge, [ids.handle]: hinge },
+		anchors: { handle: { kind: "object", object: ids.handle, local: placeDir(fr, [-0.005, 0.015, 0]) }, [n("lthigh")]: seg("Left", "l"), [n("rthigh")]: seg("Right", "r") },
+		props: { grip: { hand, origin: [L("LeftHandIndex2"), L("LeftHandMiddle2")], points: { fingers: [0, 0, 0] } } },
+		fits: [{ side: hand, anchor: "handle", effector: { prop: "grip", point: "fingers" } }],
+		checks: {
+			contacts: [{ name: "fingers on the door handle", point: "prop:grip.fingers", target: "anchor:handle", tol: 0.04, when: `w_handle_${hand}` }],
+			// the hands rest on the thighs and push on them to stand up: a contact the body check allows (qa/body-checks.js)
+			allow: [{ part: "hand", object: ids.door, depth: 0.03 }, { part: "hand", object: ids.handle, depth: 0.04 }, ...THIGH_CONTACT],
+		},
+		end: ctx.f0 + 246,
+	};
+}
+
+function choreography(k, door, { A, H }) {
+	// 1. reach for the inner handle, pull, push the door a little (f12-50)
+	k.hold(12, "w_handle_l", "fingers_l", "head_yaw", "spine_yaw", "spine_roll", "elbow_l", "hand_l");
+	k.at(32, { w_handle_l: 1, fingers_l: { grip: 1, fist: 0 }, head_yaw: 35, spine_yaw: 10, spine_roll: -8, elbow_l: [0.3, -1, -0.6], hand_l: [1.0, 0.96, 0.06] });
+	k.hold(32, door);
+	k.at(38, { [door]: -3 });
+	k.at(50, { [door]: -10, spine_roll: -16, spine_yaw: 14 });
+	// 2. let go (the door holds still), then it swings open; hands rest on the thighs (f54-84)
+	k.hold(54, "w_handle_l", "fingers_l", "w_lthigh_l", "elbow_l", door);
+	k.at(66, { w_handle_l: 0, fingers_l: { grip: 0, fist: 0 }, [door]: -10 });
+	k.at(70, { w_lthigh_l: 1, elbow_l: [0.5, -0.3, -1], spine_roll: -3, spine_yaw: 6 });
+	k.at(84, { [door]: -68, head_yaw: 40 });
+	k.hold(64, "w_rthigh_r", "elbow_r", "spine_pitch");
+	k.at(80, { w_rthigh_r: 1, elbow_r: [-0.5, -0.3, -1], spine_roll: 0, spine_yaw: 0, spine_pitch: 0 });
+	// 3. swivel; the left leg goes out over the sill and down to the ground (f84-118)
+	k.hold(84, "yaw", "root", "foot_l", "foot_r", "fyaw_l", "fyaw_r", "knee_l", "knee_r");
+	k.at(92, { foot_r: [0.4, FLOOR + A + 0.03, 0.36], fyaw_r: 15 });
+	k.at(97, { foot_l: [0.96, FLOOR + 0.22, 0.32], fyaw_l: 40, knee_l: [0.5, 0.4, 1], yaw: 30, root: [0.64, 0.915, -0.06] });
+	k.at(101, { foot_r: [0.56, FLOOR + A, 0.34], fyaw_r: 35 });
+	k.at(105, { foot_l: [1.18, FLOOR + 0.1, 0.1], fyaw_l: 60 });
+	k.at(116, { foot_l: [1.28, A, -0.12], fyaw_l: 75, knee_l: [0.4, 0.5, 1], yaw: 62, root: [0.82, 0.9, -0.06], head_yaw: 20, knee_r: [0.1, 0.6, 1], spine_pitch: 10 });
+	// 4. right leg out (f120-144)
+	k.hold(120, "foot_r", "fyaw_r");
+	k.at(129, { foot_r: [0.94, FLOOR + 0.24, 0.36], fyaw_r: 65, knee_r: [0, 0.5, 1], yaw: 80, root: [0.86, 0.9, -0.03] });
+	k.at(135, { foot_r: [1.18, FLOOR + 0.1, 0.26], fyaw_r: 85 });
+	k.hold(142, "foot_l", "fyaw_l");
+	k.at(144, { foot_r: [1.29, A, 0.22], fyaw_r: 90, knee_r: [-0.1, 0.4, 1], yaw: 90, root: [0.88, 0.9, 0.02], head_yaw: 0, knee_l: [0.1, 0.4, 1], spine_pitch: 16 });
+	// 5. lean the weight over the feet with the hands pushing on the thighs, stand up (f144-196)
+	k.hold(144, "head_pitch", "pitch", "elbow_l", "elbow_r");
+	k.at(152, { spine_pitch: 28, head_pitch: -8, root: [0.91, 0.9, 0.02], elbow_l: [0.6, -0.2, -1], elbow_r: [-0.6, -0.2, -1] });
+	k.at(162, { spine_pitch: 50, pitch: 22, head_pitch: -36, root: [0.99, 0.91, 0.02] });
+	k.at(174, { root: [1.09, 0.96, 0.02], spine_pitch: 36, pitch: 12, head_pitch: -24 });
+	k.hold(166, "armw_l", "armw_r");
+	k.at(186, { root: [1.19, H(1.0), 0.02], spine_pitch: 12, pitch: 3, head_pitch: -8, armw_l: 0, armw_r: 0 });
+	k.hold(187, "w_lthigh_l", "w_rthigh_r");
+	k.at(190, { w_lthigh_l: 0, w_rthigh_r: 0 });
+	k.at(196, { root: [1.21, H(1.005), 0.02], spine_pitch: 0, pitch: 0, head_pitch: 0 });
+	// 6. two steps away from the car with a weight shift (f196-246), onto the walk's start stance
+	k.at(205, { root: [1.26, H(0.985), 0.165] });
+	k.hold(208, "foot_l", "fyaw_l");
+	k.at(212, { root: [1.3, H(0.985), 0.16] });
+	k.at(214, { foot_l: [1.4, A + 0.06, -0.12] });
+	k.at(220, { foot_l: [1.535, A, -0.132], fyaw_l: 110, root: [1.38, H(0.98), 0.05] });
+	k.at(230, { root: [1.5, H(0.975), -0.08] });
+	k.hold(232, "foot_r", "fyaw_r");
+	k.at(236, { root: [1.52, H(0.975), -0.085] });
+	k.at(239, { foot_r: [1.53, A + 0.07, 0.09] });
+	k.at(246, { foot_r: [1.765, A, -0.048], fyaw_r: 125, yaw: 110, root: [1.62, H(0.98), -0.08] });
+}

package/src/motion3/skills/frames-auto.js

@@ -0,0 +1,29 @@
+// frames: "auto". The spec's length becomes the latest of every skill end, generator end and key
+// f, plus 1. Open parameters ({ range: [lo, hi] }) count at their upper bound, so every value the
+// search tries fits. The answer is a copy with the number, so the stored spec (and a saved take)
+// keeps it; the spec store remembers the "auto" intent beside it (spec-store.js markFramesAuto).
+import { findParams } from "../search.js";
+import { expandUse } from "./index.js";
+import { walkEnd } from "./info.js";
+
+const MAX_FRAMES = 20000;
+
+/** The spec with every open parameter at its upper bound. */
+function atUpperBound(spec) {
+	const s = structuredClone(spec);
+	for (const p of findParams(spec)) {
+		let o = s;
+		for (const k of p.path.slice(0, -1)) o = o[k];
+		o[p.path[p.path.length - 1]] = p.hi;
+	}
+	return s;
+}
+
+/** resolveFrames(spec, { sk, scene, lenient }) -> spec (a copy when frames was "auto", else spec itself). */
+export function resolveFrames(spec, { sk, scene, lenient = false } = {}) {
+	if (spec?.frames !== "auto") return spec;
+	const { spec: full, used } = expandUse({ ...atUpperBound(spec), frames: MAX_FRAMES }, { sk, scene, lenient, auto: true });
+	const ends = [...(Array.isArray(full.keys) ? full.keys.map(k => k?.f) : []), ...used.map(u => u.end),
+		...(Array.isArray(full.generators) ? full.generators.map(g => (g && Number.isFinite(g.f0) ? walkEnd(g) : null)) : [])];
+	return { ...spec, frames: Math.max(0, ...ends.filter(Number.isFinite)) + 1 };
+}