@rig-c/review 3.7.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/README.md +1 -1
  2. package/docs/DESIGN.md +145 -74
  3. package/docs/PANELS.md +20 -12
  4. package/docs/PARTS_VIEW.md +133 -76
  5. package/docs/REVIEW_PACKAGE.md +445 -99
  6. package/docs/STABILITY.md +132 -198
  7. package/docs/WORKFLOWS.md +41 -120
  8. package/package.json +4 -3
  9. package/skills/rig-review/SKILL.md +41 -27
  10. package/src/build.ts +10 -2
  11. package/src/cli.ts +17 -16
  12. package/src/comment-crops.ts +6 -1
  13. package/src/compare-html.ts +22 -24
  14. package/src/compare-server.ts +1 -1
  15. package/src/compare-session.ts +41 -3
  16. package/src/correction-handoff.ts +27 -4
  17. package/src/create-pin-gate.ts +3 -0
  18. package/src/direction-inspection.ts +6 -2
  19. package/src/feedback-export.ts +68 -1
  20. package/src/front.ts +5 -200
  21. package/src/handoff.ts +1 -1
  22. package/src/interview-routes.ts +1 -1
  23. package/src/interview-scene.ts +3 -3
  24. package/src/job-act.ts +77 -73
  25. package/src/job-api.ts +326 -13
  26. package/src/job-checkpoint-evidence.ts +113 -0
  27. package/src/job-cli.ts +27 -14
  28. package/src/job-contract.ts +284 -62
  29. package/src/job-front.ts +157 -58
  30. package/src/job-host.ts +23 -4
  31. package/src/job-session.ts +109 -24
  32. package/src/job-source.ts +209 -57
  33. package/src/job-store.ts +80 -6
  34. package/src/job-worker.ts +1 -47
  35. package/src/joined-project.ts +61 -4
  36. package/src/manifest.ts +32 -4
  37. package/src/open-workspace.ts +12 -12
  38. package/src/open.ts +19 -12
  39. package/src/parts-comment-crops.ts +126 -31
  40. package/src/parts-comment.ts +351 -28
  41. package/src/parts-server.ts +19 -7
  42. package/src/parts-view.ts +588 -109
  43. package/src/scene-inspection.ts +50 -0
  44. package/src/server.ts +31 -22
  45. package/src/session.ts +58 -0
  46. package/src/stage-comment.ts +48 -1
  47. package/src/stage-parts.ts +23 -11
  48. package/web/animation-inspection.ts +1 -1
  49. package/web/bones-panel.ts +1 -3
  50. package/web/catalog-en.ts +175 -39
  51. package/web/catalog-ko.ts +175 -39
  52. package/web/cloth-panel.ts +1 -2
  53. package/web/compare.css +3 -13
  54. package/web/compare.html +3 -3
  55. package/web/compare.ts +69 -64
  56. package/web/cuts-panel.ts +1 -3
  57. package/web/density-strip-panel.ts +1 -2
  58. package/web/direction-panel.ts +22 -6
  59. package/web/i18n.ts +13 -1
  60. package/web/idle-panel.ts +1 -2
  61. package/web/index.html +1 -5
  62. package/web/inspection-persistence.ts +2 -1
  63. package/web/inspector-blocks.ts +149 -40
  64. package/web/instance-access.ts +24 -5
  65. package/web/interview-panel.ts +224 -175
  66. package/web/job-rig-capture.ts +164 -21
  67. package/web/job-rig-screen.ts +337 -0
  68. package/web/job-session.ts +611 -1437
  69. package/web/main.ts +614 -151
  70. package/web/mesh-panel.ts +1 -2
  71. package/web/owner-workspace.ts +88 -109
  72. package/web/part-selection.ts +47 -6
  73. package/web/part-thumbnails.ts +20 -6
  74. package/web/parts-render.ts +26 -19
  75. package/web/parts-viewport-provider.ts +181 -7
  76. package/web/physics-panel.ts +1 -2
  77. package/web/readings-panel.ts +1 -2
  78. package/web/requirements-panel.ts +1 -3
  79. package/web/retained-frame-stage.ts +105 -0
  80. package/web/retarget-panel.ts +2 -3
  81. package/web/rig-fields-panel.ts +1 -2
  82. package/web/rig-host.ts +64 -0
  83. package/web/rig-viewport-provider.ts +65 -16
  84. package/web/scene-plates.ts +57 -4
  85. package/web/stage-comments.ts +103 -46
  86. package/web/styles.css +117 -63
  87. package/web/view-controls.ts +201 -12
  88. package/web/viewport-capture.ts +12 -2
  89. package/web/viewport-controller.ts +107 -27
  90. package/web/viewport-pair.ts +2 -1
  91. package/web/workspace-preferences.ts +5 -4
  92. package/web/workspace-ui.ts +151 -19
  93. package/src/front-worker.ts +0 -2
  94. package/src/interview-server.ts +0 -54
  95. package/src/job-hub.ts +0 -304
  96. package/src/job-image-set.ts +0 -50
  97. package/web/interview.css +0 -28
  98. package/web/interview.html +0 -17
  99. package/web/interview.ts +0 -40
  100. package/web/job-hub.css +0 -14
  101. package/web/job-hub.html +0 -5
  102. package/web/job-hub.ts +0 -179
  103. package/web/owner-workspace.css +0 -14
  104. package/web/owner-workspace.html +0 -5
  105. package/web/parts-flags.ts +0 -48
  106. package/web/parts.css +0 -104
  107. package/web/parts.html +0 -49
  108. package/web/parts.ts +0 -604
  109. package/web/stage-nav.ts +0 -136
@@ -1,28 +1,40 @@
1
1
  # Parts and atlas view
2
2
 
3
+ > **Historical UI reference:** the standalone parts page and its sidebar,
4
+ > flags and mesh-numbers panel were removed in #745. UI instructions for those
5
+ > surfaces below are superseded by the existing Setup workspace, Comments and
6
+ > act bar; see the [current screen specification](https://github.com/rig-c/review/blob/main/docs/SCREENS.md).
7
+ > Retained input formats, API details, historical verdicts and heading targets
8
+ > remain compatibility references, not instructions to restore that UI.
9
+
3
10
  `rig-review parts` shows a rig's parts as images, before any rig is built, so a part with missing material, a faint
4
- island or a ragged rim is caught before rigging rather than in motion after it. The same view reads a built rig's atlas
5
- to check what ships.
11
+ island or a ragged rim is caught before rigging rather than in motion after it. Atlas-only inputs refuse
12
+ `PARTS_ATLAS_NOT_CARRIED` before the parts workspace opens. Use rig review for read-only atlas inspection;
13
+ `parts --format json|issue` still reads saved atlas verdicts.
6
14
 
7
15
  ```sh
8
16
  npx rig-review parts <out> # a rig-parts build root: opens <out>/rig/parts.json
9
17
  npx rig-review parts <out>/rig # the same package, named directly
10
- npx rig-review parts <out>/check # a built rig's atlas (any review package with a compiled model)
18
+ npx rig-review open <out>/check # inspect a built rig, including its read-only atlas
19
+ npx rig-review parts <out>/check --format json # read a saved atlas verdict without opening a workspace
11
20
  ```
12
21
 
13
- Options: `--rig <file>` (mesh geometry), `--mesh-report <file>`, `--check <file>` (producer flags; see below), `--verdict <file>` (where the sign-off
22
+ Options: `--rig <file>` (mesh geometry), `--mesh-report <file>`, `--check <file>` (historical producer flags; former UI removed in #745; see below), `--verdict <file>` (where the sign-off
14
23
  is written), `--painting <png>` (the original painting), `--by <name>` (launch-only reviewer declaration), `--format json|issue` (export the saved verdict), `--port <n>`. Like `review`, it serves in the foreground and exits 3 s after its last tab closes.
15
24
 
16
25
  ## Inputs
17
26
 
18
- | Mode | Opens on | Items |
27
+ | Mode | Input and availability | Items |
19
28
  | --- | --- | --- |
20
29
  | parts | a directory holding `parts.json` beside `parts/<name>.png`, as `rig-parts assemble` writes it, or a build root whose `rig/` holds them | every part, in `parts.json` order (draw order, back first) |
21
- | atlas | a review package or build `check/` folder whose compiled model declares `pages[].regions[]` | every region, by page |
30
+ | atlas | a review package or build `check/` folder whose compiled model declares `pages[].regions[]`; read-only within rig review or saved-verdict export, refused at parts workspace open | every region, by page |
22
31
 
23
32
  ## What it shows
24
33
 
25
- - **Every part on its own**, on a sentinel background (green, magenta, black, white or checker), at native scale with
34
+ **Historical UI:** the following describes the former standalone parts page.
35
+ Use the current shared Setup workspace; these controls are not a second screen.
36
+
37
+ - **Every part on its own**, on a checker background by default (green, magenta, black and white are also available), at native scale with
26
38
  Fit and exact **1:1**, cursor-anchored wheel zoom, pinch and drag pan in the shared rig/reference viewport pair. Sampling stays nearest-neighbour. **Alpha only** shows the alpha channel as grey (white is opaque).
27
39
  - **Footprints of parts in front** (parts mode): the alpha of every part later in `parts.json` whose box meets the
28
40
  selected part's box, placed by its rig box and tinted cyan at 50 %. Where the selected part has no pixel under its
@@ -30,12 +42,15 @@ is written), `--painting <png>` (the original painting), `--by <name>` (launch-o
30
42
  occluder's shape at a glance. Nothing is measured; the tint is the front parts' own alpha.
31
43
  - **Atlas mode**: the pages as packed, with each region's box and name; the background shows through padding, and a
32
44
  region's own view keeps 4 page pixels around its box (dashed) so bleed is visible. Clicking a region opens it.
33
- - **Producer flags**, read from the files rig-parts writes and shown on the part they name. None is re-measured here. Each reads as one labelled line (an opening's parts, animation, frame and cells; a seam pair's pixel counts; a gate's name, status and readings), with the producer's object verbatim under a collapsed **Producer line**.
45
+ - **Historical UI — Producer flags (removed in #745)**, read from the files rig-parts writes and shown on the part they name. None is re-measured here. Each reads as one labelled line (an opening's parts, animation, frame and cells; a seam pair's pixel counts; a gate's name, status and readings), with the producer's object verbatim under a collapsed **Producer line**.
34
46
 
35
47
  The [23-part EN/KO comparison](https://github.com/rig-c/review/tree/main/tests/fixtures/parts-approve-all-evidence) records the same 1600×1100 initial view against installed 1.8.0: row height 49.375 → 26.1875 px, with all 23 after rows on one line (`tests/parts-approve-all-browser.ts`).
36
48
 
37
49
  ### Producer row groups
38
50
 
51
+ **Historical UI:** sidebar groups and badges below were removed in #745.
52
+ The producer row metadata and legacy API/verdict references are preserved.
53
+
39
54
  The sidebar counts **only mesh-report flags and explicit part findings**. A check row counts only
40
55
  when `row_scope: "part"`, `row_kind: "finding"` and a valid `row_subjects` array names that part.
41
56
  A block status, a JSON path, a reason or a legacy part/slot/bone field never determines classification.
@@ -97,11 +112,18 @@ The occlusion-coverage report (rig-c/parts#998) is not read yet; the footprint t
97
112
  Standalone sign-off uses saved files. The active Create and Parts cycle uses finalized acts through the
98
113
  [standing live job workflow](WORKFLOWS.md#standing-live-job-workflow).
99
114
 
100
- **Approve all** marks every pending part and available mesh clean, then saves an explicit approved sign-off. It preserves notes and existing clean outcomes; any flagged part or mesh refuses with `PARTS_APPROVE_ALL_FLAGGED` before changes are made. Individual approval remains available. `tests/parts-approve-all.test.ts` exercises the page action and unchanged verdict guard; `tests/parts-approve-all-browser.ts` checks the real save and refusal flows.
115
+ **Historical UI, superseded by #741/#751:** the former workspace kept pointed issues in the persistent **Issues** sidebar, including an empty state.
116
+ **Save sign-off** saves the current issue collection. An empty collection approves the inspection, and a
117
+ non-empty collection requests changes. The live job host submits the same issue collection through its
118
+ review dialog. Reviewer wording stays verbatim.
101
119
 
102
- Each item is **pending**, **clean** or **flagged** with a note (a note is optional on clean). **Save sign-off**
103
- writes `parts-review.json` beside `parts.json` (atlas mode: beside the model), or to `--verdict`.
104
- An unnamed save has the following `/2` shape.
120
+ Historically, **Approve all** marked every pending part and available mesh clean and saved an approved
121
+ sign-off. It preserved notes and existing clean outcomes, and refused flagged items with
122
+ `PARTS_APPROVE_ALL_FLAGGED`. Per-part approval and mesh outcomes belong to that historical UI and
123
+ `/1`–`/3` read compatibility. The existing `tests/parts-approve-all.test.ts` and
124
+ `tests/parts-approve-all-browser.ts` now exercise the shared mount and current issue-based save flows.
125
+
126
+ New saves write `schema: "rig-review-parts-verdict/4"` (`status: "approved"` when `issues` is empty, `"changes-requested"` when `issues` is non-empty, `issues: PartsIssue[]`, `updatedAt`, and optional `by`) to `parts-review.json` beside `parts.json` (atlas mode: beside the model), or to `--verdict`. In historical `/1`..`/3` saves, each item was **pending**, **clean** or **flagged** with a note (a note is optional on clean), and an unnamed historical `/2` save had the following shape (preserved on read):
105
127
 
106
128
  ```json
107
129
  {
@@ -126,12 +148,12 @@ An unnamed save has the following `/2` shape.
126
148
  - `source.sha256` is the SHA-256 of the UTF-8 lines `<path>\t<sha256>\n`, one per `source.files` entry, sorted by path
127
149
  bytewise. Review revalidates inspected inputs when reading a saved verdict.
128
150
  - `source.flags` lists the producer files the flags were read from; `parts.<name>.flags` the historical producer-attribution IDs defined above, not the classified sidebar count.
129
- - `status`: `approved` only when every part is clean; `changes-requested` only with at least one part flagged;
130
- otherwise `pending`.
151
+ - Historical `/2` `status` is `approved` when every part is clean, `changes-requested` with at least one
152
+ flagged part, and otherwise `pending`.
131
153
 
132
- Refusals, by name: `PARTS_VERDICT_MISSING_PART`, `PARTS_VERDICT_UNKNOWN_PART`, `PARTS_VERDICT_NOTE_REQUIRED`,
133
- `PARTS_VERDICT_NOT_CLEAN`, `PARTS_VERDICT_NOTHING_FLAGGED`, `PARTS_VERDICT_INVALID`, and `PARTS_VIEW_SOURCE_CHANGED`
134
- when a file changed after the view opened.
154
+ Historical per-part validation refusals include `PARTS_VERDICT_MISSING_PART`, `PARTS_VERDICT_UNKNOWN_PART`, `PARTS_VERDICT_NOTE_REQUIRED`,
155
+ `PARTS_VERDICT_NOT_CLEAN` and `PARTS_VERDICT_NOTHING_FLAGGED`. Current saves retain `PARTS_VERDICT_INVALID`
156
+ for invalid verdicts and `PARTS_VIEW_SOURCE_CHANGED` when an inspected file changes after opening.
135
157
 
136
158
  A verdict destination matching a protected part, producer report, rig/package input, model or atlas image is
137
159
  refused as `PARTS_VERDICT_INPUT_COLLISION`, including normalized paths, symbolic links and filesystem aliases.
@@ -141,8 +163,8 @@ Sign-off JSON requests are limited to 4 MiB (4,194,304 bytes) of UTF-8 while str
141
163
  cancelled before its remainder is read; a valid request exactly at the byte limit is accepted. Same-origin and
142
164
  write-capability requirements remain unchanged.
143
165
 
144
- On reopen, a saved sign-off is offered only when both `source.sha256` and `source.flags` match the files on disk. When
145
- only the producer flags differ, the page says the saved sign-off is for different producer flags and starts fresh.
166
+ **Historical flag-bound sign-off UI:** on reopen, the former page offered a saved sign-off only when both `source.sha256` and `source.flags` matched the files on disk.
167
+ **Historical UI:** when only the producer flags differed, the page said the saved sign-off was for different producer flags and started fresh.
146
168
  Consumers that gate on the sign-off (rig-c/create) check `source.sha256`.
147
169
 
148
170
  Every file the view reads from a package resolves inside it: a part PNG or `parts.json` that symlinks out is refused
@@ -170,17 +192,16 @@ no attribution authority. Opening and reading preserve the saved bytes.
170
192
  | --- | --- |
171
193
  | Legacy `rig-review-parts-verdict/1` or `/2` | `by: null`, including an ignored historical `by` extension |
172
194
  | Named `rig-review-parts-verdict/3` | Required nonblank `by`, preserved verbatim |
173
- | Explicit resave from an unnamed launch | New ordinary `/2` save with `by: null` on read, clearing the earlier name |
195
+ | Pointed-issue `rig-review-parts-verdict/4` | `issues: PartsIssue[]` (`rig-review-parts-comment/2`), optional nonblank `by` (`null` on CLI read when omitted) |
196
+ | Explicit resave from an unnamed launch | New `/4` save (historical `/2` before `/4`) with `by: null` on read, clearing the earlier name |
174
197
 
175
- Named `/3` keeps the existing verdict fields and adds required `by`. A missing, null, non-string or
176
- whitespace-only `/3` name refuses `PARTS_VERDICT_INVALID`. Older executables accepting only `/1` and `/2`
198
+ Named `/3` keeps the existing historical verdict fields and adds required `by`. Pointed-issue `/4` replaces the per-part outcome map with `issues` (`rig-review-parts-comment/2`) and optional `by`; historical `/1`, `/2` and `/3` saves that are `pending` or contain bare flagged part or mesh notes without a matching comment surface in the UI as read-only legacy verdicts (`PARTS_VERDICT_LEGACY_FORMAT`, `flaggedCount`) and preserve their historical `/1`..`/3` schema and `parts` map on `parts <input> --format json`. A missing, null, non-string or
199
+ whitespace-only `/3` (or present `/4`) name refuses `PARTS_VERDICT_INVALID`. Older executables accepting only `/1` and `/2`
177
200
  reject named `/3` with that refusal. This opt-in saved-format compatibility cost is part of the contract.
178
201
 
179
- Ordinary `parts <input> --format json` returns normalized `schema: "rig-review-parts-verdict/2"` with
180
- every existing field, including `mode`, `tool`, `source`, `status`, all per-part outcomes, notes and flags,
181
- available mesh outcomes and notes, `comments` and `updatedAt`. It adds root `by: string | null` and
202
+ Ordinary `parts <input> --format json` returns `schema: "rig-review-parts-verdict/4"` (`mode`, `tool`, `source`, `status`, `issues` with resolved `crop.path` and `nativeCrop.path`, and `updatedAt`) for `/4` saves and for historical `/1`..`/3` saves whose flags are all covered by pointed comments (or that are approved with no issues, where `/1` normalizes to `issues: []`), while historical `/1`..`/3` saves that are `pending` or carry bare flagged part or mesh notes retain their historical `schema` (`"rig-review-parts-verdict/1"`, `"/2"`, or `"/3"`), per-part outcomes, notes and flags, available mesh outcomes and notes, optional `comments`, `issues` and `updatedAt`. Every CLI JSON read adds root `by: string | null` and
182
203
  `savedFileSha256`, a 64-character lowercase hexadecimal SHA-256 of the exact saved bytes, including any
183
- final LF. Legacy reads retain their original byte digest and `/1` normalizes to empty comments.
204
+ final LF, retaining the original byte digest on legacy reads.
184
205
 
185
206
  The core, recorded name and digest derive from one validated saved-file snapshot, with current source
186
207
  and producer-flag checks. `source.sha256`, `source.files` and `source.flags` retain the inspected-input
@@ -229,14 +250,27 @@ Crash-proof exactly-once delivery requires an additional acknowledgment/replay p
229
250
 
230
251
  ## Mesh geometry
231
252
 
253
+ **Historical UI:** the toggle labels and geometry/numbers panel below describe
254
+ the removed standalone parts page (#745). Current visual inspection uses Mesh
255
+ edges in the shared workspace. Geometry inputs and legacy wire references below
256
+ remain compatibility information, not a request to restore the old panel.
257
+
232
258
  In parts mode, a `rig.json` beside `parts.json` supplies optional mesh geometry;
233
- `--rig <file>` selects an explicit input instead. The per-part **mesh from
234
- rig.json UVs** toggle starts off. It draws edges and vertices over the sentinel
235
- background, and tints nontransparent art pixels pink when their centres lie
236
- outside every nondegenerate triangle (triangle boundaries count as covered).
237
- The mesh outcome has its own Pending / Clean / Flagged states and note; Flagged
238
- requires a note. Approval requires both part and mesh outcomes to be Clean.
239
- A part without a mesh has no mesh controls or outcome.
259
+ `--rig <file>` selects an explicit input instead. The workspace-wide **mesh from
260
+ rig.json UVs** toggle starts off and retains its setting across part selection, assembled view,
261
+ Overlay and Difference in both standalone and live job hosts. It draws edges and vertices for
262
+ visible mesh-bearing parts. The selected part also tints nontransparent art pixels pink when their
263
+ centres lie outside every nondegenerate triangle (triangle boundaries count as covered).
264
+ Other assembled meshes use reduced-opacity wire lines. The selected part's geometry panel names
265
+ unavailable geometry explicitly. A draft with no mesh geometry retains a **Mesh (none 0/n)** control
266
+ and an unavailable message. A mesh attachment that declares a plain-object `generator` without inline
267
+ `uvs` or `triangles` is accepted without reconstructing geometry. Its part raster renders normally
268
+ without a mesh overlay, the item reports `meshUnavailable: "PARTS_MESH_GENERATED"`, and the **Mesh
269
+ geometry** panel states `PARTS_MESH_GENERATED: No mesh geometry is available for this part.` Non-object
270
+ `generator` values or attachments combining `generator` with `uvs` or `triangles` still refuse by name.
271
+
272
+ Historical per-part mesh outcomes had Pending / Clean / Flagged states and a note. Flagged required a
273
+ note, and approval required clean part and mesh outcomes. These fields remain legacy read data.
240
274
 
241
275
  Image-space positions are `(u × width, v × height)` from each attachment's own
242
276
  UVs and dimensions, never reconstructed through bones or weights. The mesh's raster
@@ -256,9 +290,9 @@ not an exact recovery of the producer's original unrounded positions.
256
290
 
257
291
  Mode, vertex count, triangle count, `art_coverage` and `stray_cleared` are copied
258
292
  from the part's `mesh_report.json` row without recomputing them. Absent fields
259
- say **not reported**; faint islands remain in Producer flags. A report count may
260
- differ from the loaded geometry; it is the producer's reading. The verdict's
261
- `parts[name].mesh` contains `{outcome,note}` only for a mesh-bearing part.
293
+ say **not reported**; **historical UI:** faint islands remained in Producer flags. A report count may
294
+ differ from the loaded geometry. These are producer readings. Historical verdicts stored
295
+ `parts[name].mesh` as `{outcome,note}` only for a mesh-bearing part.
262
296
  `rig.json` and the loaded mesh report enter `source.files`, and the mesh report
263
297
  also remains in `source.flags`. Changes invalidate the saved sign-off. No rig
264
298
  means the existing parts view and verdict format remain unchanged.
@@ -289,27 +323,35 @@ The four-stage navigator preserves this entry and its explicit save behavior. Co
289
323
  ## Pointed parts comments
290
324
 
291
325
  **Comment · C (n)** uses the same capture toggle, dragged region, composer and pins as the rig stage.
292
- While capture is on, drag draws only a region; close the toggle to pan. Enter adds the comment;
293
- **Save sign-off** persists the verdict. Select a comment row or pin after reopening to restore its
294
- part, both cameras, background, alpha, footprints, mesh and painting comparison view. There is no frame, animation or slot
295
- placeholder in a parts comment. Atlas inspection remains read only for pointed comments.
296
-
297
- `rig-review-parts-verdict/2` adds `comments[]`; a `/1` file reads with an empty comment array.
298
- Each closed `rig-review-parts-comment/1` carries `id`, original reviewer `summary`, `part`,
299
- `imageHash` (SHA-256 of the original part PNG), `sourceHash` (the verdict source identity),
300
- `imageRegion`, `rigRegion`, `view`, `crop` and `nativeCrop`. `imageRegion` has integer native
301
- pixel edges snapped outward from the drag. `rigRegion` is exact placement plus that region,
326
+ The **Issues** list stays visible in the side panel while C opens or closes capture. While capture is
327
+ on, drag within the rig pane away from existing pins and controls to mark a region. Close capture to
328
+ pan. Enter adds the issue,
329
+ and **Save sign-off** persists the verdict. Escape cancels the composer or capture while the inline
330
+ list stays visible. Rows and pins use the same edit, delete and jump actions.
331
+
332
+ Select an issue row or pin after reopening to restore its item or assembled view, both cameras,
333
+ background, alpha, footprints, mesh and painting comparison. Atlas inspection remains read only for
334
+ pointed comments. Joined compiled Stage 1 refuses issue authoring with
335
+ `PARTS_JOINED_ISSUE_UNSUPPORTED` and directs the reviewer to the standing live job route. Its
336
+ zero-issue approval path remains available.
337
+
338
+ `rig-review-parts-verdict/4` stores `issues[]` of closed `rig-review-parts-comment/2` records (historical `rig-review-parts-verdict/2` and `/3` stored `comments[]` of `rig-review-parts-comment/1`; a historical `/1` verdict file reads with an empty array).
339
+ Each historical closed `rig-review-parts-comment/1` carries `id`, original reviewer `summary`, `part`,
340
+ `imageHash` (SHA-256 of the original part PNG), `sourceHash` (the verdict source identity, or the server-retained publication `sourceHash` when prepared in a live job),
341
+ `imageRegion`, `rigRegion`, `view`, `crop` and `nativeCrop`; `rig-review-parts-comment/2` generalizes `part` + `imageHash` to a non-empty unique `parts: [{name, imageHash}]` array and supports `view.mode: "item"` (requiring integer `imageRegion`, exact `rigRegion = placement(parts[0]) + imageRegion`, and server-cut `nativeCrop`) and `view.mode: "assembled"` (`imageRegion: null`, `nativeCrop: null`, and integer `rigRegion` fully contained within the union bounding box of `parts`). `imageRegion` has integer native
342
+ pixel edges snapped outward from the drag. In item mode, `rigRegion` is exact placement plus that region,
302
343
  including fractional placement; it is never rounded. `view.camera` records native scale,
303
344
  center and viewport extent, plus `cameraSync` and the actual `referenceCamera` (or null), alongside `background`, `alpha`, `footprints` and `mesh`. New comments add optional
304
345
  `view.comparison: {mode:"part"|"overlay", opacity:0..1}`; older comments omit it and restore the
305
346
  ordinary part view. Unknown modes/keys and out-of-range opacity refuse `PARTS_COMPARISON_INVALID`.
306
347
 
307
348
  The viewport `crop` comes from the shared displayed-pixel compositor and includes its mark.
308
- `nativeCrop` is cut on the server from the hash-bound original PNG, preserving all RGBA bytes,
309
- including alpha. Both use the common PNG validator/content-addressed store; paths are selected
310
- by the server. The native crop has no alpha-mask, background or zoom transform. The saved
311
- viewport crop includes its private inline PNG; exported JSON and issue Markdown replace it
312
- with a resolved file path and hash. Both exports name the part and both regions and crops.
349
+ In item mode, `nativeCrop` is cut on the server from the hash-bound original PNG, preserving all
350
+ RGBA bytes, including alpha. It has no alpha-mask, background or zoom transform. Assembled issues
351
+ retain their rig-space region and viewport crop, with `imageRegion` and `nativeCrop` both null.
352
+ Crops use the common PNG validator/content-addressed store and server-selected paths. The saved
353
+ viewport crop includes its private inline PNG. Exported JSON and issue Markdown resolve stored
354
+ crops to file paths and hashes and retain the referenced parts and regions.
313
355
 
314
356
  ```sh
315
357
  npx rig-review parts <out>/rig --painting painting.png
@@ -318,7 +360,7 @@ npx rig-review parts <out>/rig --painting painting.png --format issue
318
360
  ```
319
361
 
320
362
  The optional painting must be a PNG contained in the parts package (including symlink resolution),
321
- with a portable source path. Format, size and hash derive from one buffer read. Its original dimensions
363
+ with a portable source path. In the live job host, a painting loaded from a retained snapshot via `paintingRoot` must instead resolve inside that snapshot root and match its retained seal. Format, size and hash derive from one buffer read. Its original dimensions
322
364
  must satisfy `trunc(width × scale_rig_per_source) = rig_size[0]` and the equivalent height check
323
365
  (`PARTS_PAINTING_SIZE`); missing/invalid declared geometry refuses `PARTS_PAINTING_MAPPING`.
324
366
  The painting stays in `source.files` and the protected input set. Adding it to an older verdict changes
@@ -333,7 +375,7 @@ Both use the existing canvas host/camera/capture. The original source rectangle
333
375
  `(x × originalWidth/rigWidth, y × originalHeight/rigHeight, w × originalWidth/rigWidth,
334
376
  h × originalHeight/rigHeight)`, retaining fractional placement. Browser image interpolation displays
335
377
  this continuous rectangle; it does not reproduce the producer's resampling or claim native pixel equality.
336
- Alpha-only and mesh diagnostics are disabled in Overlay; front footprints remain available.
378
+ Overlay retains the global mesh setting and front footprints. Alpha-only applies to the ordinary part raster.
337
379
  Without a painting the comparison controls are absent and the reference pane names
338
380
  `PARTS_REFERENCE_UNAVAILABLE`. No comparison changes the verdict. These behaviors are guarded by
339
381
  `tests/parts-comparison.test.ts`; `tests/parts-overlay-browser.ts` separately exercises trusted input,
@@ -357,9 +399,13 @@ For real scaled evidence, `scripts/prepare-parts-overlay-demo.ts` fetches hash-v
357
399
  inputs at `ba99e403d4058fc1cfe40699bdcde8aaf00a90c0`, then runs explicitly installed `@rig-c/parts@2.17.0`
358
400
  assemble in a separate fixture directory. It is an evidence script, never an app action.
359
401
 
360
- **Difference remains absent** pending the producer-declared rig-space painting raster and
361
- [the waiting consumer #390](https://github.com/rig-c/review/issues/390). Review adds no producer resampler.
362
- Neither visual comparison nor opening a package supplies an approval.
402
+ The earlier visual-comparison release deferred Difference to
403
+ [consumer #390](https://github.com/rig-c/review/issues/390). The current producer-declared operand and
404
+ metric are documented under [Declared-grid Difference](#declared-grid-difference).
405
+
406
+ Hold **P** to show the original painting at full opacity in item or assembled view. Capture is
407
+ suspended during the hold. Releasing P, leaving the active mount, hiding the document or losing
408
+ window focus restores the inspection view. The hold is temporary inspection state.
363
409
 
364
410
  Parts native zoom ranges from `min(fit, 1)` to 16. Exact native 1 is always reachable for a valid,
365
411
  successfully rendered frame. **Fit** is
@@ -389,30 +435,41 @@ while the existing verdict cannot be revalidated. Real source/flag identity chan
389
435
  separate stale warning. `PARTS_PAINTING_OUTSIDE` and `PARTS_PAINTING_PNG` refuse external or non-PNG
390
436
  painting inputs. `tests/parts-comments.test.ts` covers these read and cross-encoding boundaries;
391
437
  `tests/parts-async-navigation.test.ts` guards reordered painting loads and actionable atlas clicks.
392
- A downstream create consumer must support verdict/2 before a review release can ship.
438
+ The historical verdict/2 rollout required downstream create read support before release.
393
439
 
394
440
  ### Assembled package
395
441
 
396
- **Assembled** toggles the existing rig/reference pair from the selected part to the declared
442
+ **Assembled** switches the existing rig/reference pair from the selected part to the declared
397
443
  `rig_size` canvas. Parts draw back to front in package order at their exact fractional rig-pixel
398
- placements. The checkbox beside each part controls assembly visibility only; the verdict remains
399
- per part. List rows occupy one line, with full part names available to assistive technology and on hover, separate source counts and the outcome badge. The former **Visible / 표시** caption is removed; the checkbox retains its per-part accessible name (`tests/parts-approve-all.test.ts`, with full-list geometry in `tests/parts-approve-all-browser.ts`). A tap selects the frontmost visible part with nonzero native source alpha, including
400
- through transparent holes; drags remain camera gestures. The selected part's alpha edge is a
401
- separate outline, outside the comparison raster. Background, alpha-only, Fit, 1:1 and the shared
402
- camera controls remain available. `tests/parts-assembly.test.ts` guards fractional placement,
403
- order controls, picking, hidden layers, separate outline pixels and per-part verdict invariance.
404
-
405
- With `--painting`, the reference pane and optional Overlay use the same whole-canvas visual
406
- mapping described above. No producer resampler, Difference or assembled verdict is added.
407
- Without painting the reference keeps `PARTS_REFERENCE_UNAVAILABLE`; atlas assembly is disabled
408
- because atlas regions carry no rig placement, and missing `rig_size` is named separately.
409
- Comments remain bound to individual original PNGs: switch out of assembly to capture one;
410
- restoring a saved comment returns to its individual part view. Assembly visibility is temporary
411
- inspection state and is never saved into a verdict or comment. `tests/parts-assembly-browser.ts`
412
- checks real EN/KO assembly/reference pixels against an independent browser draw after a
413
- base-vs-base control, tap/hole/hide selection, pan, camera preservation, background, alpha,
414
- verdict save and missing-input refusals. Existing `tests/parts-comparison.test.ts` and
415
- `tests/parts-comments.test.ts` retain the painting-size and protected-input guards.
444
+ placements. Each part's checkbox controls assembly visibility. A tap selects the frontmost visible
445
+ part with nonzero native alpha, including through transparent holes. Hover outlines that part and
446
+ shows its name. Double-click opens its individual view. Escape returns from an individual part to
447
+ assembly when comment capture or a draft does not own the key. Drags with capture off remain camera
448
+ gestures. Selected, hovered and issue-referenced outlines stay separate from the comparison raster.
449
+ Background, alpha-only, Fit, 1:1 and shared camera controls remain available.
450
+
451
+ The one-line part rows retain full accessible names and source counts. The historical outcome badge
452
+ and **Visible / 표시** caption belong to the earlier per-part sign-off UI. Existing
453
+ `tests/parts-assembly.test.ts` guards placement, ordering, alpha picking, hidden layers and outlines.
454
+
455
+ An assembled issue can span several parts. The composer autoattaches part-name chips by sampling
456
+ frontmost visible nontransparent art within the marked region. Review the chips and add or remove
457
+ visible parts as needed. At least one referenced part is required, and the rig-space region must
458
+ remain inside their combined bounding box. Editing chips or wording validates and prepares the
459
+ candidate through the same source-bound crop pipeline before replacing the existing issue. A rejected
460
+ edit preserves the existing issue. Restoring an issue restores assembled view and highlights its
461
+ referenced parts. Assembly visibility stays temporary and is excluded from saved issues and verdicts.
462
+
463
+ With `--painting`, the reference pane and Overlay use the same whole-canvas visual mapping described
464
+ above. Without painting the reference names `PARTS_REFERENCE_UNAVAILABLE`. Atlas assembly is disabled
465
+ because atlas regions carry no rig placement, and missing `rig_size` is named separately. Difference
466
+ uses the individual part view described below.
467
+
468
+ `tests/parts-assembly-browser.ts` covers EN/KO assembly/reference pixels against an independent browser
469
+ draw, alpha picking, hidden layers, pan and camera preservation. `tests/parts-comments-browser.ts`
470
+ covers assembled seam capture, chip edits, saved-view restoration, crop evidence and source immutability
471
+ in both languages. `tests/parts-mesh-browser.ts` covers the global mesh control and unavailable states.
472
+ The live job host's `tests/job-image-screen-browser.ts` covers the same mount through submission and reconnect.
416
473
 
417
474
  ## Draft mesh correction connection
418
475