cozyclay 3.0.2 → 3.1.0

package/src/motion3/carried.js

@@ -8,6 +8,7 @@
 import { palmAxes } from "./compiler/limbs.js";
 import { SIDES } from "./compiler/pose.js";
 import { add, scale, norm, sub, dot, cross, apply, mul, T, axisRot, I3 } from "./compiler/math.js";
+import { bonePoint } from "./compiler/skeleton.js";
 
 export const isCarried = o => typeof o?.prop === "string";
 /** A follow entry { follow: <ref>, offset?, aim?, visible?, level? } (C16, follow.js): the record rides a point of the body. */
@@ -23,9 +24,16 @@ export function propOrigin(sk, spec, s, o) {
 	return scale(prop.origin.map(b => s.P[sk.index[b]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / prop.origin.length);
 }
 
-/** World { pos, R } of a carried record on pose s (at/along offset, PR #14). */
-export function carriedPose(sk, spec, s, o) {
-	const ax = palmAxes(sk, s, SIDES[spec.props[o.prop].hand]), origin = propOrigin(sk, spec, s, o);
+/** The prop origin carried by its hand's bone on pose s, where the bind pose has it against the hand: closing fingers do not move it (#816). */
+function handOrigin(sk, prop, s) {
+	const h = sk.index[`${SIDES[prop.hand]}Hand`], P = sk.restWorldPos;
+	const mean = scale(prop.origin.map(b => P[sk.index[b]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / prop.origin.length);
+	return bonePoint(s, h, apply(T(sk.restWorldRot[h]), sub(mean, P[h])));
+}
+
+/** World { pos, R } of a carried record on pose s (at/along offset, PR #14); `fixed`: the origin rides the hand bone (seat.js). */
+export function carriedPose(sk, spec, s, o, fixed = false) {
+	const ax = palmAxes(sk, s, SIDES[spec.props[o.prop].hand]), origin = fixed ? handOrigin(sk, spec.props[o.prop], s) : propOrigin(sk, spec, s, o);
 	const palm = v => add(scale(ax.d, v[0]), add(scale(ax.l, v[1]), scale(ax.n, v[2])));
 	const y = norm(palm(o.along ?? [0, 0, 1]));
 	let x = sub(ax.d, scale(y, dot(ax.d, y)));

package/src/motion3/compile-job.js

@@ -1,6 +1,6 @@
 // One motion compile as a job of plain data, the same in the compile worker (compile-worker.js) and on
 // the calling thread (commands/motion3-compile.js, where no worker runs: Node, tests): the rig by model
-// name, the motion scene (scene.js motionScene of the editor's objects: boxes only), the spec as sent, and
+// name, the motion scene (scene.js motionScene of the editor's objects: oriented boxes; shapes.js reads a sphere or a cylinder round from them), the spec as sent, and
 // what to do with it (probes, checks, lenient, repair, bake). The answer is plain data and typed arrays
 // only (the compiler's out holds closures), so it crosses a worker boundary: QA, observations, the stored
 // spec, and the baked take when asked.

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";
@@ -34,8 +35,12 @@ import { fitWeight } from "../fix/self.js";
 import { holdHook } from "../object-keys.js";
 import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
 import { objectPoseAt, handOf, restingAt, frameAt, spanOf } from "../object-pose.js";
+import { heldFor } from "./finger-close.js";
+import { sagOf } from "../load.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
@@ -133,6 +138,10 @@ function hooksFor(ctx, c, f, inFit = false, lead = true, fitSide = null) {
 		afterArm: (k, s, diag) => measureProps(ctx, k, s, diag),
 		// a fit's passes only place the wrist; the final pose (and a plain one) turns the hand onto the body
 		grip: inFit ? undefined : (k, s, diag) => gripHand(ctx, sk, s, SIDES[k], k, c, f, diag),
+		// a carry's weight lowers a plain IK hand's target, on the final pose only (load.js)
+		sag: inFit ? undefined : (k, s, target) => sagOf(ctx, k, f, s, target, (1 - fitWeight(ctx.spec, c, k)) * Math.min(1, Math.max(0, c[`armw_${k}`] ?? 0))),
+		// fingers close on what the hand holds, on the final pose only (finger-close.js)
+		heldShapes: inFit || !ctx.grasp ? undefined : (k, s) => heldFor(ctx, c, f, k, s),
 	};
 }
 
@@ -146,15 +155,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));
@@ -173,7 +192,7 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	if (!(frameCount >= 1 && frameCount <= 20000)) throw new Error("MOTION_SPEC_INVALID: frames must be 1..20000");
 	const fix = fixOptions(spec.fix);
 	const [a, b] = opts.window ? [Math.max(0, opts.window[0]), Math.min(frameCount - 1, opts.window[1])] : [0, frameCount - 1];
-	const ctx = { sk, spec, scene, softReach: fix.reach, push: { l: new Map(), r: new Map() }, swivel: { l: new Map(), r: new Map() }, skinPush: { l: new Map(), r: new Map() }, keepOut: fix.self ? wristBody(sk) : null };
+	const ctx = { sk, spec, scene, grasp: fix.grasp, softReach: fix.reach, push: { l: new Map(), r: new Map() }, swivel: { l: new Map(), r: new Map() }, skinPush: { l: new Map(), r: new Map() }, keepOut: fix.self ? wristBody(sk) : null };
 	const out = { ctx, fps: spec.fps ?? 30, frameCount, f0: a, frames: [] };
 	// object anchors read the pose refs read (object-pose.js), on the frame being solved
 	ctx.objectPose = (id, f, now) => objectPoseAt(out, id, f, now);
@@ -183,11 +202,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/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/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/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/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/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) {