cozyclay 3.0.3 → 3.1.1

package/src/motion3/compiler/finger-close.js

@@ -0,0 +1,137 @@
+// Fingers close on what the hand holds (#816). A preset curls each phalanx a fixed angle, which fits one size: on a
+// ball the index and middle sank 3 cm into it while the little finger stayed in the air (session 7f15b4ae). After the
+// arm, the hold and the elbow's swivel have placed the hand (pose.js), each finger closes phalanx by phalanx, from the
+// knuckle out: the joint turns further about the axis it curls on until the rest of the finger first touches a held
+// shape (shapes.js; its skin within TOUCH m of the surface), never past the fist's curl; a finger that cannot reach it
+// keeps the preset's curl (closing on air would curl it into whatever lies under the palm). The thumb keeps the preset's
+// turn at its base and flexes its outer joints the same way. Found by bisection (STEPS evaluations a joint) on the joints' positions,
+// then turned once; weighted by how far the hand holds (a fit's weight), so the fingers close over the reach and open
+// on the release. A joint the preset curled into the body straightens when that leaves the finger shallower; a
+// joint whose sub-chain already touches stays, and the next joint out closes on: the finger wraps the body.
+import { add, sub, scale, norm, cross, apply, axisRot } from "./math.js";
+import { rotateSubtree } from "./skeleton.js";
+import { palmAxes, fingerCurl, fistCurl } from "./limbs.js";
+import { capsuleDepth } from "../shapes.js";
+import { partsOf } from "../object-pose.js";
+import { seatsInHand } from "../seat.js";
+
+const PHALANX = 0.009, TOUCH = 0.002, STEPS = 8, THUMB_FLEX = 70;
+const FINGERS = ["Index", "Middle", "Ring", "Pinky"];
+// the hand stays open for most of a reach and closes as it arrives: from OPEN_UNTIL of the fit's weight to CLOSED_AT
+const OPEN_UNTIL = 0.6, CLOSED_AT = 0.9;
+const closing = w => { const t = Math.min(1, Math.max(0, (w - OPEN_UNTIL) / (CLOSED_AT - OPEN_UNTIL))); return t * t * (3 - 2 * t); };
+
+function chainDepth(points, entries) {
+	let depth = -Infinity;
+	for (let i = 0; i + 1 < points.length; i++) for (const e of entries) depth = Math.max(depth, capsuleDepth(e, points[i], points[i + 1], PHALANX));
+	return depth;
+}
+
+/** The turn (deg, 0..limit) about unit `axis` at `pivot` at which the chain first touches: 0 when it already does, null when it never does. */
+function touchTurn(points, pivot, axis, limit, entries) {
+	if (limit <= 0 || chainDepth(points, entries) >= -TOUCH) return 0;
+	const at = deg => { const R = axisRot(axis, deg); return points.map(p => add(pivot, apply(R, sub(p, pivot)))); };
+	if (chainDepth(at(limit), entries) < -TOUCH) return null;
+	let lo = 0, hi = limit;
+	for (let i = 0; i < STEPS; i++) { const mid = (lo + hi) / 2; if (chainDepth(at(mid), entries) >= -TOUCH) hi = mid; else lo = mid; }
+	return hi;
+}
+
+/** The turn (deg, 0..limit) back about `axis` that takes a chain inside the body just out of it (0 when it is out, or when
+ * no opening leaves it shallower). */
+function clearTurn(points, pivot, axis, limit, entries) {
+	if (chainDepth(points, entries) < -TOUCH) return 0;
+	const at = deg => { const R = axisRot(axis, -deg); return points.map(p => add(pivot, apply(R, sub(p, pivot)))); };
+	// a chain that stays in the body however far it opens opens only if that leaves it shallower
+	if (chainDepth(at(limit), entries) >= -TOUCH) return chainDepth(at(limit), entries) < chainDepth(points, entries) ? limit : 0;
+	let lo = 0, hi = limit;
+	for (let i = 0; i < STEPS; i++) { const mid = (lo + hi) / 2; if (chainDepth(at(mid), entries) < -TOUCH) hi = mid; else lo = mid; }
+	return hi;
+}
+
+/** Turns joint j by the touching turn about `axis` (or `limit` when it never touches, unless `air` is false), weighted; true when it touched. */
+function closeJoint(sk, s, j, chain, axis, limit, entries, weight, air = true) {
+	const turn = touchTurn(chain.map(i => s.P[i]), s.P[j], axis, limit, entries), deg = turn ?? (air ? limit : 0);
+	if (deg > 0) rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(axis, deg * weight));
+	return turn !== null;
+}
+
+/**
+ * closeOnShape(sk, s, side, { entries, weight, preset }): the hand on pose s ("Left" | "Right") closes on the shape
+ * entries (motion-scene entries at this frame) by `weight` 0..1; `preset` is the hand's finger weights (its fingers_<k>
+ * channel), from which each joint may close as far as the fist's curl. Answers { touched: the fingers that reached it }.
+ */
+export function closeOnShape(sk, s, side, { entries: held, stops = [], weight, preset }) {
+	if (!held?.length || !(weight > 0)) return { touched: [] };
+	// a finger stops on what it holds or on what that rests against (a table under a ball)
+	const entries = [...held, ...stops];
+	const sign = side === "Left" ? -1 : 1, J = name => sk.index[`${side}Hand${name}`], touched = [];
+	for (const f of FINGERS) {
+		const joints = [1, 2, 3, 4].map(i => J(`${f}${i}`));
+		if (joints.some(j => j === undefined)) continue;
+		let tip = false;
+		// a finger the preset curled into the body straightens, joint by joint, when the straight finger is shallower (a
+		// finger lying across a box would go deeper); each joint then closes until the finger touches
+		const pts = joints.map(i => s.P[i]), l0 = scale(palmAxes(sk, s, side).l, sign);
+		const straight = [0, 1, 2].reduce((p, k) => { const R = axisRot(l0, -fingerCurl(preset, f, k)); return p.map((q, i) => (i > k ? add(p[k], apply(R, sub(q, p[k]))) : q)); }, pts);
+		const opens = chainDepth(pts, held) >= -TOUCH && chainDepth(straight, held) < chainDepth(pts, held);
+		for (let k = 0; k < 3; k++) {
+			const axis = scale(palmAxes(sk, s, side).l, sign), curl = fingerCurl(preset, f, k), open = opens ? curl : 0;
+			if (open > 0) rotateSubtree(sk, s, joints[k], s.P[joints[k]].slice(), axisRot(axis, -open * weight));
+			tip = closeJoint(sk, s, joints[k], joints.slice(k), axis, Math.max(0, fistCurl(f, k) - curl + open), entries, weight, false);
+		}
+		if (tip) touched.push(f);
+	}
+	const thumb = [1, 2, 3, 4].map(i => J(`Thumb${i}`));
+	if (thumb.every(j => j !== undefined)) {
+		// the thumb keeps the preset's turn at its base (wrapThumb); its two outer joints back out of the body when the
+		// preset wrapped them into it, then flex until the thumb touches (one that cannot reach it keeps the preset's flex)
+		const { n } = palmAxes(sk, s, side);
+		let reached = false;
+		for (const k of [1, 2]) {
+			const axis = scale(norm(cross(norm(sub(s.P[thumb[k + 1]], s.P[thumb[k]])), n)), sign);
+			const out = clearTurn(thumb.slice(k).map(i => s.P[i]), s.P[thumb[k]], axis, THUMB_FLEX, entries);
+			if (out > 0) rotateSubtree(sk, s, thumb[k], s.P[thumb[k]].slice(), axisRot(axis, -out * weight));
+			reached = closeJoint(sk, s, thumb[k], thumb.slice(k), axis, THUMB_FLEX, entries, weight, false);
+		}
+		if (reached) touched.push("Thumb");
+	}
+	return { touched };
+}
+
+/**
+ * What hand k closes on at frame f with channels c: the object of its heaviest fit on an object anchor with grasp, while
+ * that object is not in its hand yet (a carry's hand holds it by its seat, seat.js), as { entries, weight, preset }; null
+ * when it reaches for nothing.
+ */
+export function heldFor(ctx, c, f, k, s) {
+	let best = null;
+	for (const fit of ctx.spec.fits ?? []) {
+		const a = ctx.spec.anchors?.[fit.anchor], w = c[`w_${fit.anchor}_${k}`] ?? 0;
+		if (fit.side !== k || a?.kind !== "object" || !a.grasp || !(w > 1e-4) || (best && best.weight >= w) || ctx.objectHand(a.object, f) === k) continue;
+		// a disc's rim socket (a steering wheel) is a ring the scene draws as a solid disc: the hand keeps its rim grip
+		if (ctx.sockets?.get(fit.anchor)?.rim) continue;
+		const at = ctx.objectsAt(f), entries = partsOf(ctx.scene, a.object).map(p => at[p]).filter(Boolean);
+		// as far as the skill has the hand closing (reachGrip keys its grip late in the reach: skills/reach-human.js)
+		const grip = Math.min(1, Object.entries(c[`fingers_${k}`] ?? {}).reduce((acc, [p, v]) => acc + (p === "relaxed" ? 0 : v || 0), 0));
+		if (entries.length) best = { entries, weight: closing(w) * grip, preset: c[`fingers_${k}`] };
+	}
+	return best ?? carriedFor(ctx, c, f, k, s);
+}
+
+/** A carry on the grasp path hand k holds at frame f, at its seat on pose s (seat.js), as { entries, weight, preset }. */
+function carriedFor(ctx, c, f, k, s) {
+	const { spec, scene } = ctx;
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		if (!seatsInHand(spec, o, scene, id) || spec.props?.[o.prop]?.hand !== k || !s) continue;
+		// the hand holds it from the grab on (the object eases into its seat meanwhile, settleAt)
+		const [grab, release] = ctx.carrySpan(o), weight = 1;
+		// while the keyed offset is being taken (its grab frame solved without the keys) the hand has nothing seated yet
+		if (f < grab || f > release || ctx.hold?.attaching(id)) continue;
+		// where it is on this pose (object-pose.js: easing into its seat over the settle, as it is drawn), not the full seat
+		const entries = partsOf(scene, id).map(p => ({ ...scene.objects[p], ...ctx.objectPose(p, f, { s }) }));
+		const near = Object.entries(ctx.objectsAt(f)).filter(([key, e]) => !partsOf(scene, id).includes(key) && e.half && !e.carried && entries.some(h => Math.hypot(...h.pos.map((v, i) => v - e.pos[i])) < 0.25 + Math.hypot(...e.half))).map(([, e]) => e);
+		if (entries.length) return { entries, stops: near, weight, preset: c[`fingers_${k}`] };
+	}
+	return null;
+}

package/src/motion3/compiler/limbs.js

@@ -158,12 +158,27 @@ const FINGER_PRESETS = {
 	grip: { Index: [55, 60, 35], Middle: [60, 62, 35], Ring: [62, 62, 35], Pinky: [65, 62, 35], Thumb: [15, 10, 8] },
 	cigarette: { Index: [8, 10, 6], Middle: [10, 12, 8], Ring: [60, 75, 45], Pinky: [65, 80, 45], Thumb: [35, 25, 20] },
 	point: { Index: [0, 0, 0], Middle: [80, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [40, 30, 30] },
+	spherical: { Index: [35, 40, 25], Middle: [38, 42, 25], Ring: [40, 42, 25], Pinky: [42, 44, 25], Thumb: [15, 10, 8] },
 };
+// A ball's fingers fan out round it (#816): each finger turns about the palm normal at its knuckle, degrees toward the
+// thumb side (+), by preset weight; the index leads the thumb round one side, the little finger the other.
+const SPREAD = { spherical: { Index: 9, Middle: 2, Ring: -5, Pinky: -12 } };
+
+/** Degrees phalanx k (0..2) of finger f curls at preset weights `weights` (blended over relaxed). */
+export function fingerCurl(weights, f, k) {
+	const base = FINGER_PRESETS.relaxed;
+	return base[f][k] + Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * ((FINGER_PRESETS[p]?.[f]?.[k] ?? base[f][k]) - base[f][k]), 0);
+}
+/** The fist's curl of phalanx k of finger f: as far as a finger closes. */
+export const fistCurl = (f, k) => FINGER_PRESETS.fist[f][k];
 
 /** Blend presets by weight over `relaxed` and curl every finger toward the palm. */
 export function fingers(sk, s, side, weights) {
-	const base = FINGER_PRESETS.relaxed, sign = side === "Left" ? -1 : 1;
-	const curl = (f, k) => base[f][k] + Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * ((FINGER_PRESETS[p]?.[f]?.[k] ?? base[f][k]) - base[f][k]), 0);
+	const sign = side === "Left" ? -1 : 1, curl = (f, k) => fingerCurl(weights, f, k);
+	for (const f of ["Index", "Middle", "Ring", "Pinky"]) {
+		const spread = Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * (SPREAD[p]?.[f] ?? 0), 0), j = sk.index[`${side}Hand${f}1`];
+		if (spread && j !== undefined) rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(palmAxes(sk, s, side).n, spread));
+	}
 	for (const f of ["Index", "Middle", "Ring", "Pinky", "Thumb"]) {
 		for (let k = 0; k < 3; k++) {
 			const j = sk.index[`${side}Hand${f}${k + 1}`];
@@ -181,7 +196,7 @@ export function fingers(sk, s, side, weights) {
 // palm and across it, then flexed at its two joints about their own axes (bone x palm normal). The fist's thumb lies over
 // the index and middle fingers' middle phalanges; the grip's closes around a handle against the index finger. Searched on
 // both rigs within the joints' ranges (thumb tip to the index's middle phalanx: fist 8.4 -> 3.7 cm Y Bot, 6.9 -> 2.4 X Bot).
-const THUMB_WRAP = { fist: [-70, -5, 5, 80], grip: [-30, -30, 30, 10] };
+const THUMB_WRAP = { fist: [-70, -5, 5, 80], grip: [-30, -30, 30, 10], spherical: [-40, -20, 20, 10] };
 function wrapThumb(sk, s, side, [oppose, across, flex2, flex3]) {
 	const sign = side === "Left" ? -1 : 1, J = k => sk.index[`${side}HandThumb${k}`];
 	if (J(1) === undefined) return;

package/src/motion3/compiler/pose.js

@@ -6,6 +6,7 @@ import { add, sub, scale, norm, len, apply, mul, rx, ry, rz } from "./math.js";
 import { restState, rotateSubtree } from "./skeleton.js";
 import { twoBone, orientFoot, wrist, fingers, limitFold, askedFold, swivelElbow, ELBOW_FOLD, KNEE_FOLD } from "./limbs.js";
 import { holdHand } from "./hold.js";
+import { closeOnShape } from "./finger-close.js";
 import { clampWrist } from "./wrist-clamp.js";
 import { ELBOW_REST } from "./arm-orient.js";
 import { wristBody, bodyDistance } from "../body.js";
@@ -147,6 +148,9 @@ export function pose(sk, c, hooks = {}) {
 			if (hooks.keepOut) target = hooks.keepOut(k, s, target);
 			const push = hooks.push?.(k);
 			if (push) target = add(target, push);
+			// what the hand carries weighs it down (load.js)
+			const sag = hooks.sag?.(k, s, target);
+			if (sag) target = add(target, sag);
 			// the self fix's push rides the IK as far as the arm is on it (an arm coming in from FK would jump)
 			const skinPush = hooks.skinPush?.(k);
 			if (skinPush) target = add(target, scale(skinPush, turnWeight(w)));
@@ -171,6 +175,8 @@ export function pose(sk, c, hooks = {}) {
 		// the turn keeps the hand's world turn; a wrist it takes past its limits stops there and the hand turns with the elbow
 		// (wrist-clamp.js), unless keys lead what the hand holds: that hand keeps the object's grip (hold.js limits its wrist)
 		if (turn) { swivelElbow(sk, s, side, turn * turnWeight(w)); if (!held) clampWrist(sk, s, side); }
+		const grasped = hooks.heldShapes?.(k, s);
+		if (grasped) diag[`closed_${k}`] = closeOnShape(sk, s, side, grasped).touched;
 		hooks.afterArm?.(k, s, diag);
 	}
 	return { s, diag };

package/src/motion3/compiler/validate-objects.js

@@ -7,7 +7,7 @@
 // of the body. A free entry { keys?, fall?, visible?, level? } (C17: no prop, no follow, no hinge field) moves a body or a
 // group on its own: world pose keys over the whole take, and gravity falls; a carry takes fall too, before its grab
 // or from its release on. Fields: schema/fields.js OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS. See validate.js.
-import { isVec3, fmt, didYouMean } from "./vocab.js";
+import { isVec3, fmt, didYouMean, GRASPS } from "./vocab.js";
 import { objectOk } from "./validate-common.js";
 import { OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS } from "../schema/fields.js";
 import { isSwitch, isFollow, movesRecord } from "../carried.js";
@@ -15,7 +15,7 @@ import { isFree } from "../free-motion.js";
 import { checkRef } from "../refs.js";
 import { partsOf } from "../object-pose.js";
 
-const KEY = "{ f, pos: [x, y, z], rot: [x, y, z, w] } or { f, pos, aim: [x, y, z], roll? }", FALL = "{ at, onto?, bounce?, tumble? }";
+const KEY = "{ f, pos: [x, y, z], rot: [x, y, z, w] } or { f, pos, aim: [x, y, z], roll? }", FALL = "{ at, onto?, bounce?, tumble?, v? }";
 const isQuat = q => Array.isArray(q) && q.length === 4 && q.every(Number.isFinite) && Math.abs(Math.hypot(...q) - 1) <= 0.01;
 const isDir = v => isVec3(v) && Math.hypot(...v) > 1e-9;
 
@@ -94,10 +94,23 @@ function validateFalls(err, unknown, at, o, { frames, scene, carry }) {
 		}
 		if (fl.onto !== undefined) objectOk(err, scene, `${fat}.onto`, fl.onto, { groups: true });
 		if (fl.bounce !== undefined && !(Number.isFinite(fl.bounce) && fl.bounce >= 0 && fl.bounce <= 0.6)) err(`${fat}.bounce must be 0..0.6 (the share of its landing speed it bounces back with; 0 lands dead), got ${fmt(fl.bounce)}`);
+		if (fl.v !== undefined && !((carry && fl.v === "hand") || isVec3(fl.v))) err(`${fat}.v must be [vx, vy, vz] m/s (the velocity it leaves with)${carry ? " or \"hand\" (the velocity the hand gives it at the release)" : ""}, got ${fmt(fl.v)}`);
 		if (fl.tumble !== undefined && typeof fl.tumble !== "boolean") err(`${fat}.tumble must be true (it rolls to rest on a stable face, the default) or false (it drops straight down as it was), got ${fmt(fl.tumble)}`);
 	});
 }
 
+/** A grasp that starts like the given one (4+ letters: "sphere" -> spherical), else the nearest by edit distance. */
+const prefixLen = (a, b) => { let i = 0; while (i < a.length && a[i] === b[i]) i += 1; return i; };
+function graspHint(given) {
+	const text = String(given), best = GRASPS.reduce((a, b) => (prefixLen(b, text) > prefixLen(a, text) ? b : a));
+	return prefixLen(best, text) >= 4 ? `; did you mean "${best}"?` : didYouMean(text, GRASPS);
+}
+
+/** mass (kg): what the object weighs, for the arm that holds it (#816). */
+function massOk(err, at, o) {
+	if (o.mass !== undefined && !(Number.isFinite(o.mass) && o.mass >= 0.01 && o.mass <= 60)) err(`${at}.mass must be kg in 0.01..60, got ${fmt(o.mass)}`);
+}
+
 /** visible and level name channels (C15): visible shows the record above 0.5, level scales its light, glow and effect rate. */
 function channelsOk(err, at, o) {
 	if (o.visible !== undefined && (typeof o.visible !== "string" || !o.visible)) err(`${at}.visible must name a channel (shown above 0.5)`);
@@ -110,6 +123,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		// a switch and a follow take any record (a light, an effect); the others a body or a group
 		if ((kind !== "switch" && kind !== "follow") || !scene?.others?.[id]) objectOk(err, scene, at, id, { groups: true });
 		for (const f of Object.keys(o ?? {})) if (!fields.includes(f) && !(kind === "hinge" && (f === "keys" || f === "fall"))) unknown(`${at} (${kind}) has unknown field "${f}"${didYouMean(f, fields)}; fields: ${fields.join(", ")}`);
+		massOk(err, at, o);
 		if (kind === "follow") {
 			validateFollow(spec, err, { sk, scene }, at, o);
 			channelsOk(err, at, o);
@@ -129,6 +143,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		if (kind === "carry") {
 			if (!spec.props?.[o.prop]) err(`${at}.prop "${o.prop}" is not in spec.props`);
 			for (const f of ["at", "along"]) if (o[f] !== undefined && !isVec3(o[f])) err(`${at}.${f} must be [d, l, n] along the palm axes, got ${fmt(o[f])}`);
+			if (o.grasp !== undefined && !GRASPS.includes(o.grasp)) err(`${at}.grasp must be one of ${GRASPS.join(", ")}${graspHint(o.grasp)}, got ${fmt(o.grasp)}`);
 			channelsOk(err, at, o);
 			if (frameOk(err, `${at}.grab`, o.grab, frames) && frameOk(err, `${at}.release`, o.release, frames)
 				&& o.grab !== undefined && o.release !== undefined && !(o.grab < o.release)) err(`${at}: grab (${o.grab}) must come before release (${o.release})`);

package/src/motion3/compiler/validate-parts.js

@@ -107,8 +107,9 @@ function validateChecks(spec, err, { sk, scene, frames, unknown = err, past = ""
 	each("allow");
 	for (const name of Object.keys(c.limits ?? {})) if (!(name in QA_LIMITS)) unknown(`checks.limits.${name} is not a QA limit${didYouMean(name, Object.keys(QA_LIMITS))}`);
 	const fix = spec.fix;
-	if (fix !== undefined && fix !== false && (typeof fix !== "object" || fix === null)) err("spec.fix must be false or { reach, slide, penetration, self, retime }");
+	if (fix !== undefined && fix !== false && (typeof fix !== "object" || fix === null)) err(`spec.fix must be false or { ${FIX_KEYS.join(", ")} }`);
 	else for (const k of Object.keys(fix || {})) if (!FIX_KEYS.includes(k)) unknown(`spec.fix.${k} is not a fix${didYouMean(k, FIX_KEYS)} (fixes: ${FIX_KEYS.join(", ")})`);
+	if (fix && fix.grasp !== undefined && typeof fix.grasp !== "boolean") err(`spec.fix.grasp must be true (fingers close on what a hand holds, the default) or false (the preset grip, the object at its grab-frame offset), got ${fmt(fix.grasp)}`);
 }
 
 /** opts = { sk, scene, frames, lenient, unknown: err for an unknown field (a no-op when lenient), past: the

package/src/motion3/compiler/vocab.js

@@ -10,13 +10,13 @@ export const NUM_CHANNELS = new Set(["yaw", "pitch", "roll", "spine_yaw", "spine
 export const MAP_CHANNELS = new Set(sided(["fingers"]));
 // Channels the skills key (standIdle, walks): valid in a spec, left out of motion.describe so a first spec need not read them.
 export const SKILL_CHANNELS = new Set(["arm_hang"]);
-export const FINGER_PRESETS = ["relaxed", "fist", "grip", "cigarette", "point"];
+export const FINGER_PRESETS = ["relaxed", "fist", "grip", "cigarette", "point", "spherical"];
 /** The grasps an object anchor takes a hand by (../sockets.js), and the finger preset each closes the hand to by default. */
-export const GRASPS = ["power", "pinch", "hook", "palm"];
-export const GRASP_FINGERS = { power: "grip", pinch: "cigarette", hook: "grip", palm: "relaxed" };
+export const GRASPS = ["power", "pinch", "hook", "palm", "spherical"];
+export const GRASP_FINGERS = { power: "grip", pinch: "cigarette", hook: "grip", palm: "relaxed", spherical: "spherical" };
 /** Where the held thing sits in the hand, [d, l, n] on the palm axes from the finger middles (n toward the palm; m): a bar in a
  * power grip or a hook lies across the palm under the finger middles, a pinch is held at the fingertips, a flat palm presses with its centre. */
-export const GRASP_POINTS = { power: [0, 0, 0.02], hook: [0, 0, 0.02], pinch: [0.025, 0, 0.01], palm: [-0.045, 0, 0.015] };
+export const GRASP_POINTS = { power: [0, 0, 0.02], hook: [0, 0, 0.02], pinch: [0.025, 0, 0.01], palm: [-0.045, 0, 0.015], spherical: [-0.015, 0, 0.035] };
 
 // [min, max, convention] for numeric channels whose values have a hard range.
 const RANGES = [

package/src/motion3/describe.js

@@ -103,8 +103,8 @@ function describeSkill(name) {
 const MEANT = { topics: ["objects", "channels"], skills: ["reachGrip"] };
 /** Topics no round-2 session needed for a first spec: essentials names their parts, the full topic has the fields. */
 const SHALLOW = ["checks"];
-/** Skills essentials leaves to topic skills: a flip or cartwheel is no first spec's need, and essentials has no room. */
-const FIRST_SPEC_SKIP = ["flip"];
+/** Skills essentials leaves to topic skills: a flip, a cartwheel or a body thrown by a hit is no first spec's need, and essentials has no room. */
+const FIRST_SPEC_SKIP = ["flip", "hitReaction", "throwObject", "catchObject"];
 
 /** A shared shape whose fields are mostly a skill's args (walk, walkTo): its own fields and `...<skill> args`. */
 function shapeLine(d) {

package/src/motion3/fix/index.js

@@ -16,6 +16,8 @@
 //   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)
+//   grasp        a holding hand's fingers close on what it holds and the object rests in the hand (#816);
+//                false keeps the preset grip and the grab-frame offset
 import { lowerHips, armReach } from "./reach.js";
 import { lockFeet } from "./slide.js";
 import { holdTurns } from "./turn.js";
@@ -24,14 +26,14 @@ import { pushOut } from "./push.js";
 import { retime } from "./retime.js";
 import { selfClear } from "./self.js";
 
-const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance"];
+const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance", "grasp"];
 export { FIX_KEYS };
 
 export function fixOptions(fix) {
-	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false };
+	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false, grasp: 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, stance: f.stance !== false };
+	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true, stance: f.stance !== false, grasp: f.grasp !== false };
 }
 
 /** The slide report with the flat feet whose turn waited (turn.js): turns { frames, max deg }. */

package/src/motion3/flight.js

@@ -0,0 +1,38 @@
+// A fall that leaves with a velocity (#816): a thrown thing. fall.v is the velocity its root leaves with, m/s, or "hand"
+// on a carry: the velocity the hand gives it at the release, its pose a frame after minus a frame before, x fps (the
+// frames beforePose gives the spin from, free-motion.js afterRelease). Without v, and with v zero, a fall is as before.
+// It flies on a parabola (G of free-motion.js) and lands on the first surface its path comes down onto: the highest top
+// whose point under the path at that height lies on that body (closed form per top, no stepping).
+import { add, scale, sub } from "./compiler/math.js";
+
+const ZERO = [0, 0, 0];
+
+/** The velocity fall leaves with from root pose `start` (`before`: its pose a frame earlier, a hand's release), m/s. */
+export function fallVelocity(fall, start, before, fps) {
+	if (Array.isArray(fall?.v)) return fall.v;
+	if (fall?.v === "hand" && before) return scale(sub(start.pos, before.pos), fps);
+	return ZERO;
+}
+
+export const moves = v0 => v0.some(v => v !== 0);
+
+/** Seconds until a point h m above its landing, leaving upward at vy m/s, comes down to it (G m/s^2). */
+export const flightTime = (h, vy, G) => (vy + Math.sqrt(vy * vy + 2 * G * Math.max(0, h))) / G;
+
+/** The x/z drift of a flight t s in (at most tl s, where it lands). */
+export const drift = (v0, t, tl) => { const u = Math.min(t, tl); return [v0[0] * u, 0, v0[2] * u]; };
+
+/**
+ * landingOf (free-motion.js) for a fall from `start` leaving at v0: { support, top, h } under where it comes down. `land`
+ * is landingOf(spec, scene, id, pose, onto), `tops` the heights of the bodies it may come down on, G gravity. Coming down,
+ * it meets the highest surface whose point under its path at that height is on that surface: each top from the highest
+ * down, the drift to that height, and the support there kept when it is that top (else the next lower; the floor last).
+ */
+export function landingWith(land, start, v0, G, tops = []) {
+	const here = land(start), low = here.top + here.h, at = top => ({ pos: add(start.pos, drift(v0, flightTime(low - top, v0[1], G), Infinity)), R: start.R });
+	for (const top of [...new Set(tops)].filter(t => t <= low).sort((a, b) => b - a)) {
+		const there = land(at(top));
+		if (Math.abs(there.top - top) < 1e-9) return there;
+	}
+	return land(at(0));
+}

package/src/motion3/free-motion.js

@@ -24,6 +24,7 @@ import { groupsOf } from "./scene.js";
 import { curveOf, keyedPose } from "./object-keys.js";
 import { add, apply, sub, T, quatFromMat, I3 } from "./compiler/math.js";
 import { shapeOf, airPath, settlePath, settledAt, spinOf, spinEnergy, TIP } from "./settle.js";
+import { fallVelocity, moves, flightTime, drift, landingWith } from "./flight.js";
 
 /** Gravity, m/s^2. */
 export const G = 9.8;
@@ -97,24 +98,26 @@ function shapeIn(scene, id) {
  * a frame earlier (a release from the hand), for the spin it is let go with.
  */
 function fallPlan(spec, scene, id, start, t0, fall, fps, before = null) {
-	const land = landingOf(spec, scene, id, start, fall.onto ?? null), shape = fall.tumble === false ? null : shapeIn(scene, id);
+	// a throw (fall.v, flight.js) lands where it comes down
+	const v0 = fallVelocity(fall, start, before, fps), thrown = moves(v0), landAt = pose => landingOf(spec, scene, id, pose, fall.onto ?? null);
+	const land = thrown ? landingWith(landAt, start, v0, G, Object.values(scene.objects).map(topOf)) : landAt(start), shape = fall.tumble === false ? null : shapeIn(scene, id);
 	if (shape) {
-		const spin = before ? spinOf(before.R, start.R, fps) : [0, 0, 0], air = airPath(shape, start, spin, land.top, fps);
+		const spin = before ? spinOf(before.R, start.R, fps) : [0, 0, 0], air = airPath(shape, start, spin, land.top, fps, v0);
 		// a spin tips it the way its top moves (spin x up); a spin about the vertical tips nothing
 		const path = settlePath(shape, air.at(air.tl), land.top, TIP * land.h + spinEnergy(shape, spin), [-spin[2], 0, spin[0]]);
-		if (path.steps.length || spin.some(v => v)) {
+		if (path.steps.length || spin.some(v => v) || thrown) {
 			const at = f => { const t = (f - t0) / fps; return t <= 0 ? start : t <= air.tl ? air.at(t) : settledAt(path, t - air.tl); };
 			return { t0, land: t0 + air.tl * fps, end: t0 + (air.tl + path.time) * fps, h: land.h, support: land.support, top: land.top, at, rest: path.rest };
 		}
 	}
-	const h = land.h, tl = Math.sqrt(2 * h / G);
+	const h = land.h, tl = thrown ? flightTime(h, v0[1], G) : Math.sqrt(2 * h / G), off = drift(v0, Infinity, tl);
 	const e = Math.min(0.6, Math.max(0, fall.bounce ?? BOUNCE)), vb = Math.min(e * G * tl, Math.sqrt(2 * G * BOUNCE_MAX)), tb = 2 * vb / G;
-	const rest = { pos: [start.pos[0], start.pos[1] - h, start.pos[2]], R: start.R };
+	const rest = { pos: [start.pos[0] + off[0], start.pos[1] - h, start.pos[2] + off[2]], R: start.R };
 	const at = f => {
 		const t = (f - t0) / fps;
 		if (t <= 0) return start;
-		const dy = t <= tl ? -0.5 * G * t * t : t <= tl + tb ? -h + vb * (t - tl) - 0.5 * G * (t - tl) ** 2 : -h;
-		return { pos: [start.pos[0], start.pos[1] + Math.min(0, dy), start.pos[2]], R: start.R };
+		const dy = t <= tl ? (thrown ? v0[1] * t : 0) - 0.5 * G * t * t : t <= tl + tb ? -h + vb * (t - tl) - 0.5 * G * (t - tl) ** 2 : -h, d = drift(v0, t, tl);
+		return { pos: [start.pos[0] + d[0], start.pos[1] + (thrown ? dy : Math.min(0, dy)), start.pos[2] + d[2]], R: start.R };
 	};
 	return { t0, land: t0 + tl * fps, end: t0 + (tl + tb) * fps, h, support: land.support, top: land.top, at, rest };
 }

package/src/motion3/load.js

@@ -0,0 +1,125 @@
+// What a hand holds weighs on its arm (#816). The load on a hand is the held object's mass (mass.js) x G x the
+// horizontal distance from its shoulder to its wrist (N m), read on the solved frames:
+//   sag      a carry whose load can reach LIGHT N m (its mass at the arm's full reach) lowers the wrist target of a
+//            plain IK hand (a hand_k target: not a fit, whose passes re-solve it, nor a keyed carry, whose keys lead
+//            it) by min(SAG_MAX, SAG_PER_KG x mass) and draws it as far in toward the shoulder, so the elbow bends
+//            more; eased in over the settle from the grab and out the same before the release (seat.js SETTLE)
+//   observe  output.observations.load: each hand that carries something, { object, mass, maxNm, at, frames }
+//   LOAD     "<side> holds <id> at <x> N m": past QA_LIMITS-style ONE_HAND N m with no second hand on the object; its
+//            hint asks for the other hand, and when the right hand holds, a patch adds a left reachGrip that arrives at
+//            the grab on the object's face nearest the left shoulder (second-hand.js holds only a right-hand carry)
+// fix.grasp false turns all three off: the take of before.
+import { add, sub, scale, norm, apply, T, len } from "./compiler/math.js";
+import { SIDES } from "./compiler/pose.js";
+import { armReach } from "./compiler/anchors.js";
+import { isCarried } from "./carried.js";
+import { massOf } from "./mass.js";
+import { handOf, spanOf, partsOf, objectPoseAt } from "./object-pose.js";
+import { SETTLE, restOf } from "./seat.js";
+
+const REACH = 10, G = 9.81, LIGHT = 2, SAG_MAX = 0.06, SAG_PER_KG = 0.006, ONE_HAND = 25, SECOND = 0.5;
+export const LOAD_UNITS = "load: what each hand carries, kg, and its most N m (mass x 9.81 x the shoulder-to-wrist distance across) at f; frames [first, last] held";
+
+const graspOn = spec => spec?.fix !== false && spec?.fix?.grasp !== false;
+const ease = t => { const u = Math.min(1, Math.max(0, t)); return u * u * (3 - 2 * u); };
+
+/** The carries of spec, [id, entry, hand] (hand "l" | "r"). */
+const carries = spec => Object.entries(spec.objects ?? {}).filter(([, o]) => isCarried(o) && spec.props?.[o.prop]).map(([id, o]) => [id, o, spec.props[o.prop].hand]);
+
+/**
+ * The world offset (m) the wrist target of hand k takes at frame f for what it carries, or null: ctx is the compile
+ * context (its spec, scene, sk, carrySpan), s the frame's pose so far, target the wrist target, free the share of the
+ * arm on a plain target.
+ */
+export function sagOf(ctx, k, f, s, target, free) {
+	const { spec, scene, sk } = ctx;
+	if (!graspOn(spec) || !(free > 1e-3)) return null;
+	for (const [id, o, hand] of carries(spec)) {
+		if (hand !== k || o.keys?.length) continue;
+		const mass = massOf(spec, scene, id), [grab, release] = ctx.carrySpan(o);
+		if (f < grab || f > release || mass * G * armReach(sk, k) < LIGHT) continue;
+		const w = ease((f - grab) / SETTLE) * ease((release - f) / SETTLE) * free, drop = Math.min(SAG_MAX, SAG_PER_KG * mass) * w;
+		if (!(drop > 0)) return null;
+		const toShoulder = sub(s.P[sk.index[`${SIDES[k]}Arm`]], target);
+		const across = len([toShoulder[0], 0, toShoulder[2]]) > 1e-6 ? norm([toShoulder[0], 0, toShoulder[2]]) : [0, 0, 0];
+		return add([0, -drop, 0], scale(across, drop));
+	}
+	return null;
+}
+
+/** N m on hand k on pose s holding `mass` kg. */
+const nm = (sk, s, k, mass) => { const d = sub(s.P[sk.index[`${SIDES[k]}Hand`]], s.P[sk.index[`${SIDES[k]}Arm`]]); return mass * G * Math.hypot(d[0], d[2]); };
+
+/** fn({ id, o, k, mass, f, Nm }) for each carry on each frame of out its hand holds it (grasp physics on). */
+function eachHeld(sk, out, fn) {
+	const { spec, scene } = out.ctx, f0 = out.f0 ?? 0;
+	if (!graspOn(spec)) return;
+	const list = carries(spec).map(([id, o, k]) => ({ id, o, k, mass: massOf(spec, scene, id) }));
+	if (!list.length) return;
+	out.frames.forEach(({ s }, i) => {
+		const f = i + f0;
+		for (const c of list) if (handOf(out, c.id, f) === c.k) fn({ ...c, f, Nm: nm(sk, s, c.k, c.mass) });
+	});
+}
+
+/** observeLoad(sk, out) -> { hand_l?, hand_r? } (each { object, mass, maxNm, at, frames: [first, last] }) or null. */
+export function observeLoad(sk, out) {
+	const res = {};
+	eachHeld(sk, out, ({ id, k, mass, f, Nm }) => {
+		const row = res[`hand_${k}`] ??= { object: id, mass: Math.round(mass * 1000) / 1000, maxNm: 0, at: f, frames: [f, f] };
+		if (Nm > row.maxNm) { row.maxNm = Nm; row.at = f; }
+		row.frames[1] = f;
+	});
+	for (const row of Object.values(res)) row.maxNm = Math.round(row.maxNm * 10) / 10;
+	return Object.keys(res).length ? res : null;
+}
+
+/** True when the hand other than k is on carry id (an object anchor on it or a prop anchor on its prop) at f. */
+function secondOn(out, id, o, k, f) {
+	const j = k === "r" ? "l" : "r", { spec, scene } = out.ctx, parts = new Set([id, ...partsOf(scene, id)]);
+	return Object.entries(spec.anchors ?? {}).some(([name, a]) => (out.baked?.[`w_${name}_${j}`]?.[f] ?? 0) > SECOND
+		&& ((a.kind === "object" && parts.has(a.object)) || (a.kind === "prop" && a.prop === o.prop)));
+}
+
+/** QA LOAD issues: a hand carrying past ONE_HAND N m with no second hand on the object. */
+export function loadChecks(sk, out) {
+	const issues = [];
+	eachHeld(sk, out, ({ id, o, k, f, Nm }) => {
+		if (Nm > ONE_HAND && !secondOn(out, id, o, k, f)) issues.push({ kind: "LOAD", msg: `${SIDES[k].toLowerCase()} holds ${id} at ${Nm.toFixed(0)} N m`, frame: f, value: Math.round(Nm * 10) / 10, limit: ONE_HAND });
+	});
+	return issues;
+}
+
+/**
+ * The anchor point (object local) for the left hand on carry id at frame f: the centre of the face nearest the left
+ * shoulder, of the faces other than the bottom and the one the right palm is on (the box's other side, as two hands hold it).
+ */
+function otherFace(out, id, f) {
+	const { sk, scene } = out.ctx, s = out.frames[f - (out.f0 ?? 0)]?.s, pose = objectPoseAt(out, id, f), rest = restOf(scene, id);
+	const part = scene.objects[partsOf(scene, id)[0]] ?? scene.objects[id];
+	if (!s || !pose || !part?.half) return null;
+	const toLocal = p => apply(T(pose.R), sub(p, pose.pos)), c = apply(T(rest.R), sub(add(part.pos, apply(part.R, [0, part.half[1], 0])), rest.pos));
+	const palm = toLocal(scale(add(s.P[sk.index.RightHand], s.P[sk.index.RightHandMiddle1]), 0.5)), shoulder = toLocal(s.P[sk.index.LeftArm]);
+	const faces = [0, 1, 2].flatMap(i => [-1, 1].map(sg => { const p = c.slice(); p[i] += sg * part.half[i]; return { p, i, sg }; })).filter(x => !(x.i === 1 && x.sg < 0));
+	const palmFace = faces.reduce((m, x) => (Math.abs(palm[x.i] - x.p[x.i]) < Math.abs(palm[m.i] - m.p[m.i]) ? x : m));
+	const best = faces.filter(x => x !== palmFace).reduce((m, x) => (len(sub(x.p, shoulder)) < len(sub(m.p, shoulder)) ? x : m));
+	return best.p.map(x => Math.round(x * 1000) / 1000);
+}
+
+export const loadHints = {
+	/** LOAD(X, g) -> { cause, hint, fix? }: the other hand on it; a patch when the right hand holds. */
+	LOAD(X, g) {
+		const [, side, id] = /^(left|right) holds (\S+) at/.exec(g.subject) ?? [], o = X.spec?.objects?.[id];
+		if (!o || !X.out) return null;
+		const k = side === "left" ? "l" : "r", other = k === "r" ? "left" : "right", [grab] = spanOf(X.out, o), kg = massOf(X.spec, X.out.ctx.scene, id);
+		const plain = { cause: `objects.${id} (${kg.toFixed(1)} kg)`, hint: `${id} weighs ${kg.toFixed(1)} kg: ${g.worst.toFixed(0)} N m on the ${side} arm at f${g.worstFrame} (one hand holds ${ONE_HAND}); put the ${other} hand on it too (a reachGrip on an object anchor on ${id} from f${grab}), or carry it closer to the body` };
+		if (k !== "r") return plain;
+		const local = otherFace(X.out, id, Math.max(grab, Math.min(g.worstFrame, spanOf(X.out, o)[1])));
+		if (!local) return plain;
+		const name = `${id}Other`;
+		// a big face takes the flat palm against it (a power grip's thumb would go into the box)
+		const anchor = { kind: "object", object: id, local, grasp: "palm" };
+		return { ...plain, fix: { ops: user => [user.anchors ? { op: "add", path: `/anchors/${name}`, value: anchor } : { op: "add", path: "/anchors", value: { [name]: anchor } },
+			{ op: "add", path: "/use/-", value: { skill: "reachGrip", f0: Math.max(0, grab - REACH), args: { anchor: name, side: "l", reach: Math.min(REACH, grab) || 1, hold: Math.max(1, spanOf(X.out, o)[1] - grab), release: 1 } } }] } };
+	},
+};

package/src/motion3/mass.js

@@ -0,0 +1,23 @@
+// What a scene object weighs, kg, for the arm that holds it (#816). The spec says it (spec.objects[id].mass), else a
+// small sphere is a ball (BALL kg: a baseball is 0.145), else its parts' volumes at DENSITY (wood, a filled box). A
+// group weighs what its bodies do. Never a scene record field: motion-scene entries are saved with a take (shapes.js).
+import { partsOf } from "./object-pose.js";
+import { shapeOf } from "./shapes.js";
+
+const BALL = 0.15, BALL_SIZE = 0.12, DENSITY = 400, MIN = 0.02, MAX = 60;
+
+function volumeOf(entry) {
+	const s = shapeOf(entry), h = entry.half;
+	if (s.kind === "sphere") return (4 / 3) * Math.PI * s.r ** 3;
+	if (s.kind === "cylinder") return Math.PI * s.r * s.r * s.h;
+	return 8 * h[0] * h[1] * h[2];
+}
+
+export function massOf(spec, scene, id) {
+	const given = spec?.objects?.[id]?.mass;
+	if (Number.isFinite(given)) return given;
+	const parts = partsOf(scene, id).map(k => scene.objects[k]);
+	if (parts.length === 1 && shapeOf(parts[0]).kind === "sphere" && 2 * shapeOf(parts[0]).r < BALL_SIZE) return BALL;
+	const kg = parts.reduce((sum, e) => sum + volumeOf(e) * DENSITY, 0);
+	return Math.min(MAX, Math.max(MIN, kg));
+}

package/src/motion3/object-keys.js

@@ -11,6 +11,7 @@
 // The object itself is still drawn in the hand (object-pose.js): the residual is what the arm
 // and the wrist could not reach, and QA reports it (qa/key-checks.js).
 import { isCarried, carriedPose, compose, relative } from "./carried.js";
+import { seatsInHand, seatOffset, settleAt, between as slide } from "./seat.js";
 import { groupsOf } from "./scene.js";
 import { restState } from "./compiler/skeleton.js";
 import { add, scale, sub, apply, T, matFromQuat, quatFromMat } from "./compiler/math.js";
@@ -110,7 +111,8 @@ export const keyedEntries = spec => Object.entries(spec.objects ?? {}).filter(([
 export function holdHook(ctx, out, solvePlain, solveLed) {
 	const { sk, spec, scene } = ctx, held = keyedEntries(spec);
 	if (!held.length) return null;
-	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }), attached = new WeakMap(), attaching = new Set();
+	const seated = new Set(held.map(([id]) => id).filter(id => seatsInHand(spec, spec.objects[id], scene, id)).map(id => spec.objects[id]));
+	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }, seated.has(o)), attached = new WeakMap(), attaching = new Set();
 	const restAt = (id, f) => ctx.restingAt?.(id, f) ?? scene?.objects?.[id] ?? groupsOf(scene)[id];
 	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no grasp fit, no keyed
 	// wrist at the grab) keeps the grip its keyed path holds most comfortably (grip-choice.js), solved on the plain frames with the
@@ -136,22 +138,25 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 		const cache = attached.get(out.baked), o = spec.objects[id];
 		if (cache.has(id)) return cache.get(id);
 		const picked = chosen(id);
-		if (picked && picked.name !== "today") { cache.set(id, picked.offset); return picked.offset; }
+		if (picked && picked.name !== "today") { const a = seated.has(o) ? seatOffset(sk, spec, scene, id, o, picked.offset) : picked.offset; cache.set(id, a); cache.set(`${id}|taken`, picked.offset); return a; }
 		const rest = scene?.objects?.[id] ?? groupsOf(scene)[id], group = !scene?.objects?.[id] && !!rest;
 		const keeps = o.at === undefined && o.along === undefined && (group || o.grab !== undefined);
 		// the grab frame solved without the keys: a left hand anchored on id reads it there (object-pose.js), where this offset puts it
 		attaching.add(id);
 		let s;
 		try { s = keeps ? solvePlain(spanIn(out, o)[0]).s : restState(sk); } finally { attaching.delete(id); }
-		const a = relative(palmOf(o, s), keeps ? ctx.restingAt?.(id, spanIn(out, o)[0]) ?? { pos: rest.pos, R: rest.R } : carriedPose(sk, spec, s, o));
-		cache.set(id, a);
+		const taken = relative(palmOf(o, s), keeps ? ctx.restingAt?.(id, spanIn(out, o)[0]) ?? { pos: rest.pos, R: rest.R } : carriedPose(sk, spec, s, o));
+		const a = keeps && seated.has(o) ? seatOffset(sk, spec, scene, id, o, taken) : taken;
+		cache.set(id, a); cache.set(`${id}|taken`, taken);
 		return a;
 	};
+	// on the grasp path a keyed carry's hand slides from where it took the object into its seat over the settle (seat.js)
+	const attachAt = (id, f) => { const a = attach(id), t = attached.get(out.baked)?.get(`${id}|taken`); return t && t !== a && f !== undefined ? slide(t, a, settleAt(spanIn(out, spec.objects[id])[0], f)) : a; };
 	const carryOn = (id, s) => compose(palmOf(spec.objects[id], s), attach(id));
 	const strainOn = (id, s, pose, opts) => { const o = spec.objects[id]; return holdCost(sk, s, SIDES[spec.props[o.prop].hand], compose(pose, invert(attach(id))), palmOf(o, s), opts); };
 	const heldAt = (id, o, f) => {
 		const curve = curveIn(out, id), w = leadWeight(curve, spanIn(out, o), f);
-		return w > 0 ? { w, palm: compose(keyedPose(curve, f), invert(attach(id))), measure: s => palmOf(o, s), comfort: o.keys.some(k => k.lean > 0) } : null;
+		return w > 0 ? { w, palm: compose(keyedPose(curve, f), invert(attachAt(id, f))), measure: s => palmOf(o, s), comfort: o.keys.some(k => k.lean > 0) } : null;
 	};
 	// the elbow's planned path over the frames the keys lead (hold-plan.js), once per baked channels and time map
 	const plans = new WeakMap();
@@ -263,5 +268,5 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	const firstKey = id => { const t = Math.min(...spec.objects[id].keys.map(k => k.f)); return out.timeMap ? Math.round(out.timeMap(t)) : t; };
 	// the grips chosen for keyed carries (observations.wrist reads them): [{ id, hand, name, cost, today }]
 	const grips = () => held.map(([id, o]) => { const p = chosen(id); return p && { id, hand: spec.props[o.prop].hand, name: p.name, cost: p.cost, today: p.today }; }).filter(Boolean);
-	return { lead, attach, attaching: id => attaching.has(id), plainFrame: solvePlain, carryOn, strainOn, span: id => spanIn(out, spec.objects[id]), firstKey, grips };
+	return { lead, attach, attachAt, attaching: id => attaching.has(id), plainFrame: solvePlain, carryOn, strainOn, span: id => spanIn(out, spec.objects[id]), firstKey, grips };
 }