@rig-c/review 2.0.0 → 2.1.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.
package/README.md CHANGED
@@ -46,10 +46,10 @@ the same CLI. `@rig-c/review` remains the canonical package.
46
46
 
47
47
  The CLI and `@rig-c/review/job-host` managed owner host are supported surfaces. See [Public API stability](docs/STABILITY.md) for the frozen exports and signatures.
48
48
 
49
- Example stdout from `open` (instance values vary):
49
+ Example stdout from `open` (private capability omitted):
50
50
 
51
51
  ```text
52
- http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…
52
+ http://127.0.0.1:4318/?workspace=<incarnation>#cap=…
53
53
  ```
54
54
 
55
55
  ## What you can do
@@ -57,7 +57,7 @@ http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…
57
57
  | Task | Command or panel | Destination |
58
58
  | --- | --- | --- |
59
59
  | **Hand off and compare** | | |
60
- | <a id="one-command-owner-handoff"></a>Open an inspection | `open` | [Owner handoff — WORKFLOWS](docs/WORKFLOWS.md#one-command-owner-handoff) |
60
+ | <a id="one-command-owner-handoff"></a>Open an inspection workspace | `open` | [Owner handoff — WORKFLOWS](docs/WORKFLOWS.md#one-command-owner-handoff) |
61
61
  | <a id="existing-output-handoff"></a>Inspect an existing folder | `check`, `review` | [Existing output handoff — WORKFLOWS](docs/WORKFLOWS.md#existing-output-handoff) |
62
62
  | <a id="compare-two-outputs"></a>Compare two builds against a video | `compare` | [Compare two outputs — WORKFLOWS](docs/WORKFLOWS.md#compare-two-outputs) |
63
63
  | <a id="feedback-ownership"></a>Retrieve submitted feedback | `feedback` | [Feedback ownership — WORKFLOWS](docs/WORKFLOWS.md#feedback-ownership) |
package/docs/WORKFLOWS.md CHANGED
@@ -94,10 +94,12 @@ The footer fits its measured text while retaining full hashes. Text is drawn in
94
94
 
95
95
  ## One-command owner handoff
96
96
 
97
- `open` validates and hashes an existing folder, starts a background loopback
98
- instance or reuses the exact matching one, prints its hash-bound URL, and exits.
99
- By default the URL goes through the managed front at `127.0.0.1:4318`; `--direct`
100
- prints the instance's own port instead (see [Managed front and write capability](#managed-front-and-write-capability)):
97
+ `open` validates and hashes designated folders, starts or reuses one background
98
+ loopback owner workspace, prints its owner URL, and exits. **N rigs → one
99
+ invocation, one owner link.** Targets share one listener-owning process and port.
100
+ The default port is `127.0.0.1:4318`; `RIG_REVIEW_FRONT_PORT` selects an explicit
101
+ port. The URL has the form `http://127.0.0.1:4318/?workspace=<incarnation>#cap=…`; keep its capability
102
+ private and give the person one link plus one what-to-look-at line.
101
103
 
102
104
  ```sh
103
105
  bun run open -- /absolute/output --reference /absolute/original.mp4
@@ -142,8 +144,9 @@ checkpoints do not apply another clip's time or axis. Static/source-only package
142
144
  remain inspectable without claiming clip selection; explicit unvalidatable clips
143
145
  refuse. Single review sessions remain package-wide; animation selection does not
144
146
  create an animation-specific approval identity. Opening never
145
- approves a review. The command prints the matching feedback retrieval command on
146
- stderr; stdout contains the URL alone. A selected external video takes precedence
147
+ approves a review. Retrieve submitted feedback with the original per-target input and handoff
148
+ arguments; stdout contains the owner URL alone. The workspace summary on stderr
149
+ does not print a per-target feedback command. A selected external video takes precedence
147
150
  at automatic startup; an explicit checkpoint link or manual checkpoint selection
148
151
  still chooses that checkpoint's reference.
149
152
 
@@ -162,28 +165,105 @@ binding. Headless equivalent (the original declared-reference form stays valid):
162
165
  rig-review strip /absolute/output --reference-video /absolute/original.mp4 --animation dance --frames 176:184 --out /absolute/external/strip.png
163
166
  ```
164
167
 
165
- Only tool-owned instances with matching content, canonical input locations, tool
166
- fingerprint and a private capability handshake are reused. The URL hash is
167
- checked before serving the app; a stale link never selects another instance's
168
- package. Input hashes are freshly computed, not trusted from mtime caches. In both
169
- `open` and foreground `review` / `review compare`, each open window holds a live
170
- WebSocket connection (`/api/live`); once the last window closes and stays at zero connections
171
- for the 3-second grace period, or if no window ever connects within 30 minutes
172
- (reusing a windowless worker via `open` gives it a fresh 30-minute unopened window),
173
- the server finishes any in-flight request or Apply, flushes state, prints one line
174
- stating why it exited, and exits `0`. A browser that unloads a background tab to
175
- save memory looks the same as a closed tab, so the server stops; saved feedback
176
- survives and `open` brings it back. Their
177
- private registry, requests and logs live beside feedback under
178
- `~/.local/state/rig-c-review/open/`; nothing is written into supplied folders. `RIG_REVIEW_STATE_DIR` selects another state root
179
- outside all input packages, judged by its canonical location (symlinks in the path
180
- and its existing ancestors resolved). Existing foreground review commands still work.
168
+ ### Multiple targets and repeated open
181
169
 
182
- No browser is opened, no LAN listener is added, and no misleading phone/QR URL is
183
- printed: every current instance binds only `127.0.0.1`.
170
+ `--animation` supplies the default clip for every target. Repeat
171
+ `--animation-for <index> <name>` to override distinct 1-based target positions.
172
+ This opens nine rigs, selecting `walk` for `dirB` and `idle` for the others.
184
173
 
185
- The printed feedback retrieval command uses POSIX shell quoting for literal path
186
- arguments. It is not a PowerShell or cmd.exe command string.
174
+ ```sh
175
+ rig-review open dirA dirB dirC dirD dirE dirF dirG dirH dirI \
176
+ --animation idle --animation-for 2 walk --view-only
177
+ ```
178
+
179
+ Indices outside the target list, invalid indices and duplicate overrides refuse
180
+ with `OPEN_OPTION_INVALID`. Common typed options apply to each target and retain
181
+ their existing validation. Each animation is validated against its own model.
182
+ A single primary target can use `--compare <other-dir>` with an explicit
183
+ `--reference <video>`; a multi-target batch with `--compare` is refused.
184
+ `--direct` accepts one primary target only.
185
+
186
+ Compatible repeated opens add to the same owner list and print the same root
187
+ owner URL, including its owner capability within that host incarnation. They exit
188
+ 0 and add no listener or resident per-rig worker.
189
+
190
+ ```sh
191
+ rig-review open dirA --animation idle --view-only
192
+ rig-review open dirB --animation walk --view-only
193
+ rig-review feedback dirA --animation idle --format json
194
+ ```
195
+
196
+ A consumer opened N rigs with N sequential `open` calls. Use the batch form when
197
+ all targets are known together. Duplicate compatible registrations reuse the
198
+ entry; conflicting options refuse with `WORKSPACE_TARGET_OPTIONS_MISMATCH`.
199
+ The owner selects targets from the list. `--view-only` entries are labelled
200
+ **Inspection only** and have no semantic act or pending approval. Existing
201
+ feedback semantics still apply within each inspection. Retrieve submitted
202
+ feedback using each target's exact original inputs, references and handoff
203
+ arguments. A shared owner URL supplies no feedback identity or approval.
204
+
205
+ Inspection frames load on selection and remain retained for their target's
206
+ camera, time, selected part/panel and source-bound draft. Switching pauses hidden
207
+ playback. Reviewer-authored words remain verbatim. Admission and retained frames
208
+ share a 32-target application limit. Adding target 33 refuses atomically with
209
+ `WORKSPACE_TARGET_LIMIT`, preserving the existing registrations. This bound is
210
+ an application limit, not a hardware memory or performance guarantee.
211
+
212
+ ### Workspace lifecycle and restart
213
+
214
+ The workspace owns one aggregate live lifecycle, shared by the owner page and
215
+ its target contexts. Target contexts have no independent server shutdown timers.
216
+ After all live connections close, the workspace waits the 3-second grace period
217
+ and for registrations, active response streams and target work to finish before
218
+ stopping. A workspace with no connected page has a 30-minute unopened window;
219
+ a successful registration re-arms that window when no page is connected.
220
+ These timers apply to the whole workspace. The separate per-instance behavior is
221
+ preserved under [Direct server and legacy lifecycle](#direct-server-and-legacy-lifecycle).
222
+
223
+ Reuse requires the same UID, installation, runtime and fingerprint, the designated
224
+ port and an authenticated live-host response. Mismatches refuse with
225
+ `WORKSPACE_OWNER_MISMATCH` or `WORKSPACE_HOST_MISMATCH`. A live but unresponsive
226
+ PID refuses with `WORKSPACE_HOST_UNRESPONSIVE`; a timeout leaves its ownership
227
+ intact. Concurrent launchers coordinate registration through the private store.
228
+
229
+ Restart creates a new host incarnation and rotates owner, launcher and target
230
+ secrets. The nonsecret `workspace` query changes with the incarnation, so opening
231
+ the new link in an existing tab loads a new document. Repeated opens within one
232
+ incarnation retain the same URL. Run `open` again and give the person the new
233
+ owner link. A supplied `workspace` query must match the current host; root links
234
+ without it remain accepted. Persisted input
235
+ designations are revalidated. Changed sources appear unavailable with
236
+ `WORKSPACE_SOURCE_CHANGED`; saved feedback and drafts retain their original
237
+ source binding. Registering another valid target remains possible when an
238
+ unrelated target's source has changed.
239
+
240
+ If a legacy front or another listener occupies the chosen port, launch refuses
241
+ with `FRONT_PORT_BUSY` and the instruction `use --direct` or set
242
+ `RIG_REVIEW_FRONT_PORT` explicitly. For example, choose another workspace port
243
+ with `RIG_REVIEW_FRONT_PORT=4320 rig-review open dirA --view-only`.
244
+ Leave existing workers and listeners under their current owner's control.
245
+
246
+ Workspace descriptors, designations, startup requests and logs live under
247
+ `<state>/owner-workspace/`, with private owner/launcher credentials and distinct
248
+ target capabilities. State stays outside every input package. Loopback-only,
249
+ same-origin bounded JSON mutations and contained package paths remain required.
250
+ Registration carries designated package inputs. Agents use supported commands
251
+ and APIs and never construct internal Review state or human acts.
252
+
253
+ ### Subsequent CLI and semantic paths
254
+
255
+ Plain foreground multi-target invocation and its compatible workspace joining
256
+ remain pending. The current delivery is the `open` CLI workspace. Core's
257
+ `rigc review` passes arguments through unchanged; Review owns the CLI grammar.
258
+
259
+ The embedded semantic-job hub also remains pending. Its same-process host will
260
+ own trusted `readPublished`, `partsEnumerator` and `installWriterBinding`
261
+ callbacks. General cross-process callback transport is deferred. Each job retains
262
+ independent source, reviewer, capabilities, generation CAS, cursor, displayed
263
+ acknowledgment and writer grant under job-api@2/act@2. Registration-handle detach,
264
+ host stop and semantic close remain separate lifecycle concerns. Follow the
265
+ current [standing live-job workflow](#standing-live-job-workflow) and
266
+ [public host contract](STABILITY.md#managed-owner-host) for semantic jobs.
187
267
 
188
268
  ### Launcher contract
189
269
 
@@ -192,7 +272,10 @@ stderr and exit code alone:
192
272
 
193
273
  1. On success stdout is exactly one line, the URL. `open` never writes anything
194
274
  else to stdout.
195
- 2. On success stderr carries the human lines in this fixed order: for the `check/`
275
+ 2. Managed workspace success writes per-target package/handoff and animation
276
+ diagnostics in target order, then `Review workspace started|reused; N target(s).
277
+ Retrieve feedback using the original input designation.` The direct-server
278
+ path retains the following stderr order. For the `check/`
196
279
  package of a `rig-parts build` output, `Package: rig-parts build check package <path>`
197
280
  and the handoff line (`Handoff <how>: <config path> sha256 <hash> · parts <dir>`, or
198
281
  `Handoff: <refusal>`); the animation diagnostic (when a clip is selected), the control notice (with `--control`),
@@ -205,20 +288,58 @@ stderr and exit code alone:
205
288
  - `OPEN_ANIMATION_UNKNOWN <name>`: the explicit or report-named clip (JSON-quoted) is not in the compiled model.
206
289
  - `OPEN_ANIMATION_AMBIGUOUS`: no flag or report selects one clip, or the A/B reports conflict.
207
290
  - `OPEN_ANIMATION_UNVALIDATABLE`: a clip was requested but no compiled model can validate it.
208
- - `OPEN_OPTION_INVALID <flag>`: an unknown, duplicate, empty or value-less option, a handoff flag without `--config`, `--source` without `--full` (or the reverse), or a handoff flag with `--compare`.
291
+ - `OPEN_OPTION_INVALID <flag>`: an unknown, duplicate, empty or value-less option, an invalid/out-of-range/duplicate `--animation-for` index, multi-target `--compare` or `--direct`, a handoff flag without `--config`, `--source` without `--full` (or the reverse), or a handoff flag with `--compare`.
209
292
  - `OPEN_STATE_INSIDE_PACKAGE <package | build root | handoff root>`: the state directory (`RIG_REVIEW_STATE_DIR` or the default), resolved through symlinks, lies inside an input package, the `rig-parts build` root a check package belongs to, or the producer handoff's root.
210
293
  - `OPEN_HANDOFF_INVALID <flag or path>`: a declared or discovered producer handoff path is refused — `HANDOFF_PATH_OUTSIDE_ROOT`, `HANDOFF_SYMLINK_ESCAPE`, `HANDOFF_INPUT_MISSING`, `HANDOFF_INPUT_INVALID` or `HANDOFF_PATH_INVALID`, named after the colon.
211
294
  4. Exit codes: 0 applied, 1 refused. (`control` keeps its own exit 2 for an
212
295
  unapplied command.)
213
296
 
214
- Package validation and worker startup refusals keep their existing messages; the
215
- named refusals above are decided before any state is written.
297
+ Input validation precedes workspace registration. Workspace startup and
298
+ registration refusals retain their named codes and exit 1. A refused batch
299
+ registration leaves existing registrations intact. Direct-worker refusals keep
300
+ their existing messages.
301
+
302
+ ### Direct server and legacy lifecycle
303
+
304
+ Use `rig-review open dirA --direct --animation idle --view-only` for a separate
305
+ single-target server. It prints the worker's own URL and retains the per-instance
306
+ lifecycle and hash-bound handoff described here. Foreground `review` and
307
+ `review compare` retain their existing separate-server behavior.
308
+
309
+ Only tool-owned instances with matching content, canonical input locations, tool
310
+ fingerprint and a private capability handshake are reused. The URL hash is
311
+ checked before serving the app; a stale link never selects another instance's
312
+ package. Input hashes are freshly computed, not trusted from mtime caches. In both
313
+ `open --direct` and foreground `review` / `review compare`, each open window holds a live
314
+ WebSocket connection (`/api/live`); once the last window closes and stays at zero connections
315
+ for the 3-second grace period, or if no window ever connects within 30 minutes
316
+ (reusing a windowless worker via `open --direct` gives it a fresh 30-minute unopened window),
317
+ the server finishes any in-flight request or Apply, flushes state, prints one line
318
+ stating why it exited, and exits `0`. A browser that unloads a background tab to
319
+ save memory looks the same as a closed tab, so the server stops; saved feedback
320
+ survives and `open --direct` brings it back. Their
321
+ private registry, requests and logs live beside feedback under
322
+ `~/.local/state/rig-c-review/open/`; nothing is written into supplied folders. `RIG_REVIEW_STATE_DIR` selects another state root
323
+ outside all input packages, judged by its canonical location (symlinks in the path
324
+ and its existing ancestors resolved). Existing foreground review commands still work.
325
+
326
+ No browser is opened, no LAN listener is added, and no misleading phone/QR URL is
327
+ printed: every current instance binds only `127.0.0.1`.
328
+
329
+ The printed feedback retrieval command uses POSIX shell quoting for literal path
330
+ arguments. It is not a PowerShell or cmd.exe command string.
216
331
 
217
332
  ### Managed front and write capability
218
333
 
219
- `open` is **managed by default**. It ensures one detached loopback front at
334
+ This heading preserves the legacy per-instance managed-front reference. Current
335
+ default `open` uses the [owner workspace](#one-command-owner-handoff).
336
+ `open --direct` serves its worker directly.
337
+
338
+ #### Legacy per-instance proxy
339
+
340
+ The earlier managed launcher ensured one detached loopback front at
220
341
  `127.0.0.1:4318` (`RIG_REVIEW_FRONT_PORT` overrides) for the state directory and
221
- prints `http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…`. Every
342
+ printed `http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…`. Every
222
343
  inspection therefore shares one stable browser origin, so Settings, panel sizes and
223
344
  source-bound drafts survive a reopen. The front only routes: it takes the worker
224
345
  address from that key's private open record, allows a closed per-method route
@@ -235,10 +356,12 @@ If another listener holds the front port, `open` fails with
235
356
  does not fall back silently. `open --direct` keeps the per-instance port and
236
357
  prints that worker's own URL.
237
358
 
359
+ #### Direct and legacy write capability
360
+
238
361
  One origin cannot isolate scripts that run on it, so writes are bound to a
239
362
  per-instance capability rather than to the page's origin or the key in its path.
240
363
  Each worker mints a 256-bit capability kept only in its private 0600 open record.
241
- `open` (managed or direct) and the foreground `review`/`review compare` commands
364
+ The legacy managed launcher, `open --direct` and the foreground `review`/`review compare` commands
242
365
  print it in the `#cap=` fragment, which browsers never send to a server. That
243
366
  printed link goes only to the terminal of the command that started the instance.
244
367
  Output meant for a log does not carry it: the install smoke (`bun run smoke`, whose output CI publishes) prints the same
@@ -249,7 +372,8 @@ checks it before forwarding and the worker compares it again in constant time
249
372
  before its existing same-origin check. No endpoint returns it, so a page opened
250
373
  for one instance cannot submit to another. A copied view link (without the
251
374
  fragment) opens read-only and says *Read-only view: reopen with rig-review open to
252
- edit*; run `open` again for a writable link.
375
+ edit*; run `open --direct` again for a writable per-instance link. Current workspace
376
+ owner links use the separate incarnation-bound capability described above.
253
377
 
254
378
  ## Control the current inspection page
255
379
 
@@ -273,7 +397,7 @@ rig-review control /absolute/output --reference /absolute/original.mp4 --page '<
273
397
 
274
398
  Use the same reference/compare/animation inputs as the controlled `open`. Multiple
275
399
  pages require an explicit `--page`. The URL and source binding stay unchanged;
276
- existing ordinary servers do not become controllable. Starting the opt-in worker
400
+ existing ordinary servers do not become controllable. Registering the opted-in target
277
401
  is a one-time handoff, not a new link for each parameter change.
278
402
 
279
403
  Commands cover appearance, automatic layout, synchronized or independent pane
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -10,6 +10,62 @@ compatibility: Requires Bun 1.3.0 or later on PATH. The canonical npm package is
10
10
  Use this to hand separated parts, a rig or a post to a person for inspection,
11
11
  or to read back their submitted review.
12
12
 
13
+ ## Open one owner workspace
14
+
15
+ For folder inspections, use **N rigs → one invocation, one owner link**.
16
+ `open` hosts designated targets in one loopback listener-owning process.
17
+ `--animation` supplies the default clip; `--animation-for <index> <name>` overrides
18
+ one 1-based target position. This opens nine rigs with `walk` for `dirB` and
19
+ `idle` for the others.
20
+
21
+ ```sh
22
+ rig-review open dirA dirB dirC dirD dirE dirF dirG dirH dirI \
23
+ --animation idle --animation-for 2 walk --view-only
24
+ ```
25
+
26
+ Invalid/out-of-range indices and duplicate overrides refuse with
27
+ `OPEN_OPTION_INVALID`. Common typed options retain their per-target validation.
28
+ Single-primary-target `--compare` requires `--reference`; batch compare is refused.
29
+ Compatible repeated calls also register into the same owner list.
30
+
31
+ ```sh
32
+ rig-review open dirA --animation idle --view-only
33
+ rig-review open dirB --animation walk --view-only
34
+ rig-review feedback dirA --animation idle --format json
35
+ ```
36
+
37
+ Both launchers exit 0 with the same root owner URL and capability within one
38
+ host incarnation, adding no listener or per-rig worker. A consumer opened N rigs
39
+ with N sequential `open` calls. Prefer one batch when the targets are known.
40
+ Give the person the private owner link and one what-to-look-at line.
41
+ View-only entries are labelled **Inspection only**, without semantic acts or
42
+ pending approvals. Existing feedback semantics apply per target. Retain each
43
+ target's original feedback lookup arguments, inspection state, source-bound
44
+ draft and verbatim reviewer words.
45
+
46
+ The workspace admits 32 targets and lazily retains selected frames under that
47
+ same application bound. Target 33 refuses atomically with
48
+ `WORKSPACE_TARGET_LIMIT`. The limit supplies no hardware performance guarantee.
49
+ Reuse requires matching UID, installation, runtime and fingerprint. Restart
50
+ rotates host and target secrets, so run `open` again for a new owner link. Its
51
+ nonsecret `?workspace=<incarnation>` query forces a new document in an existing
52
+ tab; same-host repeated opens retain the identical URL.
53
+ Changed sources become unavailable without rebinding their feedback.
54
+
55
+ The workspace defaults to port 4318, overridden by `RIG_REVIEW_FRONT_PORT`.
56
+ An occupied port refuses `FRONT_PORT_BUSY`; choose an explicit port or use the
57
+ single-target separate-server path
58
+ `rig-review open dirA --direct --animation idle --view-only`.
59
+ Leave existing workers under their owner's control. Follow
60
+ [workspace lifecycle and restart](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#workspace-lifecycle-and-restart)
61
+ for host reuse, live unresponsive PID refusal and aggregate shutdown behavior.
62
+
63
+ Plain foreground multi-target invocation and the embedded semantic-job hub remain
64
+ pending. Core's `rigc review` passes arguments through unchanged. Follow the
65
+ current active-cycle contract below for semantic jobs and trusted callbacks.
66
+ Keep imagery, questions and approvals in the Review UI, using supported commands
67
+ and APIs. Agents never construct internal Review state or human acts.
68
+
13
69
  ## Active cycle standing live-job contract
14
70
 
15
71
  For the active Create and Parts cycle, the authoritative contract is `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@2`, `JOB_ACT_SCHEMA` set to `rig-review/act@2`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](https://github.com/rig-c/review/blob/main/docs/STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). Do not invent public export names, producer scene fields or unimplemented flags, and never expose capabilities in reports or logs. See [Live job contract](https://github.com/rig-c/review/blob/main/docs/REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#standing-live-job-workflow).
@@ -63,7 +119,8 @@ The one-shot CLI file-handoff instructions in this section and in Correction rea
63
119
  Use the installed CLI. For compiled packages, run `rig-review check <package>`
64
120
  before handoff to validate the package and read its source SHA-256. Use managed
65
121
  `rig-review open` for joined inspection and embedded saves. Give the reviewer
66
- its URL from stdout privately and keep the exact feedback command from stderr.
122
+ its URL from stdout privately and keep the original per-target feedback lookup
123
+ arguments. The direct-server path also prints a copyable feedback command on stderr.
67
124
  The stage buttons navigate within that source binding.
68
125
 
69
126
  1. **Parts + mesh.** Open the recorded Create draft's compiled check directory.
package/src/build.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { fileURLToPath } from 'node:url';
2
2
  export const appRoot=fileURLToPath(new URL('..',import.meta.url));
3
- export async function buildWeb(mode:'single'|'compare'|'parts'|'interview'='single'):Promise<Blob> {
4
- const result=await Bun.build({entrypoints:[appRoot+(mode==='compare'?'web/compare.ts':mode==='parts'?'web/parts.ts':mode==='interview'?'web/interview.ts':'web/main.ts')],target:'browser',format:'esm',minify:false});
3
+ export async function buildWeb(mode:'single'|'compare'|'parts'|'interview'|'workspace'='single'):Promise<Blob> {
4
+ const result=await Bun.build({entrypoints:[appRoot+(mode==='workspace'?'web/owner-workspace.ts':mode==='compare'?'web/compare.ts':mode==='parts'?'web/parts.ts':mode==='interview'?'web/interview.ts':'web/main.ts')],target:'browser',format:'esm',minify:false});
5
5
  if(!result.success)throw new Error(result.logs.map(v=>v.message).join('\n'));
6
6
  const output=result.outputs.find(v=>v.path.endsWith('.js'));if(!output)throw new Error('frontend bundle: JavaScript output missing');return output;
7
7
  }
package/src/cli.ts CHANGED
@@ -25,7 +25,7 @@ import { readCompareSession } from './compare-session.ts';
25
25
  import { exportReviewStrip, exportCompareStrip, stripJson, writeStripOutput, validateStripOutput } from './strip-export.ts';
26
26
  import type { StripInterval, StripRequest } from './strip.ts';
27
27
  const handoffUsage='[--config <path> [--parts <dir>] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]]';
28
- const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> (--project-version <rig> [--post-version <post>] | --project-draft <id> [--parts-verdict-dir <dir>]) --picks-dir <dir>] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one loopback front at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) serves /instances/<key>/; --direct serves the worker on its own port.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--format json|issue] [--correction <item id>]\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n rig-review interview <create-root> --picks-dir <project-relative directory> [--port <n>]\n rig-review --version';
28
+ const usage='Usage: rig-review open <dir> [<dir> ...] [--animation-for <index> <name>] [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> (--project-version <rig> [--post-version <post>] | --project-draft <id> [--parts-verdict-dir <dir>]) --picks-dir <dir>] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one owner workspace at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) hosts targets in one process; --animation applies to all targets, --animation-for overrides one 1-based target, and --direct keeps a separate single-target worker.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--format json|issue] [--correction <item id>]\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n rig-review interview <create-root> --picks-dir <project-relative directory> [--port <n>]\n rig-review --version';
29
29
  async function stripCommand(args:string[],options:{stateDir?:string}){
30
30
  const compare=args[0]==='compare';if(compare)args.shift();const a=args.shift(),b=compare?args.shift():undefined;if(!a||compare&&!b)throw new Error('strip: expected package input(s)');
31
31
  let reference:string|undefined,referenceVideo:string|undefined,animation:string|undefined,basis:'a'|'b'|undefined,range:string|undefined,output:string|undefined,jsonOnly=false,all=false;
@@ -70,6 +70,50 @@ export function parseOpenInputs(args:string[]):OpenInputs {
70
70
  if(result.compare!==undefined&&handoffFlags(result))throw new Error('OPEN_OPTION_INVALID --config: compare takes no producer handoff; open one package with --config');
71
71
  return result;
72
72
  }
73
+
74
+ /** Common open options apply to every operand; indexed animation values override the common default. */
75
+ export function parseOpenTargets(args: readonly string[]): OpenInputs[] {
76
+ const inputs: string[] = [];
77
+ const common: string[] = [];
78
+ const animations = new Map<number, string>();
79
+ const booleanFlags = ['--control', '--direct', '--view-only'];
80
+ const valueFlags = ['--reference', '--compare', '--animation', ...projectFlags, ...HANDOFF_FLAGS.map(flag => '--' + flag)];
81
+ for (let index = 0; index < args.length; index++) {
82
+ const flag = args[index]!;
83
+ if (flag === '--animation-for') {
84
+ const target = args[++index], animation = args[++index];
85
+ if (target === undefined || !/^[1-9]\d*$/.test(target) || !Number.isSafeInteger(Number(target)) || animation === undefined || animation === '') {
86
+ throw new Error('OPEN_OPTION_INVALID --animation-for: expected a positive target index and animation name');
87
+ }
88
+ const targetIndex = Number(target);
89
+ if (animations.has(targetIndex)) throw new Error(`OPEN_OPTION_INVALID --animation-for: duplicate target index ${target}`);
90
+ animations.set(targetIndex, animation);
91
+ } else if (booleanFlags.includes(flag)) {
92
+ common.push(flag);
93
+ } else if (valueFlags.includes(flag)) {
94
+ const value = args[++index];
95
+ if (value === undefined || value === '') throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);
96
+ common.push(flag, value);
97
+ } else if (flag.startsWith('--')) {
98
+ throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);
99
+ } else {
100
+ inputs.push(flag);
101
+ }
102
+ }
103
+ if (inputs.length === 0) throw new Error(usage);
104
+ for (const target of animations.keys()) {
105
+ if (target > inputs.length) throw new Error(`OPEN_OPTION_INVALID --animation-for: target index ${target} exceeds ${inputs.length} input(s)`);
106
+ }
107
+ const targets = inputs.map(input => parseOpenInputs([input, ...common]));
108
+ if (targets.length > 1 && targets.some(target => target.compare !== undefined)) {
109
+ throw new Error('OPEN_OPTION_INVALID --compare: multi-target open requires exactly one primary input for comparison');
110
+ }
111
+ if (targets.length > 1 && targets.some(target => target.direct)) {
112
+ throw new Error('OPEN_OPTION_INVALID --direct: multi-target open requires the managed owner workspace');
113
+ }
114
+ for (const [index, animation] of animations) targets[index - 1]!.animation = animation;
115
+ return targets;
116
+ }
73
117
  async function controlCommand(args:string[],stateDir?:string){
74
118
  const input=args.shift();if(!input||input==='--help'||input==='-h'){console.log(usage);return;}
75
119
  const inputs:OpenInputs={input},options:Parameters<typeof controlReview>[1]={stateDir},seen=new Set<string>(),projectOptions:string[]=[];
@@ -117,6 +161,8 @@ function commandHelpRequested(args:readonly string[],command:'open'|'review'|'ch
117
161
  const handoff=HANDOFF_FLAGS.map(f=>'--'+f),flags=command==='open'?['--reference','--compare','--animation',...projectFlags,...handoff]:compare?['--reference','--animation','--port']:['--port','--checkpoint','--reference','--compare','--animation',...handoff,...(command==='feedback'?projectFlags:[])];
118
162
  for(let i=compare?3:1;i<args.length;){
119
163
  const flag=args[i];if(flag==='--help'||flag==='-h')return true;
164
+ if(command==='open'&&flag==='--animation-for'){i+=3;continue;}
165
+ if(command==='open'&&!flag?.startsWith('--')){i++;continue;}
120
166
  if((command==='open'&&(flag==='--control'||flag==='--direct'||flag==='--view-only'))||(command==='review'&&flag==='--view-only')){i++;continue;}if(!flags.includes(flag!))return false;i+=2;
121
167
  }
122
168
  return false;
@@ -152,7 +198,16 @@ export async function main(args:string[],options:{stateDir?:string}={}){
152
198
  options={stateDir:options.stateDir??defaultStateDir()};if(args[0]==='--')args.shift();
153
199
  if(args[0]==='--version'||args[0]==='-v'){console.log((JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8')) as {version:string}).version);return;}
154
200
  if(args[0]==='control')return controlCommand(args.slice(1),options.stateDir);
155
- if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const inputs=parseOpenInputs(openArgs);const result=await openReview(inputs,options);// Launcher contract (README): stdout is the URL line alone; stderr is diagnostic, control notice, retrieval, in that order.
201
+ if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const targets=parseOpenTargets(openArgs);
202
+ if(!targets[0]?.direct){
203
+ const {openWorkspace}=await import('./open-workspace-launch.ts');
204
+ const result=await openWorkspace(targets,options);
205
+ console.log(result.url);
206
+ for(const target of result.prepared){if(target.build)console.error(buildOpenDiagnostic(target.build));if(target.package.selection)console.error(animationDiagnostic(target.package.selection));}
207
+ console.error(`Review workspace ${result.reused?'reused':'started'}; ${targets.length} target(s). Retrieve feedback using the original input designation.`);
208
+ return;
209
+ }
210
+ const inputs=targets[0]!;const result=await openReview(inputs,options);// Launcher contract (README): stdout is the URL line alone; stderr is diagnostic, control notice, retrieval, in that order.
156
211
  console.log(result.url);if(result.build)console.error(buildOpenDiagnostic(result.build));if(result.selection)console.error(animationDiagnostic(result.selection));if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');console.error(`Review ${result.reused?'reused':'started'}; feedback: rig-review feedback ${[result.inputs.input,...(result.inputs.compare?['--compare',result.inputs.compare]:[]),...(result.inputs.reference?['--reference',result.inputs.reference]:[]),...(result.inputs.animation?['--animation',result.inputs.animation]:[]),...handoffWords(result.inputs),...projectWords(result.inputs)].map(shellWord).join(' ')}`);return;}
157
212
  if(args[0]==='parts')return partsCommand(args.slice(1));
158
213
  if(args[0]==='interview')return (await import('./interview-server.ts')).interviewCommand(args.slice(1));
@@ -20,7 +20,7 @@ import { createRequirementsCheck } from './requirements-run.ts';
20
20
  import { REQUIREMENTS_LIMIT, RequirementsError } from './requirements.ts';
21
21
  import { createEnvironmentCheck, ENVIRONMENT_CHECK_LIMIT, EnvironmentCheckError } from './environment-check.ts';
22
22
  import { renderCompareHtml } from './compare-html.ts';
23
- import { createLiveLifecycle, LIVE_PATH, type LiveExitInfo, type UpgradableServer } from './live-lifecycle.ts';
23
+ import { createLiveLifecycle, LIVE_PATH, type LiveExitInfo, type LiveLifecycle, type UpgradableServer } from './live-lifecycle.ts';
24
24
 
25
25
  const headers={'X-Content-Type-Options':'nosniff','Cache-Control':'no-store','Content-Security-Policy':"default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; media-src 'self'; frame-src 'self'; connect-src 'self'; font-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",'Referrer-Policy':'no-referrer'};
26
26
  const MALFORMED=new Set(['REBUILD_REQUEST_INVALID','DENSITY_STRIP_REQUEST_INVALID','DENSITY_STRIP_FIELD','MESH_PATCH_SCOPE','EDIT_PATCH_INVALID','EDIT_PATCH_OP_UNKNOWN','EDIT_PATCH_POINTER_INVALID','EDIT_PATCH_CMD_UNKNOWN','EDIT_PATCH_ARG_UNKNOWN','BONES_OP_OUT_OF_SCOPE','RETARGET_REQUEST_INVALID']);
@@ -43,9 +43,32 @@ function serveAsset(req:Request,path:string):Response{
43
43
  return new Response(req.method==='HEAD'?null:file,{headers:{...assetHeaders,'Content-Length':String(size)}});
44
44
  }
45
45
  /** `capability` (open workers and foreground CLI serving) gates every non-GET request; tests may omit it. */
46
- export async function startCompareServer(p:ComparePackage,options:{port?:number;stateDir?:string;open?:OpenIdentity;activity?:()=>void;control?:ControlIdentity;capability?:string;cwd?:string;stripConcurrency?:number;graceMs?:number;unopenedTimeoutMs?:number;exitOnClose?:boolean;onClose?:(info:LiveExitInfo)=>void|Promise<void>;log?:(line:string)=>void}={}){
46
+ export interface CompareServerOptions {
47
+ port?: number;
48
+ stateDir?: string;
49
+ open?: OpenIdentity;
50
+ activity?: () => void;
51
+ control?: ControlIdentity;
52
+ capability?: string;
53
+ cwd?: string;
54
+ stripConcurrency?: number;
55
+ graceMs?: number;
56
+ unopenedTimeoutMs?: number;
57
+ exitOnClose?: boolean;
58
+ onClose?: (info: LiveExitInfo) => void | Promise<void>;
59
+ log?: (line: string) => void;
60
+ }
61
+
62
+ export interface CompareRequestContextOptions extends CompareServerOptions {
63
+ lifecycle?: LiveLifecycle;
64
+ bundle?: Blob;
65
+ stopServer?: () => void | Promise<void>;
66
+ }
67
+
68
+ /** Comparison-scoped routes without a listener. An injected lifecycle belongs to its caller. */
69
+ export async function createCompareRequestContext(p: ComparePackage, options: CompareRequestContextOptions = {}) {
47
70
  const stageParts=stagePartsRoutes({a:p.a,b:p.b});
48
- const bundle=await buildWeb('compare');
71
+ const bundle=options.bundle??await buildWeb('compare');
49
72
  const frames=referenceFrameIndex(p.referencePath,p.response.binding.reference.sha256,p.response.sourceHash);
50
73
  const stateDir=options.stateDir??process.env.RIG_REVIEW_STATE_DIR??join(homedir(),'.local','state','rig-c-review');
51
74
  const makeSideTools=(side:'a'|'b',pkg:ReviewPackage)=>{
@@ -59,16 +82,17 @@ export async function startCompareServer(p:ComparePackage,options:{port?:number;
59
82
  };
60
83
  const sideTools={a:makeSideTools('a',p.a),b:makeSideTools('b',p.b)};
61
84
  const control=options.control?createControlServer({identity:options.control,sourceHash:p.response.sourceHash,mode:'compare',unchanged:()=>assertCompareUnchanged(p),activity:options.activity}):null;
62
- let rawStop:((closeActiveConnections?:boolean)=>void)|null=null;
63
- const live=createLiveLifecycle({
85
+ const busy=()=>sideTools.a.busy()||sideTools.b.busy();
86
+ const ownsLifecycle=options.lifecycle===undefined;
87
+ const live=options.lifecycle??createLiveLifecycle({
64
88
  label:'review compare',
65
89
  graceMs:options.graceMs,
66
90
  unopenedTimeoutMs:options.unopenedTimeoutMs,
67
91
  exitOnClose:options.exitOnClose,
68
92
  onClose:options.onClose,
69
93
  log:options.log,
70
- busy:()=>sideTools.a.busy()||sideTools.b.busy(),
71
- stopServer:()=>{rawStop?.(true);},
94
+ busy,
95
+ stopServer:options.stopServer,
72
96
  });
73
97
  const handle=async(req:Request,port:number|undefined,srv:UpgradableServer):Promise<Response|undefined>=>{try{
74
98
  const url=new URL(req.url),origin=`http://127.0.0.1:${port}`;
@@ -174,8 +198,22 @@ export async function startCompareServer(p:ComparePackage,options:{port?:number;
174
198
  return json({error:'Not found'},404);
175
199
  } finally { live.onRequestEnd(url.pathname); }
176
200
  }catch(e){const message=e instanceof Error?e.message:'Request failed';return json({error:message},message.includes('inputs changed')?409:400);}};
177
- const server=Bun.serve({hostname:'127.0.0.1',port:options.port??4317,websocket:live.websocket,async fetch(req,srv){const res=await handle(req,srv.port,srv);if(!res)return undefined as unknown as Response;return stampOpen(req,res,options.open);}});
201
+ return {
202
+ live,
203
+ busy,
204
+ async handle(req: Request, port: number | undefined, srv: UpgradableServer): Promise<Response | undefined> {
205
+ const response=await handle(req,port,srv);
206
+ return response?stampOpen(req,response,options.open):undefined;
207
+ },
208
+ stop() { if(ownsLifecycle)live.stop(); },
209
+ };
210
+ }
211
+
212
+ export async function startCompareServer(p: ComparePackage, options: CompareServerOptions = {}) {
213
+ let rawStop:((closeActiveConnections?:boolean)=>void)|null=null;
214
+ const context=await createCompareRequestContext(p,{...options,stopServer:()=>{rawStop?.(true);}});
215
+ const server=Bun.serve({hostname:'127.0.0.1',port:options.port??4317,websocket:context.live.websocket,async fetch(req,srv){return await context.handle(req,srv.port,srv) as Response;}});
178
216
  rawStop=server.stop.bind(server);
179
- server.stop=((closeActiveConnections?:boolean)=>{live.stop();return rawStop!(closeActiveConnections);}) as typeof server.stop;
180
- return Object.assign(server,{live});
217
+ server.stop=((closeActiveConnections?:boolean)=>{context.stop();return rawStop!(closeActiveConnections);}) as typeof server.stop;
218
+ return Object.assign(server,{live:context.live});
181
219
  }
package/src/front.ts CHANGED
@@ -90,7 +90,7 @@ export function frontRoute(mode:'single'|'compare',method:string,path:string):Ro
90
90
  if(/^\/api\/environment-check\/[a-f0-9]{64}$/.test(toolPath))return read?get:null;
91
91
  return null;
92
92
  }
93
- async function boundedBody(req:Request,limit:number,timeoutMs=10000):Promise<ArrayBuffer>{
93
+ export async function boundedBody(req:Request,limit:number,timeoutMs=10000):Promise<ArrayBuffer>{
94
94
  if(!/^application\/json(?:\s*;|$)/i.test(req.headers.get('content-type')??''))throw new Error('FRONT_JSON_REQUIRED');
95
95
  const declared=req.headers.get('content-length');if(declared!==null&&(!/^\d+$/.test(declared)||Number(declared)>limit))throw new Error('FRONT_BODY_LIMIT');
96
96
  if(!req.body)throw new Error('FRONT_JSON_REQUIRED');const reader=req.body.getReader();let timer:ReturnType<typeof setTimeout>|undefined;