@rig-c/review 0.3.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,22 +356,57 @@ 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 left, right and bottom panels are resizable. Drag a separator, or focus it
+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** 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. 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. 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 left and then
-the right panel, and when it is too short, the Inspector, become explicit
+stage keeps a usable minimum. When the window is too narrow, the side columns
+(left first on the compare page), and when it is too short, the Inspector, become explicit
 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, in the lower left, 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.
 
@@ -390,9 +427,9 @@ serving use per-port origins and keep them separate.
 
 ## Inspect a part
 
-The right Parts explorer selects an actual model slot on a specific single/A/B side. All rows follow the public held snapshot's exact draw-order z, including hidden/null slots. Search matches the exact source slot names: a row is shown when its name contains the typed text, case-sensitively, with no case folding or normalization. Arrow keys/Home/End move between result buttons, Enter/Space selects, and Escape returns to search. Whole rig restores full drawing. Selecting a drawn row fits its conservative world bounds within the existing camera zoom range; Sync cameras applies the same normalized camera action to every visible pane, while independent mode changes only that selected pane. Hidden/empty geometry reports `PART_FIT_UNAVAILABLE` and keeps the camera.
+The Parts explorer (left column; right on the compare page) selects an actual model slot on a specific single/A/B side. All rows follow the public held snapshot's exact draw-order z, including hidden/null slots. Search matches the exact source slot names: a row is shown when its name contains the typed text, case-sensitively, with no case folding or normalization. Arrow keys/Home/End move between result buttons, Enter/Space selects, and Escape returns to search. Whole rig restores full drawing. Selecting a drawn row fits its conservative world bounds within the existing camera zoom range; Sync cameras applies the same normalized camera action to every visible pane, while independent mode changes only that selected pane. Hidden/empty geometry reports `PART_FIT_UNAVAILABLE` and keeps the camera.
 
-Solo preserves the full held pose's resolved clips and filters only drawing. In context, the whole rig remains visible with an amber dashed conservative selection box; this box is geometry/clip bounds, not exact source-alpha coverage. Selection changes no track, skin, set, motion, source asset or review decision. The selected slot's side/mode survives source-bound links and local drafts. The Rig inspector shows actual posed mesh counts or region corners, page/region, current skin/set context and declared attachment candidates. **Use slot for feedback** explicitly prefills the target; selecting a row alone submits nothing.
+Solo preserves the full held pose's resolved clips and filters only drawing. In context, the whole rig remains visible with an amber dashed conservative selection box; this box is geometry/clip bounds, not exact source-alpha coverage. Selection changes no track, skin, set, motion, source asset or review decision. The selected slot's side/mode survives source-bound links and local drafts. The Setup section shows actual posed mesh counts or region corners, page/region, current skin/set context and declared attachment candidates. **Use slot for feedback** explicitly prefills the target; selecting a row alone submits nothing.
 
 The pinned published `@rig-c/play`1.12.0 supplies `slotIdentity()` and frame generation. The explorer atomically retains the public identity snapshot with the same-generation held frame: exact attachment key, owning skin, active set/skin, full z order and explicit hidden/no-attachment/timeline-null/set-hide reasons. Hidden/null slots keep null keys with their reported reason; declarations and texture/UV names never replace that public result. An identity-known attachment need not have a visible primitive or positive fit bounds. The current UI follows its selected slot as animation changes, updating the displayed identity to the actual held frame.
 
@@ -400,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 **View**, **Rig**, **Playback** and **Feedback** sections. Rig covers setup geometry, source art, pivot/joint placement, meshes, weights, draw order and angle coverage; Playback 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
 
@@ -34,6 +34,20 @@ Any future modeling edit needs provenance, undo/redo, explicit units and an expo
 
 [design-prototype.html](design-prototype.html) preserves the interactive screen concept. It is **illustrative**, with sample controls/data, separate from the implemented app. Its older motion key/curve editing concept is superseded by the current view/annotate/export boundary. It does not demonstrate completed mesh, motion, angle or audio editing.
 
+## Workspace layout
+
+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.** 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, 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
 
 An inclusive annotation interval can also become a derived frame strip. The single view selects one declared source video; compare retains its explicit shared video and chooses a producer clock basis for each interval. A batch preserves separate feedback intervals and side provenance. Source rows run down the sheet and requested producer frames run across it. A vertical batch repeats this grid rather than merging overlapping annotations.
@@ -45,7 +59,7 @@ The export uses dedicated real canvas players and leaves the live playhead/sessi
 
 ## Implemented slot inspection and public identity snapshots
 
-The right Parts explorer provides source-hash-bound slot selection, held-pose clipped Solo, Whole/context, conservative bounds fit, a diagnostic selection box, actual mesh/region counts and reproducible selection context. This is inspection rather than geometry editing. All rows use the public held identity snapshot's exact z order, including hidden/null slots. Current source-bound links/drafts and control observations retain side/slot/mode.
+The Parts explorer (the review page's left column; the compare page's right one) provides source-hash-bound slot selection, held-pose clipped Solo, Whole/context, conservative bounds fit, a diagnostic selection box, actual mesh/region counts and reproducible selection context. This is inspection rather than geometry editing. All rows use the public held identity snapshot's exact z order, including hidden/null slots. Current source-bound links/drafts and control observations retain side/slot/mode.
 
 Published Play1.12.0 supplies a frozen `slotIdentity()` snapshot coherent with `posedFrame().generation`. Review retains copied frame/identity together only after equal-generation and source-slot/order checks, uses the player's default public filter, and never seeks/reposes/changes physics merely to read identity. Exact owning skin/key, active set/skin and null reasons come from that snapshot, not a unique-declaration or texture match. A resolved identity can remain known without visible geometry or fit bounds. Clip declarations do not invent keys when the API reports no drawable attachment.
 
@@ -55,16 +69,30 @@ A future optimization operation sends explicit source-bound selection/bounds to
 
 ## Workspace geometry and browser preferences
 
-Left, right and bottom panels have pointer and keyboard separators with separator semantics: orientation, the controlled panel, an accessible name and the actual reachable minimum/maximum/current pixels. Arrow keys act only when the separator itself has focus, so text-entry arrows are never intercepted. A drag holds pointer capture; cancel, lost capture, blur, Escape and disposal restore the previous desired size and release it.
+Side and bottom panels have pointer and keyboard separators with separator semantics: orientation, the controlled panel, an accessible name and the actual reachable minimum/maximum/current pixels. Arrow keys act only when the separator itself has focus, so text-entry arrows are never intercepted. A drag holds pointer capture; cancel, lost capture, blur, Escape and disposal restore the previous desired size and release it.
 
-The allocator measures the layout rectangle minus stage chrome and keeps a 240×180 CSS-pixel stage minimum. It shrinks side panels proportionally toward their own minima; when the width still cannot hold them it turns the left, then the right panel, and when the height cannot hold it the Inspector, into a native modal drawer opened from a trigger outside it. Effective sizes are computed from desired sizes and never written back; a separator inverts the allocator so a clamped pixel value is not saved as the desktop desire.
+The allocator measures the layout rectangle minus stage chrome and keeps a 240×180 CSS-pixel stage minimum. It shrinks side panels proportionally toward their own minima; when the width still cannot hold them it turns the left, then the right column, and when the height cannot hold it the Inspector, into a native modal drawer opened from a trigger outside it. Effective sizes are computed from desired sizes and never written back; a separator inverts the allocator so a clamped pixel value is not saved as the desktop desire.
 
-Browser defaults live in one closed, versioned record: theme, default camera sync, default idle repeat and the three desired panel sizes. Each field carries a logical stamp, so stale whole-record writes from other tabs converge per field without wall-clock ordering; an equal-stamp disagreement quarantines only that field until an explicit edit repairs it. Denied, unavailable or corrupt storage falls back to in-page defaults. The legacy same-origin appearance key migrates once, only when no new record exists. Reset layout changes geometry only.
+Browser defaults live in one closed, versioned record: theme, default camera sync, default idle repeat and the three desired panel sizes. The saved `rightWidth` is the Parts explorer's width wherever the page shows it, so the review page's left parts column keeps the width chosen before the move; `leftWidth` is the compare page's sources column. Each field carries a logical stamp, so stale whole-record writes from other tabs converge per field without wall-clock ordering; an equal-stamp disagreement quarantines only that field until an explicit edit repairs it. Denied, unavailable or corrupt storage falls back to in-page defaults. The legacy same-origin appearance key migrates once, only when no new record exists. Reset layout changes geometry only.
 
 Content state stays source-bound. Each Inspector section's x/y scroll offset is captured before its panel hides and restored after it shows, after two frames of layout, and again when its content extent changes. Restoring clamps to the current extent without replacing the remembered offset, and intentional user scrolling supersedes a pending restore. Offsets are kept in the source draft's UI state, never in the global record or a copied view link.
 
 Browser storage is origin-scoped. Managed opens (the default) share one loopback front origin that routes `/instances/<key>/…` to each worker, so Settings, sizes and drafts carry across reopens; `--direct` keeps per-port origins. Because one origin cannot isolate its scripts, writes require a per-instance capability handed off only in the printed `#cap=` fragment and checked by both the front and the worker; a fragment-less copied link is read-only. Draft scopes carry the source hash, so revisions of one package never clobber each other's drafts.
 
+## Theme
+
+The palette comes from the rig-c.org site stylesheet. Its dark `:root` values (`--bg`, `--fg`, `--fg-strong`, `--fg-soft`, `--fg-muted`, `--border`, `--border-strong`, `--hover-bg`, `--active-bg`, `--link`, `--link-hover`, `--btn-fg`, `--code-*`, `--footer-bg`, `--pass`, `--warn`, `--fail`, the font stacks and `--radius`) are copied into the `:root` block of `web/styles.css` and `web/compare.css`; nothing is fetched at runtime, so the viewer stays offline. The site loads Inter and JetBrains Mono from a font CDN; the review keeps only the family stacks and falls back to local fonts. The site has no light scheme, so the light values and every review-only surface token (`--rv-*`: bars, panels, controls, fields, pressed state, focus ring, backdrop, stage) are review-local derivations of the same palette.
+
+Rules:
+
+- No literal colour (`#hex`, `rgb()`, `hsl()`) outside the `:root` token blocks of either stylesheet. Rules use `var(--…)` only.
+- 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 and the separator/scrollbar rule.
+
 ## Comparison eligibility
 
 A layout is offered only for inputs that actually loaded and rendered. One pure decision (`src/comparison-eligibility.ts`) takes load outcomes, never declared paths: the rig counts after its first successful draw, an image after `decode()`, a pose after it parses, and a video after `seeked` at the held time with a decoded frame. A new video stays pending until then; a held time outside its duration is refused as `REFERENCE_OUT_OF_DOMAIN`, never clamped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/review",
-  "version": "0.3.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))}));
+}