@rig-c/review 0.5.0 → 0.6.0

package/src/mesh-edit.ts

@@ -0,0 +1,287 @@
+/**
+ * Mesh edit (Setup): a typed delta over the actual loaded mesh attachment of one slot. Pure — no DOM, no I/O.
+ *
+ * The source is the attachment the hash-verified model declares, with its vertices taken from the last drawn pose of
+ * that slot and mapped to crop pixels (x right, y down) through the same crop mapping as the chest regions. Ops are
+ * recorded in order; nothing is retriangulated here — the preview draws the delta over the original triangulation and
+ * the producer (#45) owns the mesher. Vertex ids are stable: the source vertices keep their indices, an added vertex
+ * takes the next id after every vertex that existed before it, and a removed vertex keeps its id (it is only marked).
+ */
+export type Vec = [number, number];
+export type MeshOp =
+  | { op: 'move'; v: number; from: Vec; to: Vec }
+  | { op: 'add'; at: Vec; onEdge?: [number, number] }
+  | { op: 'remove'; v: number }
+  | { op: 'edge'; a: number; b: number }
+  | { op: 'unedge'; a: number; b: number };
+export type EdgeKind = 'hull' | 'interior' | 'constraint';
+export interface MeshEdge { a: number; b: number; kind: EdgeKind }
+export interface MeshSource {
+  slot: string; skin: string; attachment: string;
+  /** Crop px, x right, y down, one per source vertex. */
+  vertices: readonly Vec[];
+  triangles: readonly number[];
+  /** The model's `hull`: the first `hull` vertices, in order, are the hull. */
+  hull: number;
+  /** SHA-256 of the attachment's entry in the hash-verified model (see `attachmentHashText`). */
+  hash: string;
+}
+export interface MeshView {
+  /** Current position per vertex id; null when removed. */
+  vertices: (Vec | null)[];
+  edges: MeshEdge[];
+  /** Edges the delta removed (explicitly, or with a removed vertex), for the preview. */
+  removedEdges: MeshEdge[];
+  added: Set<number>;
+  /** Moved vertex id → its source (or creation) position. */
+  moved: Map<number, Vec>;
+  removed: Set<number>;
+}
+export type MeshEditResult = { ok: true; changed: boolean; code?: string } | { ok: false; code: string };
+
+export const MESH_EDIT_SCHEMA = 'rig-review-mesh-edit/1';
+export const MESH_EDIT_BINDING_SCHEMA = 'rig-review-mesh-edit-binding/1';
+export const MESH_EDIT_DRAFT_SCHEMA = 'rig-review-mesh-edit-draft/1';
+export const MESH_EDIT_SELECT_SLOT = 'MESH_EDIT_SELECT_SLOT';
+export const MESH_EDIT_NO_MESH = 'MESH_EDIT_NO_MESH';
+export const MESH_EDIT_HULL_EDGE = 'MESH_EDIT_HULL_EDGE';
+export const MESH_EDIT_EDGE_EXISTS = 'MESH_EDIT_EDGE_EXISTS';
+export const MESH_EDIT_TRIANGULATION_EDGE = 'MESH_EDIT_TRIANGULATION_EDGE';
+export const MESH_EDIT_INVALID_OP = 'MESH_EDIT_INVALID_OP';
+export const MESH_EDIT_OPS_LIMIT = 'MESH_EDIT_OPS_LIMIT';
+/** The draft rides in one form field (≤ 32768 characters), so the delta is bounded. */
+export const MESH_EDIT_MAX_OPS = 300;
+export const MESH_EDIT_PREVIEW_NOTE = 'preview only — the producer retriangulates';
+/** Screen-space hit radii in CSS px. */
+export const MESH_HIT = Object.freeze({ vertex: 6, vertexTouch: 8, edge: 4 });
+
+const round = (value: number) => Math.round(value * 100) / 100;
+export const roundVec = (p: { x: number; y: number } | Vec): Vec => Array.isArray(p) ? [round(p[0]), round(p[1])] : [round(p.x), round(p.y)];
+export const edgeKey = (a: number, b: number) => (a < b ? `${a}:${b}` : `${b}:${a}`);
+const isHullPair = (a: number, b: number, hull: number) => a < hull && b < hull && (Math.abs(a - b) === 1 || Math.abs(a - b) === hull - 1) && hull > 2;
+
+/** The original triangulation's unique edges; consecutive hull vertices (and the closing pair) are hull edges. */
+export function sourceEdges(source: Pick<MeshSource, 'triangles' | 'hull' | 'vertices'>): MeshEdge[] {
+  const seen = new Map<string, MeshEdge>(), n = source.vertices.length;
+  const add = (a: number, b: number) => { if (a === b || a < 0 || b < 0 || a >= n || b >= n) return; const key = edgeKey(a, b); if (!seen.has(key)) seen.set(key, { a: Math.min(a, b), b: Math.max(a, b), kind: isHullPair(a, b, source.hull) ? 'hull' : 'interior' }); };
+  for (let i = 0; i + 2 < source.triangles.length; i += 3) { const t = source.triangles; add(t[i]!, t[i + 1]!); add(t[i + 1]!, t[i + 2]!); add(t[i + 2]!, t[i]!); }
+  for (let i = 0; i < source.hull && source.hull > 2; i++) add(i, (i + 1) % source.hull);
+  return [...seen.values()];
+}
+
+const finiteVec = (v: unknown): v is Vec => Array.isArray(v) && v.length === 2 && v.every(n => typeof n === 'number' && Number.isFinite(n));
+const index = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+
+/** Replays ops over the source. Throws `MESH_EDIT_INVALID_OP` naming the first op that does not apply. */
+export function applyMeshOps(source: MeshSource, ops: readonly MeshOp[]): MeshView {
+  const view: MeshView = { vertices: source.vertices.map(v => [v[0], v[1]] as Vec), edges: [], removedEdges: [], added: new Set(), moved: new Map(), removed: new Set() };
+  const edges = new Map(sourceEdges(source).map(e => [edgeKey(e.a, e.b), { ...e }]));
+  const fail = (i: number, why: string): never => { throw new Error(`${MESH_EDIT_INVALID_OP}: op ${i} ${why}`); };
+  const live = (v: unknown, i: number): number => { if (!index(v) || v >= view.vertices.length || !view.vertices[v]) fail(i, `names no live vertex ${String(v)}`); return v as number; };
+  const removeEdge = (key: string) => { const edge = edges.get(key); if (edge) { edges.delete(key); view.removedEdges.push(edge); } };
+  ops.forEach((op, i) => {
+    switch (op?.op) {
+      case 'move': {
+        const v = live(op.v, i); if (!finiteVec(op.from) || !finiteVec(op.to)) fail(i, 'needs finite from/to');
+        if (!view.moved.has(v)) view.moved.set(v, [...view.vertices[v]!] as Vec);
+        view.vertices[v] = [op.to[0], op.to[1]]; break;
+      }
+      case 'add': {
+        if (!finiteVec(op.at)) fail(i, 'needs a finite at');
+        const id = view.vertices.length;
+        if (op.onEdge !== undefined) {
+          if (!Array.isArray(op.onEdge) || op.onEdge.length !== 2) fail(i, 'onEdge must be a pair');
+          const [a, b] = [live(op.onEdge![0], i), live(op.onEdge![1], i)], key = edgeKey(a, b), edge = edges.get(key);
+          if (!edge) fail(i, `splits a missing edge ${a}-${b}`);
+          edges.delete(key); view.vertices.push([op.at[0], op.at[1]]);
+          edges.set(edgeKey(a, id), { a: Math.min(a, id), b: Math.max(a, id), kind: edge!.kind });
+          edges.set(edgeKey(id, b), { a: Math.min(b, id), b: Math.max(b, id), kind: edge!.kind });
+        } else view.vertices.push([op.at[0], op.at[1]]);
+        view.added.add(id); break;
+      }
+      case 'remove': {
+        const v = live(op.v, i); view.vertices[v] = null; view.removed.add(v); view.moved.delete(v);
+        for (const [key, edge] of [...edges]) if (edge.a === v || edge.b === v) removeEdge(key);
+        break;
+      }
+      case 'edge': {
+        const a = live(op.a, i), b = live(op.b, i); if (a === b) fail(i, 'joins a vertex to itself');
+        if (edges.has(edgeKey(a, b))) fail(i, `duplicates edge ${a}-${b}`);
+        edges.set(edgeKey(a, b), { a: Math.min(a, b), b: Math.max(a, b), kind: 'constraint' }); break;
+      }
+      case 'unedge': {
+        const a = live(op.a, i), b = live(op.b, i), edge = edges.get(edgeKey(a, b));
+        if (!edge) fail(i, `removes a missing edge ${a}-${b}`); if (edge!.kind === 'hull') fail(i, `removes hull edge ${a}-${b}`);
+        removeEdge(edgeKey(a, b)); break;
+      }
+      default: fail(i, 'has an unknown op');
+    }
+  });
+  view.edges = [...edges.values()];
+  return view;
+}
+
+/** The ordered delta with per-action undo/redo. One user action (a drag of an edge or of a multi-selection) is one step of one or more ops. */
+export class MeshEditSession {
+  private list: MeshOp[] = [];
+  private steps: number[] = [];
+  private redoSteps: MeshOp[][] = [];
+  private current: MeshView;
+  constructor(readonly source: MeshSource, ops: readonly MeshOp[] = []) {
+    this.current = applyMeshOps(source, ops); this.list = ops.map(op => structuredClone(op)); this.steps = this.list.map(() => 1);
+  }
+  ops(): MeshOp[] { return this.list.map(op => structuredClone(op)); }
+  view(): MeshView { return this.current; }
+  canUndo(): boolean { return this.steps.length > 0; }
+  canRedo(): boolean { return this.redoSteps.length > 0; }
+  /** Records one step; refuses the whole step when any op does not apply. */
+  record(ops: readonly MeshOp[]): MeshEditResult {
+    if (!ops.length) return { ok: true, changed: false };
+    if (this.list.length + ops.length > MESH_EDIT_MAX_OPS) return { ok: false, code: `${MESH_EDIT_OPS_LIMIT}: at most ${MESH_EDIT_MAX_OPS} ops per attachment — download and reset to continue` };
+    let next: MeshView;
+    try { next = applyMeshOps(this.source, [...this.list, ...ops]); } catch (error) { return { ok: false, code: error instanceof Error ? error.message : String(error) }; }
+    this.list.push(...ops.map(op => structuredClone(op))); this.steps.push(ops.length); this.redoSteps = []; this.current = next;
+    return { ok: true, changed: true };
+  }
+  undo(): boolean {
+    const count = this.steps.pop(); if (count === undefined) return false;
+    this.redoSteps.push(this.list.splice(this.list.length - count, count));
+    this.current = applyMeshOps(this.source, this.list); return true;
+  }
+  redo(): boolean {
+    const ops = this.redoSteps.pop(); if (!ops) return false;
+    this.list.push(...ops); this.steps.push(ops.length); this.current = applyMeshOps(this.source, this.list); return true;
+  }
+  reset(): void { this.list = []; this.steps = []; this.redoSteps = []; this.current = applyMeshOps(this.source, []); }
+
+  /** Moves vertices by a crop-px offset from their positions at `base` (the drag's start view): one move op per vertex. */
+  moveOps(ids: readonly number[], dx: number, dy: number, base: MeshView = this.current): MeshOp[] {
+    if (!Number.isFinite(dx) || !Number.isFinite(dy) || (dx === 0 && dy === 0)) return [];
+    return [...new Set(ids)].flatMap(v => { const from = base.vertices[v]; if (!from) return []; const to = roundVec([from[0] + dx, from[1] + dy]); return to[0] === from[0] && to[1] === from[1] ? [] : [{ op: 'move' as const, v, from: [from[0], from[1]] as Vec, to }]; });
+  }
+  /** Create: a vertex on empty space, or a split of an edge at the click point. */
+  addVertex(at: Vec, onEdge?: [number, number]): MeshEditResult { return this.record([{ op: 'add', at: roundVec(at), ...(onEdge ? { onEdge: [onEdge[0], onEdge[1]] as [number, number] } : {}) }]); }
+  /** Delete on a vertex: the vertex and its edges. */
+  removeVertex(v: number): MeshEditResult { return this.record([{ op: 'remove', v }]); }
+  /** Delete on an edge: any edge but a hull edge. */
+  deleteEdge(a: number, b: number): MeshEditResult {
+    const edge = this.findEdge(a, b); if (!edge) return { ok: false, code: `${MESH_EDIT_INVALID_OP}: no edge ${a}-${b}` };
+    if (edge.kind === 'hull') return { ok: false, code: `${MESH_EDIT_HULL_EDGE}: ${a}-${b} is a hull edge and cannot be removed` };
+    return this.record([{ op: 'unedge', a, b }]);
+  }
+  /**
+   * Edges mode on a pair: a new pair adds a constraint edge; an existing constraint edge is removed; a hull edge is
+   * refused; any other existing edge is a duplicate and records nothing.
+   */
+  toggleConstraint(a: number, b: number): MeshEditResult {
+    if (a === b) return { ok: true, changed: false };
+    const edge = this.findEdge(a, b);
+    if (!edge) return this.record([{ op: 'edge', a, b }]);
+    if (edge.kind === 'hull') return { ok: false, code: `${MESH_EDIT_HULL_EDGE}: ${a}-${b} is a hull edge and cannot be removed` };
+    if (edge.kind === 'constraint') return this.record([{ op: 'unedge', a, b }]);
+    return { ok: true, changed: false, code: `${MESH_EDIT_EDGE_EXISTS}: ${a}-${b} is already a triangulation edge` };
+  }
+  findEdge(a: number, b: number): MeshEdge | undefined { const key = edgeKey(a, b); return this.current.edges.find(e => edgeKey(e.a, e.b) === key); }
+}
+
+export interface ScreenPoint { x: number; y: number }
+export type MeshHit = { kind: 'vertex'; v: number } | { kind: 'edge'; a: number; b: number; t: number; at: ScreenPoint };
+/** Screen-space hit test: the nearest vertex within the radius wins over any edge; then the nearest edge within 4 px. */
+export function hitMesh(points: readonly (ScreenPoint | null)[], edges: readonly Pick<MeshEdge, 'a' | 'b'>[], p: ScreenPoint, touch = false): MeshHit | null {
+  const radius = touch ? MESH_HIT.vertexTouch : MESH_HIT.vertex;
+  let best: MeshHit | null = null, bestDistance = Infinity;
+  points.forEach((q, v) => { if (!q) return; const d = Math.hypot(p.x - q.x, p.y - q.y); if (d <= radius && d < bestDistance) { best = { kind: 'vertex', v }; bestDistance = d; } });
+  if (best) return best;
+  for (const edge of edges) {
+    const a = points[edge.a], b = points[edge.b]; if (!a || !b) continue;
+    const dx = b.x - a.x, dy = b.y - a.y, length = dx * dx + dy * dy; if (length === 0) continue;
+    const t = Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / length)), at = { x: a.x + dx * t, y: a.y + dy * t }, d = Math.hypot(p.x - at.x, p.y - at.y);
+    if (d <= MESH_HIT.edge && d < bestDistance) { best = { kind: 'edge', a: edge.a, b: edge.b, t, at }; bestDistance = d; }
+  }
+  return best;
+}
+/** Vertex ids inside a screen rectangle (any corner order). */
+export function verticesInBox(points: readonly (ScreenPoint | null)[], from: ScreenPoint, to: ScreenPoint): number[] {
+  const [x0, x1] = [Math.min(from.x, to.x), Math.max(from.x, to.x)], [y0, y1] = [Math.min(from.y, to.y), Math.max(from.y, to.y)];
+  return points.flatMap((p, v) => p && p.x >= x0 && p.x <= x1 && p.y >= y0 && p.y <= y1 ? [v] : []);
+}
+
+/** A 2D affine map x' = a x + c y + e, y' = b x + d y + f. */
+export interface Affine { a: number; b: number; c: number; d: number; e: number; f: number }
+/** Samples an affine function at three points. */
+export function affineOf(fn: (x: number, y: number) => ScreenPoint): Affine {
+  const o = fn(0, 0), x = fn(1, 0), y = fn(0, 1);
+  return { a: x.x - o.x, b: x.y - o.y, c: y.x - o.x, d: y.y - o.y, e: o.x, f: o.y };
+}
+export function invertAffine(m: Affine): Affine | null {
+  const det = m.a * m.d - m.b * m.c; if (!Number.isFinite(det) || Math.abs(det) < 1e-12) return null;
+  return { a: m.d / det, b: -m.b / det, c: -m.c / det, d: m.a / det, e: (m.c * m.f - m.d * m.e) / det, f: (m.b * m.e - m.a * m.f) / det };
+}
+export const applyAffine = (m: Affine, x: number, y: number): ScreenPoint => ({ x: m.a * x + m.c * y + m.e, y: m.b * x + m.d * y + m.f });
+/** A screen-px offset as a crop-px offset through the inverse of crop → screen. */
+export function screenDeltaToCrop(cropToScreen: Affine, dx: number, dy: number): Vec | null {
+  const inverse = invertAffine(cropToScreen); if (!inverse) return null;
+  return [inverse.a * dx + inverse.c * dy, inverse.b * dx + inverse.d * dy];
+}
+
+/** The text hashed for `source.hash`: the attachment's entry from the hash-verified model, as `JSON.stringify` writes it. */
+export const attachmentHashText = (entry: unknown) => JSON.stringify(entry);
+
+export interface MeshEditDocument {
+  schema: typeof MESH_EDIT_SCHEMA;
+  slot: string; skin: string; attachment: string;
+  source: { vertexCount: number; triangleCount: number; hullLength: number; hash: string };
+  units: string; basis: string; preview: string;
+  ops: MeshOp[];
+}
+export function meshEditDocument(session: MeshEditSession, basis: string): MeshEditDocument {
+  const s = session.source;
+  return {
+    schema: MESH_EDIT_SCHEMA, slot: s.slot, skin: s.skin, attachment: s.attachment,
+    source: { vertexCount: s.vertices.length, triangleCount: Math.floor(s.triangles.length / 3), hullLength: s.hull, hash: s.hash },
+    units: 'crop px, x right, y down; vertex ids are source indices, added vertices take the next id in op order, removed ids are not reused',
+    basis, preview: `${MESH_EDIT_PREVIEW_NOTE}; the ops are a request over the original triangulation, not a mesh`,
+    ops: session.ops(),
+  };
+}
+export function meshEditBinding(input: { fileSha256: string; sourceHash: string; reviewedSource: { viewerVersion: string; runtimeVersion: string; rig: { sha256: string } | null; motion: { sha256: string } | null }; exportedAt: string; mapping: string; attachment: { slot: string; skin: string; name: string; sha256: string } }) {
+  return {
+    schema: MESH_EDIT_BINDING_SCHEMA,
+    file: { name: 'mesh-edit.json', sha256: input.fileSha256 },
+    package: input.sourceHash,
+    model: input.reviewedSource.rig?.sha256 ?? null,
+    motion: input.reviewedSource.motion?.sha256 ?? null,
+    attachment: { ...input.attachment },
+    exportedAt: input.exportedAt,
+    tools: { viewerVersion: input.reviewedSource.viewerVersion, runtimeVersion: input.reviewedSource.runtimeVersion },
+    mapping: input.mapping,
+    evidence: 'Mesh edit is review evidence, not an approval. Nothing was written into the package; retriangulation and regeneration are the producer path.',
+  };
+}
+
+/** Draft: per attachment, the ops bound to the attachment hash. A draft for another hash is not restored. */
+export interface MeshEditDraft { schema: typeof MESH_EDIT_DRAFT_SCHEMA; entries: Record<string, { hash: string; ops: MeshOp[] }> }
+export const draftKey = (s: Pick<MeshSource, 'slot' | 'skin' | 'attachment'>) => `${s.skin}/${s.slot}/${s.attachment}`;
+export function parseMeshDraft(text: string): MeshEditDraft {
+  const empty: MeshEditDraft = { schema: MESH_EDIT_DRAFT_SCHEMA, entries: {} };
+  if (!text.trim()) return empty;
+  let value: unknown; try { value = JSON.parse(text); } catch { return empty; }
+  const o = value as Partial<MeshEditDraft> | null;
+  if (!o || typeof o !== 'object' || o.schema !== MESH_EDIT_DRAFT_SCHEMA || !o.entries || typeof o.entries !== 'object' || Array.isArray(o.entries)) return empty;
+  const entries: MeshEditDraft['entries'] = {};
+  for (const [key, entry] of Object.entries(o.entries)) {
+    if (['__proto__', 'constructor', 'prototype'].includes(key) || !entry || typeof entry.hash !== 'string' || !/^[a-f0-9]{64}$/.test(entry.hash) || !Array.isArray(entry.ops) || entry.ops.length > MESH_EDIT_MAX_OPS) continue;
+    entries[key] = { hash: entry.hash, ops: entry.ops as MeshOp[] };
+  }
+  return { schema: MESH_EDIT_DRAFT_SCHEMA, entries };
+}
+/** Ops a draft holds for this source, or null when the draft has none or names another hash / an op that does not apply. */
+export function draftOps(draft: MeshEditDraft, source: MeshSource): MeshOp[] | null {
+  const entry = draft.entries[draftKey(source)]; if (!entry || entry.hash !== source.hash) return null;
+  try { applyMeshOps(source, entry.ops); return entry.ops; } catch { return null; }
+}
+export function writeMeshDraft(draft: MeshEditDraft, source: MeshSource, ops: readonly MeshOp[]): string {
+  const entries = { ...draft.entries }; const key = draftKey(source);
+  if (ops.length) entries[key] = { hash: source.hash, ops: ops.map(op => structuredClone(op)) }; else delete entries[key];
+  return Object.keys(entries).length ? JSON.stringify({ schema: MESH_EDIT_DRAFT_SCHEMA, entries }) : '';
+}

package/src/session.ts

@@ -5,6 +5,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { homedir } from 'node:os';
 import {referenceBinding,type ReferenceBinding} from './reference.ts';
 import { validateFeedbackSelection } from './feedback-validation.ts';
+import { parseEnvironmentContext } from './environment.ts';
 import { choice, object, string, type Json, type ReviewPackage, type ReviewedSource } from './manifest.ts';
 export interface Feedback {id:string;frameStart:number;frameEnd:number;target:{kind:'bone'|'slot'|'rig';name:string};category:'defect'|'quality';summary:string;context?:Json}
 export function parseFeedback(item:unknown,strict=true):Feedback {
@@ -25,6 +26,8 @@ export function validatePackageFeedback(feedback:Feedback,p:ReviewPackage,animat
   if(context.interval!==undefined&&!isDeepStrictEqual(context.interval,interval))throw new Error('feedback.context.interval: must match chosen inclusive frameStart/frameEnd');
   if(context.animation!==undefined&&context.animation!==null&&typeof context.animation!=='string')throw new Error('feedback.context.animation: expected animation name or null');
   if(animation!==undefined&&context.animation!==undefined&&context.animation!==null&&context.animation!==animation)throw new Error('feedback.context.animation: does not match selected comparison animation');
+  // Older records without an environment stay valid; a present one must have the recorded shape.
+  if(context.environment!==undefined)parseEnvironmentContext(context.environment);
   const selected=animation??(typeof context.animation==='string'?context.animation:null);
   validateFeedbackSelection(p.feedbackCatalog,{frameStart:feedback.frameStart,frameEnd:feedback.frameEnd,target:feedback.target,animation:selected});
   return {...feedback,context:{...context,...(animation===undefined?{}:{animation}),interval} as Json};

package/web/chest-editor.ts

@@ -0,0 +1,179 @@
+/**
+ * The chest-region editor (Setup): a view-bar toggle, an editor bar of R / L circles and direct manipulation of the
+ * circles on the rig pane. The values live in the Chest regions detail block's fields (row 0 = R, row 1 = L), so the
+ * draft, export and binding are the detail block's. Review never regenerates anything: Apply · Rebuild refuses by name.
+ */
+import {clampNonOverlapping,CHEST_CIRCLE_LIMITS,type ChestCircle,type CropWorldMapping} from '../src/chest-regions.ts';
+import {chestRowId,type ChestFieldReader} from './chest-regions-tool.ts';
+import {projectCircle,type OverlayPoint,type OverlayProject} from './rig-overlays.ts';
+import {textEntryFocused} from './view-controls.ts';
+
+export type BustSide='r'|'l';
+export type BustMode='move'|'r'|'band';
+export const bustSides=[{side:'r',row:0,tag:'R'},{side:'l',row:1,tag:'L'}] as const;
+export const bustFields=['x','y','r','band'] as const;
+export const bustInputId=(side:BustSide,field:typeof bustFields[number])=>`bust-${side}-${field}`;
+export const MODELING_INPUT_UNAVAILABLE='MODELING_INPUT_UNAVAILABLE: no producer handoff — export the JSON and rebuild with the producer';
+export const CHEST_REGIONS_CLAMPED='CHEST_REGIONS_CLAMPED';
+const sideRow=(side:BustSide)=>side==='r'?0:1;
+const sideTag=(side:BustSide)=>side==='r'?'R':'L';
+
+/** The toggle belongs to Setup only. */
+export function chestEditVisible(inspector:string|undefined):boolean {return inspector==='rig';}
+
+const number=(read:ChestFieldReader,id:string)=>{const raw=(read(id)?.value??'').trim();if(!raw)return null;const value=Number(raw);return Number.isFinite(value)?value:null;};
+/** A row is a circle when its semi-axes are equal and it has no medial clip; then r is that semi-axis. */
+export function rowCircle(read:ChestFieldReader,row:number):ChestCircle|null {
+ const cx=number(read,chestRowId(row,'cx')),cy=number(read,chestRowId(row,'cy')),ax=number(read,chestRowId(row,'ax')),ay=number(read,chestRowId(row,'ay')),band=number(read,chestRowId(row,'band'));
+ if(cx===null||cy===null||ax===null||band===null||ax<=0||ay!==ax||(read(chestRowId(row,'clip'))?.value??'').trim())return null;
+ return {cx,cy,r:ax,band};
+}
+/** Field values that store a circle in a detail row: r writes both semi-axes. */
+export function circleFields(row:number,circle:Partial<ChestCircle>):Record<string,string> {
+ const out:Record<string,string>={};
+ if(circle.cx!==undefined)out[chestRowId(row,'cx')]=String(circle.cx);
+ if(circle.cy!==undefined)out[chestRowId(row,'cy')]=String(circle.cy);
+ if(circle.r!==undefined){out[chestRowId(row,'ax')]=String(circle.r);out[chestRowId(row,'ay')]=String(circle.r);}
+ if(circle.band!==undefined)out[chestRowId(row,'band')]=String(circle.band);
+ return out;
+}
+export const bustLabel=(side:BustSide,c:ChestCircle)=>`${sideTag(side)} (${Math.round(c.cx)},${Math.round(c.cy)}) r:${Math.round(c.r)} b:${Math.round(c.band)}`;
+
+export interface ProjectedBust {side:BustSide;center:OverlayPoint;pxR:number;pxBand:number}
+/** The example's hit order: core handle or core edge → r, band handle or outer edge → band, inside the core → move. */
+export function hitBustHandle(circles:readonly ProjectedBust[],p:OverlayPoint):{side:BustSide;mode:BustMode}|null {
+ for(const c of circles){
+  const toR=Math.hypot(p.x-(c.center.x+c.pxR),p.y-c.center.y),toBand=Math.hypot(p.x-c.center.x,p.y-(c.center.y-c.pxBand)),toCenter=Math.hypot(p.x-c.center.x,p.y-c.center.y);
+  if(toR<=10||Math.abs(toCenter-c.pxR)<=6)return {side:c.side,mode:'r'};
+  if(toBand<=10||Math.abs(toCenter-c.pxBand)<=6)return {side:c.side,mode:'band'};
+  if(toCenter<=Math.max(12,c.pxR))return {side:c.side,mode:'move'};
+ }
+ return null;
+}
+const limit=(value:number,[low,high]:readonly [number,number])=>Math.max(low,Math.min(high,value));
+export interface BustDrag {side:BustSide;mode:BustMode;start:OverlayPoint;centre:OverlayPoint;from:ChestCircle}
+/** Pointer (canvas px) → source px through the camera scale (canvas px per source px), rounded as the example does. */
+export function dragBust(drag:BustDrag,p:OverlayPoint,scale:number):ChestCircle {
+ const from=drag.from;if(!(scale>0)||!Number.isFinite(scale))return {...from};
+ if(drag.mode==='move')return {...from,cx:Math.round(from.cx+(p.x-drag.start.x)/scale),cy:Math.round(from.cy+(p.y-drag.start.y)/scale)};
+ const distance=Math.hypot(p.x-drag.centre.x,p.y-drag.centre.y)/scale;
+ if(drag.mode==='r')return {...from,r:limit(Math.round(distance),CHEST_CIRCLE_LIMITS.r)};
+ return {...from,band:limit(Math.round(distance-from.r),CHEST_CIRCLE_LIMITS.band)};
+}
+/** Mirror: L takes R's y, core radius and band; L keeps its own x. */
+export const mirrorBust=(right:ChestCircle,left:Pick<ChestCircle,'cx'>):ChestCircle=>({cx:left.cx,cy:right.cy,r:right.r,band:right.band});
+const same=(a:ChestCircle,b:ChestCircle)=>a.cx===b.cx&&a.cy===b.cy&&a.r===b.r&&a.band===b.band;
+/** Live non-overlap clamp for a pair of circles; names the sides it changed. */
+export function settleBust(right:ChestCircle,left:ChestCircle):{right:ChestCircle;left:ChestCircle;clamped:BustSide[]} {
+ const out=clampNonOverlapping(right,left),round=clampNonOverlapping(right,left,-Infinity);
+ // `round` is the same integer/range pass without the distance rule (−∞ margin leaves every pair fitting), so only the non-overlap change flashes.
+ return {right:out.right,left:out.left,clamped:(['r','l'] as const).filter(side=>!same(side==='r'?out.right:out.left,side==='r'?round.right:round.left))};
+}
+/** Apply · Rebuild: review has no producer handoff (#45), so it refuses by name and runs nothing. */
+export function requestRebuild(notify:(text:string,error:boolean)=>void):{ok:false;error:string} {
+ notify(MODELING_INPUT_UNAVAILABLE,true);return {ok:false,error:MODELING_INPUT_UNAVAILABLE};
+}
+
+export interface ChestEditorHost {
+ /** Receives capture-phase pointer events before the viewport's pan. */
+ pane:HTMLElement;
+ /** The overlay canvas: pointer coordinates are local to it, as the projection's are. */
+ canvas:HTMLElement;
+ project:()=>OverlayProject|null;
+ mapping:()=>CropWorldMapping;
+ /** Re-render the detail block and the overlay after a value changed. */
+ changed:()=>void;
+ download:()=>void;
+ message:(text:string,error?:boolean)=>void;
+ inspector:()=>string|undefined;
+}
+export interface ChestEditor {active:()=>boolean;flashing:(side:BustSide)=>boolean;sync:()=>void;dispose:()=>void}
+
+export function bindChestEditor(host:ChestEditorHost):ChestEditor {
+ const node=<T extends HTMLElement>(id:string)=>document.getElementById(id) as T;
+ const toggle=node<HTMLButtonElement>('chest-edit'),bar=node<HTMLElement>('chest-editor-bar'),status=node<HTMLElement>('chest-editor-status');
+ const field=(id:string)=>document.getElementById(id) as HTMLInputElement|null;
+ const read:ChestFieldReader=id=>{const f=field(id);return f?{value:f.value}:undefined;};
+ let active=false,space=false,drag:(BustDrag&{pointer:number;other:ChestCircle|null})|null=null,flashTimer:ReturnType<typeof setTimeout>|null=null;
+ const flash=new Set<BustSide>();
+ const write=(row:number,circle:Partial<ChestCircle>)=>{for(const [id,value] of Object.entries(circleFields(row,circle))){const f=field(id);if(f)f.value=value;}};
+ const flashSides=(sides:readonly BustSide[])=>{
+  if(!sides.length)return;for(const side of sides)flash.add(side);
+  host.message(`${CHEST_REGIONS_CLAMPED}: ${sides.map(sideTag).join(' and ')} — both cores plus 8 px must fit the centre distance minus 2 px and the bands share the rest`,true);
+  if(flashTimer)clearTimeout(flashTimer);flashTimer=setTimeout(()=>{flash.clear();flashTimer=null;host.changed();},700);
+ };
+ /** Writes a changed side; when both rows are circles the pair is clamped as the rebuild script would. */
+ const commit=(side:BustSide,next:ChestCircle,other:ChestCircle|null)=>{
+  if(!other){write(sideRow(side),next);return;}
+  const [right,left]=side==='r'?[next,other]:[other,next],settled=settleBust(right,left);
+  write(0,settled.right);write(1,settled.left);flashSides(settled.clamped);
+ };
+ const projected=():ProjectedBust[]=>{
+  const project=host.project(),mapping=host.mapping();if(!project||!mapping.available)return [];
+  return bustSides.flatMap(({side,row})=>{const c=rowCircle(read,row);if(!c)return [];const at=projectCircle(project,{center:mapping.toWorld(c.cx,c.cy),r:c.r,band:c.band});return at?[{side,...at}]:[];});
+ };
+ const local=(event:PointerEvent):OverlayPoint=>{const rect=host.canvas.getBoundingClientRect();return {x:event.clientX-rect.left,y:event.clientY-rect.top};};
+ const scale=()=>{const project=host.project();if(!project)return 0;const a=project(0,0),b=project(1,0);return Math.hypot(b.x-a.x,b.y-a.y);};
+ const sync=()=>{
+  const visible=chestEditVisible(host.inspector());toggle.hidden=!visible;
+  if(!visible&&active)setActive(false);
+  for(const {side,row} of bustSides){
+   const circle=rowCircle(read,row),values={x:read(chestRowId(row,'cx'))?.value??'',y:read(chestRowId(row,'cy'))?.value??'',r:circle?String(circle.r):'',band:read(chestRowId(row,'band'))?.value??''};
+   for(const f of bustFields){const input=field(bustInputId(side,f));if(input&&document.activeElement!==input)input.value=values[f];}
+   const r=field(bustInputId(side,'r'));if(r)r.placeholder=circle||!(read(chestRowId(row,'ax'))?.value??'').trim()?'':'ellipse';
+  }
+  const mapping=host.mapping();
+  status.textContent=mapping.available?'Drag a centre to move · the right-edge handle sets r · the dashed top handle sets band · Space-drag pans':`${mapping.reason} — the values still edit and export; nothing is drawn on the stage.`;
+  status.classList.toggle('error',!mapping.available);
+ };
+ const setActive=(on:boolean)=>{active=on;toggle.setAttribute('aria-pressed',String(on));bar.hidden=!on;if(!on){drag=null;delete host.pane.dataset.chestHover;}sync();host.changed();};
+ toggle.addEventListener('click',()=>setActive(!active));
+ bar.addEventListener('input',event=>{
+  const target=event.target as HTMLInputElement,match=/^bust-([rl])-(x|y|r|band)$/.exec(target.id);if(!match)return;
+  const value=Number(target.value);if(!target.value.trim()||!Number.isFinite(value))return;
+  const side=match[1] as BustSide,key=({x:'cx',y:'cy',r:'r',band:'band'} as const)[match[2] as typeof bustFields[number]];
+  write(sideRow(side),{[key]:value});host.changed();
+ });
+ bar.addEventListener('change',event=>{
+  const target=event.target as HTMLInputElement,match=/^bust-([rl])-/.exec(target.id);if(!match)return;
+  const side=match[1] as BustSide,mine=rowCircle(read,sideRow(side)),other=rowCircle(read,sideRow(side==='r'?'l':'r'));
+  if(mine)commit(side,{...mine,r:limit(Math.round(mine.r),CHEST_CIRCLE_LIMITS.r),band:limit(Math.round(mine.band),CHEST_CIRCLE_LIMITS.band)},other);
+  sync();host.changed();
+ });
+ node<HTMLButtonElement>('bust-mirror').addEventListener('click',()=>{
+  const right=rowCircle(read,0),leftX=Number((read(chestRowId(1,'cx'))?.value??'').trim()||NaN);
+  if(!right||!Number.isFinite(leftX)){host.message('Mirror needs a complete R circle and an L x.',true);return;}
+  commit('l',mirrorBust(right,{cx:leftX}),right);sync();host.changed();
+ });
+ node<HTMLButtonElement>('bust-download').addEventListener('click',()=>host.download());
+ node<HTMLButtonElement>('bust-apply').addEventListener('click',()=>{const result=requestRebuild((text,error)=>host.message(text,error));status.textContent=result.error;status.classList.add('error');});
+ const keyDown=(event:KeyboardEvent)=>{if(event.code==='Space'&&!textEntryFocused(event.target))space=true;};
+ const keyUp=(event:KeyboardEvent)=>{if(event.code==='Space')space=false;};
+ const blur=()=>{space=false;};
+ const down=(event:PointerEvent)=>{
+  if(!active||space||!event.isPrimary||event.button!==0)return;
+  const target=event.target;if(target instanceof Element&&target.closest('button,input,select,textarea,a'))return;
+  const p=local(event),circles=projected(),hit=hitBustHandle(circles,p);if(!hit)return;
+  const row=sideRow(hit.side),from=rowCircle(read,row),at=circles.find(c=>c.side===hit.side);if(!from||!at)return;
+  // A handle drag edits values; it never reaches the viewport's pan and never moves the camera.
+  event.stopPropagation();event.preventDefault();
+  drag={side:hit.side,mode:hit.mode,start:p,centre:at.center,from,pointer:event.pointerId,other:rowCircle(read,sideRow(hit.side==='r'?'l':'r'))};
+  host.pane.setPointerCapture(event.pointerId);host.pane.dataset.chestHover=hit.mode;
+ };
+ const move=(event:PointerEvent)=>{
+  if(drag&&event.pointerId===drag.pointer){event.stopPropagation();commit(drag.side,dragBust(drag,local(event),scale()),drag.other);sync();host.changed();return;}
+  if(active&&!space&&!drag){const hit=hitBustHandle(projected(),local(event));if(hit)host.pane.dataset.chestHover=hit.mode;else delete host.pane.dataset.chestHover;}
+ };
+ const end=(event:PointerEvent)=>{if(!drag||event.pointerId!==drag.pointer)return;drag=null;delete host.pane.dataset.chestHover;if(host.pane.hasPointerCapture(event.pointerId))host.pane.releasePointerCapture(event.pointerId);host.changed();};
+ host.pane.addEventListener('pointerdown',down,true);host.pane.addEventListener('pointermove',move,true);
+ for(const type of ['pointerup','pointercancel','lostpointercapture'] as const)host.pane.addEventListener(type,end,true);
+ document.addEventListener('keydown',keyDown,true);window.addEventListener('keyup',keyUp,true);window.addEventListener('blur',blur);
+ // The selected section is the header switch's pressed state; follow it without touching the switch's own wiring.
+ const observer=new MutationObserver(()=>sync());
+ for(const selector of document.querySelectorAll('[data-inspector]'))observer.observe(selector,{attributes:true,attributeFilter:['aria-pressed','aria-selected']});
+ sync();
+ return {
+  active:()=>active,flashing:side=>flash.has(side),sync,
+  dispose:()=>{observer.disconnect();if(flashTimer)clearTimeout(flashTimer);host.pane.removeEventListener('pointerdown',down,true);host.pane.removeEventListener('pointermove',move,true);for(const type of ['pointerup','pointercancel','lostpointercapture'] as const)host.pane.removeEventListener(type,end,true);document.removeEventListener('keydown',keyDown,true);window.removeEventListener('keyup',keyUp,true);window.removeEventListener('blur',blur);},
+ };
+}

package/web/chest-regions-tool.ts

@@ -44,8 +44,13 @@ export function evaluateChestForm(read:ChestFieldReader,mapping:CropWorldMapping
  catch(error){if(error instanceof ChestRegionError)return {ok:false,error:error.message};throw error;}
 }
 
-/** Polygons in rig world coordinates for the overlay; none without a model-fixed mapping. */
-export function chestOverlayPolygons(evaluation:ChestEvaluation,mapping:CropWorldMapping):{name:string;points:{x:number;y:number}[]}[] {
+/** Polygon regions in rig world coordinates for the overlay; none without a model-fixed mapping. Circles are drawn as circles. */
+export function chestOverlayPolygons(evaluation:ChestEvaluation,mapping:CropWorldMapping):{name:string;row:number;points:{x:number;y:number}[]}[] {
  if(!evaluation.ok||!mapping.available)return [];
- return evaluation.document.mesh.value.contour.regions.map(region=>({name:region.name,points:region.points.map(([x,y])=>mapping.toWorld(x,y))}));
+ return evaluation.document.mesh.value.contour.regions.flatMap((region,row)=>region.shape==='polygon'?[{name:region.name,row,points:region.points.map(([x,y])=>mapping.toWorld(x,y))}]:[]);
+}
+/** Circle regions of a valid designation: world centre, core r and band (crop px = world px under the mapping). */
+export function chestOverlayCircles(evaluation:ChestEvaluation,mapping:CropWorldMapping):{name:string;row:number;center:{x:number;y:number};r:number;band:number}[] {
+ if(!evaluation.ok||!mapping.available)return [];
+ return evaluation.document.mesh.value.contour.regions.flatMap((region,row)=>region.shape==='circle'?[{name:region.name,row,center:mapping.toWorld(region.cx,region.cy),r:region.r,band:region.band}]:[]);
 }