cozyclay 3.0.2 → 3.0.3

package/src/motion3/compiler/anchors.js

@@ -15,7 +15,7 @@
 //                       where its installed take has it at that frame (people.js)
 // 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, T } from "./math.js";
+import { add, sub, scale, len, dot, norm, apply, ry, T } from "./math.js";
 import { bonePoint } from "./skeleton.js";
 import { palmAxes } from "./limbs.js";
 import { SIDES } from "./pose.js";
@@ -23,10 +23,12 @@ import { HAND_CLEAR, keepOut } from "../body.js";
 import { groupsOf } from "../scene.js";
 import { personJoint, peopleList } from "../people.js";
 import { isCarried } from "../carried.js";
-import { socketsOf, socketNamed, socketWorld, socketDistance, faceFrom } from "../sockets.js";
+import { socketsOf, socketNamed, socketWorld, socketDistance, faceFrom, rimPoint } from "../sockets.js";
 import { partsOf } from "../object-pose.js";
+import { GRASP_POINTS } from "./vocab.js";
 
-function armReach(sk, k) {
+/** Shoulder to wrist with the arm straight (rest bone lengths), m. */
+export 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`]]));
 }
@@ -146,13 +148,39 @@ export function anchorSocket(ctx, name, s, diag, c, side) {
 		const pick = a.socket ? socketNamed(ctx.scene, a.object, a.socket) : all.map(k => ({ k, d: socketDistance(socketWorld(k, poseOf(k.owner)), near) })).sort((x, y) => x.d - y.d)[0]?.k;
 		ctx.sockets.set(name, pick ?? null);
 	}
-	const sock = ctx.sockets.get(name), w = sock ? socketWorld(sock, poseOf(sock.owner)) : { p: local ?? poseOf(a.object).pos };
-	if (local) w.p = local;
+	const sock = ctx.sockets.get(name);
+	let w = sock ? socketWorld(sock, poseOf(sock.owner)) : { p: local ?? poseOf(a.object).pos };
+	if (sock?.rim) w = rimHold(ctx, name, side, sock, poseOf(sock.owner), w, local ?? s.P[ctx.sk.index[side ? `${SIDES[side]}Arm` : "Hips"]]);
+	else if (local) w.p = local;
+	// a thick body (a cup) holds its axis further off the finger middles than the grasp's point does (vocab.js GRASP_POINTS,
+	// 2 cm on a power grip): the point moves out from the axis toward the hand's shoulder by the difference, so the fingers
+	// close on the surface instead of being asked into the body (session 7f15b4ae: a 4 cm cup, fingers asked 2 cm inside)
+	else if (w.axis && w.radius > 0) {
+		const inset = Math.abs(GRASP_POINTS[a.grasp]?.[2] ?? 0), out = w.radius - inset, sh = s.P[ctx.sk.index[`${SIDES[side] ?? "Right"}Arm`]];
+		const v = sub(sh, w.p), across = sub(v, scale(w.axis, dot(v, w.axis)));
+		if (out > 1e-4 && len(across) > 1e-6) w.p = add(w.p, scale(norm(across), out));
+	}
 	// a socket with neither an axis nor a side (a box, a wall): the palm faces against the face of the body nearest the point
 	if (!w.axis && !w.from) w.from = faceFrom(partsOf(ctx.scene, a.object).map(id => ({ ...poseOf(id), half: ctx.scene.objects[id].half })), w.p);
 	return w;
 }
 
+/**
+ * A rim socket held by hand `side`: the rim point nearest q (the anchor's local point, else the shoulder) the first time
+ * it is asked, kept in the rim's own axes so the hand stays on that spot of the rim as the rim moves (a wheel in a truck).
+ */
+function rimHold(ctx, name, side, sock, pose, w, q) {
+	ctx.rims ??= new Map();
+	// asked with no hand (a contact check, a goal): the spot a hand already holds
+	const held = side ? null : [...ctx.rims.keys()].find(k => k.startsWith(`${name}|`) && !k.endsWith("|"));
+	const key = held ?? `${name}|${side ?? ""}`;
+	if (!ctx.rims.has(key)) {
+		const r = rimPoint(w, q), back = v => apply(T(pose.R), v);
+		ctx.rims.set(key, { at: back(sub(r.p, pose.pos)), axis: back(r.axis) });
+	}
+	return socketWorld(ctx.rims.get(key), pose);
+}
+
 /** 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;

package/src/motion3/compiler/compile.js

@@ -23,10 +23,11 @@ import { isCarried, isFollow, hingePose, movesRecord, compose, relative } from "
 import { isFree, freePoseAt } from "../free-motion.js";
 import { groupsOf } from "../scene.js";
 import { pose, SIDES } from "./pose.js";
+import { graspAnchor } from "./socket-grip.js";
 import { gripHand } from "./grip.js";
 import { bakeChannels, channelsAt, flowOptions } from "./channels.js";
 import { idleLayer, withIdle, busyHands } from "./idle.js";
-import { resolveAnchor, measureProps } from "./anchors.js";
+import { resolveAnchor, measureProps, armReach } from "./anchors.js";
 import { expandGenerators } from "./walk.js";
 import { steadyHead } from "./head-steady.js";
 import { fixOptions, applyFixes } from "../fix/index.js";
@@ -36,6 +37,8 @@ import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
 import { objectPoseAt, handOf, restingAt, frameAt, spanOf } from "../object-pose.js";
 
 const smooth = x => x * x * (3 - 2 * x);
+// how far past the straight arm a grasp fit's wrist target may end before it counts as wound up (solveFrame), m
+const REACH_SLACK = 0.02;
 
 /**
  * Scene boxes by frame. A body moves with its own spec.objects entry or its nearest group's (a
@@ -146,15 +149,25 @@ export function solveFrame(ctx, c0, f, lead = true) {
 		if (!(c[wch] > 1e-4)) continue;
 		const full = { ...c, [wch]: 1, [`armw_${fit.side}`]: 1 };
 		for (const ch of Object.keys(full)) if (ch !== wch && new RegExp(`^w_.+_${fit.side}$`).test(ch)) full[ch] = 0;
-		let corr = [0, 0, 0];
+		// each pass adds what the effector still misses; an arm at full reach misses the same each pass, so on a grasp's fit
+		// the sum wound the wrist target far past the anchor (session 7f15b4ae: 0.6 m, read back as REACH 0.845 m on a cup a
+		// few cm out of reach). A grasp fit whose wrist target ends past the straight arm (REACH_SLACK) aims instead at the
+		// anchor by the hand's own wrist-to-effector offset of its best pass: the arm reaches straight for it and its
+		// residual (REACH) is what the effector misses. Other fits keep their passes as they were (their takes are pinned).
+		let corr = [0, 0, 0], best = null, last = null;
+		const grasp = graspAnchor(ctx.spec, fit.anchor), shoulder = ctx.sk.index[`${SIDES[fit.side]}Arm`], wristAt = ctx.sk.index[`${SIDES[fit.side]}Hand`];
 		for (let i = 0; i < 6; i++) {
 			full[`fit_${fit.anchor}_${fit.side}`] = corr;
 			const { s, diag } = pose(ctx.sk, full, hooksFor(ctx, full, f, true, lead, fit.side));
 			const eff = effectorPoint(ctx.sk, s, diag, fit.effector);
 			const goal = add(resolveAnchor(ctx, fit.anchor, s, diag, full, fit.side), fit.offset ?? [0, 0, 0]);
 			if (!eff) break;
-			corr = add(corr, sub(goal, eff));
+			const miss = sub(goal, eff), err = len(miss);
+			if (grasp && (!best || err < best.err)) best = { err, hand: sub(s.P[wristAt], eff) };
+			last = { goal, shoulder: s.P[shoulder] };
+			corr = add(corr, miss);
 		}
+		if (grasp && best && last && len(sub(add(last.goal, corr), last.shoulder)) > armReach(ctx.sk, fit.side) + REACH_SLACK) corr = best.hand;
 		c[`fit_${fit.anchor}_${fit.side}`] = corr;
 	}
 	const { s, diag } = pose(ctx.sk, c, hooksFor(ctx, c, f, false, lead));
@@ -183,11 +196,15 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	// a prop anchor outside its hand's carry reads the carry's grab (release) frame (anchors.js propOnCarry)
 	ctx.carrySpan = o => spanOf(out, o);
 	ctx.solvedAt = f => frameAt(out, f);
+	// a reach's grasp is planned on its first full-weight frame (socket-grip.js plannedGrasp)
+	ctx.weightAt = (ch, f) => out.baked?.[ch]?.[f];
+	ctx.frameCount = frameCount;
 	const engine = {
 		rebake(keys) {
 			out.keys = keys;
 			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow));
 			ctx.socketTurns = new Map();
+			ctx.graspPlans = new Map();
 			steadyHead(out.baked, keys, frameCount);
 			// a held pose breathes and shifts its weight (idle.js): offsets solveFrame adds, contacts and out.baked stay as keyed
 			ctx.idle = idleLayer(out.baked, { spec, sk, frameCount });

package/src/motion3/compiler/grip.js

@@ -34,7 +34,7 @@ import { sdBox } from "../qa/geometry.js";
 import { partsOf } from "../object-pose.js";
 import { graspAnchor, socketCarry, socketHand, keepSocketTurn, ownWrist } from "./socket-grip.js";
 
-const NEAR = 0.06, THIN = 0.045, ALIGN = 0.3, PREFER = 30, DEG = 180 / Math.PI, ITER = 2, UP = [0, 1, 0];
+const NEAR = 0.06, UPRIGHT = 0.8, THIN = 0.045, ALIGN = 0.3, PREFER = 30, DEG = 180 / Math.PI, ITER = 2, UP = [0, 1, 0];
 const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];
 const flat = (v, n) => sub(v, scale(n, dot(v, n)));
 
@@ -97,7 +97,7 @@ function bodyAt(ctx, f, k, A, anchor, now) {
 	// the same with keys or without), and no other body takes its place
 	const carry = best && carryOf(ctx, best.id);
 	if (!best || (carry?.side === k && ownGrip(ctx, carry.key, k, f) === null)) return null;
-	return anchor?.kind === "object" || best.d <= NEAR ? best.box : null;
+	return anchor?.kind === "object" || best.d <= NEAR ? { ...best.box, id: best.id } : null;
 }
 
 const AXES = [0, 1, 2];
@@ -149,7 +149,7 @@ export function gripHand(ctx, sk, s, side, k, c, f, diag) {
 	// a hand that holds what it carries by a socket keeps the grasp it took on the grab frame
 	if (carry && f > carry.grab) return carry.keyed ? undefined : keepSocketTurn(ctx, sk, s, side, k, carry);
 	if (!on || on.w < 1e-3) return;
-	if (grasp) return socketHand(ctx, sk, s, side, k, c, diag, on, st => effectorAt(sk, ctx.spec, st, side, on.fit.effector ?? {}));
+	if (grasp) return socketHand(ctx, sk, s, side, k, c, diag, on, st => effectorAt(sk, ctx.spec, st, side, on.fit.effector ?? {}), null, f);
 	// a hand that carries something on this frame holds that (its carry's grip), whatever its fit's anchor
 	if (Object.keys(ctx.spec.objects ?? {}).some(id => ctx.spec.objects[id]?.prop && ctx.objectHand?.(id, f) === k && ownGrip(ctx, id, k, f) === null)) return;
 	const now = { s, diag, c }, anchor = ctx.spec.anchors?.[on.fit.anchor];
@@ -162,6 +162,12 @@ export function gripHand(ctx, sk, s, side, k, c, f, diag) {
 	const measure = st => ({ pos: effectorAt(sk, ctx.spec, st, side, on.fit.effector ?? {}), R: (({ d, l, n }) => cols(d, l, n))(palmAxes(sk, st, side)) });
 	const I = sk.index, a = I[`${side}Arm`], fa = I[`${side}ForeArm`], h = I[`${side}Hand`];
 	const long = thinAxis(box.half), axis = long >= 0 ? apply(box.R, AXES.map(i => (i === long ? 1 : 0))) : null;
+	// an upright thin body (a cup, a can) under a plain anchor that nothing carries is held the way a grasp holds it
+	// (socket-grip.js): a power wrap from the side, not the hand over its top with the fingers down along the forearm
+	// (session 7f15b4ae). A carried one keeps its carry's grip, a lying bar or handle the roll rule below.
+	if (axis && Math.abs(axis[1]) > UPRIGHT && !carryOf(ctx, box.id)) {
+		return socketHand(ctx, sk, s, side, k, c, diag, on, st => effectorAt(sk, ctx.spec, st, side, on.fit.effector ?? {}), { w: { p: A, axis }, type: "power" }, f);
+	}
 	const ax = palmAxes(sk, s, side), roll = norm(flat(ax.l, ax.d));
 	const axT = norm(sub(s.P[h], s.P[fa])), neutral = mul(s.R[fa], mul(T(sk.restWorldRot[fa]), sk.restWorldRot[h]));
 	const twist = wristNeed(neutral, s.R[h], axT, apply(mul(neutral, T(s.R[h])), ax.l)).twist;

package/src/motion3/compiler/socket-grip.js

@@ -60,23 +60,27 @@ export function socketCarry(ctx, k, f) {
 }
 
 /**
- * socketHand(ctx, sk, s, side, k, c, diag, on, effector): turn the hand of fit `on` ({ fit, w }) into its anchor's
- * socket grasp (see above); effector(st) is the fit's effector point on a pose.
+ * socketHand(ctx, sk, s, side, k, c, diag, on, effector, implicit, f): turn the hand of fit `on` ({ fit, w }) into its
+ * anchor's socket grasp (see above); effector(st) is the fit's effector point on a pose. `implicit` ({ w, type }) is
+ * the world socket and grasp of a fit without one (grip.js: an upright thin body under a plain anchor); f the frame.
  */
-export function socketHand(ctx, sk, s, side, k, c, diag, on, effector) {
+export function socketHand(ctx, sk, s, side, k, c, diag, on, effector, implicit = null, f = undefined) {
 	const I = sk.index, a = I[`${side}Arm`], fa = I[`${side}ForeArm`], h = I[`${side}Hand`], plain = s.R[fa];
-	const w = anchorSocket(ctx, on.fit.anchor, s, diag, c, k), F = effector(s), fwd = norm(sub(s.P[h], s.P[fa]));
-	const type = ctx.spec.anchors[on.fit.anchor].grasp, base = socketPalm(side, w, type, fwd, c.yaw);
+	const w = implicit?.w ?? anchorSocket(ctx, on.fit.anchor, s, diag, c, k), F = effector(s), fwd = norm(sub(s.P[h], s.P[fa]));
+	const type = implicit?.type ?? ctx.spec.anchors[on.fit.anchor].grasp, base = socketPalm(side, w, type, fwd, c.yaw);
 	const measure = st => ({ pos: effector(st), R: cols(palmAxes(sk, st, side)) }), now = measure(s);
 	// free to roll about its axis (no `from`): the roll the arm holds most easily, the Boltzmann mean of ROLLS rolls pulled
 	// lightly toward the fingers on the forearm's line, so the hand closes on the bar from the side the arm comes from
 	// then the knuckle line tilts on the bar (an oblique grip) up to TILT deg, priced, where the forearm cannot come across it
 	const strain = R => { const t = aimArm(sk, s, side, { pos: F, R }, now, 1, "palm"); return swivel(sk, s, side, t.goal, t.wristAt(t.goal), t.plane, ELBOW_REST).cost; };
 	const col = (M, i) => [M[0][i], M[1][i], M[2][i]], turned = th => mul(axisRot(col(base, 1), th * DEG), base);
-	const free = w.axis && !w.from && type !== "palm", roll = free ? softmin(th => strain(turned(th)) + PULL * (1 - Math.cos(th))) : 0;
-	const rolled = turned(roll), tilted = a => mul(axisRot(col(rolled, 2), a), rolled);
-	const tilt = w.axis && type !== "palm" ? mean(TILTS.map(a => [a, strain(tilted(a)) + SLANT * (a / TILT) ** 2])) : 0;
-	const R = tilted(tilt);
+	const pick = () => {
+		const free = w.axis && !w.from && type !== "palm", roll = free ? softmin(th => strain(turned(th)) + PULL * (1 - Math.cos(th))) : 0;
+		const rolled = turned(roll), tilted = a => mul(axisRot(col(rolled, 2), a), rolled);
+		const tilt = w.axis && type !== "palm" ? mean(TILTS.map(a => [a, strain(tilted(a)) + SLANT * (a / TILT) ** 2])) : 0;
+		return { R: tilted(tilt), roll, tilt };
+	};
+	const { R, roll, tilt } = plannedGrasp(ctx, on.fit.anchor, k, f, pick);
 	const { goal, plane, wristAt } = aimArm(sk, s, side, { pos: F, R }, now, on.w, "palm");
 	const arm = swivel(sk, s, side, goal, wristAt(goal), plane, ELBOW_REST, { w: on.w });
 	let need = { twist: 0, flex: 0, dev: 0 };
@@ -84,10 +88,30 @@ export function socketHand(ctx, sk, s, side, k, c, diag, on, effector) {
 		twoBone(sk, s, a, fa, h, wristAt(i ? s.R[h] : goal), arm.pole, ELBOW_REST, "elbow");
 		need = orient(sk, s, side, h, fa, goal);
 	}
-	diag[`grip_${k}`] = { w: on.w, socket: true, ...need };
+	diag[`grip_${k}`] = { w: on.w, socket: true, ...need, roll: roll * DEG, tilt };
 	diag[`socket_${k}`] = { rel: mul(T(plain), s.R[h]) };
 }
 
+/**
+ * The grasp frame a reach turns the hand into, chosen once on the reach's first full-weight frame and kept on the
+ * approach to it (ctx.graspPlans, per bake): a person sets the hand's turn for the grasp at its end and keeps it on the way
+ * (end-state comfort), and a choice taken anew every frame flipped between two near-equal rolls as the fingers closed
+ * (a 5.5 cm wrist jump in one frame). pick() chooses it on the pose being solved: { R, roll, tilt }.
+ */
+function plannedGrasp(ctx, name, k, f, pick) {
+	const ch = `w_${name}_${k}`, at = g => ctx.weightAt?.(ch, g) ?? 0;
+	if (!ctx.weightAt || !Number.isInteger(f)) return pick();
+	let a = f, g;
+	while (a > 0 && at(a - 1) > 1e-3) a--;
+	for (g = a; g < ctx.frameCount - 1 && at(g) < 0.999 && at(g + 1) > 1e-3; g++);
+	const key = `${ch}:${a}`;
+	ctx.graspPlans ??= new Map();
+	// from the grasp on, the hand follows what it holds (carried, it moves): the plan covers the approach only
+	if (f >= g) { const plan = pick(); if (f === g) ctx.graspPlans.set(key, plan); return plan; }
+	if (!ctx.graspPlans.has(key)) { ctx.graspPlans.set(key, null); (ctx.hold?.plainFrame ?? ctx.solvedAt)(g); }
+	return ctx.graspPlans.get(key) ?? pick();
+}
+
 /**
  * The hand of a socket carry after its grab keeps the grab frame's wrist turn against the forearm (see above), read
  * once per bake (ctx.socketTurns) off the grab frame solved without the keys: a keyed carry's curve is built on

package/src/motion3/docs.js

@@ -22,6 +22,6 @@ export const MOTION_ACTION_HELP = {
 		+ "A carried object takes pos [x, y, z] and rot [x, y, z, w], or aim [x, y, z] (its +Y) and roll?: its base's world pose (a group: its root), grab..release only (objects.<id>.keys); the hand follows. "
 		+ "A hinge takes angle (degrees) or rot (its turn about the axis). remove: true deletes the key at frame. Refused where the take neither holds nor hinges it (drag it then). "
 		+ "Answers keyed and the motion.compile output; REACH \"<id>: n cm off its keys\": what the hand missed.",
-	report: "Page through the parts of a motion.compile or motion.qa answer that did not fit (output.more): part is groups (the default), timeline or probes, from the item index to start at; "
+	report: "Page through the parts of a motion.compile or motion.qa answer that did not fit (output.more): specId names the answer (or characterId: its installed take's); part is groups (the default), timeline or probes, from the item index to start at; "
 		+ "answers { specId, part, from, items, next } (next = the index to ask for next, null at the end). Changes nothing.",
 };

package/src/motion3/fix/index.js

@@ -14,6 +14,8 @@
 //   self         arms out of the rest of the body on its fitted skin: the elbow turns about the
 //                shoulder-wrist line, the hand is pushed out along the skin (self.js)
 //   retime       speed spikes get more frames, borrowed from the neighbouring keys
+//   stance       a standIdle stance whose legs, feet or hips are in a scene body slides out of it, the least
+//                distance (skills/stance.js; applied when the skills expand, reported in observations.placed)
 import { lowerHips, armReach } from "./reach.js";
 import { lockFeet } from "./slide.js";
 import { holdTurns } from "./turn.js";
@@ -22,14 +24,14 @@ import { pushOut } from "./push.js";
 import { retime } from "./retime.js";
 import { selfClear } from "./self.js";
 
-const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime"];
+const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance"];
 export { FIX_KEYS };
 
 export function fixOptions(fix) {
-	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false };
+	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false };
 	const f = fix ?? {};
 	const pen = f.penetration === true ? 0.02 : Math.min(0.05, Math.max(0, Number(f.penetration) || 0));
-	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true };
+	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true, stance: f.stance !== false };
 }
 
 /** The slide report with the flat feet whose turn waited (turn.js): turns { frames, max deg }. */

package/src/motion3/pipeline.js

@@ -95,6 +95,8 @@ export function compileSpec(sent, { sk, scene }, opts = {}) {
 	if (paced.length) observations.paced = paced;
 	const cut = used.filter(u => u.cut).map(u => `${u.skill}: ${u.cut}`);
 	if (cut.length) observations.cut = cut;
+	const placed = used.filter(u => u.placed).map(u => `${u.skill} f${u.f0}: ${u.placed.why}: at [${u.placed.at.join(", ")}], heading ${u.placed.heading}`);
+	if (placed.length) observations.placed = placed;
 	if (plans.length) observations.planned = plans.map(p => p.note);
 	const timeline = timelineOf(out, { used, spec: expanded }), probes = asked && runProbes(out, asked, { spec: expanded, sk, scene, notes });
 	return { out, qa, observations, spec: resolved, expanded, used, fixed: out.fixed, search, timeline, ...(probes ? { probes } : {}), ...(notes.length ? { notes } : {}),

package/src/motion3/qa/spec-checks.js

@@ -11,6 +11,7 @@ import { sub, dot, norm, len } from "../compiler/math.js";
 import { carried } from "../compiler/limbs.js";
 import { resolveAnchor } from "../compiler/anchors.js";
 import { CAPSULES, segPoints, sdBox } from "./geometry.js";
+import { refDistance } from "../refs.js";
 
 export function pointOf(out, f, ref) {
 	const { s, diag, c } = out.frames[f], [kind, rest] = ref.split(/:(.*)/s);
@@ -20,6 +21,13 @@ export function pointOf(out, f, ref) {
 	throw new Error(`MOTION_SPEC_INVALID: check point "${ref}"`);
 }
 
+/** The part a contact target "anchor:<name>" holds by when that anchor takes a grasp (its socket's owner, else its object), else null. */
+function graspPart(out, ref) {
+	const [kind, name] = ref.split(/:(.*)/s), a = kind === "anchor" ? out.ctx.spec.anchors?.[name] : null;
+	if (a?.kind !== "object" || !a.grasp) return null;
+	return out.ctx.sockets?.get(name)?.owner ?? a.object;
+}
+
 const active = (out, f, when) => (Array.isArray(when) ? f + (out.f0 ?? 0) >= when[0] && f + (out.f0 ?? 0) <= when[1] : when ? (out.frames[f].c[when] ?? 0) > 0.99 : true);
 
 function alongDir(out, f, along) {
@@ -35,7 +43,10 @@ export function specChecks(out, checks = {}) {
 		for (const k of checks.contacts ?? []) if (active(out, f, k.when)) {
 			const a = pointOf(out, f, k.point), b = pointOf(out, f, k.target);
 			if (!a || !b) continue;
-			const e = len(sub(a, b));
+			// on a grasp's anchor the fingers close on the held part wherever the grasp turned them round it: they are on it
+			// when they are on its surface (as goals' near on an object), not on one point of it (session 7f15b4ae: 0.4 cm
+			// on the cup, read as 5.3 cm from the anchor)
+			const held = graspPart(out, k.target), e = held ? refDistance(out, f, k.point, `object:${held}`) ?? len(sub(a, b)) : len(sub(a, b));
 			if (e > (k.tol ?? 0.01)) push("CONTACT", `${k.name}: ${(e * 100).toFixed(1)} cm apart`, f, e, k.tol ?? 0.01);
 		}
 		for (const k of checks.orient ?? []) if (active(out, f, k.when)) {

package/src/motion3/schema/topics.js

@@ -65,7 +65,7 @@ export const NOTES = {
 	anchors: ["An anchor is a named point a hand can go to: key w_<anchor>_l / w_<anchor>_r from 0 to 1 with armw_<side> 1 (the IK arm).",
 		"An anchor name may not end in _l or _r.", "object anchors (a body or a group; local in its own axes) follow the object where it is (hinges, carries): put the other hand on a carried object with one; the carrying hand's own anchor stays where it took it. prop anchors are a point of a prop the other hand holds.",
 		"segment with reach slides from t toward tMin until the arm reaches it.",
-		"An object anchor with grasp (power, pinch, hook, palm) takes the hand by a socket of its object and the compiler turns the hand: power and hook put the knuckle line along the socket's axis with the palm on it, pinch holds at the fingertips, palm presses flat on the nearest face. socket names one (object.grasp sockets the user or you stored, or a thin part by its id: a bar, a grip, a magazine); without it the socket nearest local, or the shoulder. Two hands on one carried object: each hand an object anchor with grasp on its part (a rifle's grip and magazine). reachGrip on such an anchor closes the fingers to the grasp. Never key the wrist for it; a wrist you key (wtwist/wflex) wins.",
+		"An object anchor with grasp (power, pinch, hook, palm) takes the hand by a socket of its object and the compiler turns the hand: power and hook put the knuckle line along the socket's axis with the palm on it, pinch holds at the fingertips, palm presses flat on the nearest face. socket names one (object.grasp sockets the user or you stored, or a thin part by its id: a bar, a grip, a magazine; a disc, a steering wheel, is its rim, held where nearest the shoulder, and the hand stays there as it moves); without it the socket nearest local, or the shoulder. Two hands on one carried object: each hand an object anchor with grasp on its part (a rifle's grip and magazine). reachGrip on such an anchor closes the fingers to the grasp. Never key the wrist for it; a wrist you key (wtwist/wflex) wins.",
 		"person { person: <character id>, bone, offset? } is another character's joint where its installed take has it that frame (a hand on a shoulder, a push on the chest): install that character's take first; reachGrip on it allows the hand to touch that person."],
 	props: ["A prop is a set of points fixed to one hand, [d, l, n] along the palm axes; prop:<prop>.origin is the mean of its origin bones.",
 		"fits: the hand target moves so the effector (a prop point or the mean of joints), not the wrist, lands on the anchor.",
@@ -109,6 +109,6 @@ export const NOTES = {
 		"object:<id> takes a body or a group (the box around its parts); in a distance a bare object:<id> means its surface.",
 		"Goals and probes take every kind; spec.checks keep joint:, prop: and anchor:."],
 	fix: [`spec.fix keys: ${FIX_KEYS.join(", ")}; false turns all off. output.fixed reports what each one changed.`,
-		"reach, slide and self are on by default; penetration and retime are opt-in.",
+		"reach, slide, self and stance are on by default; penetration and retime are opt-in.",
 		"self keeps the arms out of the body on its fitted skin (QA BODY measures the same skin): wrist targets inside it go onto it, elbows turn about the shoulder-wrist line, a hand a little inside is pushed out. A fit's target (the mouth) is never moved; what is left is BODY, with checks.allow { part, object: <body part>, depth } for a contact meant to touch (a hand on a knee)."],
 };

package/src/motion3/schema/types.js

@@ -140,6 +140,7 @@ export const FIX_TYPES = {
 	penetration: { oneOf: [{ type: "boolean" }, { type: "number", minimum: 0, maximum: 0.05 }], default: 0, description: "push hands out of boxes up to this depth, m (true = 0.02)" },
 	self: bool("arms kept out of the body's skin (wrists, elbows)", { default: true }),
 	retime: bool("speed spikes borrow frames from the neighbouring keys", { default: false }),
+	stance: bool("a standIdle stance in a scene body slides out of it (observations.placed)", { default: true }),
 };
 
 export const REF_DOCS = {

package/src/motion3/skills/basic.js

@@ -5,22 +5,36 @@ import { walk } from "../compiler/walk.js";
 import { keyBook, skillError } from "./book.js";
 import { walkEnd } from "./info.js";
 import { GRASP_FINGERS, GRASP_POINTS } from "../compiler/vocab.js";
+import { clearStance, reachStance } from "./stance.js";
+import { CLOSE, GAZE, gazeAt, headKeyed, earlyTransport, holdsOpen, transportKeys } from "./reach-human.js";
 
 /** The fingers' point a reachGrip fits onto its anchor: the finger middles, or where a grasp holds the thing (the palm is -n on the right hand). */
 const graspPoint = (grasp, k) => (GRASP_POINTS[grasp] ? GRASP_POINTS[grasp].map((v, i) => (i === 2 && k === "r" ? -v : v)) : [0, 0, 0]);
 
-/** standIdle({ at: [x, z], heading = 0, until }): a neutral standing pose, arms down (FK). */
+/**
+ * standIdle({ at: [x, z], heading = 0, until }): a neutral standing pose, arms down (FK). Without `at` (and no root
+ * keyed) before a reachGrip it stands within that hand's reach of the anchor, facing it; a stance in a scene body
+ * slides out of it (stance.js). Either says so in `placed`.
+ */
 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)");
+	let h = args.heading ?? state.yaw ?? 0, base = args.at ?? (state.root ? [state.root[0], state.root[2]] : null), placed = null;
+	if (!base) {
+		const auto = reachStance(ctx);
+		if (!auto) skillError(ctx.tag, "needs args.at: [x, z] (no root is keyed before f0), or a reachGrip after it to stand within reach of");
+		({ at: base, heading: h } = auto);
+		placed = { at: base, heading: h, why: `within reach of anchor ${auto.anchor}` };
+	} else if (args.at && ctx.place !== false) {
+		const out = clearStance(sk, ctx.scene, [base[0], base[base.length - 1]], h);
+		if (out) { base = out.at; placed = { at: base, heading: h, why: `moved ${out.moved} m out of a scene body` }; }
+	}
 	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 };
+	return { keys, end: args.until ?? ctx.f0, ...(placed ? { placed } : {}) };
 }
 
 /**
@@ -52,6 +66,23 @@ export function walkTo(ctx) {
 	return { keys, end };
 }
 
+/** base when `props` has no other prop of that name (the same one again is fine), else base_<side>, base_<side>2, ... */
+function freeName(props = {}, base, k, mine) {
+	const taken = n => props[n] && JSON.stringify(props[n]) !== JSON.stringify(mine);
+	if (!taken(base)) return base;
+	let name = `${base}_${k}`;
+	for (let i = 2; taken(name); i++) name = `${base}_${k}${i}`;
+	return name;
+}
+
+/** What a hand on `obj` may touch: the object, or for a group (an Empty, no body of its own) every part under it. */
+const touchable = (scene, obj) => {
+	const objects = scene?.objects ?? {};
+	if (!obj || objects[obj] || obj.startsWith("person:")) return obj ? [obj] : [];
+	const parts = Object.keys(objects).filter(k => objects[k].ancestors?.includes(obj));
+	return parts.length ? parts : [obj];
+};
+
 /**
  * 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
@@ -67,23 +98,40 @@ export function reachGrip(ctx) {
 	// an anchor that takes a grasp closes the hand to that grasp's fingers (../sockets.js)
 	const grasp = (args.define ?? ctx.anchors?.[name])?.grasp, preset = args.fingers ?? GRASP_FINGERS[grasp] ?? "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;
+	// a take that ends before the hand lets go cuts the hold or the release: the grip holds to the last frame (a hold
+	// asked past the end was refused, session 7f15b4ae: "needs 92 frames from f10 (to f102), past the last frame f85")
+	const last = ctx.frames - 1, cut = ctx.f0 + reach <= last && ctx.f0 + reach + hold + release > last;
+	const held = Math.min(reach + hold, last - ctx.f0);
 	for (const [c, v] of [[w, 0], [fg, { [preset]: 0 }], [armw, 0]]) if (state[c] === undefined) state[c] = v;
+	// the head looks at what the hand goes for unless the keys already move it (reach-human.js); read before the keys move state
+	// the reach's own view: a thing that spec.objects moves before the hand gets there is not at rest (reach-human.js)
+	const end = reach + hold + release, rc = { ...ctx, until: ctx.f0 + reach };
+	const look = !headKeyed(ctx.keys ?? [], ctx.f0, ctx.f0 + end) && gazeAt(rc, args.define ?? ctx.anchors?.[name], state);
+	const head = look ? { head_yaw: state.head_yaw ?? 0, head_pitch: state.head_pitch ?? 0 } : null;
 	const b = keyBook(state, ctx.f0);
-	b.hold(0, w, fg, armw, el);
+	b.hold(0, w, fg, armw, el, ...(look ? ["head_yaw", "head_pitch"] : []));
+	// the transport's early-peaked bell; on a thing the open hand clears, the fingers stay open to CLOSE of the reach, then close
+	// (a reach for a moving point, or below the knees, keeps the plain ease: reach-human.js earlyTransport)
+	const target = args.define ?? ctx.anchors?.[name], w0 = state[w], a0 = state[armw], lerp = (a, z, t) => a + (z - a) * t;
+	if (earlyTransport(rc, target)) for (const [f, t, ta] of transportKeys(reach)) b.at(f, { [w]: lerp(w0, 1, t), [armw]: lerp(a0, 1, ta) });
+	const close = Math.round(CLOSE * reach);
+	if (close > 0 && close < reach && holdsOpen(rc, target, state)) b.hold(close, fg);
+	if (look) b.at(Math.max(1, Math.round(GAZE * reach)), look);
 	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`;
+	b.hold(held, w, fg, armw, el, ...(look ? ["head_yaw", "head_pitch"] : []));
+	if (!cut) b.at(end, { [w]: 0, [fg]: { ...state[fg], [preset]: 0 }, ...(wasFk ? { [armw]: 0 } : {}), ...(head ?? {}) });
+	// the fingers' prop is <anchor>Grip, unless the spec (or another skill) has a prop of that name of its own: its points
+	// would replace these (session 7f15b4ae: props.ballGrip for a carry broke reachGrip on anchor "ball")
+	const S = k === "l" ? "Left" : "Right", fingersProp = { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: graspPoint(grasp, k) } };
+	const prop = freeName(ctx.props, `${name}Grip`, k, fingersProp);
 	const def = args.define ? { [name]: args.define } : {};
 	// the hand may touch what it grips: an object, or the other person (people.js) whose joint the anchor is on
 	const a = args.define ?? ctx.anchors?.[name], obj = a?.kind === "object" ? a.object : a?.kind === "person" ? `person:${a.person}` : 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: graspPoint(grasp, k) } } },
+		keys: b.keys, end: cut ? last : ctx.f0 + reach + hold + release, ...(cut ? { cut: `${held < reach + hold ? "hold" : "release"} cut at f${last} (hold to the end)` } : {}), anchors: def,
+		props: { [prop]: fingersProp },
 		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 }] : [] },
+			allow: touchable(ctx.scene, obj).map(object => ({ part: "hand", object, depth: 0.04 })) },
 	};
 }

package/src/motion3/skills/index.js

@@ -7,6 +7,7 @@ import { stateAt } from "../compiler/walk.js";
 import { didYouMean, suggestField } from "../compiler/vocab.js";
 import { USE_FIELDS } from "../schema/fields.js";
 import { SKILL_INFO } from "./info.js";
+import { fixOptions } from "../fix/index.js";
 import { standIdle, walkTo, reachGrip } from "./basic.js";
 import { sitInSeat, exitCar } from "./car.js";
 import { smokeCigarette } from "./smoke.js";
@@ -60,7 +61,8 @@ export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
 		argsOk(u, i, lenient);
 		if (!Number.isInteger(u.f0) || u.f0 < 0 || u.f0 > spec.frames - 1) bad(`use[${i}].f0 must be an integer frame within 0..${spec.frames - 1}, got ${JSON.stringify(u.f0)}`);
 		const keys = [...skillKeys, ...own];
-		const ctx = { sk, scene, frames: spec.frames, auto, self: spec.fix !== false && spec.fix?.self !== false, f0: u.f0, args: structuredClone(u.args ?? {}), tag, keys, state: structuredClone(stateAt(keys, u.f0)), anchors: { ...merged.anchors, ...spec.anchors } };
+		const ctx = { sk, scene, frames: spec.frames, auto, props: { ...merged.props, ...spec.props }, self: spec.fix !== false && spec.fix?.self !== false, f0: u.f0, args: structuredClone(u.args ?? {}), tag, keys,
+			use: spec.use, index: i, place: fixOptions(spec.fix).stance, state: structuredClone(stateAt(keys, u.f0)), anchors: { ...merged.anchors, ...spec.anchors }, objects: { ...merged.objects, ...spec.objects } };
 		const part = SKILLS[u.skill](ctx), last = Math.max(part.end ?? u.f0, ...part.keys.map(k => k.f));
 		if (last > spec.frames - 1) bad(`${tag} needs ${last - u.f0} frames from f${u.f0} (to f${last}), past the last frame f${spec.frames - 1}; set frames >= ${last + 1} or frames: "auto"`);
 		skillKeys.push(...part.keys.map(k => ({ ...k, src: k.src ?? tag })));
@@ -70,7 +72,7 @@ export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
 		for (const fit of part.fits ?? []) if (!merged.fits.some(x => same(x, fit))) merged.fits.push(fit);
 		for (const ch of part.channels ?? []) if (!merged.channels.includes(ch)) merged.channels.push(ch);
 		mergeChecks(merged.checks, part.checks);
-		used.push({ skill: u.skill, f0: u.f0, end: part.end, ...(part.paced ? { paced: part.paced } : {}), ...(part.cut ? { cut: part.cut } : {}) });
+		used.push({ skill: u.skill, f0: u.f0, end: part.end, ...(part.paced ? { paced: part.paced } : {}), ...(part.cut ? { cut: part.cut } : {}), ...(part.placed ? { placed: part.placed } : {}) });
 	});
 	const out = { ...spec, keys: [...skillKeys, ...own], anchors: { ...merged.anchors, ...spec.anchors }, props: { ...merged.props, ...spec.props },
 		objects: { ...merged.objects, ...spec.objects } };

package/src/motion3/skills/info.js

@@ -19,7 +19,7 @@ const walkArgs = Object.fromEntries(WALK_FIELDS.filter(f => f !== "type" && f !=
 
 export const SKILL_INFO = {
 	standIdle: {
-		args: { at: xz("[x, z] world m; default the root keyed before f0"), heading: num("degrees (yaw); default the keyed yaw"), until: int("hold the pose to this frame") },
+		args: { at: xz("[x, z] world m; default the root keyed before f0, else within reach of the next reachGrip's anchor (output.observations.placed); a stance in a body slides out of it"), heading: num("degrees (yaw); default the keyed yaw"), until: int("hold the pose to this frame") },
 		needs: "args.at, or a root keyed before f0", frames: "1 (to args.until when given)",
 		adds: ["keys: a standing pose, FK arms down"], example: { f0: 0, args: { at: [0, 0], heading: 0 } },
 		place: { at: 0.03 },