@rig-c/review 0.4.0 → 0.6.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,61 @@ 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.
+
+Animate's **Environment** block drives the player's physics while you
+inspect: a **Wind** base (−100…100), **Breeze**, a **Gust** pulse
+(peak 0…200, duration 0.1…20 s, **Repeat** every max(6, duration + 0.6) s)
+and **Gravity** (0…4), applied through `player.environment` in the same frame
+step that draws. The gust clock is the stepped player time, so pausing freezes
+it. **Jolt** sends a translate-and-return impulse through `player.moved`;
+with **Drag to trail** on, dragging the rig pane moves the rig's physics
+instead of the camera (Space still pans). **Reset physics** returns the
+runtime start values and re-poses from the current time, clearing the physics
+history. The physics constraints are listed read only as the compiled model
+declares them; `@rig-c/play` exposes no per-constraint mix, so none is offered.
+Until a control is touched the player stays at the runtime start values. The
+state is kept in the local draft and recorded in feedback as
+`context.environment`; nothing is written to the model or motion. The compare
+page does not have this block.
+
+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 +418,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 +453,41 @@ 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)
+
+In **Setup**, the view bar's **Chest regions** button (pressed state; hidden in Animate) opens the chest-region editor bar directly under the view bar and enables editing on the rig pane. The bar has an **R** and an **L** group, each with **X**, **Y**, **R** (core radius, 6–120) and **Band** (4–120) in crop pixels, x screen-right and y down; **Mirror R → L** copies R's y, core radius and band to L; **Download JSON**; and **Apply · Rebuild**.
+
+On the rig pane each region is drawn as two circles: the core (full weight) and a dashed outer circle at core + band, R in one colour and L in another (two theme tokens per side), with a centre handle, a core handle on the right edge, a band handle on the top edge and a label `R (x,y) r:… b:…` under the outer circle. Dragging the centre moves the region, dragging the core edge sets r and dragging the band handle sets the band, all in crop pixels through the current camera scale. Each drag and each committed bar value is clamped live with the public example rebuild script's non-overlap rule: integer values, both cores plus 8 px must fit the centre distance minus a 2 px margin (both shrink by one factor) and the bands share what remains. A side the rule changed flashes its label and the footer says `CHEST_REGIONS_CLAMPED`. A handle drag never moves the camera; a drag anywhere else, or with Space held, still pans, and the wheel still zooms.
+
+**Apply · Rebuild** refuses by name, `MODELING_INPUT_UNAVAILABLE: no producer handoff — export the JSON and rebuild with the producer`, in its tooltip, the editor bar and the footer. Review never runs a generator, a rebuild script or a manifest command; regenerating the rig from these regions is the producer's job.
+
+The editor's values are the fields of Setup's **Chest regions · detail** block (R is region 1, L is region 2), which also holds what the bar does not: per region a name, a bone chosen from the loaded model's actual bones, the two semi-axes, a spacing and an optional medial clip x, plus the contour settings (tolerance, margin, spacing, max edge, stray, bridges). Setting R in the bar writes both semi-axes. A region with equal semi-axes and no clip exports as the examples' circle, `{"name", "shape": "circle", "cx", "cy", "r", "bone", "spacing", "band"}`; unequal semi-axes or a clip export as the generator's 32-sample polygon on its 1/256-pixel grid and are drawn filled, without handles.
+
+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 editor bar and the detail block show `CHEST_REGION_MAPPING_UNAVAILABLE: <what is missing>`, nothing is drawn, and the values still edit numerically and export from a crop size you enter.
+
+**Download JSON** (and the detail block's **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>`. Two circles overlap when their centre distance minus both cores is less than the sum of their bands; any other pair is tested through polygons. 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 (see `docs/DESIGN.md`).
+
+## Mesh edit (typed delta, preview only)
+
+In **Setup**, the view bar's **Edit mesh** button (pressed state; hidden in Animate) edits the selected slot's actual mesh attachment. With **Whole rig** selected it refuses `MESH_EDIT_SELECT_SLOT`; a slot whose active attachment is not a mesh refuses `MESH_EDIT_NO_MESH <slot>`. Entering pauses playback, turns the chest-region editor off and opens the mesh editor bar under the view bar. The rig pane dims except the slot's own triangles; the mesh is drawn at full opacity with every vertex as a handle, hull edges, interior triangulation edges and added constraint edges each in their own theme token.
+
+The bar has four sub-modes, one pressed at a time, with single keys that avoid the layer keys `I` / `M` / `B`:
+
+| Key | Sub-mode | Pointer |
+| --- | --- | --- |
+| `V` | Modify | drag a vertex, or an edge to move both ends; Shift-click adds to the selection; drag empty space to box-select; arrow keys nudge the selection 1 crop px (Shift 10) |
+| `C` | Create | click empty space to add a vertex; click an edge to split it at the click point |
+| `X` | Delete | click a vertex to remove it and its edges; click an edge to remove it (hull edges are refused, `MESH_EDIT_HULL_EDGE`) |
+| `E` | Edges | click vertex A then vertex B to add a constraint edge; click a constraint edge to remove it; a hull edge is refused and an existing edge records nothing |
+
+Hit-testing is in screen pixels through the current camera: a vertex within 6 px (8 on touch) wins over an edge within 4 px. In a sub-mode a press never pans; Space-drag still pans and the wheel still zooms. Escape leaves the sub-mode, a second Escape leaves mesh edit. **Undo** / **Redo** (Cmd/Ctrl-Z, Shift-Cmd/Ctrl-Z) step one action at a time — an edge or multi-selection drag is one action of several `move` ops. **Reset** drops the attachment's whole delta after a confirmation.
+
+Everything is a typed delta over the loaded mesh, in crop pixels (x right, y down, the chest regions' crop mapping): `{slot, skin, attachment, source:{vertexCount, triangleCount, hullLength, hash}, ops}` with ordered ops `move {v, from, to}`, `add {at, onEdge?}`, `remove {v}`, `edge {a, b}` and `unedge {a, b}`. Source vertex ids are the attachment's indices; an added vertex takes the next id; a removed id is never reused. `hullLength` is the model's `hull` (the first `hull` vertices, in order, are the hull) and `hash` is the SHA-256 of the attachment's entry in the hash-verified model. The vertices are the slot's last drawn posed vertices, so `basis` names the animation and time they were held at. The overlay previews moved, added and removed vertices and the constraint edges over the original triangulation; nothing is retriangulated in the browser (the status line says *preview only — the producer retriangulates*).
+
+**Download JSON** saves `mesh-edit.json` and `mesh-edit.binding.json` (package source hash, rig and motion SHA-256, the attachment and its hash, export time, viewer and runtime versions and the mapping). **Apply · Rebuild** refuses `MODELING_INPUT_UNAVAILABLE` as the chest editor's does. The delta rides in the inspection's local draft bound to the attachment hash (at most 300 ops per attachment); it never enters the review session and nothing is written into the package.
+
 ## 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, audio inspection and the inspection environment (wind, gravity, impulses and a read-only physics constraint list through the published player's `environment`/`moved`; its state is feedback context, never a model or motion edit). 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,17 @@ 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.
-- **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.
+- **Left column.** A fixed header row (Parts title and slot search on one line; the search's name, *Find slot*, is its `aria-label`) 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. Settings opens and closes from its own header (`#settings-toggle`, `aria-expanded`, controlling `#settings-body`); it starts collapsed and the state is a browser preference.
+- **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.
+- **Chest-region editor.** In Setup only, the view bar's **Chest regions** toggle (`#chest-edit`, `aria-pressed`) opens `#chest-editor-bar` under the view bar: R / L groups (X, Y, R, Band), Mirror R → L, Download JSON and **Apply · Rebuild**, which refuses `MODELING_INPUT_UNAVAILABLE: no producer handoff — export the JSON and rebuild with the producer` and runs nothing. The circles, their centre / core / band handles and labels are drawn on `#rig-overlay` through the crop → world mapping; handle drags (move, r, band) are clamped live with the example rebuild script's non-overlap rule (`CHEST_REGIONS_CLAMPED`) and never move the camera, while other drags and Space-drags pan. The values are the Setup **Chest regions · detail** block's fields, so its draft, export and binding apply unchanged; the block keeps names, bones, semi-axes, clip and the contour. This is designation evidence, not a mesh editor: nothing is regenerated here.
+- **Mesh edit.** In Setup only, the view bar's **Edit mesh** toggle (`#mesh-edit`, `aria-pressed`) opens `#mesh-editor-bar`: sub-modes Modify / Create / Delete / Edges (keys `V` / `C` / `X` / `E`, one pressed), Undo, Redo, Reset, Download JSON and **Apply · Rebuild** refusing `MODELING_INPUT_UNAVAILABLE`. Whole rig refuses `MESH_EDIT_SELECT_SLOT`; a non-mesh slot `MESH_EDIT_NO_MESH <slot>`. It records a typed delta over the actual loaded attachment (`src/mesh-edit.ts`) and previews it over the original triangulation on the overlay; it is not a mesher and never retriangulates, writes the package or runs a producer. The chest editor and mesh edit are exclusive: turning one on turns the other off.
+- **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 View region body is a `position:fixed` popover above the 40px footer, right-aligned, its width and height clamped to the viewport and its content scrolling inside, so the footer's clipping never hides it and opening it never scrolls the page.
 
-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
 
@@ -60,6 +65,10 @@ The Parts explorer (the review page's left column; the compare page's right one)
 
 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.
 
+Selecting the selected row again (click, Space or Enter) clears the selection, the same as **Whole rig**; the control value is then `null`.
+
+Each row shows a 24×24 CSS-pixel thumbnail (2× backing store) of the attachment the held identity snapshot says is active: the region the compiled model's `pages[].regions[]` declares under that attachment's path (or name), cut from the loaded page image by its page UVs. It is drawn when the row scrolls into view and cached per skin/attachment key. A row whose attachment has no such region (no active attachment, a non-image kind, no or several regions of that name, a rotated packing, a page that did not load) shows the type icon, and its tooltip names the reason. A whole atlas page is never a part's thumbnail. Row text and the slot count are unchanged; the compare page registers no thumbnail source and keeps its icons.
+
 Live selection follows a slot. A source-bound bookmark captures its exact identity tuple at that pose; restore validates it after applying time/animation/set and drawing, with transactional rollback on a named mismatch. Old slot-only bookmarks resolve through current public identity. Generation belongs to current readback/feedback, not a stable source target. Named weights and original part alpha remain unavailable without an exact original-source mapping. A conservative bounds box and counts are not source-faithfulness or physics validation.
 
 A future optimization operation sends explicit source-bound selection/bounds to the owning producer. That producer returns a new package revision/hash and provenance including producer version/request identity; Review never regenerates rig, motion or mesh bytes. Candidate Apply/undo/export requires its own implemented contract and acceptance, rather than being inferred from the explorer.
@@ -70,7 +79,7 @@ Side and bottom panels have pointer and keyboard separators with separator seman
 
 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. 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.
+Browser defaults live in one closed, versioned record: theme, default camera sync, default idle repeat, whether Settings is collapsed (`settingsCollapsed`, default `true`) and the three desired panel sizes. A record saved before `settingsCollapsed` existed carries neither the value nor its stamp and loads as collapsed at stamp revision 0; the schema name is unchanged. 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.
 
@@ -86,8 +95,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/docs/REVIEW_PACKAGE.md

@@ -96,6 +96,8 @@ For a matching report/actual model animation with an explicit bounded clock, `fr
 
 The server derives `context.interval:{frameStart,frameEnd,inclusive:true}` from the chosen top-level annotation. Contradictory supplied interval data is refused; optional inspection `time` and `frame` remain separate and do not replace it. Compare uses the selected side's catalog and the CLI's exact animation; a row cannot borrow another side's names or bypass the animation binding.
 
+A single-review note also records `context.environment`, the Animate environment it was written under: `{applied, wind:{base, breeze, gust:{peak, duration, repeat, active, value}, total}, gravity, standing:{wind:[x,y], gravity:[x,y]}}`, where `standing` is what the player reported (x right, y down) and `applied:false` means the runtime start values (`wind [1, 0]`, `gravity [0, 1]`). It is `null` when no compiled model was drawn. Records without it (older sessions, compare) stay valid; a present value must have exactly this shape within the control limits. The issue export adds an `Environment:` line for it. The environment is inspection context only: it is never written to the model, the motion or any producer file.
+
 Both session responses include server-derived `feedbackWarnings:[{id,error}]`. Reading an older session preserves invalid target rows and previously accepted integer indices outside JavaScript's safe range, together with source identity, inspection context and original state-file bytes; a missing chosen interval can be derived in memory. Contradictory existing interval evidence remains visible with its warning. The UI shows these warnings and prevents resubmission until the affected rows are corrected or removed. Strict saves independently validate every row and ignore a client's attempt to clear warnings; exports retain the warnings and original feedback evidence. Syntax and source-binding failures remain refusals rather than silently repaired data.
 
 The state filename is a digest of identity, revision, source hash and reviewed artifact/tool identity, so package names cannot select arbitrary filesystem paths. Writes are atomic and source files remain untouched. Review/session load and save stream-hash the declared inputs; changed bytes produce HTTP 409 and require restart. Asset reads do not rehash an entire video: single byte ranges return 206 and invalid ranges 416. Asset documents receive a sandbox CSP with no scripts or same-origin permission, so delivered authoring HTML cannot approve its own package. No network listener beyond loopback or cross-origin mutation is offered.

package/package.json

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

package/src/chest-regions.ts

@@ -0,0 +1,306 @@
+/**
+ * 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 ChestPolygonRegion { name: string; bone: string; shape: 'polygon'; points: CropPoint[]; spacing: number; band: number }
+/** The examples' `config.json` circle (key order as there): core radius r at full weight, linear falloff over band. */
+export interface ChestCircleRegion { name: string; shape: 'circle'; cx: number; cy: number; r: number; bone: string; spacing: number; band: number }
+export type ChestRegion = ChestPolygonRegion | ChestCircleRegion;
+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;
+}
+/** Two circles are tested exactly (centre distance minus both cores); any other pair through polygons. */
+export function chestRegionsOverlap(a: ChestRegion, b: ChestRegion): boolean {
+  if (a.shape === 'circle' && b.shape === 'circle') return Math.hypot(b.cx - a.cx, b.cy - a.cy) - a.r - b.r < a.band + b.band;
+  return regionsOverlap({ points: regionPoints(a), band: a.band }, { points: regionPoints(b), band: b.band });
+}
+export const regionPoints = (region: ChestRegion): CropPoint[] => region.shape === 'circle' ? ellipsePolygon([region.cx, region.cy], [region.r, region.r]) : region.points;
+
+/** Python's `round` (half to even), which the example's rebuild script applies before clamping. */
+export function pythonRound(value: number): number {
+  const floor = Math.floor(value), fraction = value - floor;
+  if (fraction > 0.5) return floor + 1;
+  if (fraction < 0.5) return floor;
+  return floor % 2 === 0 ? floor : floor + 1;
+}
+export interface ChestCircle { cx: number; cy: number; r: number; band: number }
+export const CHEST_CIRCLE_LIMITS = { r: [6, 120], band: [4, 120] } as const;
+const clampInt = (value: number, [low, high]: readonly [number, number]) => Math.max(low, Math.min(high, value));
+/**
+ * The example rebuild script's `clamp_non_overlapping`, reproduced: integer values, r 6–120 and band 4–120,
+ * both cores plus 8 px must fit the centre distance minus the margin (both shrink by one factor), and the band
+ * sum is limited to what remains. Pure; returns the clamped pair and whether the non-overlap rule changed it.
+ */
+export function clampNonOverlapping(right: ChestCircle, left: ChestCircle, margin = 2): { right: ChestCircle; left: ChestCircle; clamped: boolean } {
+  const integer = (c: ChestCircle): ChestCircle => ({ cx: pythonRound(c.cx), cy: pythonRound(c.cy), r: pythonRound(c.r), band: pythonRound(c.band) });
+  const r = integer(right), l = integer(left);
+  r.r = clampInt(r.r, CHEST_CIRCLE_LIMITS.r); l.r = clampInt(l.r, CHEST_CIRCLE_LIMITS.r);
+  r.band = clampInt(r.band, CHEST_CIRCLE_LIMITS.band); l.band = clampInt(l.band, CHEST_CIRCLE_LIMITS.band);
+  const dist = Math.hypot(l.cx - r.cx, l.cy - r.cy), avail = Math.max(16, dist - margin);
+  let clamped = false;
+  if (r.r + l.r + 8 > avail) {
+    const scale = Math.max(0.25, (avail - 8) / Math.max(1, r.r + l.r));
+    r.r = Math.max(6, Math.floor(r.r * scale)); l.r = Math.max(6, Math.floor(l.r * scale));
+    clamped = true;
+  }
+  const maxBandSum = Math.max(8, Math.floor(avail - (r.r + l.r))), bandSum = r.band + l.band;
+  if (bandSum > maxBandSum) {
+    const ratio = maxBandSum / Math.max(1, bandSum);
+    r.band = Math.max(4, Math.floor(r.band * ratio)); l.band = Math.max(4, maxBandSum - r.band);
+    clamped = true;
+  }
+  return { right: r, left: l, clamped };
+}
+
+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}`);
+    }
+    // Equal semi-axes without a clip are the examples' circle; anything else stays the 32-sample polygon.
+    if (ax === ay && region.clip === undefined) {
+      if (cx - ax < 0 || cy - ax < 0 || cx + ax > w || cy + ax > h) throw new ChestRegionError('CHEST_REGION_OUT_OF_CROP', name);
+      regions.push({ name, shape: 'circle', cx, cy, r: ax, bone: region.bone, spacing, band });
+      continue;
+    }
+    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 (chestRegionsOverlap(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): Emit => r.shape === 'circle'
+          ? { name: r.name, shape: r.shape, cx: r.cx, cy: r.cy, r: r.r, bone: r.bone, spacing: r.spacing, band: r.band }
+          : { 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.',
+  };
+}