cozyclay 3.0.0 → 3.0.1

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.0.0\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"e6a50c77650f2894d8154267dec8faafb86cad41e859b2594f233d5a18348530\"}","signature":"rwtYOUdZUQo57FluVUioxvNg+gKzRgBC38gyKcd7GIrm5nhq3iff5eV90XV7YFAJfVHn466qu3iLBsnjKkpIDA=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.0.1\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"bedf955b7367c9d4e883baa9c0b6fd14a205f6d39a3bf447f628488cd2893564\"}","signature":"+2TEXB+bXFUPN34/ls1YvimKkHfSdSCs0IiIyjIhsHqvz3j+XcKkEkqx1zjXn8MQlybgStGOS290YH40Nw1hBQ=="}

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-DjHD8u7k.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/analytics-C9sUnndd.js">
-    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-CC4xe4HM.js">
+    <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">
   </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-C4yKH1p4.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-D78eiKTa.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/analytics-C9sUnndd.js">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-BWCqdgWA.js">
     <link rel="modulepreload" crossorigin href="/assets/fflate.module-KbGj5-H6.js">
-    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-Hx_FzdOH.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-U3kS2rvK.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.0",
+  "version": "3.0.1",
   "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/App.jsx

@@ -1282,7 +1282,7 @@ export default function App() {
 	const [inspectorActionsOpen, setInspectorActionsOpen] = useState(false);
 
 	const objectsDomain = useObjects(appContext.forRender({
-		get animatedSceneObjects() { return animatedSceneObjects; },
+		get animatedSceneObjects() { return animatedSceneObjects; }, get attachFrameRef() { return attachFrameRef; },
 		get castMemberOf() { return castMemberOf; },
 		get charIdFromHierarchyId() { return charIdFromHierarchyId; },
 		get characters() { return characters; },

package/src/agent-progress.js

@@ -5,6 +5,7 @@
 // In-page only: nothing here is saved with the project, undone, or sent to the agent. Each character keeps its
 // last KEEP drafts; the images keep the last KEEP. A new agent turn starts clean (clearProgress).
 
+import { qaProblems } from "./qa-label.js";
 const KEEP = 12;
 const drafts = new Map(), sheets = [], listeners = new Set();
 let version = 0, counter = 0;
@@ -21,7 +22,7 @@ const pick = (row, keys) => Object.fromEntries(keys.filter(k => row?.[k] !== und
 /**
  * publishDraft(characterId, { take, installed, specId, label, qa, timeline }) -> the stored draft:
  * { n (1, 2, ... per character), at (ms), characterId, take, frames, installed, specId, label,
- *   qa: { ok, total, groups: [{ kind, subject, count, first, last, worst }], goals: [{ name, kind, ok, value, need, at }] },
+ *   qa: { ok, total, problems, groups: [{ kind, subject, count, first, last, worst }], goals: [{ name, kind, ok, value, need, at }] },
  *   timeline: the compile's beats (pipeline.js timelineOf) }.
  */
 export function publishDraft(characterId, { take, installed = false, specId = null, label = null, qa = null, timeline = [] }) {
@@ -29,7 +30,7 @@ export function publishDraft(characterId, { take, installed = false, specId = nu
 	const draft = Object.freeze({
 		n: (list.at(-1)?.n ?? 0) + 1, at: Date.now(), seq: ++counter, characterId, take, frames: take?.frameCount ?? 0,
 		installed: !!installed, specId, label,
-		qa: { ok: !!qa?.ok, total: qa?.total ?? 0,
+		qa: { ok: !!qa?.ok, total: qa?.total ?? 0, problems: qaProblems(qa),
 			groups: (qa?.groups ?? []).map(g => pick(g, ["kind", "subject", "count", "first", "last", "worst"])),
 			goals: (qa?.goals ?? []).map(g => pick(g, ["name", "kind", "ok", "value", "need", "at"])) },
 		timeline: timeline ?? [],

package/src/app-context.js

@@ -1,8 +1,13 @@
-import { createContext, useContext } from 'react';
+import { createContext, useContext, useMemo } from 'react';
 import { StudioProtocolError } from './studio-agent-protocol.js';
 
 export const AppContext = createContext(null);
-export function useBus() { return useContext(AppContext).bus; }
+// Reading `bus` refreshes the studio binding (it serializes the whole scene), so a panel must not read it while it
+// renders: playback re-renders panels every frame. The hook hands back a stable handle that opens the bus per call.
+export function useBus() {
+  const app = useContext(AppContext);
+  return useMemo(() => ({ run: (...args) => app.bus.run(...args), subscribe: (...args) => app.bus.subscribe(...args) }), [app]);
+}
 
 const ref = current => ({ current });
 

package/src/command-bus.js

@@ -2,7 +2,7 @@
 // the editor ports own native state/history, and the existing journal owns
 // idempotency. Synchronous UI actions stay synchronous (including user gestures).
 import { HISTORY_LIMIT } from './history.js';
-import { StudioProtocolError, StudioSchemas, validateStudioSchema, validateReceipt, validateStudioIdentity } from './studio-agent-protocol.js';
+import { StudioProtocolError, StudioSchemas, validateStudioSchema, validateReceipt, validateStudioIdentity, refusalCode } from './studio-agent-protocol.js';
 import { agentTurnControls, markAgentTurn } from './agent-turn-mark.js';
 
 // A batching/retention adapter over the existing object history owner. The
@@ -203,7 +203,7 @@ export function createCommandBus({ registry, ports }) {
   function refusal(request, before, error, mutated) {
     const changed = mutated ?? (ports.read().revision !== before.revision);
     return validateReceipt({ ok: false, commandId: request.commandId, host: before.host,
-      code: error.code ?? 'INVALID_ARGUMENT', phase: changed ? 'commit' : 'admission', affectedIds: [], expectedTargets: [], currentTargets: [],
+      code: refusalCode(error), phase: changed ? 'commit' : 'admission', affectedIds: [], expectedTargets: [], currentTargets: [],
       mutated: changed, preserved: { authoredState: changed ? 'changed' : 'unchanged' }, recovery: { action: 'inspect', retryAllowed: false },
       message: [...String(error.message || error)].slice(0, 500).join('') });
   }

package/src/commands/motion3.js

@@ -18,9 +18,11 @@ import { fitOutput, reportPage } from "../motion3/report.js";
 import { keyObject } from "../motion3/key-edit.js";
 import { expandUse } from "../motion3/skills/index.js";
 import { publishDraft } from "../agent-progress.js";
+import { qaSay } from "../qa-label.js";
 import { carryEdit } from "../motion3/edit-carry.js";
 import { normalizeCompileArgs } from "../motion3/lenient.js";
 import { createCompileRunner } from "./motion3-compile.js";
+import { peopleOf } from "../motion3/people.js";
 
 const TIMELINE_FPS = 24;
 const id = { type: "string", minLength: 1 };
@@ -91,6 +93,11 @@ export function register(registry, ports) {
 		if (Math.abs((character.scale ?? 1) - 1) > 1e-6) fail("TARGET_NOT_READY", "Set the character's scale back to 1 before compiling motion.");
 		return sk;
 	};
+	// the scene a compile sees: the objects, and the other characters' installed takes as moving bodies (people.js)
+	const sceneFor = character => {
+		const state = ports.state(), people = peopleOf(state.characters, character.id, id => owner().motionFor(id));
+		return { ...motionScene(state.objects), ...(Object.keys(people).length ? { people } : {}) };
+	};
 	// one compile worker per editor in the browser, the calling thread elsewhere (motion3-compile.js)
 	const runner = createCompileRunner();
 	const workerWarning = () => { const note = runner.takeWarning(); return note ? { warnings: [note] } : {}; };
@@ -101,7 +108,7 @@ export function register(registry, ports) {
 	const compile = (character, spec, opts = {}, bake) => {
 		rigOf(character);
 		const placed = bake && { position: [character.x ?? 0, character.y ?? 0, character.z ?? 0], yaw: character.rot ?? 0, ...bake };
-		return runner.run({ model: character.model, scene: motionScene(ports.state().objects), spec, ...opts, ...(placed ? { bake: placed } : {}) });
+		return runner.run({ model: character.model, scene: sceneFor(character), spec, ...opts, ...(placed ? { bake: placed } : {}) });
 	};
 	/** The whole output, kept in the store (motion.report, delta) and cut to the receipt budget (report.js). */
 	const report = (r, head, extra = {}) => {
@@ -153,12 +160,12 @@ export function register(registry, ports) {
 			const output = report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: wanted, ...adjustedOf(notes) }, { ...delta, ...(r.repair ? { repair: r.repair } : {}), ...(timing ? { timing } : {}) });
 			// agent-progress.js: viewport ghost, timeline beats, agent panel
 			publishDraft(characterId, { take, installed: installs || kept, specId: output.specId, label: r.label, qa, timeline: r.timeline });
-			return { affectedIds: installs ? [characterId] : [], summary: `Compiled ${r.frameCount} frames; QA ${qa.ok ? "clean" : `${qa.total} issues`}${how}${adjustedSay(notes)}.`, output, ...workerWarning() };
+			return { affectedIds: installs ? [characterId] : [], summary: `Compiled ${r.frameCount} frames; QA ${qaSay(qa)}${how}${adjustedSay(notes)}.`, output, ...workerWarning() };
 		});
 	} });
 	registry.register({ ...declarations[1], available: mounted, run({ characterId, checks }) {
 		const character = characterOf(ports, characterId), take = installed(characterId);
-		return after(compile(character, take.spec, { checks }), r => ({ affectedIds: [], summary: `QA ${r.qa.ok ? "clean" : `${r.qa.total} issues`}${adjustedSay(r.notes ?? [])}.`,
+		return after(compile(character, take.spec, { checks }), r => ({ affectedIds: [], summary: `QA ${qaSay(r.qa)}${adjustedSay(r.notes ?? [])}.`,
 			output: report(r, adjustedOf(r.notes ?? [])), ...workerWarning() }));
 	} });
 	registry.register({ ...declarations[2], available: mounted, run({ characterId, frames, bones = DEFAULT_BONES }) {
@@ -196,11 +203,11 @@ export function register(registry, ports) {
 	// 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
 	registry.register({ ...declarations[5], available: mounted, target: args => args.characterId, run({ characterId, ...args }, context) {
-		const character = characterOf(ports, characterId), take = installed(characterId), scene = motionScene(ports.state().objects);
+		const character = characterOf(ports, characterId), take = installed(characterId), scene = sceneFor(character);
 		const { spec, keyed } = asArgument(() => keyObject(take.spec, scene, args, expandUse(take.spec, { sk: rigOf(character), scene, lenient: true }).spec.objects));
 		return after(compile(character, spec, { lenient: true }, { prompt: take.prompt }), r => {
 			const timing = put(character, r.take, context);
-			return { affectedIds: [characterId], summary: `${keyed.removed ? "Removed the key of" : "Keyed"} ${keyed.objectId} at f${keyed.f}; QA ${r.qa.ok ? "clean" : `${r.qa.total} issues`}; installed.`,
+			return { affectedIds: [characterId], summary: `${keyed.removed ? "Removed the key of" : "Keyed"} ${keyed.objectId} at f${keyed.f}; QA ${qaSay(r.qa)}; installed.`,
 				output: report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: true, keyed }, timing ? { timing } : {}), ...workerWarning() };
 		});
 	} });

package/src/commands/shot.js

@@ -22,10 +22,9 @@ const number = { type: 'number' };
 const frame = { type: 'integer', minimum: 0 };
 const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
 const mutation = (id, label, schema, description = label) => ({ id, label, description, kind: 'mutation', undoDomain: 'shot', input: schema });
-const existing = ['shot.create', 'shot.createStill', 'shot.setCaption', 'shot.setCastOverride', 'shot.setHold', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.reorder'].map(studioActionDeclaration);
+const existing = ['shot.create', 'shot.createStill', 'shot.setCaption', 'shot.setCastOverride', 'shot.setHold', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.setCameraMode', 'shot.rename', 'shot.reorder'].map(studioActionDeclaration);
 const extra = [
   mutation('shot.set', 'Set shot fields', elementSetSchema('shot')),
-  mutation('shot.rename', 'Rename shot', input({ shotId: id, name: { type: 'string', maxLength: 240 } })),
   mutation('shot.setCamera', 'Set camera block', input({ shotId: id, patch: { type: 'object', properties: {}, additionalProperties: true } })),
   mutation('shot.addKey', 'Add camera key', input({ shotId: id, frame })),
   mutation('shot.moveKey', 'Move camera key', input({ shotId: id, keyId: id, frame })),
@@ -159,6 +158,11 @@ export function register(registry, ports) {
       patchShot(shotId, shot => ({ ...shot, camera: removeCameraRail(shot.camera) }));
     },
     'shot.rename': ({ shotId, name }) => { shotOf(shotId); owner().write(current => renameShot(current, shotId, name)); },
+    'shot.setCameraMode': ({ shotId, mode }) => {
+      const shot = shotOf(shotId);
+      if (mode === 'rail' && !createCameraBlock(shot.camera).cameraRail) fail('TARGET_NOT_READY', `${shot.name || shotId} has no camera rail; lay one with shot.setCameraRail.`);
+      patchShot(shotId, row => ({ ...row, camera: updateCameraBlock(row.camera, { mode }) }));
+    },
     'shot.setCamera': ({ shotId, patch }) => patchShot(shotId, shot => ({ ...shot, camera: updateCameraBlock(shot.camera, patch) })),
     'shot.addKey': ({ shotId, frame }) => {
       const shot = shotOf(shotId), target = Math.min(owner().state().frameCount - 1, frame);

package/src/domains/motion/take-source.js

@@ -22,7 +22,7 @@ const finite3 = value => Array.isArray(value) && value.length === 3 && value.eve
 export function takeSource(take, sceneObjects = []) {
 	if (!isTakeV3(take) || !plain(take.spec)) return null;
 	return structuredClone({ schema: TAKE_SCHEMA, rig: take.rig, spec: take.spec,
-		placement: { position: take.placement?.position ?? [0, 0, 0], yaw: take.placement?.yaw ?? 0 }, scene: motionScene(sceneObjects) });
+		placement: { position: take.placement?.position ?? [0, 0, 0], yaw: take.placement?.yaw ?? 0 }, scene: { ...motionScene(sceneObjects), ...(plain(take.people) ? { people: take.people } : {}) } });
 }
 
 /** A saved source (with the Studio take id it carried), checked and owned by the caller; null when it is not one. */
@@ -31,8 +31,10 @@ export function normalizeTakeSource(value) {
 	if (!plain(value.spec) || value.spec.schema !== SPEC_SCHEMA || !Number.isFinite(value.spec.frames)) return null;
 	if (!plain(value.placement) || !finite3(value.placement.position) || !Number.isFinite(value.placement.yaw)) return null;
 	const objects = plain(value.scene?.objects) ? value.scene.objects : {}, others = plain(value.scene?.others) ? { others: value.scene.others } : {};
+	// the joints a person anchor named when it was compiled (people.js keptPeople)
+	const people = plain(value.scene?.people) && Object.values(value.scene.people).every(p => plain(p) && Array.isArray(p.names) && Array.isArray(p.P) && p.P.length === p.frames * p.names.length * 3) ? { people: value.scene.people } : {};
 	return structuredClone({ schema: TAKE_SCHEMA, rig: value.rig, spec: value.spec,
-		placement: { position: value.placement.position, yaw: value.placement.yaw }, scene: { objects, ...others },
+		placement: { position: value.placement.position, yaw: value.placement.yaw }, scene: { objects, ...others, ...people },
 		...(typeof value.takeId === "string" && value.takeId ? { takeId: value.takeId } : {}),
 		...(normalizeTakeEdit(value.edit, value.spec.frames) ? { edit: normalizeTakeEdit(value.edit, value.spec.frames) } : {}) });
 }

package/src/draft-ghost.js

@@ -6,6 +6,7 @@
 // GIZMO_LAYER, so captures, contact sheets and exports never see it.
 import { useSyncExternalStore } from "react";
 import { ko } from "./locale.js";
+import { qaLabel } from "./qa-label.js";
 
 /** Teal: apart from the onion skin's blue (before) and orange (after). */
 export const DRAFT_GHOST_COLOR = "#2fc79a";
@@ -28,8 +29,8 @@ export function draftGhostState(draft, now) {
 	return { shown: true, opacity: +opacity.toFixed(3), frame: Math.floor((age / 1000) * fps) % take.frameCount };
 }
 
-/** "Draft 3 · QA 31" ("초안 3 · QA 31"). */
-export const draftLabel = draft => `${ko("Draft", "초안")} ${draft?.n ?? 0} · QA ${draft?.qa?.total ?? 0}`;
+/** "Draft 3 · 2 problems" ("초안 3 · 문제 2개"), "Draft 7 · QA clean": problems, not frame-level issues (qa-label.js). */
+export const draftLabel = draft => `${ko("Draft", "초안")} ${draft?.n ?? 0} · ${qaLabel(draft?.qa)}`;
 
 let shown = true;
 const listeners = new Set();

package/src/motion/beat-board-model.js

@@ -63,7 +63,7 @@ export function beatBoardModel(draft, motion) {
 	for (const block of blocks) block.rows = rows;
 	const spans = groups.map(g => ({ f0: g.first ?? 0, f1: g.last ?? g.first ?? 0, text: `${g.kind} ${g.subject}` })).sort((a, b) => a.f0 - b.f0);
 	const marks = goals.map(g => ({ f: g.at, ok: !!g.ok, text: goalText(g) })).sort((a, b) => a.f - b.f);
-	return { mode, n: draft.n, total: draft.qa?.total ?? 0, ok: !!draft.qa?.ok, blocks, spans, marks };
+	return { mode, n: draft.n, total: draft.qa?.total ?? 0, ok: !!draft.qa?.ok, qa: draft.qa ?? null, blocks, spans, marks };
 }
 
 /** One goal as a line: "✓ name 1.2 cm (≤ 2 cm)"; a distance in metres reads in cm. */

package/src/motion/beat-board.jsx

@@ -8,6 +8,7 @@ import { useSyncExternalStore } from "react";
 import { ko } from "../locale.js";
 import { latestDraft, progressVersion, subscribeProgress } from "../agent-progress.js";
 import { beatBoardModel, blockTitle } from "./beat-board-model.js";
+import { draftLabel } from "../draft-ghost.js";
 import "./beat-board.css";
 
 function stateChip(block) {
@@ -51,7 +52,7 @@ export function BeatBoard({ motion, frame, displayFrameCount, clipPct, onJump })
 			{model.mode === "draft" && (
 				<span className={"tl-beat-head" + (model.ok ? " ok" : "")} data-testid="beat-board-head"
 					title={ko("The agent's newest draft, not installed yet", "에이전트가 만든 최신 초안 (아직 적용 전)")}>
-					{ko(`Draft ${model.n} · QA ${model.total}`, `초안 ${model.n} · QA ${model.total}`)}
+					{draftLabel({ n: model.n, qa: model.qa })}
 				</span>
 			)}
 		</div>

package/src/motion3/compile-job.js

@@ -10,6 +10,7 @@ import { compileSpec, liftRequest } from "./pipeline.js";
 import { repairSpec } from "./repair.js";
 import { bakeTake } from "./take.js";
 import { skeletonFor } from "./rigs/index.js";
+import { keptPeople } from "./people.js";
 
 const TIMELINE_FPS = 24;
 const refuse = (code, message) => { throw Object.assign(new Error(message), { code }); };
@@ -52,6 +53,9 @@ export function runCompileJob({ model, scene, spec: asked, probes: sentProbes, c
 	// ms.repair: the whole repair's wall time, so a sweep that repairs every variant shows what it costs
 	const r = fixed.result, label = fixed.spec?.label ?? null, ms = fixed.repair ? { ...r.ms, repair: Math.round(performance.now() - t0) } : r.ms;
 	const take = bake ? bakeTake(sk, r.out, { position: bake.position, yaw: bake.yaw }, { spec: r.stored, prompt: ("prompt" in bake ? bake.prompt : label) ?? "" }) : undefined;
+	// a person anchor's joints ride with the take, so its saved source compiles the same without the others' takes (people.js)
+	const people = take && keptPeople(scene, [r.expanded, r.stored]);
+	if (people) take.people = people;
 	return { stored: r.stored, qa: r.qa, observations: r.observations, used: r.used, fixed: r.fixed, search: r.search, timeline: r.timeline,
 		...(r.probes ? { probes: r.probes } : {}), ...(r.notes ? { notes: r.notes } : {}), ms, frameCount: r.out.frameCount, label,
 		...(fixed.repair ? { repair: fixed.repair } : {}), ...(take ? { take } : {}) };

package/src/motion3/compiler/anchors.js

@@ -10,6 +10,8 @@
 //                       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: "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";
@@ -18,6 +20,7 @@ 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";
 
 function armReach(sk, k) {
 	const side = SIDES[k], P = sk.restWorldPos, I = sk.index;
@@ -85,6 +88,11 @@ function anchorPoint(ctx, a, name, s, diag, c, side) {
 			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]);
 		}
+		case "person": {
+			const p = personJoint(ctx.scene, a.person, a.bone, diag?.frame ?? 0);
+			if (!p) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" names person "${a.person}" bone "${a.bone}", which the scene does not have (people: ${peopleList(ctx.scene)})`);
+			return add(p, a.offset ?? [0, 0, 0]);
+		}
 		default: throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" has unknown kind "${a.kind}"`);
 	}
 }

package/src/motion3/compiler/limbs.js

@@ -103,16 +103,21 @@ export function twoBone(sk, s, root, mid, end, target, pole, restBend, stop = nu
 	return inside || d - dc;
 }
 
-/** Aim a foot: Foot->ToeBase along yaw/pitch of its rest direction, sole kept level. */
-export function orientFoot(sk, s, side, yawDeg, pitchDeg) {
+/**
+ * Aim a foot: Foot->ToeBase along yaw/pitch of its rest direction, sole kept level. With `tilt` (pose.js tiltFrame: a body
+ * turned well past upright) the yaw and pitch are read in that frame and the sole levels to its up, so a foot in a flip
+ * points with the shin instead of staying flat to the floor; no toe-off then (the toes are off the ground).
+ */
+export function orientFoot(sk, s, side, yawDeg, pitchDeg, tilt = null) {
 	const foot = sk.index[`${side}Foot`], toe = sk.index[`${side}ToeBase`];
 	const rest = sub(sk.restWorldPos[toe], sk.restWorldPos[foot]);
-	const want = apply(ry(yawDeg), apply(rx(pitchDeg), rest));
+	const want = tilt ? apply(tilt.R, apply(ry(yawDeg - tilt.yaw), apply(rx(pitchDeg), rest))) : apply(ry(yawDeg), apply(rx(pitchDeg), rest));
+	const up = tilt ? apply(tilt.R, [0, 1, 0]) : [0, 1, 0];
 	// level the sole: the foot's own carried up vector goes to world up (no roll from the leg IK)
-	rotateSubtree(sk, s, foot, s.P[foot].slice(), align(sub(s.P[toe], s.P[foot]), carried(sk, s, foot, [0, 1, 0]), want, [0, 1, 0]));
+	rotateSubtree(sk, s, foot, s.P[foot].slice(), align(sub(s.P[toe], s.P[foot]), carried(sk, s, foot, [0, 1, 0]), want, up));
 	// Toe-off: bend the toe joint so the toes stay flat on the ground while the heel rises.
 	const tip = sk.index[`${side}Toe_End`];
-	if (pitchDeg > 0 && tip !== undefined) {
+	if (!tilt && pitchDeg > 0 && tip !== undefined) {
 		const seg = sub(s.P[tip], s.P[toe]), flat = [seg[0], 0, seg[2]];
 		if (len(flat) > 1e-6) rotateSubtree(sk, s, toe, s.P[toe].slice(), align(seg, [0, 1, 0], flat, [0, 1, 0]));
 	}
@@ -144,11 +149,13 @@ export function wrist(sk, s, side, twistDeg, flexDeg) {
 	rotateSubtree(sk, s, h, s.P[h].slice(), axisRot(axT, clamp(twistDeg, -85, 85)));
 }
 
-// Finger curl presets, degrees per phalanx (1, 2, 3); thumb is [opposition, curl, curl].
+// Finger curl presets, degrees per phalanx (1, 2, 3); thumb is [opposition, curl, curl]. A fist and a grip keep the
+// relaxed thumb here and close it with THUMB_WRAP: these thumb curls turn about the knuckle line and the hand's long axis,
+// which only swings a thumb out to the side (a fist read as a thumbs-up).
 const FINGER_PRESETS = {
 	relaxed: { Index: [12, 18, 10], Middle: [15, 20, 12], Ring: [18, 22, 12], Pinky: [20, 24, 14], Thumb: [15, 10, 8] },
-	fist: { Index: [80, 95, 60], Middle: [85, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [45, 30, 35] },
-	grip: { Index: [55, 60, 35], Middle: [60, 62, 35], Ring: [62, 62, 35], Pinky: [65, 62, 35], Thumb: [40, 20, 20] },
+	fist: { Index: [80, 95, 60], Middle: [85, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [15, 10, 8] },
+	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] },
 };
@@ -166,5 +173,25 @@ export function fingers(sk, s, side, weights) {
 			rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(ax, sign * curl(f, k)));
 		}
 	}
+	const wrap = [0, 1, 2, 3].map(i => Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * (THUMB_WRAP[p]?.[i] ?? 0), 0));
+	if (wrap.some(Boolean)) wrapThumb(sk, s, side, wrap);
+}
+
+// A closing hand's thumb, by preset weight after the relaxed one, degrees: turned in about the hand's long axis toward the
+// 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] };
+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;
+	const { d, n } = palmAxes(sk, s, side);
+	rotateSubtree(sk, s, J(1), s.P[J(1)].slice(), axisRot(d, sign * oppose));
+	// n = d x l flips with the mirror, so the turn across the palm keeps its sign on both hands
+	rotateSubtree(sk, s, J(1), s.P[J(1)].slice(), axisRot(n, across));
+	for (const [k, deg] of [[2, flex2], [3, flex3]]) {
+		const ax = norm(cross(norm(sub(s.P[J(k + 1)], s.P[J(k)])), n));
+		rotateSubtree(sk, s, J(k), s.P[J(k)].slice(), axisRot(ax, sign * deg));
+	}
 }
 

package/src/motion3/compiler/pose.js

@@ -82,6 +82,21 @@ function hangOf(sk, down) {
 	return hang;
 }
 
+/**
+ * The frame the knee and elbow poles and the feet are read in once the whole body turns well past upright (a flip, a
+ * cartwheel): the root's yaw, pitch and roll, the tilt eased in from TILT_FROM to TILT_FULL degrees (the larger of the
+ * wrapped pitch and roll). Under TILT_FROM it is null and the poles turn with the yaw only, as they always have, so an
+ * upright take is unchanged.
+ */
+const TILT_FROM = 60, TILT_FULL = 120;
+const wrap180 = a => a - 360 * Math.round(a / 360);
+export function tiltFrame(yaw, pitch, roll) {
+	const p = wrap180(pitch), r = wrap180(roll), u = (Math.max(Math.abs(p), Math.abs(r)) - TILT_FROM) / (TILT_FULL - TILT_FROM);
+	if (u <= 0) return null;
+	const w = u >= 1 ? 1 : u * u * (3 - 2 * u);
+	return { yaw, R: mul(ry(yaw), mul(rx(p * w), rz(r * w))) };
+}
+
 export function pose(sk, c, hooks = {}) {
 	const s = restState(sk);
 	const diag = {};
@@ -107,7 +122,7 @@ export function pose(sk, c, hooks = {}) {
 	rotateSubtree(sk, s, hips, s.P[hips].slice(), mul(ry(yaw), mul(rx(num(c.pitch)), rz(num(c.roll)))));
 	const shift = sub(v3(c.root, s.P[hips]), s.P[hips]);
 	for (let j = 0; j < s.P.length; j++) s.P[j] = add(s.P[j], shift);
-	const body = ry(yaw);
+	const tilt = tiltFrame(yaw, num(c.pitch), num(c.roll)), body = tilt?.R ?? ry(yaw);
 	// Legs: two-bone IK to the ankle targets, the knee no further folded than its stop (limbs.js KNEE_STOP), then aim the feet.
 	for (const [k, side] of Object.entries(SIDES)) {
 		if (!c[`foot_${k}`]) continue;
@@ -117,7 +132,7 @@ export function pose(sk, c, hooks = {}) {
 		// a target nearer the hip than the knee folds leaves a residual (leg_miss); leg_fold says what it asked
 		const fold = askedFold(sk, s, side, target, LEG);
 		if (fold > KNEE_FOLD) diag[`leg_fold_${k}`] = fold;
-		orientFoot(sk, s, side, num(c[`fyaw_${k}`], yaw), num(c[`fpitch_${k}`]));
+		orientFoot(sk, s, side, num(c[`fyaw_${k}`], yaw), num(c[`fpitch_${k}`]), tilt);
 	}
 	// Arms: blend the FK hand toward the hook's target, poles blended the same way.
 	for (const k of hooks.armOrder ?? ["r", "l"]) {

package/src/motion3/compiler/validate-objects.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? }";
+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 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;
 
@@ -77,7 +77,7 @@ function frameOk(err, at, v, frames) {
 	return false;
 }
 
-/** objects.<id>.fall (C17): { at, onto?, bounce? } or a list, each on its own frame; a carry falls only out of hand. */
+/** objects.<id>.fall (C17): { at, onto?, bounce?, tumble? } or a list, each on its own frame; a carry falls only out of hand. */
 function validateFalls(err, unknown, at, o, { frames, scene, carry }) {
 	const list = Array.isArray(o.fall) ? o.fall : [o.fall], seen = new Set();
 	if (!list.length) err(`${at}.fall is an empty list; give ${FALL} or a list of them`);
@@ -94,6 +94,7 @@ 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.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)}`);
 	});
 }
 

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

@@ -8,6 +8,7 @@ import { ANCHOR_FIELDS, PROP_FIELDS, FIT_FIELDS, WALK_FIELDS, CHECK_FIELDS, CHEC
 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";
 
 const SIDE = new Set(["l", "r"]);
 const isObject = v => Boolean(v) && typeof v === "object" && !Array.isArray(v);
@@ -29,6 +30,7 @@ function validateAnchors(spec, err, { sk, scene, unknown = err }) {
 		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 === "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/validate.js

@@ -23,10 +23,10 @@ function checkValue(err, at, ch, v) {
 		if (!isVec3(v)) return err(`${at} ${ch} must be [x, y, z] (3 finite numbers), got ${fmt(v)}`);
 		if (POLE_CHANNELS.has(ch)) {
 			const l = Math.hypot(...v);
-			if (l < 1e-6) return err(`${at} ${ch} = ${fmt(v)} has no direction; a pole is ${CONVENTIONS.pole}`);
-			if (ch.startsWith("knee") && v[2] < -0.7 * l) err(`${at} ${ch} = ${fmt(v)} points backward; knees bend toward +z. A pole is ${CONVENTIONS.pole}`);
+			if (l < 1e-6) return err(`${at} ${ch} = ${fmt(v)} has no direction; a pole is a ${CONVENTIONS.pole}`);
+			if (ch.startsWith("knee") && v[2] < -0.7 * l) err(`${at} ${ch} = ${fmt(v)} points backward; knees bend toward +z. A pole is a ${CONVENTIONS.pole}`);
 		}
-		if (ch.startsWith("foot") && v[1] < 0.04) err(`${at} ${ch} y = ${v[1]} puts the ankle into the floor; foot_* is ${CONVENTIONS.foot}`);
+		if (ch.startsWith("foot") && v[1] < 0.04) err(`${at} ${ch} y = ${v[1]} puts the ankle into the floor; foot_* is the ${CONVENTIONS.foot}`);
 		return;
 	}
 	if (MAP_CHANNELS.has(ch)) {

package/src/motion3/compiler/vocab.js

@@ -14,33 +14,34 @@ export const FINGER_PRESETS = ["relaxed", "fist", "grip", "cigarette", "point"];
 
 // [min, max, convention] for numeric channels whose values have a hard range.
 const RANGES = [
-	[/^(armw)_[lr]$/, 0, 1, "0 = FK arm, 1 = IK to the hand target"],
+	[/^(armw)_[lr]$/, 0, 1, "0 FK, 1 IK to the hand target"],
 	[/^arm_hang$/, 0, 1, "1 = a free FK forearm hangs plumb"],
-	[/^w_.+_[lr]$/, 0, 1, "a hand-target weight; the weights of one hand add up to at most 1"],
-	[/^wtwist_[lr]$/, -85, 85, "wrist twist about the forearm in degrees"],
-	[/^wflex_[lr]$/, -70, 70, "wrist flex about the knuckle line in degrees"],
-	[/^fpitch_[lr]$/, -60, 90, "toe-down pitch in degrees: + lifts the heel (the toes stay flat), - lifts the toes"],
-	[/^(pitch|spine_pitch|head_pitch)$/, -120, 120, "degrees, + bends forward"],
-	[/^(roll|spine_roll|head_roll)$/, -90, 90, "degrees"],
+	[/^w_.+_[lr]$/, 0, 1, "hand-target weight; a hand's sum <= 1"],
+	[/^wtwist_[lr]$/, -85, 85, "twist about the forearm, deg"],
+	[/^wflex_[lr]$/, -70, 70, "flex about the knuckle line, deg"],
+	[/^fpitch_[lr]$/, -60, 90, "toe-down pitch, deg: + lifts the heel (toes flat), - lifts the toes"],
+	// the whole-body pitch and roll have none: they turn in full (flips, cartwheels; pose.js tiltFrame)
+	[/^(spine_pitch|head_pitch)$/, -120, 120, "degrees, + bends forward"],
+	[/^(spine_roll|head_roll)$/, -90, 90, "degrees"],
 ];
 export const rangeOf = ch => RANGES.find(([re]) => re.test(ch)) ?? null;
 
 export const CONVENTIONS = {
 	yaw: "yaw 0 faces +Z and + turns toward +X",
-	fyaw: "foot heading in degrees, as yaw",
-	pole: "a body-frame direction (turned by the root yaw only): +z forward, +x the character's left, +y up",
-	foot: "the ANKLE target in world metres (standing: 0.087 X Bot, 0.105 Y Bot)",
-	hand: "the WRIST target in world metres",
-	root: "the hips joint in world metres (standing: 1.03 X Bot, 0.99 Y Bot)",
+	fyaw: "foot heading, as yaw",
+	pole: "body-frame direction (root yaw): +z forward, +x its left, +y up",
+	foot: "ANKLE target, world m (standing 0.087 X Bot, 0.105 Y Bot)",
+	hand: "WRIST target, world m",
+	root: "hips joint, world m (standing 1.03 X Bot, 0.99 Y Bot)",
 };
 
 /** What each channel family means (a family drops the _l/_r side), for motion.describe "channels". */
 export const CHANNEL_DOCS = {
-	root: CONVENTIONS.root, yaw: `degrees; ${CONVENTIONS.yaw}`, pitch: "whole-body pitch, degrees", roll: "whole-body roll, degrees",
-	spine_yaw: "degrees", spine_pitch: "degrees, + bends forward", spine_roll: "degrees", head_yaw: "degrees", head_pitch: "degrees, + looks down", head_roll: "degrees",
-	arm_rest: "FK arms down from the T-pose (default 72)", arm_hang: "1 = a free FK forearm hangs plumb (standIdle and walks key it)", foot: CONVENTIONS.foot, fyaw: CONVENTIONS.fyaw, fpitch: "toe-down pitch, degrees, + heel up",
+	root: CONVENTIONS.root, yaw: `deg; ${CONVENTIONS.yaw}`, pitch: "degrees", roll: "degrees",
+	spine_yaw: "degrees", spine_pitch: "deg, + bends forward", spine_roll: "degrees", head_yaw: "degrees", head_pitch: "degrees, + looks down", head_roll: "degrees",
+	arm_rest: "FK arms down, deg, default 72", arm_hang: "1 = a free FK forearm hangs plumb (standIdle and walks key it)", foot: CONVENTIONS.foot, fyaw: CONVENTIONS.fyaw, fpitch: "toe-down pitch, degrees, + heel up",
 	knee: `knee pole, ${CONVENTIONS.pole}`, armw: "0 = FK arm, 1 = IK to hand_* / the anchors", hand: CONVENTIONS.hand, elbow: `elbow pole, ${CONVENTIONS.pole}`,
-	wtwist: "wrist twist, degrees", wflex: "wrist flex, degrees", aswing: "FK arm swing, degrees, + forward", abend: "FK elbow bend, degrees",
+	wtwist: "wrist twist, degrees", wflex: "wrist flex, degrees", aswing: "FK arm swing, deg, + forward", abend: "FK elbow bend, deg",
 	fingers: "{ preset: weight 0..1 }",
 };
 export const channelFamily = ch => ch.replace(/_[lr]$/, "");

package/src/motion3/describe.js

@@ -81,7 +81,7 @@ const SCHEMAS = {
 	probes: () => listOf({ ...objectOf(PROBE_FIELDS, PROBE_TYPES, "probes", ["name"]), ...oneOfRequired(["distance", "position"]) }, { maxItems: 16 }),
 	channels: () => ({ type: "object", description: "key.set: channel -> value",
 		properties: Object.fromEntries([...VEC_CHANNELS, ...NUM_CHANNELS, ...MAP_CHANNELS].filter(ch => !SKILL_CHANNELS.has(ch)).map(ch => [ch, channelSchema(ch)])),
-		patternProperties: { "^w_.+_[lr]$": { type: "number", minimum: 0, maximum: 1, description: rangeOf("w_a_l")[3] }, "_vis$": { type: "number", description: "shown above 0.5" } },
+		patternProperties: { "^w_.+_[lr]$": { type: "number", minimum: 0, maximum: 1, description: rangeOf("w_a_l")[3] }, "_vis$": { type: "number", description: "shown > 0.5" } },
 		additionalProperties: { type: "number", description: "spec.channels, an object's or a check's when" } }),
 	refs: () => ({ type: "string", oneOf: REF_KINDS.map(k => ({ pattern: `^${k}:`, description: typeOf(REF_DOCS, k, "refs") })) }),
 	fix: () => ({ oneOf: [{ const: false }, objectOf(FIX_KEYS, FIX_TYPES, "fix")] }),
@@ -103,6 +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"];
 
 /** A shared shape whose fields are mostly a skill's args (walk, walkTo): its own fields and `...<skill> args`. */
 function shapeLine(d) {
@@ -134,7 +136,8 @@ function essentials() {
 	}
 	// use.skill without the enum: the skills list below names them
 	if (shared.use) shared.use = objectOf(USE_FIELDS, USE_TYPES, "use", ["skill", "f0"]);
-	const skills = SKILL_NAMES.map(n => {
+	// a skill no first spec needs (FIRST_SPEC_SKIP) is in topic skills only
+	const skills = SKILL_NAMES.filter(n => !FIRST_SPEC_SKIP.includes(n)).map(n => {
 		const { args, required = [], needs, frames, adds } = SKILL_INFO[n] ?? bad(`describe: skill ${n} has no entry in skills/info.js`);
 		return { name: n, args: briefType({ type: "object", properties: args, required }, { means: MEANT.skills.includes(n) }), needs, frames, adds };
 	});

package/src/motion3/docs.js

@@ -6,7 +6,7 @@ export const MOTION_ACTION_HELP = {
 		+ "Send spec, or base (an answered specId) + optional patch (JSON Patch); base alone or patch: [] re-measures (new probes). "
 		+ "spec = { schema: \"cozyclay.motion-spec.v1\", fps: 24, frames (number or \"auto\"), ... } (parts: motion.describe); any number may be { range: [lo, hi] } (searched). "
 		+ "probes (at most 16, request level; spec.probes: measured, not stored): { name, distance: [ref, ref] | position: ref, frames, every? }. "
-		+ "Refs need a prefix (joint: prop: anchor: landmark: object:; goals[].moved: a bare id too) and take loose bone names (any case); spec.checks need exact ones. "
+		+ "Refs need a prefix (joint: prop: anchor: landmark: object: person:; goals[].moved: a bare id too) and take loose bone names (any case); spec.checks need exact ones. "
 		+ "repair: { rounds } (1-8, default 4) applies group patches while severity drops. "
 		+ "qa judges only what is broken; speed, acceleration, balance, knee bend are observations unless checks.limits names them. "
 		+ "Answers frames, installed, specId, qa { ok, total, goals, groups (GOAL first, then severity; cause, hint, patch?) }, observations, delta (with base), repair, probes, timeline, fixed, search, skills. output.more: motion.report pages the rest.",