@rig-c/review 0.4.0 → 0.5.0

package/README.md

@@ -69,7 +69,7 @@ Compare feedback requires side `a` or `b` and carries both package source hashes
 
 ## Feedback ownership
 
-Opening leaves status **pending**. The person explicitly saves **approved**, **changes-requested**, or **pending**, checkpoint outcomes/notes, and feedback containing an inclusive frame interval, a bone/slot/rig target, defect/quality category and one-line summary. Frame numbers are entered explicitly; the app does not invent a source FPS. The primary **리뷰 제출** action saves that explicit status and feedback. JSON and issue-ready Markdown exports carry the original source binding and reproducible inspection context. Each submission records `reviewedSource`: package revision, actual viewer/runtime versions, and separate exact-byte SHA-256 plus path for the reviewed rig and motion; an absent artifact stays null. An active compiled model is the rig identity; raw skeleton JSON is evidence with playback unavailable.
+Opening leaves status **pending**. The person explicitly saves **approved**, **changes-requested**, or **pending**, checkpoint outcomes/notes, and feedback containing an inclusive frame interval, a bone/slot/rig target, defect/quality category and one-line summary. Frame numbers are entered explicitly; the app does not invent a source FPS. **Write review**, at the top right, opens the review dialog: review status, reviewed source, selected checkpoint, structured feedback and the frame-strip export. Its **Submit review** saves that explicit status and feedback; closing the dialog keeps the unsubmitted draft. The page has no feedback export buttons: `rig-review feedback --format json` and `--format issue` (below) are the export path, and carry the original source binding and reproducible inspection context. Each submission records `reviewedSource`: package revision, actual viewer/runtime versions, and separate exact-byte SHA-256 plus path for the reviewed rig and motion; an absent artifact stays null. An active compiled model is the rig identity; raw skeleton JSON is evidence with playback unavailable.
 
 New submissions validate bone/slot names against the exact loaded model; the target field offers those names. A rig target names the package id. Source-only packages cannot validate a bone/slot target and say so explicitly. When a matching animation has a declared producer clock, the inclusive interval cannot end beyond the last declared sample at or before the actual clip end. Unknown clocks keep manual frame intervals without inventing a limit. `context.interval` records the chosen interval; inspection `time`/`frame` remain separate. Older invalid feedback stays readable with per-row warnings and exports its original evidence, but cannot be resubmitted until corrected or removed.
 
@@ -93,7 +93,7 @@ rig-review feedback /absolute/output --reference /absolute/original.mp4 --format
 rig-review feedback /absolute/a --compare /absolute/b --reference /absolute/original.mp4 --animation dance --format issue
 ```
 
-The header counts feedback records by defect/quality and by build; blocks group by category, then exact target kind/name. Overlapping intervals and A/B sides remain distinct items. Each block retains its id, inclusive interval, one-line summary and selected/full paired provenance. Historical tool identities and validation warnings remain visible; output never migrates approval, writes state or publishes an issue. Default output and `--format json` remain the existing session JSON. Only feedback accepts `--format`, with `json` or `issue` as its value.
+The header counts feedback records by defect/quality and by build; blocks group by category, then exact target kind/name. Overlapping intervals and A/B sides remain distinct items. Each block retains its id, inclusive interval, one-line summary and selected/full paired provenance. Historical tool identities and validation warnings remain visible; output never migrates approval, writes state or publishes an issue. Default output and `--format json` remain the existing session JSON. Only feedback accepts `--format`, with `json` or `issue` as its value. These two formats are how submitted feedback leaves the tool; the browser page offers no JSON or Markdown download.
 
 ## Development
 
@@ -334,7 +334,9 @@ active pane, and each canonical camera center with visible bounds. Reloading a m
 it does not restart an idle loop or submit a review. Coordinates adapt to the
 current viewport instead of replaying another window's CSS pan offsets.
 Historical links without a sync mode restore with sync off to preserve their
-saved views; fresh inspections start with sync on. Legacy modeling/motion
+saved views; fresh inspections start with sync on. The page keeps the current
+fragment in the address bar as you inspect, so copying the address copies the
+view; there is no separate copy button. Legacy modeling/motion
 workspace selections are accepted without restoring a top-level workspace switch. A link
 for a different source binding is refused.
 
@@ -354,25 +356,45 @@ or corrupt saved data remains available to download, with an explicit warning;
 recovering a conflicting draft requires choosing a pending review. Storage
 errors never count as a successful save. Nothing is written to the server or
 input package merely by restoring a page. Browser storage is convenient local
-recovery, not a durable backup; export feedback separately when it must be kept.
+recovery, not a durable backup; submit the review (and retrieve it with
+`rig-review feedback`) when it must be kept.
 Control capabilities are excluded from links and browser persistence.
 
 ## Workspace settings and panels
 
 The review page has a left column (Parts explorer, with checkpoints and the
 reference select folded above it), the stage, the Inspector below it with
-**Setup**, **Animate** and **Feedback** sections, and a status footer. The
-compare page keeps sources on the left and the Parts explorer on the right.
-
-The view bar keeps the layer toggles in reach in every section: **Images**
+**Setup** and **Animate** sections, and a status footer. The compare page
+keeps sources on the left and the Parts explorer on the right. The page
+header carries the **Setup** / **Animate** mode switch next to the package
+title; it is the only way to change the Inspector's section. Setup is the
+mesh-review composition (selected part, part presets, modeling-review
+proposals) and holds nothing that seeks or plays; the angle inspection, the
+transport and frame navigation are in Animate. **Write review** at the top
+right opens the review dialog, a modal holding the review status, reviewed
+source, selected checkpoint, structured feedback and frame-strip export, with
+its own **Submit review**. Escape or Close dismisses it and returns focus to
+**Write review**; the draft keeps saving whether the dialog is open or not,
+and the footer and the dialog both show its state.
+The left column's header (Parts title and search) stays fixed at the top;
+the checkpoint strip, the part list and Settings scroll beneath it as one
+body. A drawer keeps its title and close button in place while its body
+scrolls. The per-inspection **Repeat idle** toggle sits in the Animate
+transport row.
+
+The view bar is one row and keeps the layer toggles in reach in every section: **Images**
 (`I`), **Mesh edges** (`M`) and **Bone points** (`B`). The keys do nothing while
 a text field, textarea, select or editable text has focus, with Ctrl/Alt/Cmd
 held, or on key repeat; Space stays pan and Enter stays frame entry. A disabled
 toggle shows why as a tooltip, and the footer shows the same layer status. The
 footer also gathers the message, player, layout, renderer, idle, remote control
-and draft state; **View region** opens the numeric view.
+and draft state; **View region** opens the numeric view. Side by side,
+Reference and Rig are in the **View** menu at the right end of the view bar,
+labelled with the current choice.
 
-The side and bottom panels are resizable. Drag a separator, or focus it
+The side and bottom panels are resizable. The separators are thin (4px)
+lines whose colour is never the scrollbar's; the grab area is wider than the
+line. Drag a separator, or focus it
 and use the arrow keys (Shift for larger steps) and Home/End. Escape, a
 cancelled pointer or window blur during a drag returns the previous size. The
 stage keeps a usable minimum. When the window is too narrow, the side columns
@@ -380,9 +402,11 @@ stage keeps a usable minimum. When the window is too narrow, the side columns
 drawers opened from buttons above the stage instead of shrinking to nothing. Responsive clamping
 never overwrites the desired size, so a wider window restores it.
 
-Settings, at the bottom of the left column, holds browser defaults: Theme, Sync cameras by
+Settings, at the end of the left column's scrolling body, holds browser defaults: Theme, Sync cameras by
 default, Repeat idle by default, and Reset layout. Defaults seed a new
-inspection only. A view link or source draft keeps its own appearance, camera
+inspection only. Theme is the page's only appearance control: it shows the
+current inspection's appearance, and changing it applies it and saves it as the
+default. A view link or source draft keeps its own appearance, camera
 sync and idle choice, and restoring it neither changes the saved defaults nor
 starts playback. Reset layout restores panel sizes and nothing else.
 
@@ -413,6 +437,16 @@ Source-bound links/drafts and explicit feedback preserve that side/slot plus exa
 
 This explorer is inspection. Producer-backed optimization and candidate Apply/undo/export remain separate work; the explorer does not generate mesh, rig or motion bytes.
 
+## Chest regions (designation only)
+
+Setup's **Chest regions** tool records two chest deformation regions in the public generator's `family-chest-regions/1` schema: per region a name, a bone chosen from the loaded model's actual bones, a core centre and semi-axes, a spacing, a linear band and an optional medial clip x, plus the contour settings (tolerance, margin, spacing, max edge, stray, bridges). Values are crop pixels, x screen-right and y down. The fields are numeric only; there are no drag handles.
+
+Each core is drawn on the rig pane as the generator's 32-sample polygon on its 1/256-pixel grid. The overlay needs the loaded model to fix the crop: its declared stage must be the crop frame with the root at its bottom centre (`x = -width/2`, `y = 0`) and the drawn root bone must sit at the world origin, so crop `(x, y)` is world `(x - width/2, height - y)`. Otherwise the tool shows `CHEST_REGION_MAPPING_UNAVAILABLE: <what is missing>`, draws nothing and still exports from a crop size you enter.
+
+**Download chest-regions.json** saves two files in the browser: `chest-regions.json`, formatted exactly as the public example files, and `chest-regions.binding.json`, which names the package source hash, the rig and motion SHA-256 values, the export time, the viewer and runtime versions and the mapping used. Export refuses `CHEST_REGION_NAME_DUPLICATE`, `CHEST_REGION_BONE_UNKNOWN <bone>`, `CHEST_REGION_OUT_OF_CROP <name>`, `CHEST_REGION_OFF_GRID` and `CHEST_REGIONS_OVERLAP <a> <b>`. The overlap test is geometric: two regions are refused when the distance between their polygons is less than the sum of their bands. The generator refuses per mesh vertex, so this check can refuse a pair it would accept, never the reverse.
+
+Field values stay in the inspection's local draft. They never enter the review session's feedback, nothing is written into the package, and an export is review evidence, not an approval. Regenerating a mesh from these regions is the producer's job (see `docs/DESIGN.md`).
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/docs/DESIGN.md

@@ -4,7 +4,7 @@
 
 The delivery unit is an existing output folder or an optional curated review package handed from an agent to a person. This reusable app owns inspection, reference comparison, annotations and feedback export. Upstream compiler, splitter and runtime remain their respective tools. The existing producing agent needs no change to open its output here.
 
-The person uses one inspection workspace with **Setup**, **Animate** and **Feedback** sections (the compare page keeps **View**, **Rig**, **Playback** and **Feedback**). Setup covers setup geometry, source art, pivot/joint placement, meshes, weights, draw order and angle coverage; Animate covers frame intervals, reference video/poses, contact/deformation and audio inspection. Motion is strictly **view, annotate and export**: time/angle controls navigate inspection. This app does not author animation keys, retime motion or write `motion.json`. Future modeling touch-up remains in scope as a design goal; it is not implemented by this starter.
+The person uses one inspection workspace with **Setup** and **Animate** sections and a review dialog for feedback (the compare page keeps **View**, **Rig**, **Playback** and **Feedback** sections). Setup covers setup geometry, source art, pivot/joint placement, meshes, weights and draw order; Animate covers angle coverage, frame intervals, reference video/poses, contact/deformation and audio inspection. Motion is strictly **view, annotate and export**: time/angle controls navigate inspection. This app does not author animation keys, retime motion or write `motion.json`. Future modeling touch-up remains in scope as a design goal; it is not implemented by this starter.
 
 ## Implemented foundation
 
@@ -38,12 +38,15 @@ Any future modeling edit needs provenance, undo/redo, explicit units and an expo
 
 The single review page is one inspection workspace: a left column, the stage, the Inspector under the stage and one status footer. There is no right panel.
 
-- **Left column.** The Parts explorer fills it. Checkpoints, the current checkpoint title and the reference select fold into a compact strip above the part list; the strip opens when the package supplies checkpoints or references and stays folded for a plain output folder. Browser Settings sit at the bottom.
-- **View bar.** Pane choice, the persistent image / mesh edges / bone points layer toggles (keys `I`, `M`, `B`), camera sync and zoom, then appearance, repeat idle and Copy view link at the right end. The toggles stay native checkboxes, so their checked state is the pressed state, the draft input and the `layers` control value. A disabled toggle names the footer's layer reason as its tooltip. Turning images off leaves the mesh/bone overlay alone.
-- **Inspector.** Three sections: **Setup** (selected part, part presets, modeling-review proposals, angle panel), **Animate** (transport, frame navigation, motion-review proposals, sound cues, report events) and **Feedback** (review status, reviewed source with the read-only source-file list, selected checkpoint, structured feedback, frame-strip export). Their element ids and saved section names (`rig`, `playback`, `feedback`) are unchanged; a saved `view` section from older links restores without selecting a section.
+- **Left column.** A fixed header row (Parts title and slot search) and one scrolling body. Nothing sits above the header and it never scrolls. The body holds, in order, the checkpoints/reference strip (current checkpoint title, checkpoints and the reference select, folded into a compact strip that opens when the package supplies checkpoints or references), the part list and browser Settings; it is the column's only scroll container.
+- **Header.** The **Setup** / **Animate** mode switch sits next to the package title and is the Inspector's only section control: its buttons carry `data-inspector` and `aria-pressed`, and every section change (click, `showInspector` from a part selection or a tool, a restored bookmark) goes through them. On the right, **Write review** (primary) opens the review dialog. The top bar has no feedback export buttons; `rig-review feedback --format json|issue` is the export path.
+- **View bar.** One row: the persistent image / mesh edges / bone points layer toggles (keys `I`, `M`, `B`), camera sync and zoom, then the **View** menu (a `<details>` holding Side by side, Reference and Rig, labelled with the effective choice) at the right end. The toggles stay native checkboxes, so their checked state is the pressed state, the draft input and the `layers` control value. A disabled toggle names the footer's layer reason as its tooltip. Turning images off leaves the mesh/bone overlay alone. Appearance lives only in Settings (its Theme select shows the inspection's current appearance and drives it), the per-inspection Repeat idle toggle lives in the Animate transport row, and there is no Copy view link button: the persisted `#review=` fragment stays in the address bar and the numeric region stays behind **View region**.
+- **Panel headers and scrolling.** The left column's header is a fixed row outside its scrolling body. The Inspector heading, the Settings title and each drawer's header (title and close) carry `.sticky-header` and are their panel's first child, so the body scrolls beneath them. Every scrolling region shares one thin scrollbar rule on `*` whose colours are the `--rv-scrollbar-*` tokens. Resize separators are drawn 4px with a 16px transparent hit area (22px on coarse pointers) and use `--rv-separator` / `--rv-separator-hover`, never a scrollbar colour.
+- **Inspector.** Two sections and no tab row: **Setup** is the mesh-review composition (selected part, part presets, the modeling-review proposals for mesh density, contour curvature and chest position) and holds no control that seeks or plays; **Animate** has the transport with the Repeat idle toggle, frame navigation, the motion-review proposals and angle inspection with its axis panel, sound cues and report events. Their element ids and saved section names (`rig`, `playback`) are unchanged. A saved `view` or `feedback` section from older links and drafts restores without selecting a section or opening the dialog.
+- **Review dialog.** A native modal `<dialog id="review-dialog">` holds the former Feedback section unchanged (review status, reviewed source with the read-only source-file list, selected checkpoint, structured feedback, frame-strip export; every element id kept) and the **Submit review** button (`#save`). **Write review**, a part's or a proposal tool's Add feedback opens it with `showModal()` and pauses playback; Escape or Close dismisses it and focus returns to **Write review**. Its inputs stay in the document while it is closed, so the draft mechanism (autosave, recovery, conflict handling) is unchanged and closing loses nothing. The modal makes the rest of the page inert, so the dialog repeats the footer's message and draft state in its own status line; the footer keeps reporting both.
 - **Footer.** Message (truncated, full text as tooltip) on the left; player, effective layout, renderer, layers, idle, remote control and draft state in the middle; the numeric view region (behind **View region**) and the source hash on the right.
 
-The compare page keeps its own markup and stylesheet: sources left, Parts explorer right and its four Inspector sections.
+The compare page keeps its own markup and stylesheet: sources left, Parts explorer right, its four Inspector sections, its export buttons and its separator colour. It shares the workspace coordinator, so its separators are drawn at the same 4px.
 
 ## Inspection strips
 
@@ -86,8 +89,9 @@ Rules:
 - Every colour token is defined for both schemes: `:root` holds dark (the default before any script runs) and `:root[data-theme=light]` redefines the same set. The appearance control resolves `system` through `prefers-color-scheme` and always writes `data-theme=dark|light` on the root element, so the stylesheets carry no per-component light overrides.
 - State colours: pressed and current selections use the `--pass` family, primary actions and links `--link`, dirty and draft notices `--warn`, errors `--fail`.
 - The stage (pane gradient, grid dots, pane labels, empty-state text, video letterbox) stays dark in both schemes so source pixels and overlays read the same; its tokens carry equal values in both blocks.
+- Resize separators and scrollbars never share a colour: `--rv-separator` and `--rv-separator-hover` resolve to values different from both `--rv-scrollbar-*` colours in each scheme (the review page; the compare stylesheet keeps its own separator colour).
 
-`tests/theme.test.ts` enforces the first two rules.
+`tests/theme.test.ts` enforces the first two rules and the separator/scrollbar rule.
 
 ## Comparison eligibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/review",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Local human rig inspection and structured feedback export",
   "license": "MIT",

package/src/chest-regions.ts

@@ -0,0 +1,253 @@
+/**
+ * Chest-region designation (`family-chest-regions/1`): pure geometry, validation and the exact JSON text the
+ * public generator's example files use. No DOM, no filesystem. Review designates and exports these values as
+ * evidence; regenerating a mesh from them is the producer path, never this module.
+ */
+
+/** The generator's coordinate grid: every point is a multiple of 1/256 crop pixel. */
+export const CHEST_REGION_GRID = 256;
+export const CHEST_REGIONS_SPEC = 'family-chest-regions/1';
+
+export type CropPoint = [number, number];
+export type ChestSegment = string | [string, [number, number], [number, number]];
+export interface ChestRegion { name: string; bone: string; shape: 'polygon'; points: CropPoint[]; spacing: number; band: number }
+export interface ChestContour { tolerance: number; margin: number; spacing: number; maxEdge: number; stray: number; bridges: boolean; regions: ChestRegion[] }
+export interface ChestMesh { contour: ChestContour; r?: number; segments?: ChestSegment[] }
+export interface ChestRegionsDocument {
+  spec: typeof CHEST_REGIONS_SPEC;
+  coordinates: string;
+  publicGenerator: string;
+  mesh: { name: string; value: ChestMesh };
+  sourceRule?: string;
+}
+
+export interface ChestRegionInput {
+  name: string;
+  bone: string;
+  center: [number, number];
+  semiAxes: [number, number];
+  spacing: number;
+  band: number;
+  /** Medial clip line x: the polygon side toward this x stops at it (x ≤ clip when clip > centre x, x ≥ clip when clip < centre x). */
+  clip?: number;
+}
+export interface ChestRegionsInput {
+  crop: { w: number; h: number };
+  generator: string;
+  mesh?: string;
+  contour: Omit<ChestContour, 'regions'>;
+  regions: ChestRegionInput[];
+  r?: number;
+  segments?: unknown;
+  sourceRule?: string;
+  /** The loaded model's bone names; when present every region bone must be one of them. */
+  bones?: readonly string[] | null;
+}
+
+export class ChestRegionError extends Error {
+  constructor(readonly code: string, detail: string) { super(`${code} ${detail}`.trim()); }
+}
+
+const quantize = (value: number): number => { const q = Math.round(value * CHEST_REGION_GRID) / CHEST_REGION_GRID; return q === 0 ? 0 : q; };
+const onGrid = (value: number): boolean => Number.isInteger(value * CHEST_REGION_GRID);
+
+/**
+ * The 32-sample ellipse the examples encode: sample i at angle θ = 2πi/samples, starting at +x (screen-right)
+ * and turning toward +y (down, crop pixels), each coordinate rounded to the nearest 1/256 pixel. A clip x
+ * (on the grid) then stops the side that faces it.
+ */
+export function ellipsePolygon(center: [number, number], semiAxes: [number, number], samples = 32, clip?: number): CropPoint[] {
+  const [cx, cy] = center, [ax, ay] = semiAxes, points: CropPoint[] = [];
+  for (let i = 0; i < samples; i++) {
+    const angle = 2 * Math.PI * i / samples;
+    let x = quantize(cx + ax * Math.cos(angle));
+    const y = quantize(cy + ay * Math.sin(angle));
+    if (clip !== undefined) x = clip > cx ? Math.min(x, clip) : Math.max(x, clip);
+    points.push([x, y]);
+  }
+  return points;
+}
+
+function finite(value: unknown, region: string, field: string, min: number, inclusive = true): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || (inclusive ? value < min : value <= min)) throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', `${region} ${field}`);
+  return value;
+}
+
+function pointSegmentDistance(p: CropPoint, a: CropPoint, b: CropPoint): number {
+  const dx = b[0] - a[0], dy = b[1] - a[1], length = dx * dx + dy * dy;
+  const t = length === 0 ? 0 : Math.max(0, Math.min(1, ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / length));
+  return Math.hypot(p[0] - (a[0] + t * dx), p[1] - (a[1] + t * dy));
+}
+const cross = (o: CropPoint, a: CropPoint, b: CropPoint) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+function segmentsCross(a: CropPoint, b: CropPoint, c: CropPoint, d: CropPoint): boolean {
+  const d1 = cross(c, d, a), d2 = cross(c, d, b), d3 = cross(a, b, c), d4 = cross(a, b, d);
+  return ((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0));
+}
+function inside(p: CropPoint, polygon: CropPoint[]): boolean {
+  let hit = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    const [xi, yi] = polygon[i]!, [xj, yj] = polygon[j]!;
+    if ((yi > p[1]) !== (yj > p[1]) && p[0] < (xj - xi) * (p[1] - yi) / (yj - yi) + xi) hit = !hit;
+  }
+  return hit;
+}
+/** Distance between two closed polygons; 0 when their edges cross or one contains the other. */
+export function polygonDistance(a: CropPoint[], b: CropPoint[]): number {
+  if (inside(a[0]!, b) || inside(b[0]!, a)) return 0;
+  let best = Infinity;
+  for (let i = 0; i < a.length; i++) {
+    const a0 = a[i]!, a1 = a[(i + 1) % a.length]!;
+    for (let j = 0; j < b.length; j++) {
+      const b0 = b[j]!, b1 = b[(j + 1) % b.length]!;
+      if (segmentsCross(a0, a1, b0, b1)) return 0;
+      best = Math.min(best, pointSegmentDistance(a0, b0, b1), pointSegmentDistance(a1, b0, b1), pointSegmentDistance(b0, a0, a1), pointSegmentDistance(b1, a0, a1));
+    }
+  }
+  return best;
+}
+
+/**
+ * Review's pre-check for the generator's no-overlap rule: two regions are refused when their supports (polygon
+ * grown by its band) overlap, i.e. polygon distance < bandA + bandB. The generator itself refuses per mesh
+ * vertex (`RIG_CONTOUR_REGIONS_OVERLAP`, a vertex weighted by two falloffs); without a mesh this geometric test
+ * is the stricter side of that rule: it can refuse a pair the generator would accept, never the reverse.
+ */
+export function regionsOverlap(a: { points: CropPoint[]; band: number }, b: { points: CropPoint[]; band: number }): boolean {
+  return polygonDistance(a.points, b.points) < a.band + b.band;
+}
+
+function coordinatesText(crop: { w: number; h: number }, regions: ChestRegionInput[]): string {
+  const [left, right] = [...regions].sort((a, b) => a.center[0] - b.center[0]);
+  return `${crop.w}x${crop.h} crop pixels, x screen-right and y down; ${left!.bone} screen-left, ${right!.bone} screen-right`;
+}
+
+function segmentList(value: unknown): ChestSegment[] {
+  if (!Array.isArray(value)) throw new ChestRegionError('CHEST_SEGMENTS_INVALID', 'expected an array');
+  const point = (v: unknown): v is [number, number] => Array.isArray(v) && v.length === 2 && v.every(n => typeof n === 'number' && Number.isFinite(n));
+  return value.map((item: unknown, i) => {
+    if (typeof item === 'string' && item) return item;
+    if (Array.isArray(item) && item.length === 3 && typeof item[0] === 'string' && item[0] && point(item[1]) && point(item[2])) return [item[0], [item[1][0], item[1][1]], [item[2][0], item[2][1]]] as ChestSegment;
+    throw new ChestRegionError('CHEST_SEGMENTS_INVALID', `segments[${i}]`);
+  });
+}
+
+export function buildChestRegions(input: ChestRegionsInput): ChestRegionsDocument {
+  const w = finite(input.crop?.w, 'crop', 'w', 0, false), h = finite(input.crop?.h, 'crop', 'h', 0, false);
+  if (typeof input.generator !== 'string' || !input.generator.trim()) throw new ChestRegionError('CHEST_REGIONS_GENERATOR_MISSING', '');
+  if (input.regions.length !== 2) throw new ChestRegionError('CHEST_REGIONS_COUNT', String(input.regions.length));
+  const c = input.contour;
+  for (const field of ['tolerance', 'margin', 'spacing', 'maxEdge', 'stray'] as const) finite(c[field], 'contour', field, 0);
+  if (typeof c.bridges !== 'boolean') throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', 'contour bridges');
+  const names = new Set<string>(), regions: ChestRegion[] = [];
+  for (const region of input.regions) {
+    const name = region.name;
+    if (typeof name !== 'string' || !/^[A-Za-z0-9_.-]{1,64}$/.test(name)) throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', `${String(name)} name`);
+    if (names.has(name)) throw new ChestRegionError('CHEST_REGION_NAME_DUPLICATE', name);
+    names.add(name);
+    if (typeof region.bone !== 'string' || !region.bone) throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', `${name} bone`);
+    if (input.bones && !input.bones.includes(region.bone)) throw new ChestRegionError('CHEST_REGION_BONE_UNKNOWN', region.bone);
+    const cx = finite(region.center?.[0], name, 'center x', -Infinity), cy = finite(region.center?.[1], name, 'center y', -Infinity);
+    const ax = finite(region.semiAxes?.[0], name, 'semi-axis x', 0, false), ay = finite(region.semiAxes?.[1], name, 'semi-axis y', 0, false);
+    const spacing = finite(region.spacing, name, 'spacing', 0, false), band = finite(region.band, name, 'band', 0);
+    if (region.clip !== undefined) finite(region.clip, name, 'clip', -Infinity);
+    for (const [field, value] of [['center x', cx], ['center y', cy], ['band', band], ...(region.clip === undefined ? [] : [['clip', region.clip]])] as [string, number][]) {
+      if (!onGrid(value)) throw new ChestRegionError('CHEST_REGION_OFF_GRID', `${name} ${field}`);
+    }
+    const points = ellipsePolygon([cx, cy], [ax, ay], 32, region.clip);
+    if (points.some(([x, y]) => x < 0 || y < 0 || x > w || y > h)) throw new ChestRegionError('CHEST_REGION_OUT_OF_CROP', name);
+    regions.push({ name, bone: region.bone, shape: 'polygon', points, spacing, band });
+  }
+  if (regionsOverlap(regions[0]!, regions[1]!)) throw new ChestRegionError('CHEST_REGIONS_OVERLAP', `${regions[0]!.name} ${regions[1]!.name}`);
+  const mesh: ChestMesh = { contour: { tolerance: c.tolerance, margin: c.margin, spacing: c.spacing, maxEdge: c.maxEdge, stray: c.stray, bridges: c.bridges, regions } };
+  if (input.r !== undefined) mesh.r = finite(input.r, 'mesh', 'r', 0);
+  if (input.segments !== undefined) mesh.segments = segmentList(input.segments);
+  const meshName = input.mesh ?? 'topwear';
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(meshName)) throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', 'mesh name');
+  return { spec: CHEST_REGIONS_SPEC, coordinates: coordinatesText({ w, h }, input.regions), publicGenerator: input.generator, mesh: { name: meshName, value: mesh }, ...(input.sourceRule ? { sourceRule: input.sourceRule } : {}) };
+}
+
+/** Python-style JSON text (`json.dumps(value, indent=2)` + newline), the examples' exact formatting; `{float}` marks a Python float. */
+type Emit = { float: number } | number | string | boolean | Emit[] | { [key: string]: Emit };
+const isFloat = (v: unknown): v is { float: number } => !!v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 1 && 'float' in v;
+function numberText(value: number, float: boolean): string {
+  if (!Number.isFinite(value)) throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', 'non-finite number');
+  const v = value === 0 ? 0 : value, text = String(v);
+  if (/e/i.test(text)) throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', `number ${text} needs exponent notation`);
+  return float && Number.isInteger(v) ? `${text}.0` : text;
+}
+const stringText = (value: string) => JSON.stringify(value).replace(/[\u007f-￿]/g, ch => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
+function emit(value: Emit, depth: number): string {
+  const pad = '  '.repeat(depth + 1), close = '  '.repeat(depth);
+  if (isFloat(value)) return numberText(value.float, true);
+  if (typeof value === 'number') return numberText(value, false);
+  if (typeof value === 'string') return stringText(value);
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (Array.isArray(value)) return value.length ? `[\n${value.map(v => pad + emit(v, depth + 1)).join(',\n')}\n${close}]` : '[]';
+  const entries = Object.entries(value);
+  return entries.length ? `{\n${entries.map(([k, v]) => `${pad}${stringText(k)}: ${emit(v, depth + 1)}`).join(',\n')}\n${close}}` : '{}';
+}
+
+export function serializeChestRegions(doc: ChestRegionsDocument): string {
+  const mesh = doc.mesh.value, contour = mesh.contour;
+  const value: { [key: string]: Emit } = {
+    spec: doc.spec,
+    coordinates: doc.coordinates,
+    publicGenerator: doc.publicGenerator,
+    [`meshes.${doc.mesh.name}`]: {
+      contour: {
+        tolerance: contour.tolerance, margin: contour.margin, spacing: contour.spacing, maxEdge: contour.maxEdge, stray: contour.stray, bridges: contour.bridges,
+        regions: contour.regions.map(r => ({ name: r.name, bone: r.bone, shape: r.shape, points: r.points.map(([x, y]) => [{ float: x }, { float: y }]), spacing: r.spacing, band: r.band })),
+      },
+      ...(mesh.r === undefined ? {} : { r: mesh.r }),
+      ...(mesh.segments === undefined ? {} : { segments: mesh.segments as Emit[] }),
+    },
+    ...(doc.sourceRule === undefined ? {} : { sourceRule: doc.sourceRule }),
+  };
+  return emit(value, 0) + '\n';
+}
+
+/** Crop → rig world mapping, only when the loaded model fixes it. */
+export type CropWorldMapping =
+  | { available: true; crop: { w: number; h: number }; toWorld: (x: number, y: number) => { x: number; y: number }; basis: string }
+  | { available: false; reason: string };
+
+/**
+ * The rig-parts crop convention is world = (x − W/2, H − y): root at the crop's bottom centre, world y up. A
+ * model fixes W×H only when its declared `stage` is exactly that frame (x = −width/2, y = 0) and the root bone's
+ * drawn world position is the origin. Anything else is reported as missing; no frame is assumed.
+ */
+export function cropWorldMapping(stage: { x: number; y: number; width: number; height: number } | null | undefined, root: { x: number; y: number } | null): CropWorldMapping {
+  const missing = (what: string): CropWorldMapping => ({ available: false, reason: `CHEST_REGION_MAPPING_UNAVAILABLE: ${what}` });
+  if (!stage) return missing('the model declares no stage');
+  if (![stage.x, stage.y, stage.width, stage.height].every(Number.isFinite) || stage.width <= 0 || stage.height <= 0) return missing('the model stage is not a positive finite box');
+  if (stage.x !== -stage.width / 2 || stage.y !== 0) return missing(`the model stage (${stage.x}, ${stage.y}, ${stage.width}×${stage.height}) is not a crop frame with the root at its bottom centre`);
+  if (!root) return missing('no drawn root bone position');
+  if (Math.abs(root.x) > 1e-6 || Math.abs(root.y) > 1e-6) return missing(`the drawn root bone is at (${root.x}, ${root.y}), not the world origin`);
+  const { x: ox, y: oy, width, height } = stage;
+  return { available: true, crop: { w: width, h: height }, toWorld: (x, y) => ({ x: ox + x, y: oy + height - y }), basis: `model stage ${width}×${height} at (${ox}, ${oy}), root at world origin: world = (x − ${width / 2}, ${height} − y)` };
+}
+
+export interface ChestRegionsBinding {
+  schema: 'rig-review-chest-regions-binding/1';
+  file: { name: 'chest-regions.json'; sha256: string };
+  package: string;
+  model: string | null;
+  motion: string | null;
+  exportedAt: string;
+  tools: { viewerVersion: string; runtimeVersion: string };
+  mapping: string;
+  evidence: string;
+}
+export function chestRegionsBinding(input: { fileSha256: string; sourceHash: string; reviewedSource: { viewerVersion: string; runtimeVersion: string; rig: { sha256: string } | null; motion: { sha256: string } | null }; exportedAt: string; mapping: string }): ChestRegionsBinding {
+  return {
+    schema: 'rig-review-chest-regions-binding/1',
+    file: { name: 'chest-regions.json', sha256: input.fileSha256 },
+    package: input.sourceHash,
+    model: input.reviewedSource.rig?.sha256 ?? null,
+    motion: input.reviewedSource.motion?.sha256 ?? null,
+    exportedAt: input.exportedAt,
+    tools: { viewerVersion: input.reviewedSource.viewerVersion, runtimeVersion: input.reviewedSource.runtimeVersion },
+    mapping: input.mapping,
+    evidence: 'Designation is review evidence, not an approval. Nothing was written into the package; regeneration is the producer path.',
+  };
+}

package/web/chest-regions-tool.ts

@@ -0,0 +1,51 @@
+/** Setup's Chest regions tool: form fields → designation input, without DOM access (main.ts owns the elements). */
+import {buildChestRegions,ChestRegionError,serializeChestRegions,type ChestRegionsDocument,type ChestRegionsInput,type CropWorldMapping} from '../src/chest-regions.ts';
+
+export const chestRegionRows=[0,1] as const;
+export const chestRegionFields=['name','bone','cx','cy','ax','ay','spacing','band','clip'] as const;
+export const chestContourFields=[['tolerance','chest-tolerance'],['margin','chest-margin'],['spacing','chest-spacing'],['maxEdge','chest-max-edge'],['stray','chest-stray']] as const;
+export const chestRowId=(row:number,field:typeof chestRegionFields[number])=>`chest-${row}-${field}`;
+/** Every input id the tool owns; the inspection draft captures them like any other form input. */
+export const chestInputIds=[
+ 'chest-crop-w','chest-crop-h','chest-generator','chest-source-rule','chest-r','chest-segments','chest-bridges',
+ ...chestContourFields.map(([,id])=>id),
+ ...chestRegionRows.flatMap(row=>chestRegionFields.map(field=>chestRowId(row,field))),
+];
+
+export interface ChestFieldValue {value:string;checked?:boolean}
+export type ChestFieldReader=(id:string)=>ChestFieldValue|undefined;
+
+const invalid=(what:string)=>new ChestRegionError('CHEST_REGION_VALUE_INVALID',what);
+function numberField(read:ChestFieldReader,id:string,what:string,optional=false):number|undefined {
+ const raw=(read(id)?.value??'').trim();
+ if(!raw){if(optional)return undefined;throw invalid(what);}
+ const value=Number(raw);if(!Number.isFinite(value))throw invalid(what);return value;
+}
+
+/** Reads the tool's fields; crop comes from the model mapping when it exists, else from the crop fields. */
+export function readChestForm(read:ChestFieldReader,mapping:CropWorldMapping,bones:readonly string[]|null):ChestRegionsInput {
+ const crop=mapping.available?mapping.crop:{w:numberField(read,'chest-crop-w','crop w')!,h:numberField(read,'chest-crop-h','crop h')!};
+ const contour={tolerance:0,margin:0,spacing:0,maxEdge:0,stray:0,bridges:read('chest-bridges')?.checked===true};
+ for(const [key,id] of chestContourFields)contour[key]=numberField(read,id,`contour ${key}`)!;
+ const regions=chestRegionRows.map(row=>{
+  const name=(read(chestRowId(row,'name'))?.value??'').trim()||`row ${row+1}`,num=(field:typeof chestRegionFields[number],optional=false)=>numberField(read,chestRowId(row,field),`${name} ${field}`,optional);
+  const clip=num('clip',true);
+  return {name:(read(chestRowId(row,'name'))?.value??'').trim(),bone:read(chestRowId(row,'bone'))?.value??'',center:[num('cx')!,num('cy')!] as [number,number],semiAxes:[num('ax')!,num('ay')!] as [number,number],spacing:num('spacing')!,band:num('band')!,...(clip===undefined?{}:{clip})};
+ });
+ const segmentsText=(read('chest-segments')?.value??'').trim();let segments:unknown;
+ if(segmentsText){try{segments=JSON.parse(segmentsText);}catch{throw new ChestRegionError('CHEST_SEGMENTS_INVALID','not JSON');}}
+ const r=numberField(read,'chest-r','mesh r',true),sourceRule=(read('chest-source-rule')?.value??'').trim();
+ return {crop,generator:(read('chest-generator')?.value??'').trim(),contour,regions,...(r===undefined?{}:{r}),...(segments===undefined?{}:{segments}),...(sourceRule?{sourceRule}:{}),bones};
+}
+
+export type ChestEvaluation={ok:true;document:ChestRegionsDocument;text:string}|{ok:false;error:string};
+export function evaluateChestForm(read:ChestFieldReader,mapping:CropWorldMapping,bones:readonly string[]|null):ChestEvaluation {
+ try{const document=buildChestRegions(readChestForm(read,mapping,bones));return {ok:true,document,text:serializeChestRegions(document)};}
+ 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}[]}[] {
+ 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))}));
+}

package/web/compare.css

@@ -114,6 +114,7 @@ body{display:grid;grid-template-rows:auto minmax(0,1fr) auto}.layout{grid-templa
 .workspace-drawer:not([open]){display:none}.workspace-drawer[open]{display:flex;flex-direction:column;gap:8px}
 .workspace-drawer::backdrop{background:var(--rv-backdrop)}
 .workspace-drawer-close{align-self:flex-end;flex:none}
+.workspace-drawer-header{display:flex;align-items:center;justify-content:space-between;gap:8px;flex:none}
 .workspace-drawer>.left-panel{display:flex!important;flex-direction:column;flex:1;overflow:hidden;min-height:0;padding:0}
 .workspace-drawer>.parts-explorer{display:block;grid-template-columns:none;flex:1;width:auto;min-width:0;min-height:0;height:auto;overflow:auto}
 .workspace-drawer>.inspector{flex:1;height:auto!important;min-height:0!important;max-height:none;overflow:hidden}