cozyclay 2.0.2 → 2.1.0

package/src/panels/sculpt.css

@@ -0,0 +1,162 @@
+/* Unlayered and rooted like src/panels/details.css: the Foldout's v2 Details primitives
+   (.v2-details-section.v2-details-section .btn / .inspector-hint) are unlayered too, so the
+   overrides below repeat that root to win on specificity. */
+/* One shrinkable column: an image's intrinsic width must not widen the Details column. */
+.sculpt-panel { display: grid; grid-template-columns: minmax(0, 1fr); gap: var(--sp-1); min-width: 0; padding: 4px var(--sp-2) var(--sp-2); }
+.sculpt-panel > *, .sculpt-sheet > * { min-width: 0; }
+.v2-details-section.v2-details-section .sculpt-panel .btn.full { margin-top: 0; }
+.v2-details-section.v2-details-section .sculpt-panel .btn:disabled { opacity: .45; cursor: not-allowed; }
+.sculpt-label { display: flex; align-items: center; justify-content: space-between; gap: var(--sp-1); color: var(--text-2); font-size: 11px; font-weight: 500; white-space: nowrap; }
+.sculpt-label small { min-width: 0; overflow: hidden; text-overflow: ellipsis; font-size: 11px; font-variant-numeric: tabular-nums; color: var(--text-3); }
+
+/* Reference well */
+.sculpt-well { position: relative; border-radius: var(--r-2); border: 1px solid var(--row-divider); background: var(--field); overflow: hidden; }
+.sculpt-well-empty { display: grid; justify-items: center; gap: 4px; padding: var(--sp-3) var(--sp-2); border-style: dashed; border-color: var(--divider-strong); color: var(--text-2); text-align: center; cursor: pointer; transition: border-color var(--fast), background var(--fast); }
+.sculpt-well-empty:hover, .sculpt-well-empty[data-dragging="true"] { border-color: var(--select); background: var(--select-tint); color: var(--text-1); }
+.sculpt-well-empty:focus-visible { outline: none; border-color: var(--select); box-shadow: 0 0 0 2px var(--select-tint); }
+.sculpt-well-title { font-size: 12px; font-weight: 500; color: var(--text-1); }
+.sculpt-well-sub { font-size: 11px; color: var(--text-3); }
+.v2-details-section.v2-details-section .sculpt-well-empty .btn.ghost { width: auto; margin-top: 4px; pointer-events: none; }
+.sculpt-well-filled { display: grid; justify-items: center; background: var(--surface-0); }
+/* The frame shrink-wraps the picture, so the measured slices land on the subject. */
+.sculpt-ref-frame { position: relative; max-width: 100%; }
+.sculpt-ref-frame img { display: block; max-width: 100%; max-height: 220px; }
+.v2-details-section.v2-details-section .sculpt-well-replace { position: absolute; right: 6px; bottom: 6px; width: auto; background: var(--overlay); color: var(--text-1); }
+
+/* Primary action */
+.v2-details-section.v2-details-section .sculpt-cancel { color: var(--danger); background: none; box-shadow: inset 0 0 0 1px var(--danger); }
+.v2-details-section.v2-details-section .sculpt-cancel:hover { background: var(--surface-active); color: var(--danger); }
+.v2-details-section.v2-details-section .sculpt-refusal { color: var(--text-2); }
+
+/* Progress */
+.sculpt-progress { display: grid; gap: var(--sp-1); padding: var(--sp-1); border-radius: var(--r-2); background: var(--surface-raised); }
+.sculpt-stepper { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); margin: 0; padding: 0; list-style: none; }
+.sculpt-step { position: relative; display: grid; justify-items: center; gap: 4px; color: var(--text-3); font-size: 10.5px; white-space: nowrap; letter-spacing: -.01em; }
+/* Connector from the previous step's dot to this one. */
+.sculpt-step + .sculpt-step::before { content: ""; position: absolute; top: 4px; right: 50%; width: 100%; height: 1px; background: var(--divider-strong); }
+.sculpt-step[data-state="complete"]::before, .sculpt-step[data-state="current"]::before { background: var(--select); }
+.sculpt-step-dot { position: relative; z-index: 1; width: 9px; height: 9px; border-radius: 50%; border: 1px solid var(--divider-strong); background: var(--surface-raised); }
+.sculpt-step[data-state="complete"] { color: var(--text-2); }
+.sculpt-step[data-state="complete"] .sculpt-step-dot { background: var(--select); border-color: var(--select); }
+.sculpt-step[data-state="current"] { color: var(--text-1); font-weight: 600; }
+.sculpt-step[data-state="current"] .sculpt-step-dot { border-color: var(--select); background: var(--select); box-shadow: 0 0 0 3px var(--select-tint); animation: sculpt-pulse 1.4s var(--ease) infinite; }
+@keyframes sculpt-pulse { 50% { box-shadow: 0 0 0 5px var(--select-tint); } }
+@media (prefers-reduced-motion: reduce) { .sculpt-step[data-state="current"] .sculpt-step-dot { animation: none; } }
+
+.sculpt-stats { display: flex; justify-content: space-between; color: var(--text-2); font-size: 11px; font-variant-numeric: tabular-nums; }
+.sculpt-iou { display: grid; gap: 4px; }
+.sculpt-iou .sculpt-label small { color: var(--text-1); font-family: var(--mono); }
+.sculpt-iou-target { color: var(--text-3); }
+.sculpt-iou-bar { position: relative; height: 6px; border-radius: 3px; background: var(--field); }
+.sculpt-iou-fill { position: absolute; inset: 0 auto 0 0; width: calc(var(--sculpt-iou) * 100%); border-radius: inherit; background: var(--primary); transition: width var(--med) var(--ease); }
+.sculpt-iou-bar[data-reached="true"] .sculpt-iou-fill { background: var(--ok); }
+.sculpt-iou-marker { position: absolute; top: -3px; bottom: -3px; left: calc(var(--sculpt-target) * 100%); width: 2px; margin-left: -1px; border-radius: 1px; background: var(--select); }
+.v2-details-section.v2-details-section .sculpt-done { color: var(--ok); }
+.v2-details-section.v2-details-section .sculpt-error { color: var(--danger); }
+
+/* Overlay sheet */
+.sculpt-sheet { display: grid; grid-template-columns: minmax(0, 1fr); gap: 6px; }
+.v2-details-section.v2-details-section .sculpt-sheet .btn[aria-pressed="true"] { color: var(--text-1); box-shadow: inset 0 0 0 1px var(--select); }
+.sculpt-sheet-image { display: block; width: 100%; border-radius: var(--r-1); border: 1px solid var(--row-divider); background: var(--surface-0); }
+
+
+/* --------------------------------------------------- live narration (#739) ---
+   Everything below says "it is working": a lump of clay being kneaded while we
+   wait, a bar against the usual wait, the score trail, the candidate race and
+   the log. Motion stops under prefers-reduced-motion; the words stay. */
+
+/* What we wait on now */
+.sculpt-now { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: start; column-gap: 8px; row-gap: 4px; padding: 6px 8px; border-radius: var(--r-1); background: var(--field); font-size: 12px; color: var(--text-1); }
+.sculpt-now-label { min-width: 0; overflow-wrap: anywhere; line-height: 1.35; font-weight: 500; }
+.sculpt-now-time { font-family: var(--mono); font-variant-numeric: tabular-nums; color: var(--text-2); }
+.sculpt-now-expect { grid-column: 2 / 4; font-size: 11px; color: var(--text-3); }
+.sculpt-now[data-over="true"] .sculpt-now-expect { color: var(--warn, var(--text-2)); }
+.sculpt-now-bar { grid-column: 1 / -1; position: relative; height: 3px; border-radius: 2px; background: var(--surface-active); overflow: hidden; }
+.sculpt-now-bar > span { position: absolute; inset: 0 auto 0 0; width: calc(var(--sculpt-wait) * 100%); background: var(--select); border-radius: inherit; transition: width .5s linear; }
+.sculpt-now[data-over="true"] .sculpt-now-bar > span { width: 100%; background: linear-gradient(90deg, var(--select-tint), var(--select), var(--select-tint)); background-size: 200% 100%; animation: sculpt-shimmer 1.2s linear infinite; }
+@keyframes sculpt-shimmer { to { background-position: -200% 0; } }
+
+/* A lump of clay being kneaded: squash, stretch, a thumb press. */
+.sculpt-clay { width: 16px; height: 16px; margin-top: 1px; border-radius: 52% 48% 46% 54% / 55% 50% 50% 45%; background: radial-gradient(circle at 35% 30%, #e9c9a6, #c08a5c 70%); box-shadow: inset -2px -2px 0 rgba(0, 0, 0, .12); animation: sculpt-knead 1.1s ease-in-out infinite; }
+@keyframes sculpt-knead {
+	0%, 100% { transform: scale(1, 1) rotate(0deg); border-radius: 52% 48% 46% 54% / 55% 50% 50% 45%; }
+	30% { transform: scale(1.18, .82) rotate(-6deg); border-radius: 60% 40% 55% 45% / 45% 55% 45% 55%; }
+	60% { transform: scale(.86, 1.14) rotate(5deg); border-radius: 45% 55% 40% 60% / 60% 40% 60% 40%; }
+}
+.sculpt-now[data-what="score"] .sculpt-clay, .sculpt-now[data-what="measure"] .sculpt-clay { animation-duration: .6s; }
+
+/* IoU trail */
+.sculpt-trail { position: relative; height: 34px; }
+.sculpt-trail svg { display: block; width: 100%; height: 100%; overflow: visible; }
+.sculpt-trail-target { stroke: var(--select); stroke-width: 1; stroke-dasharray: 2 2; vector-effect: non-scaling-stroke; opacity: .7; }
+.sculpt-trail-line { fill: none; stroke: var(--primary); stroke-width: 1.5; vector-effect: non-scaling-stroke; }
+.sculpt-trail-dot { fill: var(--primary); }
+.sculpt-trail-dot[data-last="true"] { fill: var(--ok); animation: sculpt-dot 1.6s ease-in-out infinite; transform-box: fill-box; transform-origin: center; }
+@keyframes sculpt-dot { 50% { transform: scale(1.6); } }
+.sculpt-delta { position: absolute; right: 0; top: -4px; padding: 1px 6px; border-radius: 9px; font: 600 11px/1.4 var(--mono); background: var(--surface-raised); box-shadow: 0 0 0 1px var(--row-divider); animation: sculpt-float 1.8s var(--ease) both; }
+.sculpt-delta[data-sign="up"] { color: var(--ok); }
+.sculpt-delta[data-sign="down"] { color: var(--danger); }
+@keyframes sculpt-float { from { opacity: 0; transform: translateY(8px) scale(.9); } 25% { opacity: 1; transform: none; } }
+
+/* Candidate race */
+.sculpt-race { display: grid; gap: 3px; margin: 0; padding: 6px 8px; list-style: none; border-radius: var(--r-1); background: var(--field); }
+.sculpt-race-row { display: grid; grid-template-columns: minmax(0, 7fr) minmax(0, 6fr) auto; align-items: center; gap: 6px; font-size: 11px; color: var(--text-2); }
+.sculpt-race-label { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.sculpt-race-bar { height: 5px; border-radius: 3px; background: var(--surface-active); overflow: hidden; }
+.sculpt-race-bar > span { display: block; height: 100%; width: calc(var(--sculpt-race) * 100%); border-radius: inherit; background: var(--text-3); transform-origin: left; animation: sculpt-grow .7s var(--ease) both; animation-delay: var(--sculpt-race-delay); }
+@keyframes sculpt-grow { from { transform: scaleX(0); } }
+.sculpt-race-score { font-family: var(--mono); font-variant-numeric: tabular-nums; }
+.sculpt-race-row[data-leader="true"] { color: var(--text-1); font-weight: 600; }
+.sculpt-race-row[data-leader="true"] .sculpt-race-bar > span { background: var(--ok); }
+.sculpt-race-row[data-leader="true"] .sculpt-race-label::before { content: "\2605  "; color: var(--ok); }
+.sculpt-race-row[data-refused="true"] { opacity: .5; text-decoration: line-through; }
+
+/* Activity log */
+.sculpt-log { display: grid; gap: 2px; max-height: 168px; margin: 0; padding: 4px 2px; list-style: none; overflow-y: auto; overscroll-behavior: contain; scroll-behavior: smooth; }
+.sculpt-log-row { display: grid; grid-template-columns: 30px 8px minmax(0, 1fr); align-items: baseline; gap: 6px; font-size: 11px; line-height: 1.4; color: var(--text-2); animation: sculpt-in .35s var(--ease) both; }
+.sculpt-log-row:last-child { color: var(--text-1); }
+@keyframes sculpt-in { from { opacity: 0; transform: translateY(4px); } }
+.sculpt-log-time { font-family: var(--mono); font-variant-numeric: tabular-nums; color: var(--text-3); }
+.sculpt-log-dot { width: 6px; height: 6px; border-radius: 50%; background: var(--text-3); align-self: center; }
+.sculpt-log-row[data-kind="agent"] .sculpt-log-dot { background: var(--select); }
+.sculpt-log-row[data-kind="ok"] .sculpt-log-dot, .sculpt-log-row[data-kind="done"] .sculpt-log-dot { background: var(--ok); }
+.sculpt-log-row[data-kind="score"] .sculpt-log-dot { background: var(--primary); }
+.sculpt-log-row[data-kind="warn"] .sculpt-log-dot { background: var(--warn, #d9a441); }
+.sculpt-log-row[data-kind="error"] .sculpt-log-dot { background: var(--danger); }
+.sculpt-log-row[data-kind="done"] { color: var(--ok); font-weight: 600; }
+.sculpt-log-text { min-width: 0; overflow-wrap: anywhere; }
+
+/* Measuring the reference: a scan line, then the slices it found */
+.sculpt-scanline { position: absolute; left: 0; right: 0; top: 0; height: 2px; background: var(--select); box-shadow: 0 0 8px 2px var(--select-tint); animation: sculpt-scan 1.1s ease-in-out infinite alternate; pointer-events: none; }
+@keyframes sculpt-scan { to { top: calc(100% - 2px); } }
+.sculpt-scan { position: absolute; inset: 0; width: 100%; height: 100%; pointer-events: none; }
+.sculpt-scan-span { fill: var(--select); opacity: .8; animation: sculpt-slice .45s var(--ease) both; }
+@keyframes sculpt-slice { from { opacity: 0; transform: scaleX(0); } }
+.sculpt-scan-span { transform-box: fill-box; transform-origin: center; }
+
+@media (prefers-reduced-motion: reduce) {
+	.sculpt-clay, .sculpt-trail-dot, .sculpt-delta, .sculpt-race-bar > span, .sculpt-log-row, .sculpt-scanline, .sculpt-scan-span, .sculpt-now[data-over="true"] .sculpt-now-bar > span { animation: none; }
+}
+
+/* Model and effort */
+.sculpt-model { display: grid; gap: 4px; }
+.sculpt-model-row { display: grid; grid-template-columns: minmax(0, 1fr); gap: 4px; }
+.sculpt-select { min-width: 0; height: 26px; padding: 0 6px; border-radius: var(--r-1); border: 1px solid var(--row-divider); background: var(--field); color: var(--text-1); font: inherit; font-size: 12px; }
+.sculpt-select:disabled { opacity: .6; }
+
+
+/* Blueprint (model sheet) */
+.sculpt-blueprint { display: grid; grid-template-columns: minmax(0, 1fr); gap: 6px; min-width: 0; padding: 8px; border-radius: var(--r-2); background: var(--surface-raised); }
+.sculpt-blueprint-row { display: grid; grid-template-columns: minmax(0, 1fr); min-width: 0; }
+.sculpt-blueprint > * { min-width: 0; }
+.sculpt-blueprint .sculpt-label small { overflow: hidden; text-overflow: ellipsis; }
+.sculpt-notes { box-sizing: border-box; width: 100%; min-width: 0; resize: vertical; padding: 6px; border-radius: var(--r-1); border: 1px solid var(--row-divider); background: var(--field); color: var(--text-1); font: inherit; font-size: 12px; }
+.sculpt-blueprint .sculpt-now .btn { grid-column: 1 / -1; justify-self: end; width: auto; }
+.sculpt-sheet-figure { display: grid; gap: 4px; margin: 0; }
+.sculpt-sheet-figure > a { position: relative; display: block; border-radius: var(--r-1); overflow: hidden; border: 1px solid var(--row-divider); background: #fff; }
+.sculpt-sheet-figure img { display: block; width: 100%; }
+.sculpt-sheet-tag { position: absolute; margin: 3px; padding: 0 4px; border-radius: 3px; font-size: 9.5px; line-height: 1.5; color: #fff; background: rgba(20, 22, 28, .62); pointer-events: none; }
+.sculpt-sheet-figure figcaption { display: flex; justify-content: space-between; font-size: 11px; color: var(--text-3); }
+.sculpt-sheet-figure figcaption a { color: var(--select); }
+.sculpt-prompt summary { cursor: pointer; font-size: 11px; color: var(--text-2); }
+.sculpt-prompt pre { max-height: 180px; margin: 4px 0 0; padding: 6px; overflow: auto; white-space: pre-wrap; border-radius: var(--r-1); background: var(--field); font: 10.5px/1.45 var(--mono); color: var(--text-2); }

package/src/plan-diagram.js

@@ -0,0 +1,184 @@
+// The Top View the Studio agent reads (verify_result visual "plan",
+// capture_plan_png): a 2D data diagram drawn from editor state, not a render.
+// planDiagramLayout computes the world->pixel transform and a list of
+// primitives; drawPlanDiagram paints them on any 2D canvas context.
+// Pure: no renderer, no React, no DOM.
+import { isEffectivelyHidden } from './scene-objects.js';
+import { shotAtFrame } from './cuts.js';
+import { occludersOf, primarySubjects, shotCamera, sideOfAxis } from './studio-geometry-facts.js';
+import { entityWorldBounds } from './studio-agent-commands.js';
+
+export const PLAN_DIAGRAM = Object.freeze({ marginM: 1.5, maxSpanM: 30, minSpanM: 6, characterRadiusM: 0.3, frustumM: 3, defaultFovDeg: 40 });
+const SIDE_LABEL = { left: 'L', right: 'R', 'on-axis': 'on-axis' };
+const GROUP_HUES = ['#c9a46a', '#a8c47a', '#d39a8c', '#8fb7c9', '#c0a0d0', '#d6c06a'];
+const round = v => Math.round(v * 1000) / 1000 + 0;
+const flat = p => ({ x: round(p.x), z: round(p.z) });
+
+function groupRoot(object, objects) {
+  let node = object;
+  for (let guard = 0; node?.parent && guard < 64; guard += 1) {
+    const parent = objects.find(o => o.id === node.parent);
+    if (!parent) break;
+    node = parent;
+  }
+  return node;
+}
+
+/** Footprint corners in world x/z: width*scaleX by depth*scaleZ, turned by rot (yaw deg, 0 = +Z, positive toward +X). */
+function footprintCorners(o) {
+  const w = (o.footprint?.width ?? 0) * (o.scaleX ?? 1) / 2, d = (o.footprint?.depth ?? 0) * (o.scaleZ ?? 1) / 2;
+  const yaw = (o.rot ?? 0) * Math.PI / 180, c = Math.cos(yaw), s = Math.sin(yaw);
+  return [[-w, -d], [w, -d], [w, d], [-w, d]].map(([lx, lz]) => flat({ x: o.x + lx * c + lz * s, z: o.z - lx * s + lz * c }));
+}
+
+/**
+ * The diagram's content and framing. `options`: width/height of the output in
+ * pixels, `ports` for world bounds (occluders), `currentShotId` (defaults to
+ * the shot under state.frame), `aspect` of the shot frame for the horizontal FOV.
+ */
+export function planDiagramLayout(state, { width = 1280, height = 720, ports, currentShotId, aspect = 16 / 9 } = {}) {
+  const visible = e => !isEffectivelyHidden(e, state.objects, state.characters);
+  const characters = state.characters.filter(visible);
+  // A carried prop's numbers are local to the bone it rides, so it has no floor spot of its own.
+  const objects = state.objects.filter(o => visible(o) && !o.attach);
+  const shots = [...(state.shotDocument?.shots ?? [])].sort((a, b) => a.startFrame - b.startFrame);
+  const currentId = currentShotId ?? shotAtFrame(shots, state.frame ?? 0)?.id ?? null;
+  const primitives = [];
+
+  // Largest footprints first, so a ground plane never covers the props standing on it.
+  const area = o => (o.footprint?.width ?? 0) * (o.scaleX ?? 1) * (o.footprint?.depth ?? 0) * (o.scaleZ ?? 1);
+  for (const o of [...objects].sort((p, q) => area(q) - area(p))) {
+    const root = groupRoot(o, state.objects), grouped = root !== o || state.objects.some(child => child.parent === o.id);
+    const hue = grouped ? GROUP_HUES[[...root.id].reduce((sum, ch) => sum + ch.charCodeAt(0), 0) % GROUP_HUES.length] : '#d8c39a';
+    primitives.push({ kind: 'object', id: o.id, label: o.name || o.id, center: flat(o), corners: footprintCorners(o), groupId: grouped ? root.id : null, fill: hue });
+  }
+  for (const c of characters) {
+    const yaw = (c.rot ?? 0) * Math.PI / 180;
+    primitives.push({ kind: 'character', id: c.id, label: c.subject || c.id, x: round(c.x), z: round(c.z), radius: PLAN_DIAGRAM.characterRadiusM, facing: flat({ x: Math.sin(yaw), z: Math.cos(yaw) }) });
+  }
+  shots.forEach((shot, index) => {
+    const camera = shotCamera(shot, state);
+    if (!camera) return;
+    const fovDeg = shot.cameraKeys?.[0]?.framing?.fovDeg ?? PLAN_DIAGRAM.defaultFovDeg;
+    const halfFov = Math.atan(Math.tan(fovDeg * Math.PI / 360) * aspect), heading = Math.atan2(camera.lookAt.x - camera.position.x, camera.lookAt.z - camera.position.z);
+    const edge = angle => flat({ x: camera.position.x + Math.sin(angle) * PLAN_DIAGRAM.frustumM, z: camera.position.z + Math.cos(angle) * PLAN_DIAGRAM.frustumM });
+    const current = shot.id === currentId, entry = { kind: 'camera', shotId: shot.id, label: `S${index + 1}`, current, position: flat(camera.position), lookAt: flat(camera.lookAt),
+      halfFovRad: round(halfFov), frustum: [edge(heading - halfFov), edge(heading + halfFov)], cameraSide: null };
+    primitives.push(entry);
+    if (!current) return;
+    const pair = primarySubjects(shot.subjectIds ?? [], camera.position, state);
+    if (pair.length !== 2) return;
+    entry.cameraSide = SIDE_LABEL[sideOfAxis(pair[0], pair[1], camera.position)] ?? null;
+    primitives.push({ kind: 'actionLine', shotId: shot.id, subjectIds: pair.map(c => c.id), a: flat(pair[0]), b: flat(pair[1]), distanceM: round(Math.hypot(pair[1].x - pair[0].x, pair[1].z - pair[0].z)), cameraSide: entry.cameraSide });
+    if (!ports) return;
+    for (const subject of pair) {
+      const box = entityWorldBounds(subject, state, ports);
+      if (!box) continue;
+      for (const hit of occludersOf(subject, camera.position, state, ports, box)) {
+        const blocker = state.objects.find(o => o.id === hit.byObjectId);
+        primitives.push({ kind: 'occluder', shotId: shot.id, subjectId: hit.subjectId, byObjectId: hit.byObjectId, corners: blocker && !blocker.attach ? footprintCorners(blocker) : [],
+          segment: { from: flat(camera.position), to: flat({ x: (box.min.x + box.max.x) / 2, z: (box.min.z + box.max.z) / 2 }) } });
+      }
+    }
+  });
+
+  // Fit everything visible plus a margin, keep the output aspect, cap the span.
+  // A capped view centres on the cast and cameras, so the action stays in frame.
+  const box = points => {
+    const xs = points.map(p => p.x), zs = points.map(p => p.z);
+    return xs.length ? { min: { x: Math.min(...xs), z: Math.min(...zs) }, max: { x: Math.max(...xs), z: Math.max(...zs) } } : null;
+  };
+  const action = box(primitives.flatMap(p => p.kind === 'character' ? [p] : p.kind === 'camera' ? [p.position] : []));
+  const { min, max } = box(primitives.flatMap(p => p.kind === 'object' ? [p.center, ...p.corners] : p.kind === 'character' ? [p] : p.kind === 'camera' ? [p.position] : [])) ?? { min: { x: 0, z: 0 }, max: { x: 0, z: 0 } };
+  const pixelAspect = width / height;
+  let spanX = max.x - min.x + 2 * PLAN_DIAGRAM.marginM, spanZ = max.z - min.z + 2 * PLAN_DIAGRAM.marginM;
+  spanZ = Math.max(spanZ, PLAN_DIAGRAM.minSpanM);
+  if (spanX / spanZ < pixelAspect) spanX = spanZ * pixelAspect; else spanZ = spanX / pixelAspect;
+  const cap = Math.min(1, PLAN_DIAGRAM.maxSpanM / Math.max(spanX, spanZ));
+  spanX *= cap; spanZ *= cap;
+  const focus = cap < 1 && action ? action : { min, max }, centre = { x: (focus.min.x + focus.max.x) / 2, z: (focus.min.z + focus.max.z) / 2 };
+  const scale = width / spanX, view = { minX: centre.x - spanX / 2, maxX: centre.x + spanX / 2, minZ: centre.z - spanZ / 2, maxZ: centre.z + spanZ / 2 };
+  primitives.unshift({ kind: 'grid', stepM: 1, labelStepM: 2, ...Object.fromEntries(Object.entries(view).map(([k, v]) => [k, round(v)])) });
+  // +X to the right, +Z down the image.
+  const toPixel = p => [(p.x - view.minX) * scale, (p.z - view.minZ) * scale];
+  return { width, height, scale: round(scale), view, toPixel, currentShotId: currentId, primitives };
+}
+
+/** Paint the plan diagram on a 2D context of the output size; returns the layout. */
+export function drawPlanDiagram(ctx, state, options = {}) {
+  const layout = planDiagramLayout(state, options), { width, height, scale, view, toPixel } = layout;
+  const path = (corners, close = true) => {
+    ctx.beginPath();
+    corners.forEach((p, i) => { const [x, y] = toPixel(p); i ? ctx.lineTo(x, y) : ctx.moveTo(x, y); });
+    if (close) ctx.closePath();
+  };
+  const text = (value, x, y, colour = '#222', align = 'left') => {
+    ctx.textAlign = align; ctx.lineWidth = 3; ctx.strokeStyle = 'rgba(250, 248, 242, 0.9)'; ctx.fillStyle = colour;
+    ctx.strokeText(value, x, y); ctx.fillText(value, x, y);
+  };
+  ctx.fillStyle = '#f7f5ef'; ctx.fillRect(0, 0, width, height);
+  ctx.font = '500 13px system-ui, sans-serif'; ctx.textBaseline = 'middle';
+  for (const p of layout.primitives) {
+    if (p.kind === 'grid') {
+      for (let x = Math.ceil(view.minX); x <= view.maxX; x += 1) {
+        const [px] = toPixel({ x, z: 0 });
+        ctx.strokeStyle = x === 0 ? '#9a968c' : x % 2 ? '#e8e5dc' : '#d9d5ca'; ctx.lineWidth = x === 0 ? 1.5 : 1;
+        ctx.beginPath(); ctx.moveTo(px, 0); ctx.lineTo(px, height); ctx.stroke();
+        if (x % 2 === 0) text(`x ${x}`, px + 3, height - 10, '#6d695f');
+      }
+      for (let z = Math.ceil(view.minZ); z <= view.maxZ; z += 1) {
+        const [, py] = toPixel({ x: 0, z });
+        ctx.strokeStyle = z === 0 ? '#9a968c' : z % 2 ? '#e8e5dc' : '#d9d5ca'; ctx.lineWidth = z === 0 ? 1.5 : 1;
+        ctx.beginPath(); ctx.moveTo(0, py); ctx.lineTo(width, py); ctx.stroke();
+        if (z % 2 === 0) text(`z ${z}`, 4, py - 8, '#6d695f');
+      }
+      const [ox, oy] = toPixel({ x: 0, z: 0 });
+      ctx.strokeStyle = '#5c584f'; ctx.lineWidth = 2;
+      ctx.beginPath(); ctx.arc(ox, oy, 5, 0, Math.PI * 2); ctx.stroke();
+      text('0', ox + 8, oy + 10, '#5c584f');
+    } else if (p.kind === 'object') {
+      ctx.fillStyle = p.fill; ctx.strokeStyle = '#8a7350'; ctx.lineWidth = 1.5;
+      if (p.corners.some((c, i) => c.x !== p.corners[(i + 2) % 4].x || c.z !== p.corners[(i + 2) % 4].z)) { path(p.corners); ctx.fill(); ctx.stroke(); }
+      const [x, y] = toPixel(p.center);
+      text(p.label.length > 24 ? `${p.label.slice(0, 23)}\u2026` : p.label, x, y, '#4a3b22', 'center');
+    } else if (p.kind === 'character') {
+      const [x, y] = toPixel(p), r = p.radius * scale, [fx, fy] = toPixel({ x: p.x + p.facing.x * (p.radius + 0.35), z: p.z + p.facing.z * (p.radius + 0.35) });
+      ctx.fillStyle = '#6ea8e0'; ctx.strokeStyle = '#2f6aa8'; ctx.lineWidth = 2;
+      ctx.beginPath(); ctx.arc(x, y, r, 0, Math.PI * 2); ctx.fill(); ctx.stroke();
+      ctx.beginPath(); ctx.moveTo(x, y); ctx.lineTo(fx, fy); ctx.stroke();
+      const head = Math.atan2(fy - y, fx - x);
+      ctx.beginPath(); ctx.moveTo(fx, fy); ctx.lineTo(fx - 8 * Math.cos(head - 0.5), fy - 8 * Math.sin(head - 0.5)); ctx.lineTo(fx - 8 * Math.cos(head + 0.5), fy - 8 * Math.sin(head + 0.5)); ctx.closePath(); ctx.fillStyle = '#2f6aa8'; ctx.fill();
+      // The name goes behind the character, so two people facing each other keep their labels apart.
+      const behind = p.facing.x >= 0 ? -1 : 1, name = p.label.length > 24 ? `${p.label.slice(0, 23)}\u2026` : p.label;
+      text(name, x + behind * (r + 4), y - r - 6, '#1f4f80', behind < 0 ? 'right' : 'left');
+    } else if (p.kind === 'camera') {
+      const [cx, cy] = toPixel(p.position), [lx, ly] = toPixel(p.lookAt);
+      ctx.fillStyle = p.current ? 'rgba(214, 64, 52, 0.22)' : 'rgba(120, 120, 120, 0.14)'; ctx.strokeStyle = p.current ? '#d64034' : '#7d7a73'; ctx.lineWidth = p.current ? 2 : 1.25;
+      path([p.position, ...p.frustum]); ctx.fill(); ctx.stroke();
+      ctx.lineWidth = 1; ctx.beginPath(); ctx.moveTo(cx, cy); ctx.lineTo(lx, ly); ctx.stroke();
+      ctx.beginPath(); ctx.arc(cx, cy, 6, 0, Math.PI * 2);
+      if (p.current) { ctx.fillStyle = '#d64034'; ctx.fill(); } else { ctx.fillStyle = '#ffffff'; ctx.fill(); ctx.stroke(); }
+      text(p.cameraSide ? `${p.label} (${p.cameraSide})` : p.label, cx + 9, cy + 12, p.current ? '#b02d22' : '#55524b');
+    } else if (p.kind === 'actionLine') {
+      const [ax, ay] = toPixel(p.a), [bx, by] = toPixel(p.b);
+      ctx.strokeStyle = '#3c7d3a'; ctx.lineWidth = 2; ctx.setLineDash([8, 6]);
+      ctx.beginPath(); ctx.moveTo(ax, ay); ctx.lineTo(bx, by); ctx.stroke(); ctx.setLineDash([]);
+      text(`${p.distanceM.toFixed(2)} m`, (ax + bx) / 2, (ay + by) / 2 - 12, '#2d5f2b', 'center');
+    } else if (p.kind === 'occluder') {
+      ctx.strokeStyle = '#e0241b'; ctx.lineWidth = 3;
+      if (p.corners.length) { path(p.corners); ctx.stroke(); }
+      const [fx, fy] = toPixel(p.segment.from), [tx, ty] = toPixel(p.segment.to);
+      ctx.lineWidth = 2; ctx.beginPath(); ctx.moveTo(fx, fy); ctx.lineTo(tx, ty); ctx.stroke();
+    }
+  }
+  // Legend, top-right.
+  const rows = [['character', '#6ea8e0'], ['object', '#d8c39a'], ['camera (filled: current shot)', '#d64034'], ['action line', '#3c7d3a'], ['blocked sight line', '#e0241b']];
+  const lx = width - 236, ly = 12;
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.92)'; ctx.strokeStyle = '#c9c4b8'; ctx.lineWidth = 1;
+  ctx.fillRect(lx, ly, 224, rows.length * 20 + 12); ctx.strokeRect(lx, ly, 224, rows.length * 20 + 12);
+  rows.forEach(([name, colour], i) => {
+    ctx.fillStyle = colour; ctx.fillRect(lx + 10, ly + 12 + i * 20, 14, 10);
+    ctx.fillStyle = '#333'; ctx.textAlign = 'left'; ctx.fillText(name, lx + 32, ly + 17 + i * 20);
+  });
+  return layout;
+}