cozyclay 2.0.0 → 2.1.0

package/src/studio-agent-commands.js

@@ -1,12 +1,15 @@
 // Studio composites prepare private domain drafts; the App owns publication,
 // history, gesture fences and semantic revision/telemetry. No UI callbacks here.
-import { Euler, Vector3, PerspectiveCamera } from 'three';
+import { Euler, Vector3, Quaternion, PerspectiveCamera } from 'three';
 import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, isEffectivelyHidden, supportHeightForObject, OBJECT_LIBRARY } from './scene-objects.js';
 import { createCharacterEntry } from './scenes.js';
 import { createShot, shotAtFrame } from './cuts.js';
 import { captureFraming } from './camera-move.js';
 import { createStableItemId } from './stable-items.js';
 import { focalMmToFov, SENSOR_FORMATS } from './shot.js';
+import { coplanarConflicts } from './coplanar-depth.js';
+import { clampWarning } from './receipt-findings.js';
+import { occludersOf, primarySubjects, sideOfAxis } from './studio-geometry-facts.js';
 import { StudioProtocolError, StudioSchemas, STUDIO_PATCH_KINDS, STUDIO_PATCH_DESCRIPTORS, validateStudioSchema, validateStudioIdentity, validateReceipt, freezeStudioData } from './studio-agent-protocol.js';
 
 const DEG = Math.PI / 180, EPS = 1e-8, CHARACTER_SUPPORT_TOLERANCE = 5e-3;
@@ -20,6 +23,39 @@ const entityById = (state, id) => {
   if (!entity) fail('AMBIGUOUS_TARGET', 'Target ID is not present in the admitted scene.');
   return entity;
 };
+/** Resolve a placement reference against the evolving batch draft: an id first,
+ * else the unique name of an object or character already in it. Parts created
+ * earlier in the same batch are in the draft, so they resolve by name. */
+function resolveRef(ref, state, field) {
+  const all = [...state.objects, ...state.characters];
+  if (all.some(e => e.id === ref)) return ref;
+  const named = all.filter(e => normalizedName(e.name ?? e.subject ?? '') === normalizedName(ref));
+  if (named.length === 1) return named[0].id;
+  if (named.length) fail('AMBIGUOUS_TARGET', `${field} '${ref}' matches ${named.length} objects by name (${named.map(e => e.id).join(', ')}); reference one by id.`);
+  fail('AMBIGUOUS_TARGET', `${field} '${ref}' not found; reference an existing id, or a part created EARLIER in this batch by its name (create it before it is referenced).`);
+}
+/** The op with every reference field (relativeTo, onObject, between, support,
+ * facing targets) resolved to an id in the current draft. */
+function resolveOpRefs(op, state, selfId) {
+  const { position: p, facing: f } = op;
+  if (!p && !f) return op;
+  const r = (value, field) => {
+    const resolved = resolveRef(value, state, field);
+    if (resolved === selfId) fail('INVALID_ARGUMENT', `${field} '${value}' is the object being placed; reference a different part.`);
+    return resolved;
+  };
+  const out = { ...op };
+  if (p) out.position = { ...p,
+    ...(p.relativeTo !== undefined ? { relativeTo: r(p.relativeTo, 'relativeTo') } : {}),
+    ...(p.onObject !== undefined ? { onObject: r(p.onObject, 'onObject') } : {}),
+    ...(p.between ? { between: p.between.map(value => r(value, 'between')) } : {}),
+    ...(p.support && typeof p.support === 'object' ? { support: { objectId: r(p.support.objectId, 'support.objectId') } } : {}) };
+  if (f) {
+    const key = ['towardId', 'awayFromId', 'sameAsId'].find(k => f[k] !== undefined);
+    if (key) out.facing = { [key]: r(f[key], `facing.${key}`) };
+  }
+  return out;
+}
 function boxPoints(bounds) {
   if (!bounds || ['x', 'y', 'z'].some(a => !Number.isFinite(bounds.min?.[a]) || !Number.isFinite(bounds.max?.[a]) || bounds.min[a] > bounds.max[a])) fail('TARGET_NOT_READY', 'Evaluated bounds are unavailable.');
   return [bounds.min.x, bounds.max.x].flatMap(x => [bounds.min.y, bounds.max.y].flatMap(y => [bounds.min.z, bounds.max.z].map(z => new Vector3(x, y, z))));
@@ -55,7 +91,7 @@ function support(spec, state) {
   const id = spec.onObject ?? (typeof spec.support === 'object' ? spec.support.objectId : null);
   if (!id) return { y: state.floorY, label: 'floor' };
   const object = entityById(state, id);
-  if (!object.renderer || object.renderer === 'cutout' || ['sphere', 'capsule', 'cone', 'car', 'small-plane'].includes(object.renderer) || object.path || object.attach || Math.abs(object.rotX) > EPS || Math.abs(object.rotZ) > EPS || isEffectivelyHidden(object, state.objects, state.characters)) fail('TARGET_NOT_READY', 'Support must be a stationary solid upright surface.');
+  if (!object.renderer || object.renderer === 'cutout' || ['sphere', 'capsule', 'cone', 'car', 'small-plane', 'empty', 'sculpt'].includes(object.renderer) || object.path || object.attach || Math.abs(object.rotX) > EPS || Math.abs(object.rotZ) > EPS || isEffectivelyHidden(object, state.objects, state.characters)) fail('TARGET_NOT_READY', 'Support must be a stationary solid upright surface.');
   return { y: object.y + supportHeightForObject(object) * object.scaleY, label: `object:${id}`, object };
 }
 function facingYaw(spec, entity, state) {
@@ -106,6 +142,9 @@ function place(entity, op, state, ports) {
     if (Math.hypot(result.x - previous.x, result.z - previous.z, result.rot - previous.rot) < EPS) { converged = true; break; }
   }
   if (!converged) fail('AMBIGUOUS_BASIS', 'Facing and placement cannot satisfy the requested relation.');
+  // A pitched/rolled part rests its lowest corner on the support.
+  if (result.renderer && !result.attach && !result.path && (Math.abs(result.rotX) > EPS || Math.abs(result.rotZ) > EPS))
+    result = patchEntity(result, { y: result.y + surface.y - Math.min(...geometry(result, state, ports).map(p => p.y)) });
   const points = geometry(result, state, ports);
   const supportTolerance = !result.renderer && surface.label === 'floor' ? CHARACTER_SUPPORT_TOLERANCE : EPS;
   if (Math.abs(Math.min(...points.map(p => p.y)) - surface.y) > supportTolerance) fail('TARGET_NOT_READY', 'Tilted or offset bounds cannot rest on the requested support.');
@@ -116,14 +155,90 @@ function place(entity, op, state, ports) {
   }
   return { entity: result, relation: { id: result.id, spec, axis, support: surface.label, baseY: surface.y, ...(axis ? { actualGapM, requestedGapM: spec.gapM, basis: spec.basis } : {}) } };
 }
+// Parent-relative (local) space. Object rows are flat world-space; `parent` only
+// groups. A parent's frame is its stored pivot (base, y = bottom) and Euler XYZ
+// degrees; parent SCALE is deliberately not part of the frame.
+const objectQuat = o => new Quaternion().setFromEuler(new Euler((o.rotX ?? 0) * DEG, (o.rot ?? 0) * DEG, (o.rotZ ?? 0) * DEG, 'XYZ'));
+const wrapDeg = a => ((a + 540) % 360 + 360) % 360 - 180;
+// XYZ Euler angles come in two equal-orientation spellings, (x,y,z) and
+// (x+180, 180-y, z+180). Report the one with the least pitch/roll, so a pure
+// yaw of 135 reads back as yaw 135 rather than (180, 45, 180).
+function eulerDegOf(q) {
+  const e = new Euler().setFromQuaternion(q, 'XYZ'), a = { x: e.x / DEG, y: e.y / DEG, z: e.z / DEG };
+  const b = { x: wrapDeg(a.x + 180), y: wrapDeg(180 - a.y), z: wrapDeg(a.z + 180) };
+  return Math.abs(b.x) + Math.abs(b.z) < Math.abs(a.x) + Math.abs(a.z) - 1e-9 ? b : a;
+}
+const eulerQuat = r => new Quaternion().setFromEuler(new Euler(r.x * DEG, r.y * DEG, r.z * DEG, 'XYZ'));
+/** world = parentPivot + R_parent * local; orientation = R_parent * R_local. */
+export function localToWorld(parent, local) {
+  const p = vector(local.position ?? { x: 0, y: 0, z: 0 }).applyQuaternion(objectQuat(parent)).add(vector(pos(parent)));
+  const q = objectQuat(parent).multiply(eulerQuat(local.rotationDeg ?? { x: 0, y: 0, z: 0 }));
+  return { position: { x: p.x, y: p.y, z: p.z }, rotationDeg: eulerDegOf(q) };
+}
+/** Inverse of localToWorld for an object row under its parent row. */
+export function worldToLocal(parent, object) {
+  const inverse = objectQuat(parent).invert();
+  const p = vector(pos(object)).sub(vector(pos(parent))).applyQuaternion(inverse);
+  return { position: { x: p.x, y: p.y, z: p.z }, rotationDeg: eulerDegOf(inverse.multiply(objectQuat(object))) };
+}
+const tidy = v => Math.round(v * 1e4) / 1e4 + 0;
+/** Compact readback: the object's transform in its parent's frame, or null for
+ * a root, a missing parent or a parent whose stored pose is not its world pose. */
+export function localTransformReadback(object, objects) {
+  const parent = object.parent ? objects.find(o => o.id === object.parent) : null;
+  if (!parent || parent.attach || parent.path || object.attach || object.path) return null;
+  const { position, rotationDeg } = worldToLocal(parent, object);
+  const round = v => ({ x: tidy(v.x), y: tidy(v.y), z: tidy(v.z) });
+  return { position: round(position), rotationDeg: round(rotationDeg) };
+}
+const resolveParentRef = (ref, rows, createdByName) => rows.some(e => e.id === ref) ? ref : createdByName.get(normalizedName(ref));
+/** Rewrites an op given in the parent's local frame into the equivalent world op. */
+function parentFrameOp(op, entity, rows, createdByName) {
+  const create = op.op === 'create';
+  if (create && op.parent === undefined) fail('INVALID_ARGUMENT', 'space "parent" needs `parent` on a create: an existing object id, or the name of an object created earlier in this batch.');
+  if (!create && !entity.parent) fail('INVALID_ARGUMENT', 'space "parent" needs an object that already has a parent; group it under one first, or omit space for world coordinates.');
+  const parentId = create ? resolveParentRef(op.parent, rows, createdByName) : entity.parent;
+  const parent = rows.find(e => e.id === parentId);
+  if (!parent) fail('AMBIGUOUS_TARGET', 'space "parent": the parent is neither an existing object id nor an object created earlier in this batch.');
+  if (parent.attach || parent.path) fail('CAPABILITY_MISSING', 'space "parent": an attached or routed parent has no fixed pose to place against.');
+  if (!op.position && !op.rotationDeg && !op.facing) fail('INVALID_ARGUMENT', 'space "parent" applies to position, rotationDeg or facing; none was given.');
+  if (op.position && !op.position.world) fail('INVALID_ARGUMENT', 'space "parent" takes position {world:{x,y,z}} as local metres from the parent pivot; relativeTo, between and onObject resolve in world space, so omit space for them.');
+  if (op.facing && !('yawDeg' in op.facing)) fail('INVALID_ARGUMENT', 'space "parent" takes facing {yawDeg} only (local yaw); towardId, awayFromId and sameAsId are world-space.');
+  const current = create ? { position: { x: 0, y: 0, z: 0 }, rotationDeg: { x: 0, y: 0, z: 0 } } : worldToLocal(parent, entity);
+  // Local rotation: rotationDeg, else the current local one with its yaw set by
+  // facing; a new child with neither takes the parent's orientation (local zero).
+  const rotation = op.rotationDeg ?? (op.facing ? { ...current.rotationDeg, y: op.facing.yawDeg } : create ? current.rotationDeg : null);
+  const world = localToWorld(parent, { position: op.position ? op.position.world : current.position, rotationDeg: rotation ?? current.rotationDeg });
+  const { space, facing, ...rest } = op;
+  return { ...rest, ...(op.position ? { position: { world: world.position } } : {}), ...(rotation ? { rotationDeg: world.rotationDeg } : {}) };
+}
+function groupRootOf(id, objects) {
+  const seen = new Set();
+  let current = objects.find(o => o.id === id);
+  while (current?.parent && !seen.has(current.id)) {
+    seen.add(current.id);
+    current = objects.find(o => o.id === current.parent) ?? current;
+  }
+  return current?.id ?? id;
+}
 function overlapsFor(entity, state, ports) {
   const own = aabb(geometry(entity, state, ports));
-  return [...state.objects, ...state.characters].filter(e => e.id !== entity.id && !isEffectivelyHidden(e, state.objects, state.characters)).map(other => ({ id: other.id, bounds: aabb(geometry(other, state, ports)) })).map(other => ({ ...other, depth: overlap(own, other.bounds) })).filter(o => o.depth > EPS);
+  // Parts of one grouped object are built to touch; only other bodies count.
+  const root = groupRootOf(entity.id, state.objects);
+  return [...state.objects, ...state.characters].filter(e => e.id !== entity.id && !isEffectivelyHidden(e, state.objects, state.characters)
+    && groupRootOf(e.id, state.objects) !== root).map(other => ({ id: other.id, bounds: aabb(geometry(other, state, ports)) })).map(other => ({ ...other, of: entity.id, depth: overlap(own, other.bounds) })).filter(o => o.depth > EPS);
 }
 function overlapsOf(ids, state, ports) {
   const entities = [...state.objects, ...state.characters];
   return ids.flatMap(id => { const e = entities.find(row => row.id === id); return e ? overlapsFor(e, state, ports) : []; });
 }
+/** World AABB of one entity as {min,max}, or null when its evaluated bounds are unavailable (a prop whose renderer is not mounted). */
+export function entityWorldBounds(entity, state, ports) {
+  try {
+    const box = aabb(geometry(entity, state, ports)), round = v => Number(v.toFixed(4));
+    return { min: Object.fromEntries(['x', 'y', 'z'].map(a => [a, round(box[a].min)])), max: Object.fromEntries(['x', 'y', 'z'].map(a => [a, round(box[a].max)])) };
+  } catch { return null; }
+}
 const overlapEvidence = overlaps => ({ coverage: 'same-frame-world-AABB-proxies', overlapIds: [...new Set(overlaps.map(o => o.id))].slice(0, 100), maximumFootprintOverlapM: Math.max(0, ...overlaps.map(o => o.depth)) });
 /** Placement evidence for entity ids in the given scene: the same-frame AABB
  * overlap an arrangement receipt reports for the entities it moved. */
@@ -152,32 +267,49 @@ function transformPatch(op, isObject) {
 export function arrangement(command, before, ports) {
   const isObject = command.name === 'arrange_objects', key = isObject ? 'objects' : 'characters';
   let rows = before[key];
-  const relations = [], warnings = [];
-  for (const op of command.args.ops) {
-    const id = op.id ?? op.characterId;
+  const relations = [], warnings = [], clamps = [], createdByName = new Map();
+  // References resolve against the evolving draft (`rows`), in op order.
+  const draft = () => ({ ...before, [key]: rows });
+  for (const rawOp of command.args.ops) {
+    const id = rawOp.id ?? rawOp.characterId;
     let entity = id ? rows.find(e => e.id === id) : null;
-    if (id && !entity) fail('AMBIGUOUS_TARGET', 'Edited target is not present in the draft.');
+    if (id && !entity) fail('AMBIGUOUS_TARGET', `Edited target '${id}' is not present in the draft; ids of parts created in this batch are not known yet, so use the part name in position references and create it before it is referenced.`);
+    let op = resolveOpRefs(rawOp, draft(), id);
     if (op.op === 'create') {
       if (op.name && rows.some(e => normalizedName(e.name ?? e.subject) === normalizedName(op.name))) fail('DUPLICATE_NAME', 'Create name already exists in the domain.');
+      let parentId;
+      if (isObject && op.parent !== undefined) {
+        parentId = rows.some(e => e.id === op.parent) ? op.parent : createdByName.get(normalizedName(op.parent));
+        if (!parentId) fail('AMBIGUOUS_TARGET', `Create parent '${op.parent}' is neither an existing object id nor an object created earlier in this batch; create the parent first.`);
+      }
       entity = isObject ? createSceneObject(op.source.kind, rows) : createCharacterEntry({ id: createStableItemId('character'), subject: normalizedName(op.name) });
       if (!entity) fail('INVALID_ARGUMENT', 'Unsupported object library kind.');
       rows = [...rows, entity];
+      // Parent before placing, so avoidance and overlap checks see one body.
+      if (parentId) { rows = setSceneObjectParent(rows, entity.id, parentId); entity = rows.find(e => e.id === entity.id); }
     }
     if (['create', 'update'].includes(op.op)) {
       if (entity.attach) fail('CAPABILITY_MISSING', 'Attached transforms require a world-preserving attachment adapter.');
+      if (op.space === 'parent') op = parentFrameOp(op, entity, rows, createdByName);
       entity = patchEntity(entity, transformPatch(op, isObject));
-      const placed = place(entity, op, before, ports);
+      const placed = place(entity, op, draft(), ports);
       entity = placed.entity;
-      if (command.args.collisionPolicy === 'avoid') {
-        entity = avoid(entity, placed.relation, { ...before, [key]: rows }, ports);
-        entity = patchEntity(entity, { rot: facingYaw(op.facing, entity, before) });
-        const reference = entityById(before, op.position.relativeTo);
-        placed.relation.actualGapM = interval(geometry(entity, before, ports), placed.relation.axis).min - interval(geometry(reference, before, ports), placed.relation.axis).max;
+      // What was asked against what the domain kept: scale and position limits move values silently.
+      const asked = isObject ? { ...(op.position?.world ?? {}), ...(op.scale ? { scaleX: op.scale.x, scaleY: op.scale.y, scaleZ: op.scale.z } : {}) }
+        : { ...(op.position?.world ?? {}), ...(op.scale === undefined ? {} : { scale: op.scale }) };
+      const clamp = clampWarning(entity.id, Object.fromEntries(Object.entries(asked).filter(([k]) => ['x', 'y', 'z', 'scale', 'scaleX', 'scaleY', 'scaleZ'].includes(k))), entity);
+      if (clamp) clamps.push(clamp);
+      if (command.args.collisionPolicy === 'avoid' && placed.relation?.axis) {
+        entity = avoid(entity, placed.relation, draft(), ports);
+        entity = patchEntity(entity, { rot: facingYaw(op.facing, entity, draft()) });
+        const reference = entityById(draft(), op.position.relativeTo);
+        placed.relation.actualGapM = interval(geometry(entity, draft(), ports), placed.relation.axis).min - interval(geometry(reference, draft(), ports), placed.relation.axis).max;
         if (placed.relation.actualGapM < op.position.gapM - EPS) fail('VERIFICATION_FAILED', 'Avoidance cannot preserve the requested facing and minimum clearance.');
       }
       const patch = Object.fromEntries(Object.entries(entity).filter(([k, v]) => !equal(v, rows.find(e => e.id === entity.id)[k])));
       rows = isObject ? updateSceneObject(rows, entity.id, patch) : rows.map(e => e.id === entity.id ? entity : e);
       if (placed.relation) relations.push(placed.relation);
+      if (op.op === 'create' && op.name) createdByName.set(normalizedName(op.name), entity.id);
     } else if (op.op === 'remove') {
       if (!isObject && (rows.length <= 1 || entity.id === before.activeCharacterId)) fail('INVALID_ARGUMENT', 'Cannot remove the final or active character without a separate selection operation.');
       rows = isObject ? removeSceneObject(rows, id) : rows.filter(e => e.id !== id);
@@ -205,7 +337,24 @@ export function arrangement(command, before, ports) {
     relation.actualGapM = actualGapM;
   }
   if (command.args.collisionPolicy === 'avoid' && overlaps.length) fail('VERIFICATION_FAILED', 'The final batch is still blocked after its outward adjustments.');
-  for (const item of overlaps.slice(0, 10)) warnings.push({ code: 'FOOTPRINT_OVERLAP', id: item.id });
+  // Every finding the receipt carries: a value moved to a limit first, then what the final scene shows wrong.
+  const nameOf = id => { const e = [...after.objects, ...after.characters].find(row => row.id === id); return e?.name ?? e?.subject ?? id; };
+  warnings.push(...clamps.slice(0, 3));
+  for (const item of overlaps.slice(0, 5)) warnings.push({ code: 'FOOTPRINT_OVERLAP', id: item.id, message: [...`${nameOf(item.of)} overlaps ${nameOf(item.id)} by ${Number(item.depth.toFixed(2))} m`].slice(0, 120).join('') });
+  if (overlaps.length > 5) warnings.push({ code: 'FOOTPRINT_OVERLAP', count: overlaps.length - 5, message: `${overlaps.length - 5} more footprint overlaps omitted` });
+  if (isObject) {
+    // Parts of one assembly touch on purpose, but faces sharing one plane flicker as the camera moves.
+    const touched = new Set(affectedIds), groups = new Map();
+    for (const row of rows) if (touched.has(row.id)) { const root = groupRootOf(row.id, rows); if (root !== row.id || rows.some(o => o.parent === row.id)) groups.set(root, null); }
+    const coplanar = [];
+    for (const root of groups.keys()) for (const pair of coplanarConflicts(rows.filter(row => groupRootOf(row.id, rows) === root))) {
+      if (!touched.has(pair.a) && !touched.has(pair.b)) continue;
+      const planes = pair.planes.map(plane => `${plane.face} coincide at ${plane.axis ? `${plane.axis}=${plane.at}` : `offset ${plane.at}`}`).join(', ');
+      coplanar.push({ code: 'COPLANAR_FACES', id: pair.b, message: [...`${nameOf(pair.a)} and ${nameOf(pair.b)} ${planes}`].slice(0, 120).join('') });
+    }
+    warnings.push(...coplanar.slice(0, 2));
+    if (coplanar.length > 2) warnings.push({ code: 'COPLANAR_FACES', count: coplanar.length - 2, message: `${coplanar.length - 2} more coplanar face pairs omitted` });
+  }
   if (relations.some(r => r.adjustmentM)) warnings.push({ code: 'OUTWARD_ADJUSTMENT', count: relations.filter(r => r.adjustmentM).length });
   const relation = relations.length === 1 ? relations[0] : null;
   return { domain: isObject ? 'objects' : 'cast', draft: equal(rows, before[key]) ? before[key] : rows, affectedIds,
@@ -232,12 +381,23 @@ function projectSubject(points, camera, fov, aspectRatio) {
   const derivedSize = [['extreme close-up', 2.8], ['close-up', 1.6], ['medium close-up', 1.15], ['medium shot', 0.8], ['medium-wide shot', 0.52], ['wide shot', 0.3], ['extreme wide shot', 0]].find(([, threshold]) => screenFraction >= threshold)[0];
   return { screenBounds, checks: { coverage: 'same-frame-subject-bounds-projection', screenFraction, derivedSize, behindCamera, clipped: behindCamera || screen.some(p => Math.abs(p.x) > 1 || Math.abs(p.y) > 1 || p.z < -1 || p.z > 1) } };
 }
+const boundsOf = points => { const box = aabb(points); return { min: { x: box.x.min, y: box.y.min, z: box.z.min }, max: { x: box.x.max, y: box.y.max, z: box.z.max } }; };
+/** What stands in the way of the camera and where it stands: occluded when a prop
+ * crosses the sight line to any subject, and the camera's side of the line between
+ * the two leading characters (the subjects, else the ones nearest the camera). */
+function sightChecks(subjects, boxes, cameraPosition, state, ports) {
+  const occluders = subjects.flatMap((subject, index) => occludersOf(subject, cameraPosition, state, ports, boundsOf(boxes[index])));
+  const pair = primarySubjects(subjects.map(subject => subject.id), cameraPosition, state);
+  const cameraSide = pair.length === 2 ? sideOfAxis(pair[0], pair[1], cameraPosition) : null;
+  return { occluders, checks: { occluded: occluders.length > 0, ...(cameraSide ? { cameraSide } : {}) } };
+}
 /** Framing evidence for entity ids through the current shot camera at the
- * current frame: the same subject-bounds projection frame_shot reports. */
+ * current frame: the same subject-bounds projection and sight line frame_shot reports. */
 export function framingChecks(ids, state, ports) {
   if (!state.camera || !SENSOR_FORMATS[state.filmback?.sensorId] || !(state.filmback.aspectRatio > 0)) fail('TARGET_NOT_READY', 'The shot camera and filmback must be available.');
-  const points = ids.flatMap(id => geometry(entityById(state, id), state, ports));
-  return projectSubject(points, state.camera, focalMmToFov(state.camera.focalMm, state.filmback.sensorId, state.filmback.aspectRatio), state.filmback.aspectRatio).checks;
+  const subjects = ids.map(id => entityById(state, id)), boxes = subjects.map(entity => geometry(entity, state, ports));
+  const projected = projectSubject(boxes.flat(), state.camera, focalMmToFov(state.camera.focalMm, state.filmback.sensorId, state.filmback.aspectRatio), state.filmback.aspectRatio).checks;
+  return { ...projected, ...sightChecks(subjects, boxes, state.camera.position, state, ports).checks };
 }
 export function frameDraft(command, state, ports) {
   if (state.frameCount <= 0) fail('TARGET_NOT_READY', 'A nonempty timeline is required.');
@@ -249,7 +409,9 @@ export function frameDraft(command, state, ports) {
   const created = !shot && !state.shotDocument.shots.length && !command.args.shotId;
   if (created) shot = createShot('Shot 1', 0, state.frameCount - 1);
   if (!shot) fail('AMBIGUOUS_TARGET', 'No shot owns this frame; select an existing shot explicitly.');
-  const frame = command.args.keyAtFrame ?? state.frame;
+  const still = shot.kind === 'still';
+  const existingKey = shot.cameraKeys[0];
+  const frame = still ? (existingKey?.frame ?? shot.startFrame) : command.args.keyAtFrame ?? state.frame;
   if (frame < shot.startFrame || frame > shot.endFrame || shot.endFrame >= state.frameCount) fail('INVALID_RANGE', 'Framing/key frame must be inside the shot range.');
   const intent = command.args.framing.intent;
   let camera = command.args.framing.exact;
@@ -270,18 +432,19 @@ export function frameDraft(command, state, ports) {
   const framing = captureFraming({ pos: camera.position, yaw: Math.atan2(-direction.x, -direction.z), pitch: Math.atan2(direction.y, Math.hypot(direction.x, direction.z)), fovDeg: fov / DEG });
   let keyId;
   let keys = shot.cameraKeys;
-  if (command.args.keyAtFrame !== undefined) {
-    keyId = keys.find(k => k.frame === frame)?.id ?? createStableItemId('camera-key');
-    keys = [...keys.filter(k => k.frame !== frame), { id: keyId, frame, framing }].sort((a, b) => a.frame - b.frame);
+  if (still || command.args.keyAtFrame !== undefined) {
+    keyId = (still ? existingKey?.id : keys.find(k => k.frame === frame)?.id) ?? createStableItemId('camera-key');
+    keys = still ? [{ id: keyId, frame, framing }] : [...keys.filter(k => k.frame !== frame), { id: keyId, frame, framing }].sort((a, b) => a.frame - b.frame);
   }
   const nextShot = { ...shot, cameraKeys: keys, camera: { ...shot.camera, mode: 'keys' } };
   const shots = created ? [nextShot] : state.shotDocument.shots.map(s => s.id === shot.id ? nextShot : s);
-  const { screenBounds, checks } = projectSubject(points, camera, fov, state.filmback.aspectRatio), derivedSize = checks.derivedSize;
+  const { screenBounds, checks: projected } = projectSubject(points, camera, fov, state.filmback.aspectRatio), derivedSize = projected.derivedSize;
+  const sight = sightChecks([subject], [points], camera.position, state, ports), checks = { ...projected, ...sight.checks };
   const resolvedCamera = { ...camera, sensorId: state.filmback.sensorId, slate: derivedSize };
   const draft = { shotDocument: { ...state.shotDocument, shots }, camera: resolvedCamera, manual: true };
   return { domain: 'shot', draft, affectedIds: [shot.id, ...(keyId ? [keyId] : [])],
     checks,
-    warnings: [{ code: 'OCCLUSION_UNMEASURED' }], details: { created, shotId: shot.id, keyId, frame, framing, screenBounds, subjectIds: [subject.id] } };
+    warnings: sight.occluders.slice(0, 5).map(item => ({ code: 'OCCLUDED', id: item.byObjectId })), details: { created, shotId: shot.id, keyId, frame, framing, screenBounds, subjectIds: [subject.id] } };
 }
 
 /** Local journal. Unsettled/protected records are never evicted. Call prune on

package/src/studio-agent-context.js

@@ -10,10 +10,6 @@ export function encodeStudioContext(context) {
 	if (utf8ByteLength(encoded) > STUDIO_CONTEXT_MAX_BYTES) fail("CONTEXT_TOO_LARGE", `Escaped Studio context exceeds ${STUDIO_CONTEXT_MAX_BYTES / 1024} KiB.`);
 	return encoded;
 }
-export function buildStudioHistoryItem(context, userText) {
-	if (typeof userText !== "string") fail("INVALID_REQUEST", "User text must be a string.");
-	return { role: "user", content: [{ type: "input_text", text: `<studio-context>\n${encodeStudioContext(context)}\n</studio-context>` }, { type: "input_text", text: userText }] };
-}
 export function studioCacheKey(context, projectionKind = "scene") {
 	const c = validateStudioContext(context);
 	if (typeof projectionKind !== "string" || !projectionKind || projectionKind.length > 120) fail("INVALID_ARGUMENT", "Projection kind must be a bounded string.");
@@ -38,8 +34,9 @@ export function validateStudioCursor(cursor, context) {
 /** The compact command index the turn carries: id and label for every
  * registered command, plus the declared generation and hub timeout. The
  * description and input schema stay out; the agent reads them on request. */
-export function studioActionIndex(actions) {
-	return actions.map(({ id, label, generation, timeoutMs }) => ({ id, ...(label ? { label: [...label].slice(0, 120).join("") } : {}),
+export function studioActionIndex(actions, { previsMode } = {}) {
+	const available = actions.filter(action => !action.agentHidden && (previsMode !== "storyboard" || (action.generation !== "motion" && action.domain !== "motion")));
+	return available.map(({ id, label, generation, timeoutMs }) => ({ id, ...(label ? { label: [...label].slice(0, 120).join("") } : {}),
 		...(generation ? { generation } : {}), ...(timeoutMs === undefined ? {} : { timeoutMs }) }));
 }
 
@@ -49,7 +46,7 @@ export function studioActionIndex(actions) {
 // truncation so forbidden data cannot hide in an omitted row.
 export function buildStudioContext({ actions, ...input }) {
 	const c = structuredClone(input);
-	if (actions) c.actionIndex = studioActionIndex(actions);
+	if (actions) c.actionIndex = studioActionIndex(actions, { previsMode: c.scene?.previsMode });
 	const boundDisplay = value => {
 		if (!value || typeof value !== "object") return;
 		for (const [key, child] of Object.entries(value)) {
@@ -117,13 +114,18 @@ const object = fields => ({ type: "object", properties: fields, required: Object
 const array = (items, maxItems = 10000, minItems = 0) => ({ type: "array", items, minItems, maxItems });
 const vec = StudioSchemas.Vec3;
 const timing = object({ cuts: array(object({ t: nonnegative, d: nonnegative }), 64), envelopes: array(array(nonnegative, 24, 24), 65, 1) });
-const path = object({ points: array(vec, 64, 2), speed: nonnegative, faceTravel: bool, loop: bool, extend: bool, timing: nullable(timing) });
+// `marks` (the editor's grab dots, arc fractions) is optional: it is UI state on
+// the route, and older fixtures and agent-written routes carry none.
+const pathFields = { points: array(vec, 64, 2), speed: nonnegative, faceTravel: bool, loop: bool, extend: bool, timing: nullable(timing) };
+// A mark is an arc fraction, or { t, bank, pitch } (degrees) when it carries a lean.
+const routeMark = { oneOf: [nonnegative, { type: "object", properties: { t: nonnegative, bank: num, pitch: num }, required: ["t"], additionalProperties: false }] };
+const path = { ...object({ ...pathFields, marks: array(routeMark, 6) }), required: Object.keys(pathFields) };
 const physicalObject = object({ id, renderer: id, position: vec, rotationDeg: vec, scale: object({ x: positive, y: positive, z: positive }),
 	footprint: object({ width: nonnegative, depth: nonnegative }), height: nonnegative, supportY: num, parentId: nullable(id), attachment: nullable(object({ characterId: id, bone: nullable(id) })), path: nullable(path), hidden: bool });
 const physicalCharacter = object({ id, incarnation: id, modelId: nullable(id), rigId: nullable(id), rigReady: bool, hidden: bool, position: vec, yawDeg: num, scale: positive,
 	takeId: nullable(id), sessionMotionId: nullable(id), motionRevision: int, calibrationRevision: int, ikRevision: int,
 	waypoints: array(object({ frame: int, position: vec }), 10000) });
-export const PHYSICS_FINGERPRINT_SCHEMA = freezeStudioData(object({ objects: array(physicalObject), characters: array(physicalCharacter), floor: object({ model: id, y: num }), frameCount: int }));
+const PHYSICS_FINGERPRINT_SCHEMA = freezeStudioData(object({ objects: array(physicalObject), characters: array(physicalCharacter), floor: object({ model: id, y: num }), frameCount: int }));
 export function physicsFingerprintInput(input) {
 	// Ignore explicitly nonphysical source fields. Nested physical shapes remain
 	// closed and validated, including path timing and every inactive actor stamp.

package/src/studio-agent-motion.js

@@ -14,6 +14,7 @@ import { createGroundSampler } from './ardy/ground.js';
 import { OBJECT_LIBRARY } from './scene-objects.js';
 import { objectTransformAt } from './object-path.js';
 import { sampleAt } from './sample-at.js';
+import { isProxyFigure } from './scenes.js';
 
 const PROFILE = 'studio-motion-v1', BLEND = 6;
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
@@ -76,7 +77,7 @@ const copyEnvironment = env => ({ ...env, host: structuredClone(env.host), floor
  * refused rig leaves every evaluator made before it disposable. */
 function stageCast(env, characterId, cast) {
   for (const member of env.cast) {
-    if (member.character.id === characterId || member.character.hidden) continue;
+    if (member.character.id === characterId || member.character.hidden || isProxyFigure(member.character)) continue;
     // Unsupported bystanders remain explicit missing coverage, never vanish
     // into characterBlockers' otherwise legitimate best-effort skip path.
     const entry = { character: structuredClone(member.character), motion: member.motion ? structuredClone(member.motion) : null, layer: copyLayer(member.ikState), evaluator: null };

package/src/studio-agent-protocol.js

@@ -1,5 +1,8 @@
 // Shared by the browser and sidecar. No Node, React, renderer or provider imports.
 import { STUDIO_ELEMENTS, isSettableElement } from "./studio-elements.js";
+// Mirrors PREVIS_MODES (project.js) and POSTURES (scenes.js). Neither is imported:
+// both pull in three.js, which the agent sidecar must not load. The protocol test pins the lists to their owners.
+const PREVIS_MODES = ["storyboard", "animation"], POSTURES = ["stand", "sit", "lie"];
 
 export const STUDIO_PROTOCOL_VERSION = "studio-agent-v1";
 // Sized for the compact index of up to 400 entities (~100 bytes each) beside
@@ -76,6 +79,8 @@ const positiveVec3 = object({ x: positive, y: positive, z: positive });
 const range = { ...object({ startFrame: integer(), endFrameExclusive: integer(1) }), "x-studio-range": true };
 const ids = (max = 100, min = 1) => array(id, max, min, true);
 const name = text(120);
+// A placement reference: an id, or the name of a part created earlier in the same ops list.
+const ref = { ...text(120), description: "Object id, or the name of a part created EARLIER in this ops list (create it first)." };
 const identityFields = { workspaceId: id, documentEpoch: id, sceneId: id, sceneEpoch: id };
 const identity = object(identityFields);
 const host = object({ surface: literal("studio"), ...identityFields, workspaceHandle: nullable(id) });
@@ -84,18 +89,22 @@ const selection = nullable(object({ kind: choices(STUDIO_VARIANTS.selectionKinds
 const view = object({ mode: choices(STUDIO_VARIANTS.modes), frame: integer(), playing: bool, lookThrough: bool, grid: bool, autoColor: bool });
 const position = union(
 	object({ world: vec3 }),
-	object({ relativeTo: id, basis: choices(STUDIO_VARIANTS.positionBases), side: choices(STUDIO_VARIANTS.positionSides), gapM: number(0), support: union(literal("floor"), object({ objectId: id })) }),
-	object({ between: ids(2, 2), fraction: number(0, 1), support: literal("floor") }),
-	object({ onObject: id }, { offsetXZ: object({ x: number(), z: number() }) }),
+	object({ relativeTo: ref, basis: choices(STUDIO_VARIANTS.positionBases), side: choices(STUDIO_VARIANTS.positionSides), gapM: number(0), support: union(literal("floor"), object({ objectId: ref })) }),
+	object({ between: array(ref, 2, 2, true), fraction: number(0, 1), support: literal("floor") }),
+	object({ onObject: ref }, { offsetXZ: object({ x: number(), z: number() }) }),
 );
-const facing = union(object({ yawDeg: number() }), object({ towardId: id }), object({ sameAsId: id }), object({ awayFromId: id }));
+const facing = union(object({ yawDeg: number() }), object({ towardId: ref }), object({ sameAsId: ref }), object({ awayFromId: ref }));
 const framing = union(
 	object({ intent: object({ size: choices(STUDIO_VARIANTS.framingSizes), view: choices(STUDIO_VARIANTS.framingViews), level: choices(STUDIO_VARIANTS.framingLevels), side: choices(STUDIO_VARIANTS.framingSides) }, { focalMm: positive }) }),
 	object({ exact: object({ position: vec3, lookAt: vec3, focalMm: positive }) }),
 );
+const localSpace = { ...choices(["parent"]), description: "\"parent\" reads position.world, rotationDeg and facing.yawDeg in the parent's local frame (its pivot and rotation, not its scale); omit for world space." };
 const objectOp = union(
-	object({ op: literal("create"), source: object({ kind: id }), position }, { name, facing, scale: positiveVec3 }),
-	object({ op: literal("update"), id }, { position, facing, rotationDeg: vec3, scale: positiveVec3, color: text(32), name, hidden: bool }),
+	object({ op: literal("create"), source: object({ kind: id }), position }, { name, facing, scale: positiveVec3,
+		rotationDeg: { ...vec3, description: "Euler XYZ degrees (x pitch, y yaw, z roll), as in update. Exclusive with facing. A pitched/rolled part rests its lowest corner on its support." },
+		parent: { ...name, description: "Group this new object under a parent: an existing object id, or the name of an object created earlier in this same ops list. Moving the parent then moves it too." },
+		space: localSpace }),
+	object({ op: literal("update"), id }, { position, facing, rotationDeg: vec3, scale: positiveVec3, color: text(32), name, hidden: bool, space: localSpace }),
 	object({ op: literal("remove"), id }),
 	object({ op: literal("group"), parentId: id, childIds: ids() }),
 	object({ op: literal("ungroup"), childIds: ids() }),
@@ -105,7 +114,8 @@ const characterOp = union(
 	object({ op: literal("update"), characterId: id }, { position, facing, scale: positive, name, hidden: bool }),
 	object({ op: literal("remove"), characterId: id }),
 );
-const generateSource = object({ kind: literal("generate"), beats: array(object({ text: text(2000) }, { seconds: number(0.5, 60) }), 8, 1) }, { durationSeconds: number(2, 60), seed: integer(-2147483648, 2147483647) });
+export const BEAT_TEXT_MAX = 500;
+const generateSource = object({ kind: literal("generate"), beats: array(object({ text: { ...text(BEAT_TEXT_MAX), description: 'An English description of the body movement starting with "A person". The editor refuses prompts over 500 characters.' } }, { seconds: number(0.5, 60) }), 8, 1) }, { durationSeconds: number(2, 60), seed: integer(-2147483648, 2147483647) });
 const source = union(generateSource, object({ kind: literal("reuse"), artifactId: id }));
 
 /* ----------------------------------------------- element patches ----
@@ -118,7 +128,11 @@ const source = union(generateSource, object({ kind: literal("reuse"), artifactId
 const dataImage = { ...text(2 * 1024 * 1024), pattern: "^data:image/[A-Za-z0-9.+-]+[;,]" };
 const promptBlock = object({ startFrame: integer(), endFrame: integer(1), text: text(2000) }, { id });
 const cameraKey = object({ frame: integer(), framing: object({ pos: vec3, yaw: number(), pitch: number(), fovDeg: number(1, 179) }) }, { id });
-const objectRoute = nullable(object({ points: array(vec3, 64, 2) }, { speed: number(0, 50), faceTravel: bool, loop: bool, extend: bool }));
+// A mark is an arc fraction, or { t, bank, pitch } when the object should lean
+// there (degrees, +-90). The route normaliser (src/object-path.js) owns the
+// rules; this only carries the shape through untouched.
+const routeMark = union(number(0, 1), object({ t: number(0, 1) }, { bank: number(-90, 90), pitch: number(-90, 90) }));
+const objectRoute = nullable(object({ points: array(vec3, 64, 2) }, { speed: number(0, 50), faceTravel: bool, loop: bool, extend: bool, marks: array(routeMark, 6) }));
 const PATCH_VALUE_SCHEMAS = {
 	"character.pose": nullable(id), "character.identityImage": nullable(dataImage), "character.promptBlocks": array(promptBlock, 64),
 	"object.parent": nullable(id), "object.path": objectRoute, "stage.environmentImage": nullable(dataImage),
@@ -186,12 +200,12 @@ const patchOp = union(
 const toolSchemas = {
 	inspect_studio: object({ scope: choices(STUDIO_VARIANTS.inspectionScopes) }, { ids: ids(32), select: ids(32), query: name, cursor: text(512), limit: { ...integer(1, 32), default: 12 } }),
 	operate_studio: object({}, { selection, shotId: id, frame: integer(), playing: bool, mode: choices(STUDIO_VARIANTS.modes), view: object({}, { lookThrough: bool, grid: bool, autoColor: bool }) }),
-	arrange_objects: object({ ops: array(objectOp, 100, 1) }, { collisionPolicy: { ...choices(STUDIO_VARIANTS.collisionPolicies), default: "report" } }),
+	arrange_objects: object({ ops: { ...array(objectOp, 100, 1), description: "Applied in order, as one undo step. Each op sees the parts created by earlier ops, so build an assembly in one call: create the main part, then place the rest with position.onObject / relativeTo(+side,gapM) / between naming earlier parts (e.g. relativeTo \"Hood\"). Reference parts created in this call by name, never by id." } }, { collisionPolicy: { ...choices(STUDIO_VARIANTS.collisionPolicies), default: "report" } }),
 	arrange_characters: object({ ops: array(characterOp, 8, 1) }),
 	patch_elements: object({ ops: array(patchOp, 32, 1) }),
-	frame_shot: object({ subjectIds: ids(1), framing }, { shotId: id, keyAtFrame: integer() }),
+	frame_shot: object({ subjectIds: ids(1), framing }, { shotId: id, caption: { type: "string", maxLength: 500 }, keyAtFrame: integer() }),
 	generate_motion: object({ characterId: id, source }, { repair: { ...choices(["bounded", "none"]), default: "bounded" } }),
-	verify_result: object({ checks: array(choices(["placement", "framing", "motion"]), 3, 1, true) }, { receiptId: id, targets: ids(), range: union(literal("whole_clip"), range), visual: { ...choices(["none", "frame", "contact_sheet"]), default: "none" } }),
+	verify_result: object({ checks: array(choices(["placement", "framing", "motion"]), 3, 1, true) }, { receiptId: id, targets: ids(), range: union(literal("whole_clip"), range), visual: { ...choices(["none", "frame", "contact_sheet", "plan"]), default: "none" } }),
 	undo_edit: object({ receiptId: id }),
 	run_action: object({ action: id }, { args: openObject, confirmationToken: id }),
 };
@@ -203,9 +217,13 @@ export const STUDIO_CATALOGUE = freezeStudioData(STUDIO_TOOLS.map(name => ({ nam
 const bounds = object({ min: vec3, max: vec3 });
 const entity = object({ id, kind: choices(["object", "character", "rig"]), token: id }, {
 	name, detailsOmitted: bool, position: vec3, yawDeg: number(), rotationDeg: vec3, scale: union(positive, positiveVec3), bounds: nullable(bounds),
-	libraryKind: id, renderer: id, color: nullable(text(32)), tint: nullable(text(32)), modelId: nullable(text(120)), assetId: id, parentId: nullable(id), attachment: nullable(object({ characterId: id, bone: nullable(id) })), pathPointCount: integer(0, 64),
+	libraryKind: id, renderer: id, color: nullable(text(32)), tint: nullable(text(32)), modelId: nullable(text(120)), assetId: id, parentId: nullable(id), attachment: nullable(object({ characterId: id, bone: nullable(id) })), pathPointCount: integer(0, 64), pathMarks: array(union(number(0, 1), object({ t: number(0, 1) }, { bank: number(-90, 90), pitch: number(-90, 90) })), 6),
+	local: object({ position: vec3, rotationDeg: vec3 }),
 	motion: object({ takeId: nullable(id), frames: integer(), ikKeyCount: integer(), promptBlockCount: integer() }, { poseId: nullable(id), keyIds: ids(8, 0) }),
 	capabilities: object({ rigReady: bool, ik: bool, measuredFeet: bool }),
+	// `kind` above already names the entity class ("character"); a character's own
+	// kind is `characterKind`: a rigged model, or a rig-free capsule figure.
+	characterKind: choices(["rig", "proxy"]), posture: choices(POSTURES),
 });
 // One compact row per entity, so the model sees the whole scene even when
 // only 24 rows carry full detail.
@@ -214,8 +232,8 @@ const indexRow = object({ id, kind: choices(["object", "character", "rig"]) }, {
 // Its schema is on request (inspect_studio scope "actions" with ids); the
 // declared generation and hub timeout ride along for the sidecar's gate.
 const actionIndexRow = object({ id }, { label: name, generation: literal("motion"), timeoutMs: integer(1, 300_000) });
-const shotSummary = object({ id, name, range, keyCount: integer() }, { subjectIds: ids(24, 0) });
-const currentShot = object({ id, name, range, mode: choices(STUDIO_VARIANTS.shotModes) }, { subjectIds: ids(24, 0) });
+const shotSummary = object({ id, name, range, keyCount: integer() }, { subjectIds: ids(24, 0), kind: choices(["clip", "still"]), caption: text(500) });
+const currentShot = object({ id, name, range, mode: choices(STUDIO_VARIANTS.shotModes) }, { subjectIds: ids(24, 0), kind: choices(["clip", "still"]), caption: text(500) });
 const camera = object({ position: vec3, lookAt: vec3, focalMm: positive, sensorId: id, slate: name });
 // What the agent can place: a catalogue kind, or an asset imported into the scene.
 const assetTypes = choices(["primitive", "set-piece", "image", "mesh"]);
@@ -224,12 +242,12 @@ const jobSummary = object({ id, characterId: id, state: choices(STUDIO_VARIANTS.
 const contextSchema = object({
 	schema: literal("studio-context-v1"), host, revision,
 	units: object({ distance: literal("m"), angle: literal("deg"), up: literal("+Y"), yawZero: literal("+Z"), yawPositiveToward: literal("+X"), pivot: literal("base"), fps: literal(24), rangeEnd: literal("exclusive") }),
-	scene: object({ name, aspect: text(40), floorY: number(), frameCount: integer(), objectCount: integer(), characterCount: integer() }),
+	scene: object({ name, aspect: text(40), floorY: number(), frameCount: integer(), objectCount: integer(), characterCount: integer() }, { previsMode: choices(PREVIS_MODES) }),
 	selection, activeCharacterId: nullable(id), view, shot: nullable(currentShot), camera: nullable(camera),
 	entities: array(entity, 24), entityPage: object({ returned: integer(0, 24), total: integer(), truncated: bool, nextCursor: nullable(text(512)) }),
 	shots: array(shotSummary, 8), shotsTruncated: bool, assets: array(assetSummary, STUDIO_CONTEXT_LIMITS.assets),
 	recentReceipts: array(object({ id, summary: name, canUndoDirect: bool }), 3), jobs: array(jobSummary, 8),
-	capabilities: object({ profile: literal("studio-slice-1"), tools: array(choices(STUDIO_TOOLS), STUDIO_TOOLS.length, 0, true) }, { rigReady: bool, cameraReady: bool, bridgeReady: bool }),
+	capabilities: object({ profile: literal("studio-slice-1"), tools: array(choices(STUDIO_TOOLS), STUDIO_TOOLS.length, 0, true) }, { rigReady: bool, cameraReady: bool, bridgeReady: bool, storyboard: bool }),
 }, { entityIndex: array(indexRow, STUDIO_CONTEXT_LIMITS.entityIndex), actionIndex: array(actionIndexRow, 512) });
 const guardSchema = object({ ...identityFields, targetId: id, token: id });
 const efforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
@@ -238,7 +256,7 @@ const efforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ul
 // and the three inline types are the ones the model actually reads. Four, and
 // six megabytes of base64 each, is what one turn may carry.
 const attachment = object({ dataUrl: { ...text(6_000_000), pattern: "^data:image/(png|jpeg|webp);base64," } }, { name: text(120) });
-const turnSchema = object({ surface: literal("studio"), sessionId: uuidSchema, turnId: uuidSchema, text: text(16000), context: contextSchema }, { model: text(120), effort: choices(efforts), attachFrame: bool, attachments: array(attachment, 4, 1) });
+const turnSchema = object({ surface: literal("studio"), sessionId: uuidSchema, turnId: uuidSchema, text: text(16000), context: contextSchema }, { model: text(120), effort: choices(efforts), attachFrame: bool, attachments: array(attachment, 4, 1), supervisor: bool });
 const stopSchema = object({ surface: literal("studio"), sessionId: uuidSchema, turnId: uuidSchema }, { jobId: id });
 const revisions = object({ before: integer(), after: integer() });
 const undo = object({ historyEntryId: id, entries: literal(1), canUndoDirect: bool });
@@ -254,10 +272,21 @@ const verification = object({ id, status: choices(["verified", "unverified"]), p
 // not a missing member.
 const patchedValue = object({ path: text(120) }, { number: number(), text: nullable(text(512)), flag: bool, vec: vec3, count: integer(), bytes: integer() });
 const readback = object({}, { position: vec3, yawDeg: number(), rotationDeg: vec3, scale: union(positive, positiveVec3), name, color: text(32), hidden: bool, modelId: id, renderer: id,
-	parentId: nullable(id), childIds: ids(100, 0), removed: bool, range, camera, keyId: id, frame: integer(), subjectIds: ids(24, 0), selection, activeCharacterId: nullable(id), shotId: nullable(id), view, token: id, takeId: nullable(id), statureM: positive,
+	parentId: nullable(id), childIds: ids(100, 0), childCount: integer(0), bounds: nullable(bounds), removed: bool, range, camera, keyId: id, frame: integer(), subjectIds: ids(24, 0), selection, activeCharacterId: nullable(id), shotId: nullable(id), view, token: id, takeId: nullable(id), statureM: positive,
 	patched: array(patchedValue, 32, 1) });
+const CAMERA_SIDES = ["left", "right", "on-axis"];
 const checks = object({ coverage: name }, { relationSatisfied: bool, overlapIds: ids(100, 0), actualGapM: number(), requestedGapM: number(0), maximumFootprintOverlapM: number(0),
-	basis: choices(STUDIO_VARIANTS.positionBases), clipped: bool, occluded: bool, behindCamera: bool, screenFraction: number(0), derivedSize: choices(STUDIO_VARIANTS.framingSizes), support: name, baseY: number(), facesTargetId: id });
+	basis: choices(STUDIO_VARIANTS.positionBases), clipped: bool, occluded: bool, behindCamera: bool, screenFraction: number(0), derivedSize: choices(STUDIO_VARIANTS.framingSizes), support: name, baseY: number(), facesTargetId: id,
+	cameraSide: choices(CAMERA_SIDES), axisConsistent: bool });
+// Code-computed shot geometry verify_result carries beside a framing check
+// (src/studio-geometry-facts.js): bounded to 8 shots and 24 subjects.
+const geometryFacts = object({
+	subjects: array(object({ id, position: vec3, yawDeg: number() }), 24),
+	pairs: array(object({ a: id, b: id, distanceM: number(0) }), 24),
+	shots: array(object({ shotId: id, subjectIds: ids(2, 0), camera: nullable(object({ position: vec3, lookAt: vec3 })), cameraSide: nullable(choices(CAMERA_SIDES)),
+		occluders: array(object({ subjectId: id, byObjectId: id }), 8) }), 8),
+	axisConsistent: nullable(bool),
+});
 const warning = object({ code: id }, { id, message: name, suggestedOutwardDeltaM: number(), count: integer() });
 const receiptBase = { ok: literal(true), commandId: id, receiptId: id, host: identity, status: choices(STUDIO_VARIANTS.receiptStatuses), authored: bool, revision: revisions, affectedIds: ids(100, 0),
 	delta: array(object({ id, after: readback }), 8), checks, undo: nullable(undo), warnings: array(warning, 12) };
@@ -293,7 +322,7 @@ const failureSchema = object({ ok: literal(false), commandId: id, host: identity
 // x-studio-range is the sole relational schema annotation: end > start.
 export const StudioSchemas = freezeStudioData({ catalogue: STUDIO_CATALOGUE, variants: STUDIO_VARIANTS, Vec3: vec3, FrameRange: range, PositionSpec: position, FacingSpec: facing,
 	ObjectOp: objectOp, CharacterOp: characterOp, Framing: framing, GenerateSource: generateSource, Source: source, Identity: identity, Host: host, TargetGuard: guardSchema,
-	Entity: entity, ShotSummary: shotSummary, StudioContextV1: contextSchema, StudioTurn: turnSchema, StudioStop: stopSchema, Receipt: receiptSchema, ReceiptVariants: receiptVariants, Failure: failureSchema });
+	Entity: entity, ShotSummary: shotSummary, StudioContextV1: contextSchema, StudioTurn: turnSchema, StudioStop: stopSchema, Receipt: receiptSchema, ReceiptVariants: receiptVariants, Failure: failureSchema, GeometryFacts: geometryFacts });
 
 /** Validate the closed JSON Schema subset used above; return a detached value
  * with declared defaults. Errors contain schema paths, never payload values. */
@@ -341,7 +370,7 @@ export function validateStudioSchema(schema, value, code = "INVALID_ARGUMENT", p
 		return result;
 	}
 	if (schema.type === "string") {
-		if (typeof value !== "string" || !value.trim() || (schema.maxLength !== undefined && [...value].length > schema.maxLength) || (schema.pattern && !new RegExp(schema.pattern).test(value))) fail(code, "Invalid or oversized string.", path);
+		if (typeof value !== "string" || !value.trim() || (schema.maxLength !== undefined && [...value].length > schema.maxLength) || (schema.pattern && !new RegExp(schema.pattern).test(value))) fail(code, typeof value === "string" && schema.description && [...value].length > schema.maxLength ? `Over ${schema.maxLength} characters. ${schema.description}` : "Invalid or oversized string.", path);
 		if (schema.enum && !schema.enum.includes(value)) fail(code, "Unsupported enum value.", path);
 		return value;
 	}
@@ -463,10 +492,14 @@ export function validateStudioCommand(command) {
 		if (new Set(names).size !== names.length) fail("DUPLICATE_NAME", "Create names must be unique; resolve existing targets by ID.");
 		for (const op of args.ops) {
 			if (op.op === "update" && Object.keys(op).length === 2) fail("INVALID_ARGUMENT", "Update has no fields.");
-			if (op.facing && op.rotationDeg) fail("INVALID_ARGUMENT", "Facing and exact rotation are exclusive.");
+			if (op.facing && op.rotationDeg) fail("INVALID_ARGUMENT", "Facing and rotationDeg are exclusive: facing sets yaw only (toward/away/same-as/yawDeg); rotationDeg {x,y,z} sets the full rotation, with y as the yaw.");
 			if (op.op === "group" && op.childIds.includes(op.parentId)) fail("INVALID_ARGUMENT", "Cannot group an object under itself.");
-			if (args.collisionPolicy === "avoid" && (!["create", "update"].includes(op.op) || !op.position?.relativeTo)) fail("INVALID_ARGUMENT", "Avoid requires a side-relative position for every operation.");
+			if (op.op === "create" && op.parent !== undefined && op.name !== undefined && op.parent.normalize("NFC").trim() === op.name.normalize("NFC").trim()) fail("INVALID_ARGUMENT", "Cannot group an object under itself.");
 		}
+		// Avoidance nudges outward from a relativeTo reference, so at least one op needs one;
+		// the others (world/onObject/between, remove, group) are placed as given and the
+		// final batch is still checked for overlap.
+		if (args.collisionPolicy === "avoid" && !args.ops.some(op => ["create", "update"].includes(op.op) && op.position?.relativeTo)) fail("INVALID_ARGUMENT", "collisionPolicy avoid needs at least one op with position.relativeTo (it nudges outward from that reference); other ops are placed as given.");
 	}
 	if (command.name === "generate_motion" && args.source.kind === "generate") {
 		args.source.beats = args.source.beats.map(beat => ({ ...beat, text: beat.text.trim().replace(/\s+/g, " ") }));