cozyclay 3.0.1 → 3.0.2

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.0.1\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"bedf955b7367c9d4e883baa9c0b6fd14a205f6d39a3bf447f628488cd2893564\"}","signature":"+2TEXB+bXFUPN34/ls1YvimKkHfSdSCs0IiIyjIhsHqvz3j+XcKkEkqx1zjXn8MQlybgStGOS290YH40Nw1hBQ=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.0.2\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"7232c78719451c250c0be94e5f375e56c3c05984e94882724c50048b900c6c71\"}","signature":"+LLNPJc5HYZikPGbfrI57GjEjarn3TRJiaHrrsn4z1CuRMN958copspe2aRT+Y3j5wBo1vH0gYI2UsYn2J6sBA=="}

package/dist/index.html

@@ -301,9 +301,9 @@
         .btn, a.card, .seg button, .tutorial-steps li { transition: none; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/landing-yfZaJkWc.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/analytics-BWCqdgWA.js">
-    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-DNO8kv_N.js">
+    <script type="module" crossorigin src="/assets/landing-mq5bnqFE.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/analytics-DbKG0NgD.js">
+    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-CrGZ3n_O.js">
   </head>
   <body>
     <header class="site">

package/dist/workflow/index.html

@@ -8,11 +8,11 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-D78eiKTa.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-dUhurYUc.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/analytics-BWCqdgWA.js">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-DbKG0NgD.js">
     <link rel="modulepreload" crossorigin href="/assets/fflate.module-KbGj5-H6.js">
-    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-U3kS2rvK.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-7J-w5oNh.js">
     <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-_S8NQl5B.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozyclay",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Open source previs software in the browser: block a scene, pose characters, author camera moves and cuts, then take the same shots to an AI video model.",
   "scripts": {
     "dev": "node tools/dev-full.mjs --host 127.0.0.1 --port 5180",

package/src/agent-turn-mark.js

@@ -23,8 +23,41 @@ export function markAgentTurn(id, turn) {
   const { mark } = turn;
   if (!mark) throw new StudioProtocolError('STALE_TARGET', 'The agent turn has no mark to roll back to.');
   turn.mark = null;
+  turn.edits = (turn.edits ?? []).filter(edit => edit.mark !== mark);
   // No session at the mark: everything the turn authored came after it.
   turn.session?.rollback(mark.point ?? undefined);
   turn.affectedIds = mark.affectedIds;
   return { txId: turn.txId, affectedIds: [...mark.since], toasts: [] };
 }
+
+// The turn's own edits, newest last: each keeps the savepoint before it, so undo_edit on the
+// newest one's receipt rolls back to there and the turn stays open (9240db36 was refused twice).
+/** Where the turn stands before a command runs: the savepoint, the ids so far, the open mark. */
+export const turnEditPoint = turn => turn && { point: turn.session?.savepoint() ?? null, affectedIds: new Set(turn.affectedIds), since: turn.mark && new Set(turn.mark.since), mark: turn.mark };
+
+/** Files an authored receipt of the turn with the point before it; answers the receipt. */
+export function recordTurnEdit(turn, at, recorded) {
+  if (turn && at && recorded?.ok && recorded.authored) (turn.edits ??= []).push({ ...at, receiptId: recorded.receiptId, ids: recorded.affectedIds });
+  return recorded;
+}
+
+/**
+ * edit.undo from inside the owning turn once it has authored. A receipt of the turn's newest edit
+ * rolls back to the point before it and answers the receipt (before: the bus's read at admission;
+ * read: a read after); anything else is refused with what the agent can do instead.
+ */
+export function undoTurnEdit(turn, args, request, before, read) {
+  const edits = turn.edits ?? [], at = edits.findIndex(edit => edit.receiptId === args.receiptId);
+  if (at < 0) throw new StudioProtocolError('TARGET_BUSY', `Finish the agent turn before traversing history or opening another transaction. Inside the turn, undo_edit with the receiptId of this message's newest edit reverts it${edits.length ? ` (now ${edits.at(-1).receiptId})` : ''}; an earlier message's edit is undone after this one ends.`);
+  const edit = edits[at];
+  if (at < edits.length - 1) throw new StudioProtocolError('UNDO_CONFLICT', `Later edits of this message come after it; undo them first, newest first: ${edits.slice(at + 1).reverse().map(later => later.receiptId).join(', ')}.`);
+  turn.session.rollback(edit.point ?? undefined);
+  edits.pop();
+  turn.affectedIds = edit.affectedIds;
+  // Nothing came after a mark this edit predates, so the mark moves to now: a script's rollback still finds it.
+  if (turn.mark && edit.mark !== turn.mark) turn.mark = { point: turn.session.savepoint(), affectedIds: new Set(turn.affectedIds), since: new Set() };
+  else if (turn.mark) turn.mark.since = edit.since;
+  return { ok: true, status: 'completed', kind: 'transaction', action: 'edit.undo', txId: turn.txId, commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+    summary: `Undid ${edit.receiptId} inside this message.`, authored: false, revision: { before: before.revision, after: read().revision }, affectedIds: edit.ids, delta: [],
+    checks: { coverage: 'agent-turn-savepoint' }, undo: null, warnings: [], output: { undoneReceiptId: edit.receiptId } };
+}

package/src/command-bus.js

@@ -3,7 +3,7 @@
 // idempotency. Synchronous UI actions stay synchronous (including user gestures).
 import { HISTORY_LIMIT } from './history.js';
 import { StudioProtocolError, StudioSchemas, validateStudioSchema, validateReceipt, validateStudioIdentity, refusalCode } from './studio-agent-protocol.js';
-import { agentTurnControls, markAgentTurn } from './agent-turn-mark.js';
+import { agentTurnControls, markAgentTurn, turnEditPoint, recordTurnEdit, undoTurnEdit } from './agent-turn-mark.js';
 
 // A batching/retention adapter over the existing object history owner. The
 // native store still owns every snapshot and transition; this tracks only the
@@ -102,12 +102,11 @@ export function createCommandBus({ registry, ports }) {
       finally { agentTurn = null; }
       return transactionReceipt(id, turn, request, turn.before);
     }
-    // Every Studio turn opens a turn transaction (#715), so "undo the last thing" arrives
-    // inside one. Until the turn has authored anything (no session yet) history traversal
-    // is safe: the undo lands as its own entry and a later edit still groups into the turn.
-    // After the first authored edit the turn owns the frontier and traversal waits (#735).
+    // Every Studio turn opens a turn transaction (#715), so "undo the last thing" arrives inside one. Until the
+    // turn has authored (no session yet) history traversal is safe: the undo lands as its own entry (#735).
+    // After that the turn owns the frontier: its own agent may undo its newest edit (agent-turn-mark.js).
     const traversal = id === 'edit.undo' || id === 'edit.redo';
-    if (agentTurn && !id.startsWith('job.') && !(traversal && !agentTurn.session)) fail('TARGET_BUSY', 'Finish the agent turn before traversing history or opening another transaction.');
+    if (agentTurn && !id.startsWith('job.') && !(traversal && !agentTurn.session)) { if (id === 'edit.undo' && request.turnId === agentTurn.txId) return validateReceipt(undoTurnEdit(agentTurn, args, request, before, () => ports.read())); fail('TARGET_BUSY', 'Finish the agent turn before traversing history or opening another transaction.'); }
     if (traversal) {
       const redo = id === 'edit.redo', historyEntryId = ports.history?.(redo);
       const previous = args.receiptId ? ports.receipt(args.receiptId) : historyReceipts.get(historyEntryId)
@@ -358,13 +357,13 @@ export function createCommandBus({ registry, ports }) {
         const deadline = new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true }));
         return Promise.race([value, deadline]);
       };
-      const value = entry.kind === 'mutation' ? recordAction(entry.undoDomain, invoke, validated.characterId ?? null) : { result: invoke(), historyEntryId: null };
+      const point = turnEditPoint(turn), value = entry.kind === 'mutation' ? recordAction(entry.undoDomain, invoke, validated.characterId ?? null) : { result: invoke(), historyEntryId: null };
       const finish = ({ result, historyEntryId }) => mapResult(result, output => {
         clearTimer();
         releaseToasts?.(); releaseToasts = null;
-        const refused = toastRefusal();
+        const refused = output?.output === undefined ? toastRefusal() : null; // a job that answered was not refused by a toast that showed meanwhile
         if (refused) throw refused;
-        return remember(receipt(entry, request, before, { ...output, affectedIds: [...new Set([...output.affectedIds, ...nestedIds])] }, historyEntryId ?? committedHistoryId, toasts, turn));
+        return recordTurnEdit(turn, point, remember(receipt(entry, request, before, { ...output, affectedIds: [...new Set([...output.affectedIds, ...nestedIds])] }, historyEntryId ?? committedHistoryId, toasts, turn)));
       });
       const finished = value?.then ? value.then(finish) : finish(value);
       const answer = finished?.then ? finished.catch(rejected) : finished;

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/motion3.js

@@ -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 ?? [])];

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/motion3/compiler/anchors.js

@@ -9,18 +9,22 @@
 //   { 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, 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 } from "../sockets.js";
+import { partsOf } from "../object-pose.js";
 
 function armReach(sk, k) {
 	const side = SIDES[k], P = sk.restWorldPos, I = sk.index;
@@ -81,10 +85,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 +105,54 @@ 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), w = sock ? socketWorld(sock, poseOf(sock.owner)) : { p: local ?? poseOf(a.object).pos };
+	if (local) w.p = local;
+	// 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;
+}
+
 /** 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

@@ -33,7 +33,7 @@ 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);
 
@@ -180,10 +180,14 @@ 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);
 	const engine = {
 		rebake(keys) {
 			out.keys = keys;
 			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow));
+			ctx.socketTurns = 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,6 +32,7 @@ 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 cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[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 ?? {}));
 	// 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];

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

@@ -0,0 +1,107 @@
+// 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): 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.
+ */
+export function socketHand(ctx, sk, s, side, k, c, diag, on, effector) {
+	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 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 { 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 };
+	diag[`socket_${k}`] = { rel: mul(T(plain), s.R[h]) };
+}
+
+/**
+ * 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));
+}

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

@@ -1,7 +1,7 @@
 // Validation of the spec parts other than keys: anchors, props, fits, generators, checks and
 // fix; objects (validate-objects.js) and goals (validate-goals.js) run from here too. Unknown
 // fields go through opts.unknown, which ignores them on a lenient reload. See validate.js.
-import { didYouMean, suggestField, CONVENTIONS, isVec3, fmt } from "./vocab.js";
+import { didYouMean, suggestField, CONVENTIONS, isVec3, fmt, GRASPS } from "./vocab.js";
 import { FIX_KEYS } from "../fix/index.js";
 import { QA_LIMITS } from "../qa/checks.js";
 import { ANCHOR_FIELDS, PROP_FIELDS, FIT_FIELDS, WALK_FIELDS, CHECK_FIELDS, CHECK_ENTRY_FIELDS } from "../schema/fields.js";
@@ -9,6 +9,7 @@ import { boneOk, objectOk, refOk } from "./validate-common.js";
 import { validateObjects } from "./validate-objects.js";
 import { validateGoals } from "./validate-goals.js";
 import { personJoint, peopleList } from "../people.js";
+import { socketsOf, socketNamed } from "../sockets.js";
 
 const SIDE = new Set(["l", "r"]);
 const isObject = v => Boolean(v) && typeof v === "object" && !Array.isArray(v);
@@ -29,7 +30,11 @@ function validateAnchors(spec, err, { sk, scene, unknown = err }) {
 		if ((a.kind === "world" || a.kind === "body") && a.p === undefined) err(`${at} (${a.kind}) needs p: [x, y, z]${a.kind === "body" ? `, ${CONVENTIONS.pole}` : ""}`);
 		if (a.kind === "bone") boneOk(err, sk, at, a.bone);
 		if (a.kind === "segment") { boneOk(err, sk, `${at}.from`, a.from); boneOk(err, sk, `${at}.to`, a.to); if (a.reach !== undefined && !SIDE.has(a.reach)) err(`${at}.reach must be "l" or "r"`); }
-		if (a.kind === "object") objectOk(err, scene, at, a.object, { groups: true });
+		if (a.kind === "object" && objectOk(err, scene, at, a.object, { groups: true })) {
+			if (a.grasp !== undefined && !GRASPS.includes(a.grasp)) err(`${at}.grasp must be one of ${GRASPS.join(", ")}, got ${fmt(a.grasp)}`);
+			if (a.socket !== undefined && scene?.objects && !socketNamed(scene, a.object, a.socket)) err(`${at}.socket: "${a.object}" has no socket ${fmt(a.socket)} (sockets: ${socketsOf(scene, a.object).map(k => k.name).join(", ") || "none"})`);
+			if (a.socket !== undefined && a.grasp === undefined) err(`${at}.socket needs grasp (${GRASPS.join(", ")}): the socket says how the hand takes it`);
+		}
 		if (a.kind === "person" && !personJoint(scene, a.person, a.bone ?? "", 0)) err(`${at} (person) needs person: the id of another character with an installed take (people: ${peopleList(scene)}) and bone: one of its joints, got ${fmt(a.person)} ${fmt(a.bone)}`);
 		if (a.kind === "landmark" && a.name !== "mouth") err(`${at}: the only landmark is "mouth", got ${fmt(a.name)}`);
 		if (a.kind === "prop" && !spec.props?.[a.prop]?.points?.[a.point] && a.point !== "origin") err(`${at} needs prop point ${a.prop}.${a.point}, which spec.props does not define`);

package/src/motion3/compiler/vocab.js

@@ -11,6 +11,12 @@ 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"];
+/** 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" };
+/** 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] };
 
 // [min, max, convention] for numeric channels whose values have a hard range.
 const RANGES = [