cozyclay 3.0.1 → 3.0.3

package/src/commands/elements/character.js

@@ -1,6 +1,7 @@
 import { createCharacterEntry } from '../../scenes.js';
 import { STUDIO_ELEMENTS } from '../../studio-elements.js';
 import { registerElementKind } from '../elements.js';
+import { readCastTakes } from './take-read.js';
 
 const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('character.')).map(row => {
   const { min, max, gizmo, ...element } = row;
@@ -9,5 +10,5 @@ const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('character.')
   if (row.path === 'character.pose') return { ...element, readback: item => ({ text: item?.pose?.id ?? null }) };
   return element;
 });
-registerElementKind('character', { collection: true, documentKey: 'characters', elements, normalize: createCharacterEntry });
+registerElementKind('character', { collection: true, documentKey: 'characters', elements, read: readCastTakes, normalize: createCharacterEntry });
 registerElementKind('poseLibrary', { collection: true, documentKey: 'customPoses', elements: [], normalize: value => value });

package/src/commands/elements/motion.js

@@ -1,4 +1,5 @@
 import { registerElementKind } from '../elements.js';
+import { readTake } from './take-read.js';
 
 const elements = [
   { path: 'motion.take.prompt', type: 'string' },
@@ -6,4 +7,9 @@ const elements = [
   { path: 'motion.takeRecipe', type: 'object', readOnly: true },
   { path: 'motion.takeVersions', type: 'array', readOnly: true },
 ];
-registerElementKind('motion', { collection: true, elements, normalize: row => ({ ...row, take: row.take && { ...row.take } }) });
+// The full take is the take itself until an edit splits them: a read answers its source once.
+const readMotion = (rows, named) => rows.map(row => {
+  const same = Boolean(row.fullTake?.resourceId) && row.fullTake.resourceId === row.take?.resourceId;
+  return { ...row, take: readTake(row.take, named(row.id)), fullTake: readTake(row.fullTake, !same && named(row.id)) };
+});
+registerElementKind('motion', { collection: true, elements, read: readMotion, normalize: row => ({ ...row, take: row.take && { ...row.take } }) });

package/src/commands/elements/scene.js

@@ -1,4 +1,5 @@
 import { registerElementKind } from '../elements.js';
+import { readCastTakes } from './take-read.js';
 
 // Array position is the authoritative order. The owner refreshes this persisted
 // field after every move, so generic set/read and the project file agree.
@@ -8,6 +9,8 @@ registerElementKind('scene', {
     { path: 'scene.name', type: 'string' },
     { path: 'scene.order', type: 'number' },
   ],
+  // a saved scene keeps its cast's takes: a read answers their spec ids (take-read.js)
+  read: (scenes, named) => scenes.map(scene => (scene?.stage?.characters ? { ...scene, stage: { ...scene.stage, characters: readCastTakes(scene.stage.characters, named) } } : scene)),
   normalize: scene => ({ ...scene, name: scene.name.trim(), order: Math.max(0, Math.round(scene.order)) }),
 });
 registerElementKind('project', {

package/src/commands/elements/stage.js

@@ -1,6 +1,7 @@
 import { createSceneStage } from '../../scenes.js';
 import { STUDIO_ELEMENTS } from '../../studio-elements.js';
 import { registerElementKind } from '../elements.js';
+import { readCastTakes } from './take-read.js';
 
 const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('stage.'));
 export const STAGE_FIELDS = [...new Set(elements.map(element => (element.documentPath ?? element.path.slice(6)).split('.')[0]))];
@@ -8,4 +9,4 @@ export function normalizeStage(source) {
   const normalized = createSceneStage(source);
   return Object.fromEntries(STAGE_FIELDS.map(key => [key, normalized[key]]));
 }
-registerElementKind('stage', { elements, normalize: normalizeStage });
+registerElementKind('stage', { elements, read: (stage, named) => (stage?.characters ? { ...stage, characters: readCastTakes(stage.characters, named) } : stage), normalize: normalizeStage });

package/src/commands/elements/take-read.js

@@ -0,0 +1,31 @@
+import { specIdOf } from '../../motion3/spec-store.js';
+
+// A take's source (its spec, placement and the scene boxes it was compiled against) runs to
+// ~110k characters a character, and a document read carried it in full wherever a take sits:
+// motion (as take and fullTake), the cast and stage (motionTake) and every saved scene. One read
+// of motion alone answered 460k characters, ~300k tokens a model call for the rest of the turn.
+// A read answers the take's specId instead (motion.compile { base: specId } recompiles it); a
+// character named in ids also gets its spec and placement, never the scene boxes.
+const LEFT_OUT = 'left out of this read: name this character in ids for its spec and placement, or compile { base: specId }';
+const leftOutScene = scene => `left out (the ${Object.keys(scene?.objects ?? {}).length} scene objects it was compiled against)`;
+
+/** A take source ({ schema, rig, spec, placement, scene, ... }) as a read answers it: { specId, ... }. */
+function readSource(source, named) {
+  const specId = specIdOf(source.spec);
+  if (!named) return { specId, frames: source.spec?.frames, ...(source.takeId ? { takeId: source.takeId } : {}), ...(source.edit ? { edit: source.edit } : {}), spec: LEFT_OUT };
+  const { scene, ...kept } = source;
+  return { specId, ...kept, scene: leftOutScene(scene) };
+}
+
+/** A motion layer's take descriptor, its source read as above. */
+export function readTake(take, named) {
+  if (!take?.source) return take;
+  const { source, ...descriptor } = take, specId = specIdOf(source.spec);
+  if (!named) return { ...descriptor, specId, source: LEFT_OUT };
+  const { scene, ...kept } = source;
+  return { ...descriptor, specId, source: { ...kept, scene: leftOutScene(scene) } };
+}
+
+/** Cast rows with their saved takes (motionTake) read as above. */
+export const readCastTakes = (characters, named) => (Array.isArray(characters)
+  ? characters.map(row => (row?.motionTake?.spec ? { ...row, motionTake: readSource(row.motionTake, named(row.id)) } : row)) : characters);

package/src/commands/elements.js

@@ -42,15 +42,29 @@ export function elementSetSchema(kind) {
 export function elementTarget(kind, value, id, sceneId) {
   return kinds.get(projectionKind(kind)).collection ? value.find(row => row.id === id) : id === sceneId ? value : undefined;
 }
-export function readElementDocument(projection, { ids, select } = {}, sceneId) {
+// A kind's `read` shapes what a document read answers (motion leaves out a take's bulky source
+// unless its row id was named): `named` are the ids the caller asked for by name. A read answers
+// at most DOCUMENT_READ_CHARS of kinds, the smallest first; the rest are named in `omitted` with
+// their size, to select alone or by ids. One kind alone answers whole (ids narrow it).
+const DOCUMENT_READ_CHARS = 90_000;
+export function readElementDocument(projection, { ids, select, named = ids } = {}, sceneId) {
   const entries = Object.entries(projection).flatMap(([key, value]) => {
     const kind = projectionKind(key);
     if (select && !select.includes(key) && !select.includes(kind)) return [];
     if (!ids || ids.includes(key) || ids.includes(kind) || ids.includes(sceneId)) return [[key, value]];
     const selected = kinds.get(kind).collection ? value.filter(row => ids.includes(row.id)) : [];
     return selected.length ? [[key, selected]] : [];
+  }).map(([key, value]) => {
+    const read = kinds.get(projectionKind(key))?.read;
+    return [key, read ? read(value, id => Boolean(named?.includes(id))) : value];
   });
-  return { document: structuredClone(Object.fromEntries(entries)), schema: Object.fromEntries(entries.map(([key]) => [key, elementSetSchema(projectionKind(key))])) };
+  const sized = entries.map(([key, value]) => { const schema = elementSetSchema(projectionKind(key)); return { key, value, schema, chars: JSON.stringify([value, schema]).length }; });
+  let room = DOCUMENT_READ_CHARS;
+  const fits = new Set(sized.length < 2 ? sized.map(row => row.key) : [...sized].sort((a, b) => a.chars - b.chars).filter(row => (room -= row.chars) >= 0).map(row => row.key));
+  const kept = sized.filter(row => fits.has(row.key)), omitted = sized.filter(row => !fits.has(row.key));
+  return { document: structuredClone(Object.fromEntries(kept.map(row => [row.key, row.value]))), schema: Object.fromEntries(kept.map(row => [row.key, row.schema])),
+    ...(omitted.length ? { omitted: Object.fromEntries(omitted.map(row => [row.key, row.chars])),
+      note: `Left out to keep this read under ${DOCUMENT_READ_CHARS} characters (sizes in omitted): select a kind alone, name ids, or page objects with scope "entities".` } : {}) };
 }
 export function readElement(document, path) {
   const element = kinds.get(path.slice(0, path.indexOf('.'))).elements.find(row => row.path === path);

package/src/commands/motion.js

@@ -1,6 +1,6 @@
 // Motion and IK commands share one per-character authored-intent owner.
 import { STUDIO_IK_CHAIN_TRACKS, studioActionDeclaration } from "../studio-actions.js";
-import { fail, characterOf } from "./shared.js";
+import { fail, characterOf, checkPoseBones } from "./shared.js";
 import { elementSetSchema, registerElementSet } from './elements.js';
 import { registerTiming, timingDeclarations } from './motion-timing.js';
 import './elements/motion.js';
@@ -41,6 +41,7 @@ export function register(registry, ports) {
 	for (const declaration of tools) registry.register({ ...declaration, available: mounted, run(args) {
 		characterOf(ports, args.characterId);
 		if (args.frame >= ports.state().frameCount) fail('INVALID_RANGE', 'IK frame is outside the timeline.');
+		checkPoseBones(args.pose.bones);
 		for (const angles of Object.values(args.pose.bones)) if (!Array.isArray(angles) || angles.length !== 3 || !angles.every(Number.isFinite)) fail('INVALID_ARGUMENT', 'Pose bones require three finite rotation angles.');
 		owner().keyPose(args.characterId, args.frame, args.pose);
 		return { affectedIds: [args.characterId], summary: declaration.label };

package/src/commands/motion3.js

@@ -48,7 +48,7 @@ const declarations = Object.freeze([
 		input: input({ topic: { type: "string", enum: DESCRIBE_TOPICS }, name: id,
 			topics: list({ oneOf: [{ type: "string", enum: DESCRIBE_TOPICS }, input({ topic: { type: "string", enum: DESCRIBE_TOPICS }, name: id }, ["topic"])] }, 8) }, []) },
 	{ id: "motion.report", label: "Read motion report", kind: "job", domain: "motion", timeoutMs: 10000, readOnly: true, description: HELP.report,
-		input: input({ specId, part: { type: "string", enum: ["groups", "timeline", "probes"], default: "groups" }, from: { type: "integer", minimum: 0, default: 0 } }, ["specId"]) },
+		input: input({ specId, characterId: id, part: { type: "string", enum: ["groups", "timeline", "probes"], default: "groups" }, from: { type: "integer", minimum: 0, default: 0 } }, []) },
 	{ id: "motion.keyObject", label: "Key held object", kind: "job", domain: "motion", timeoutMs: 120000, description: HELP.keyObject,
 		input: input({ characterId: id, objectId: id, frame: { type: "integer", minimum: 0 }, pos: numbers(3), rot: numbers(4), aim: numbers(3), roll: { type: "number" },
 			angle: { type: "number" }, remove: { type: "boolean", default: false } }, ["characterId", "objectId", "frame"]) },
@@ -141,7 +141,9 @@ export function register(registry, ports) {
 		const character = characterOf(ports, characterId);
 		if ((spec === undefined) === (base === undefined)) fail("INVALID_ARGUMENT", "Send exactly one of spec or base (the specId of a compiled spec, with patch).");
 		if (patch !== undefined && base === undefined) fail("INVALID_ARGUMENT", "patch applies to base, the specId of a compiled spec; send base with it, or the whole spec.");
-		const patched = [], source = spec ?? asArgument(() => applyPatch(store.get(base) ?? unknownSpec("base", base), patch ?? [], patched));
+		// a base the store forgot (a reload) may still be the installed take's spec: a document read names it by specId
+		const installedSpec = () => { const take = owner().motionFor(characterId); return take?.spec && specIdOf(take.spec) === base ? structuredClone(take.spec) : null; };
+		const patched = [], source = spec ?? asArgument(() => applyPatch(store.get(base) ?? installedSpec() ?? unknownSpec("base", base), patch ?? [], patched));
 		// the take is always baked: the user watches every draft, installed or not
 		return after(compile(character, source, { probes, repair }, {}), r => {
 			const { qa, take } = r, notes = [...patched, ...(r.notes ?? [])];
@@ -196,9 +198,15 @@ export function register(registry, ports) {
 		}
 		return { affectedIds: [], summary: `Described ${topic}${name ? ` ${name}` : ""}.`, output: asArgument(() => describe(topic, name)) };
 	} });
-	registry.register({ ...declarations[4], available: always, run({ specId: wanted, part = "groups", from = 0 }) {
-		const page = reportPage(store.parts(wanted) ?? unknownSpec("specId", wanted, "compile it again"), wanted, part, from);
-		return { affectedIds: [], summary: `${page.items.length} ${part} from ${from}.`, output: page };
+	// a characterId reads the installed take's report (session 2ad2760a asked for it that way and was refused): the stored
+	// one when this session compiled that spec, else the take's QA run now
+	registry.register({ ...declarations[4], available: always, run({ specId: wanted, characterId, part = "groups", from = 0 }) {
+		const answer = (parts, id) => { const page = reportPage(parts, id, part, from); return { affectedIds: [], summary: `${page.items.length} ${part} from ${from}.`, output: page }; };
+		if (wanted) return answer(store.parts(wanted) ?? unknownSpec("specId", wanted, "compile it again"), wanted);
+		if (!characterId) fail("INVALID_ARGUMENT", "motion.report needs specId (from a motion.compile or motion.qa answer) or characterId (its installed take).");
+		const take = installed(characterId), id = specIdOf(take.spec), kept = store.parts(id);
+		if (kept) return answer(kept, id);
+		return after(compile(characterOf(ports, characterId), take.spec), r => { const out = report(r, {}); return answer(store.parts(out.specId), out.specId); });
 	} });
 	// motion.keyObject (C14): one key of a held object (or a hinge angle) in the installed take's spec, compiled
 	// and installed whatever QA says (a user edit), as one undo entry

package/src/commands/objects.js

@@ -24,7 +24,7 @@ const PATCH_HINTS = { scale: 'use scaleX, scaleY, scaleZ', rotY: 'use rot for ya
 const mutation = (id, label, input) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'objects', input });
 const semantic = [
 	mutation('object.set', 'Set object fields', setInput),
-	mutation('object.add', 'Add object', input({ kind: { type: 'string' }, placement, name: { type: 'string' }, parent: id, first: { type: 'boolean' } }, ['kind'])),
+	mutation('object.add', 'Add object', input({ kind: { type: 'string' }, placement, name: { type: 'string' }, parent: id, first: { type: 'boolean' }, text: setInput.properties.set.properties.text }, ['kind'])),
 	// A clay prop from a recipe of soft parts (docs/sculpt-from-image.md). With `id` it re-sculpts that
 	// sculpt in place (one undo); without, it creates one. The recipe is checked by sculpt-recipe.js.
 	{ ...mutation('object.sculpt', 'Sculpt a clay prop from a recipe', input({ recipe: { type: 'object', properties: {}, additionalProperties: true }, edits: { type: 'array', minItems: 1, maxItems: 48, items: { type: 'object', properties: {}, additionalProperties: true } }, id, name: { type: 'string', maxLength: 240 }, placement, parent: id }, [])),
@@ -75,7 +75,7 @@ export function register(registry, ports) {
 		'object.add': args => {
 			const before = owned().read();
 			if (args.parent !== undefined) objectOf(args.parent);
-			const object = createSceneObject(args.kind, before, args.placement);
+			const object = createSceneObject(args.kind, before, args.placement, args.text);
 			if (!object) fail('INVALID_ARGUMENT', `Unknown object kind: ${args.kind}`);
 			const placed = updateSceneObject([object], object.id, { ...(args.placement ?? {}), ...(args.name === undefined ? {} : { name: args.name }) })[0];
 			// `first`: the Outliner lists Props in record order, so a UI-made object

package/src/commands/shared.js

@@ -2,9 +2,18 @@
 // object: its members are read at call time, so a run always reaches the
 // latest handlers and `ports.state()` the synchronously published document.
 import { StudioProtocolError } from "../studio-agent-protocol.js";
+import { POSE_BONES } from "../poses.js";
 
 export const fail = (code, message) => { throw new StudioProtocolError(code, message); };
 
+// A pose bone outside POSE_BONES is dropped by applyPose, so the pose falls back to the
+// rest (T) pose for that joint. Refuse it and name the joints a pose can set (#773).
+const POSE_BONE_IDS = POSE_BONES.map(entry => entry.id);
+export function checkPoseBones(bones) {
+	const unknown = Object.keys(bones ?? {}).filter(name => !POSE_BONE_IDS.includes(name));
+	if (unknown.length) fail("INVALID_ARGUMENT", `Unknown pose bone ${unknown.join(", ")}. Use one of: ${POSE_BONE_IDS.join(", ")}.`);
+}
+
 /** Ids of the rows added, changed or removed between two renders of a list. */
 export const changedIds = (before, after) => [...new Set([
 	...after.filter(row => !before.includes(row)).map(row => row.id),

package/src/motion3/compiler/anchors.js

@@ -9,20 +9,26 @@
 //   { kind: "object",   object: "Car_Door_L", local: [x,y,z] }  point fixed to a scene object or group where it is at
 //                       that frame (hinged, carried, following; object-pose.js objectPoseAt), in its own axes
 //   { kind: "landmark", name: "mouth" }                     measured face landmark on the Head bone
-//   { kind: "prop",     prop: "cig", point: "tip", offset: [x,y,z] }  a point on a prop held by the other hand
+//   { kind: "prop",     prop: "cig", point: "tip", offset: [x,y,z] }  a point on a prop held by the other hand; while
+//                       that hand does not hold the object it carries, the point stays on that object (propOnCarry)
 //   { kind: "person",   person: "char-b", bone: "LeftArm", offset: [x,y,z] }  world offset from another character's joint
 //                       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 } 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";
 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, 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`]]));
 }
@@ -81,10 +87,14 @@ function anchorPoint(ctx, a, name, s, diag, c, side) {
 			for (let t = a.t ?? 0.45; t >= (a.tMin ?? 0.15); t -= 0.01) if (len(sub(at(t), sh)) <= r) return at(t);
 			return at(a.tMin ?? 0.15);
 		}
-		case "object": { const o = objectFrame(ctx, a, name, { s, diag, c }, side); return add(o.pos, apply(o.R, a.local ?? [0, 0, 0])); }
+		case "object": {
+			if (a.grasp && a.local === undefined) return anchorSocket(ctx, name, s, diag, c, side).p;
+			const o = objectFrame(ctx, a, name, { s, diag, c }, side);
+			return add(o.pos, apply(o.R, a.local ?? [0, 0, 0]));
+		}
 		case "landmark": return bonePoint(s, I.Head, sk.landmarks[a.name] ?? (() => { throw new Error(`MOTION_SPEC_INVALID: unknown landmark "${a.name}"`); })());
 		case "prop": {
-			const p = diag.props?.[a.prop]?.[a.point];
+			const p = propOnCarry(ctx, a, name, diag?.frame) ?? diag.props?.[a.prop]?.[a.point];
 			if (!p) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" needs prop ${a.prop}.${a.point}, which is held by an arm solved later`);
 			return add(p, a.offset ?? [0, 0, 0]);
 		}
@@ -97,6 +107,80 @@ function anchorPoint(ctx, a, name, s, diag, c, side) {
 	}
 }
 
+/**
+ * A point of a prop on a hand that carries an object, at a frame that hand does not hold it: where the point sits on
+ * the object at the grab (or the release) nearest in time, carried with the object (at rest before the grab, let go
+ * after the release). In hand the point rides the palm; before the grab the palm still turns into its grip (and after
+ * the release out of it), and a point held off it swept through the other arm's reach: session 02263581's barbell put
+ * the left hand on a point 55 cm off the right palm, and the left elbow jumped 28 cm in a frame at the grab and the
+ * release. Read off the object, the point is where the left hand takes the bar, and meets the palm's at the grab. null
+ * when no carry of that hand applies (the palm's point is used).
+ */
+function propOnCarry(ctx, a, name, f) {
+	const hand = ctx.spec.props?.[a.prop]?.hand;
+	if (!hand || f === undefined || !ctx.solvedAt || !ctx.carrySpan) return null;
+	let pick = null;
+	for (const [id, o] of Object.entries(ctx.spec.objects ?? {})) {
+		if (!isCarried(o) || ctx.spec.props?.[o.prop]?.hand !== hand) continue;
+		const [grab, release] = ctx.carrySpan(o);
+		if (f >= grab && f <= release) return null;
+		const at = f < grab ? grab : release;
+		if (!pick || Math.abs(f - at) < Math.abs(f - pick.at)) pick = { id, at };
+	}
+	if (!pick) return null;
+	const there = nested(ctx, name, pick.id, pick.at, () => ctx.solvedAt(pick.at).diag.props?.[a.prop]?.[a.point]);
+	const was = ctx.objectPose(pick.id, pick.at), now = ctx.objectPose(pick.id, f);
+	return there && was && now ? add(now.pos, apply(now.R, apply(T(was.R), sub(there, was.pos)))) : null;
+}
+
+/**
+ * The socket (../sockets.js) an object anchor with `grasp` takes the hand by, in world space on its object's pose that
+ * frame: { p, axis?, from?, thumb? }, p the anchor's point (its `local` when it has one). Its `socket`, else the one
+ * nearest its `local` point or, without one, nearest the shoulder of the hand: picked once per compile (ctx.sockets),
+ * so the hand does not hop between sockets. An object with no socket gives the bare point: the palm faces it.
+ */
+export function anchorSocket(ctx, name, s, diag, c, side) {
+	const a = ctx.spec.anchors[name], now = { s, diag, c }, poseOf = id => objectFrame(ctx, { ...a, object: id }, name, now, side);
+	const local = a.local && (o => add(o.pos, apply(o.R, a.local)))(poseOf(a.object));
+	ctx.sockets ??= new Map();
+	if (!ctx.sockets.has(name)) {
+		const all = socketsOf(ctx.scene, a.object), I = ctx.sk.index, near = local ?? s.P[I[side ? `${SIDES[side]}Arm` : "Hips"]];
+		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);
+	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,19 +23,22 @@ 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";
 import { fitWeight } from "../fix/self.js";
 import { holdHook } from "../object-keys.js";
 import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
-import { objectPoseAt, handOf, restingAt } from "../object-pose.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));
@@ -180,10 +193,18 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	ctx.objectHand = (id, f) => handOf(out, id, f);
 	// a keyed carry's grab offset is taken where it rests at grab (object-keys.js; a fall before grab: where it landed)
 	ctx.restingAt = (id, f) => restingAt(out, id, f);
+	// 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

@@ -24,6 +24,7 @@
 // forearm's neutral roll. A thin body (a cup, a can) keeps the neutral offset: its aim keys pick the
 // roll the arm holds most easily from it, and the cylindrical grip measured worse on every bench cup.
 // Those frames read the carried body where it rested before the grab, never a pose the hand moves.
+// An anchor that takes a grasp (an object anchor with `grasp`) turns the hand by its socket instead (socket-grip.js).
 import { add, sub, scale, norm, cross, dot, len, apply, ry, mul, T, axisRot } from "./math.js";
 import { palmAxes, twoBone } from "./limbs.js";
 import { aimArm, orient } from "./hold.js";
@@ -31,8 +32,9 @@ import { ELBOW_REST, WRIST_COMFORT, wristNeed } from "./arm-orient.js";
 import { resolveAnchor } from "./anchors.js";
 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)));
 
@@ -95,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];
@@ -141,9 +143,13 @@ function comfortable(F, now, twist) {
  */
 export function gripHand(ctx, sk, s, side, k, c, f, diag) {
 	// a wrist the spec turns on this frame is the agent's (or a skill's) own; a neutral 0 asks for nothing
-	if (Math.abs(c[`wtwist_${k}`] ?? 0) > 1e-3 || Math.abs(c[`wflex_${k}`] ?? 0) > 1e-3) return;
-	const on = activeFit(ctx.spec, c, k);
+	// a hand that takes a grasp (socket-grip.js) yields only to the agent's own wrist keys, not to a skill's (a walk's swing)
+	const on = activeFit(ctx.spec, c, k), carry = socketCarry(ctx, k, f), grasp = on && on.w >= 1e-3 && graspAnchor(ctx.spec, on.fit.anchor);
+	if (carry || grasp ? ownWrist(ctx.spec, k) : Math.abs(c[`wtwist_${k}`] ?? 0) > 1e-3 || Math.abs(c[`wflex_${k}`] ?? 0) > 1e-3) return;
+	// 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 ?? {}), 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];
@@ -156,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

@@ -0,0 +1,131 @@
+// The hand of a fit whose anchor takes a grasp (an object anchor with `grasp`, ../sockets.js) holds the object by its
+// socket: the palm frame comes from the socket (the knuckle line along its axis, the palm against the side the hand
+// comes from), not from the forearm's roll rule (grip.js). With no side given, the hand rolls about the axis to where
+// the arm holds it most easily, and where the forearm cannot come across the axis the knuckle line tilts on it (an
+// oblique grip, priced, up to TILT deg). The fingers' point stays where the fit put it; the elbow swivels to the pole
+// that leaves the wrist least strained (arm-orient.js, as a held object's hand, hold.js), the forearm takes its share of
+// the turn and the wrist the rest within its limits. Weighted by the fit's weight, so the hand turns into the grasp on
+// the reach and out of it on the release.
+// A hand that carries what it holds by a socket without keys keeps, after the grab, the wrist turn it had on the grab
+// frame against the forearm (diag.socket_<k>.rel, measured on the plain forearm before the turn): the object rides the
+// palm as it was taken (object-pose.js keeps the grab-frame offset), so neither the hand nor the object turns back. A
+// keyed carry's hand follows the keys (hold.js), whose grab offset is taken on that same grasp (object-keys.js attach).
+import { sub, norm, mul, T, axisRot } from "./math.js";
+import { palmAxes, twoBone } from "./limbs.js";
+import { aimArm, orient } from "./hold.js";
+import { ELBOW_REST, swivel } from "./arm-orient.js";
+import { anchorSocket } from "./anchors.js";
+import { socketPalm } from "../sockets.js";
+import { partsOf } from "../object-pose.js";
+
+const ITER = 3, ROLLS = 12, TEMP = 0.05, PULL = 0.3, DEG = 180 / Math.PI, TILT = 40, SLANT = 1, STEADY = 0.3;
+const TILTS = [-TILT, -TILT / 2, 0, TILT / 2, TILT];
+
+/** The Boltzmann-weighted mean of [value, cost] pairs at a softer temperature (STEADY): it moves smoothly between them. */
+function mean(all) {
+	const low = Math.min(...all.map(x => x[1])), e = all.map(([a, c]) => [a, Math.exp(-(c - low) / STEADY)]);
+	return e.reduce((m, [a, x]) => m + a * x, 0) / e.reduce((m, [, x]) => m + x, 0);
+}
+
+/** The Boltzmann-weighted circular mean of ROLLS angles under cost(th) (second-hand.js softmin). */
+function softmin(cost) {
+	const all = Array.from({ length: ROLLS }, (_, i) => { const th = (2 * Math.PI * i) / ROLLS - Math.PI; return [th, cost(th)]; }), low = Math.min(...all.map(x => x[1]));
+	const m = all.reduce((acc, [th, v]) => { const e = Math.exp(-(v - low) / TEMP); return [acc[0] + e * Math.cos(th), acc[1] + e * Math.sin(th)]; }, [0, 0]);
+	return Math.atan2(m[1], m[0]);
+}
+const cols = ({ d, l, n }) => [[d[0], l[0], n[0]], [d[1], l[1], n[1]], [d[2], l[2], n[2]]];
+
+/** True when the anchor named `name` takes a grasp (an object anchor with `grasp`). */
+export const graspAnchor = (spec, name) => spec.anchors?.[name]?.kind === "object" && !!spec.anchors[name].grasp;
+
+/** True when the agent's own keys (spec.keys, not a skill's or a generator's) turn hand k's wrist (wtwist_<k>, wflex_<k>). */
+export const ownWrist = (spec, k) => (spec.keys ?? []).some(key => (!key.src || key.src.startsWith("keys[")) && (key.set?.[`wtwist_${k}`] !== undefined || key.set?.[`wflex_${k}`] !== undefined));
+
+/** True when a grasp fit of hand k is anchored on body or group `id` (on it, a part of it, or a group holding it). */
+export function graspedBy(spec, scene, id, k) {
+	const parts = new Set(partsOf(scene, id));
+	return (spec.fits ?? []).some(fit => {
+		if (fit.side !== k || !graspAnchor(spec, fit.anchor)) return false;
+		const at = spec.anchors[fit.anchor].object;
+		return at === id || parts.has(at) || partsOf(scene, at).some(p => parts.has(p));
+	});
+}
+
+/** The carry hand k holds at frame f by a socket (graspedBy): { id, grab, keyed } for that spec.objects carry, else null. */
+export function socketCarry(ctx, k, f) {
+	const { spec, scene } = ctx;
+	if (!ctx.objectHand || !(spec.fits ?? []).some(fit => fit.side === k && graspAnchor(spec, fit.anchor))) return null;
+	for (const [id, o] of Object.entries(spec.objects ?? {})) if (o?.prop && ctx.objectHand(id, f) === k && graspedBy(spec, scene, id, k)) return { id, grab: ctx.carrySpan(o)[0], keyed: !!o.keys?.length };
+	return null;
+}
+
+/**
+ * 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, 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 = 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 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 };
+	for (let i = 0; i < ITER; i++) {
+		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, 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
+ * frames solved without keys, which come here, so the keyed solve of the grab frame would need that curve again.
+ */
+export function keepSocketTurn(ctx, sk, s, side, k, carry) {
+	const key = `${k}:${carry.grab}`;
+	ctx.socketTurns ??= new Map();
+	if (!ctx.socketTurns.has(key)) {
+		ctx.socketTurns.set(key, null);
+		ctx.socketTurns.set(key, (ctx.hold?.plainFrame ?? ctx.solvedAt)(carry.grab)?.diag?.[`socket_${k}`]?.rel ?? null);
+	}
+	const rel = ctx.socketTurns.get(key);
+	if (!rel) return;
+	const I = sk.index, fa = I[`${side}ForeArm`], h = I[`${side}Hand`];
+	orient(sk, s, side, h, fa, mul(s.R[fa], rel));
+}