cozyclay 2.0.2 → 2.1.1

package/src/studio-agent-commands.js

@@ -1,13 +1,17 @@
 // 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';
+import { sampleContactSheetFrames } from './studio-contact-sheet.js';
 
 const DEG = Math.PI / 180, EPS = 1e-8, CHARACTER_SUPPORT_TOLERANCE = 5e-3;
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
@@ -20,6 +24,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 +92,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 +143,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 +156,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 +268,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 +338,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 +382,49 @@ 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 };
+}
+
+/** Framing evidence over explicit timeline samples. The caller supplies the
+ * sampled state so camera keys and animated subject bounds use the same frame.
+ * A sample is evidence for that frame only; it is never advertised as an
+ * all-frame proof. */
+export function sampledFramingChecks(ids, state, ports, frames) {
+  if (!Array.isArray(frames) || !frames.length) fail('INVALID_RANGE', 'Framing sampling needs at least one timeline frame.');
+  if (typeof ports.sampleStateAt !== 'function') fail('CAPABILITY_MISSING', 'This editor cannot sample framing at timeline frames.');
+  const samples = frames.map(frame => {
+    const sampledState = ports.sampleStateAt(frame, state);
+    if (!sampledState) fail('TARGET_NOT_READY', `The editor could not read timeline frame ${frame}.`);
+    const checks = framingChecks(ids, sampledState, ports), codes = [checks.clipped ? 'CLIPPED' : null, checks.behindCamera ? 'BEHIND_CAMERA' : null, checks.occluded ? 'OCCLUDED' : null].filter(Boolean);
+    return { frame, checks, codes };
+  });
+  const sampledChecks = samples.map(({ frame, checks }) => ({ frame, screenFraction: checks.screenFraction, clipped: checks.clipped, behindCamera: checks.behindCamera, occluded: checks.occluded }));
+  const issueFrames = samples.filter(sample => sample.codes.length).map(({ frame, checks, codes }) => ({ frame, codes, screenFraction: checks.screenFraction }));
+  return { ...samples.at(-1).checks, coverage: 'sampled-timeline-subject-bounds-projection', evaluatedFrames: frames.length, sampledFrames: frames, sampledChecks, issueFrames };
+}
+export function sampledFramingResult(args, scene, ports, frameCount, measured, receipt) {
+  const range = args.range === 'whole_clip' ? { startFrame: 0, endFrameExclusive: frameCount } : args.range;
+  if (range.endFrameExclusive > frameCount) fail('INVALID_RANGE', 'Framing verification range exceeds the scene timeline.');
+  const ids = measured ?? (args.targets ?? receipt?.affectedIds ?? []).filter(id => scene.objects.some(o => o.id === id) || scene.characters.some(c => c.id === id));
+  if (!ids.length) return { reason: 'No target is available for sampled framing verification.' };
+  try { return sampledFramingChecks(ids, scene, ports, sampleContactSheetFrames(args.range, frameCount)); }
+  catch (error) { if (!(error instanceof StudioProtocolError)) throw error; return { reason: error.message }; }
 }
 export function frameDraft(command, state, ports) {
   if (state.frameCount <= 0) fail('TARGET_NOT_READY', 'A nonempty timeline is required.');
@@ -249,7 +436,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 +459,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 };