@rig-c/review 2.12.0 → 2.13.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 (89) hide show
  1. package/docs/DESIGN.md +82 -71
  2. package/docs/PANELS.md +20 -12
  3. package/docs/PARTS_VIEW.md +31 -11
  4. package/docs/REVIEW_PACKAGE.md +99 -9
  5. package/docs/STABILITY.md +74 -3
  6. package/docs/WORKFLOWS.md +40 -12
  7. package/package.json +2 -1
  8. package/skills/rig-review/SKILL.md +29 -1
  9. package/src/build.ts +10 -2
  10. package/src/cli.ts +14 -12
  11. package/src/compare-html.ts +22 -24
  12. package/src/compare-server.ts +1 -1
  13. package/src/create-pin-gate.ts +3 -0
  14. package/src/feedback-export.ts +49 -1
  15. package/src/front.ts +10 -16
  16. package/src/interview-routes.ts +1 -1
  17. package/src/job-act.ts +39 -21
  18. package/src/job-api.ts +102 -11
  19. package/src/job-contract.ts +44 -4
  20. package/src/job-front.ts +15 -7
  21. package/src/job-host.ts +4 -3
  22. package/src/job-hub.ts +4 -4
  23. package/src/job-session.ts +5 -2
  24. package/src/job-source.ts +42 -13
  25. package/src/joined-project.ts +61 -4
  26. package/src/open-workspace.ts +12 -12
  27. package/src/open.ts +17 -9
  28. package/src/parts-comment.ts +31 -1
  29. package/src/parts-server.ts +19 -7
  30. package/src/parts-view.ts +71 -20
  31. package/src/server.ts +30 -21
  32. package/src/stage-comment.ts +11 -1
  33. package/src/stage-parts.ts +18 -10
  34. package/web/animation-inspection.ts +1 -1
  35. package/web/bones-panel.ts +1 -3
  36. package/web/catalog-en.ts +76 -12
  37. package/web/catalog-ko.ts +76 -12
  38. package/web/cloth-panel.ts +1 -2
  39. package/web/compare.css +3 -9
  40. package/web/compare.html +3 -3
  41. package/web/compare.ts +69 -64
  42. package/web/cuts-panel.ts +1 -3
  43. package/web/density-strip-panel.ts +1 -2
  44. package/web/i18n.ts +13 -1
  45. package/web/idle-panel.ts +1 -2
  46. package/web/index.html +1 -5
  47. package/web/inspection-persistence.ts +2 -1
  48. package/web/inspector-blocks.ts +144 -39
  49. package/web/instance-access.ts +24 -5
  50. package/web/interview-panel.ts +224 -175
  51. package/web/job-hub.ts +50 -69
  52. package/web/job-rig-capture.ts +103 -10
  53. package/web/job-rig-screen.ts +317 -0
  54. package/web/job-session.ts +927 -1365
  55. package/web/main.ts +535 -129
  56. package/web/mesh-panel.ts +1 -2
  57. package/web/owner-workspace.ts +88 -109
  58. package/web/part-selection.ts +47 -6
  59. package/web/part-thumbnails.ts +20 -6
  60. package/web/parts-viewport-provider.ts +166 -9
  61. package/web/physics-panel.ts +1 -2
  62. package/web/readings-panel.ts +1 -2
  63. package/web/requirements-panel.ts +1 -3
  64. package/web/retained-frame-stage.ts +105 -0
  65. package/web/retarget-panel.ts +2 -3
  66. package/web/rig-fields-panel.ts +1 -2
  67. package/web/rig-host.ts +62 -0
  68. package/web/rig-viewport-provider.ts +63 -16
  69. package/web/stage-comments.ts +29 -26
  70. package/web/styles.css +127 -43
  71. package/web/view-controls.ts +201 -12
  72. package/web/viewport-controller.ts +97 -26
  73. package/web/viewport-pair.ts +2 -1
  74. package/web/workspace-preferences.ts +5 -4
  75. package/web/workspace-ui.ts +152 -19
  76. package/src/interview-server.ts +0 -54
  77. package/web/interview.css +0 -28
  78. package/web/interview.html +0 -17
  79. package/web/interview.ts +0 -40
  80. package/web/job-hub.css +0 -14
  81. package/web/job-hub.html +0 -5
  82. package/web/owner-workspace.css +0 -14
  83. package/web/owner-workspace.html +0 -5
  84. package/web/parts-flags.ts +0 -48
  85. package/web/parts-page.ts +0 -217
  86. package/web/parts.css +0 -116
  87. package/web/parts.html +0 -15
  88. package/web/parts.ts +0 -986
  89. package/web/stage-nav.ts +0 -136
package/docs/STABILITY.md CHANGED
@@ -1,5 +1,39 @@
1
1
  # Public API stability
2
2
 
3
+ ## Interview-stage project opening
4
+
5
+ The additional CLI form is:
6
+
7
+ ```sh
8
+ rig-review open /path/to/project --project /path/to/project --picks-dir scratch/review-picks
9
+ ```
10
+
11
+ Both root operands must resolve to the same Create project. The picks directory
12
+ must already exist, be project-relative and be disjoint from declared inputs.
13
+ Omitting both selectors is supported only at `stage: "interview"` without a
14
+ recorded draft or a non-null `versions[].review_package`. Demo/build versions
15
+ without a review package are allowed. Unrelated files under `derived/` do not
16
+ select or manufacture a review package. Explicit `--project-version` and
17
+ `--project-draft` retain their strict package joins and never fall back here.
18
+ This form is single-target and accepts no additional inspection options;
19
+ `feedback` and `control` keep their existing selector requirements.
20
+
21
+ The existing single-entry workspace opens the interview in its existing modal.
22
+ Its internal `/api/review` transport uses `subject: "interview"`, an actual
23
+ `project.json` path/hash, source hash, label and availability flags. It carries
24
+ no manifest, compiled model, reviewed-package identity or package session.
25
+ Model-dependent APIs refuse `MODEL_UNAVAILABLE`. Project, retained option sets
26
+ and declared inputs are hash-bound and rechecked; drift refuses
27
+ `INTERVIEW_OPTIONS_STALE`. Opening and reading change no source files.
28
+ The joined dialog and standing record form use one shared list | image | survey
29
+ answer builder. There is no interview Note input. Existing saved or historical
30
+ notes remain readable as read-only text and are carried unchanged. Joined picks
31
+ omit `note` when none exists; the job act retains its required string field.
32
+ Historical records, picks/act/verdict schemas and explicit
33
+ version/draft joins retain their existing readers and checks. This introduces
34
+ no job API, act schema, consumer contract or package-export change; it does not
35
+ replace the active standing review cycle with a picks-file handoff.
36
+
3
37
  ## Managed owner host
4
38
 
5
39
  `@rig-c/review/job-host` is the installed Bun entry for the full standing owner
@@ -564,10 +598,42 @@ model binding nor a valid image-set binding uses `JOB_ASK_INVALID`.
564
598
  The backend rig-still extension retains the original twelve runtime exports and `JOB_ACT_SCHEMA` at act@2. `JobAct` additionally includes `JobRigReviewAct` at act@3 with top-level `JobRigStill` and `JobPartsVerdictAct` at act@5 (`PartsVerdictValue` with pointed `issues` and `words`, while preserving `JobLegacyPartsVerdictValue` at act@2 for historical acts). The facade adds type-only `JobLegacyAct`, `JobRigReviewAct`, `JobPartsVerdictAct`, `JobLegacyPartsVerdictValue`, `PartsVerdictValue`, `JobPanelComposition`, `PanelComponent`, `JobRigStill` and `JobRigCapture` exports, [Review #563](https://github.com/rig-c/review/issues/563) adds five type-only exports (`JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`, `JobHostAttachField` and `JobHostAttachFailure`), and [Review #555](https://github.com/rig-c/review/issues/555) adds four type-only interview diagnostic exports (`JobInterviewJson`, `JobInterviewRecord`, `JobInterviewDiagnostic` and `JobInterviewDiagnostics`). [Review #588](https://github.com/rig-c/review/issues/588) activates record mode when `readRecordPublished` and `recordReaderId` are supplied to a host or session (`publicationMode: 'record-and-package'`), serving `rig-review/job-api@3` (`JOB_API_V3_SCHEMA`), `rig-review/act@4` (`JOB_RECORD_ACT_SCHEMA`) and normal owner URL model-free record inspection while keeping default package-only hosts and exact `package-only` `job-ui/<jobId>.json` descriptor bytes at @2 and enforcing `publicationMode` / `recordReaderId` reuse compatibility across ordinary reuse and strict `reuseOnly` attachment. It exports six additional record-mode runtime symbols (`JOB_API_V3_SCHEMA`, `JOB_RECORD_ACT_SCHEMA`, `JOB_RECORD_READER_ID`, `parseRecordAct`, `prepareJobRecordAct` and `prepareJobRecordSource`, for eighteen runtime exports total) and the V3/record type surface listed below. The rig and parts-verdict act revision constants, transport limits and the internal `POST /jobs/<jobId>/host` helper remain internal to their modules. Consumer checks distinguish these act revisions as described in [Rig verdict still backend](REVIEW_PACKAGE.md#rig-verdict-still-backend) and [Model-free record mode and source seam](REVIEW_PACKAGE.md#model-free-record-mode-and-source-seam).
565
599
 
566
600
  The comments decoder extension adds six functions and four schema constants,
567
- for twenty-eight runtime exports total. It is a read-only contract preparation;
568
- the existing UI finalizers and legacy type unions retain their current versions.
601
+ for twenty-eight runtime exports total.
569
602
  See [Comments decoder contract](REVIEW_PACKAGE.md#comments-decoder-contract).
570
603
 
604
+ [Review #714](https://github.com/rig-c/review/issues/714) adds the act@7 decoder
605
+ `parseContextCommentsAct` and its constant `JOB_COMMENT_CONTEXT_ACT_SCHEMA`
606
+ (`rig-review/act@7`), for thirty runtime exports total, plus the type-only
607
+ `JobCommentContext`, `JobContextComment` and `JobContextCommentsAct`. The change
608
+ is additive: `parseCommentsAct`, `JobComment` and `JobCommentsAct` keep their @6
609
+ shapes, and @2–@6 decode unchanged. Review does not emit @7 until Create pins a
610
+ Review version that reads it. See [Comment context (act@7)](REVIEW_PACKAGE.md#comment-context-act7).
611
+
612
+ [Review #713](https://github.com/rig-c/review/issues/713) turns on the act@6
613
+ writers. `JobAct` widens to `JobLegacyAct | JobRigReviewAct | JobPartsVerdictAct |
614
+ JobCommentsAct`, so `JobActV3`, `JobEvent`, `JobEventV3`, `JobNextValue`,
615
+ `JobNextValueV3` and `JobHostPorts.commitUIAct` admit fresh act@6 values. No
616
+ export is added or removed, and `JobComment` is unchanged. Fresh UI checkpoint,
617
+ parts-verdict, rig and direction review-verdict and signoff acts are
618
+ `rig-review/act@6`. Image-review verdicts and interview picks stay at act@2, and
619
+ record acts stay at act@4. Consumers narrow on `schema`. A consumer's
620
+ `Extract<JobAct, {kind: ...}>` alias now also contains the act@6 arm of that
621
+ kind. This changes the type on the consumer's next pin and does not break any
622
+ runtime reader. Historical act@2–@5 bytes keep their readers.
623
+
624
+ [Review #746](https://github.com/rig-c/review/issues/746) adds optional
625
+ `feedback: readonly Feedback[]` to `JobUIActValues['review-verdict']` only when
626
+ `stage` is `rig-review`; `stage`, `verdict` and required `words` remain.
627
+ A present list, including `[]`, supplies the complete comments through the
628
+ existing `feedbackItemComments` mapper and act@6 decoder. It preserves entry
629
+ order, text, IDs, frames, target, category and `anchor.context` (including point,
630
+ crop, bookmark and valid time-only null-frame evidence). `words` is not appended
631
+ as another comment. Without `feedback`, serialized output bytes stay unchanged.
632
+ Direction and image submissions retain their previous closed shapes. The
633
+ written act stays act@6, historical words-only acts still parse, and the
634
+ act@7 top-level `comment.context` emission gate remains off. There are no new
635
+ exports or schemas. See [Comments decoder contract](REVIEW_PACKAGE.md#comments-decoder-contract).
636
+
571
637
  The exact runtime exports are listed below. Constants preserve their literal
572
638
  values from the frozen semantic contract.
573
639
 
@@ -578,12 +644,14 @@ values from the frozen semantic contract.
578
644
  - `prepareJobRecordAct`
579
645
  - `prepareJobRecordSource`
580
646
  - `parseCommentsAct`
647
+ - `parseContextCommentsAct`
581
648
  - `projectComments`
582
649
  - `parseCommentsSession`
583
650
  - `parseCommentsCompareSession`
584
651
  - `parseCommentsPartsVerdict`
585
652
  - `projectSelectedCommentsFeedback`
586
653
  - `JOB_COMMENTS_ACT_SCHEMA`
654
+ - `JOB_COMMENT_CONTEXT_ACT_SCHEMA`
587
655
  - `REVIEW_COMMENTS_SESSION_SCHEMA`
588
656
  - `REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA`
589
657
  - `PARTS_COMMENTS_VERDICT_SCHEMA`
@@ -756,6 +824,9 @@ without aliases or copied wire shapes.
756
824
  - `JobCommentImageAnchor`
757
825
  - `JobCommentsAct`
758
826
  - `JobCommentsActValues`
827
+ - `JobCommentContext`
828
+ - `JobContextComment`
829
+ - `JobContextCommentsAct`
759
830
  - `ReviewCommentsSession`
760
831
  - `CompareCommentsSession`
761
832
  - `PartsCommentsVerdict`
@@ -771,7 +842,7 @@ Rows are capped at 4096, roles at 128 UTF-16 code units and literal paths at 409
771
842
  ## Installed acceptance
772
843
 
773
844
  `bun run smoke` packs the package and installs that tarball into an empty project.
774
- A consumer checks the twenty-eight runtime exports and every listed type, including
845
+ A consumer checks the thirty runtime exports and every listed type, including
775
846
  `JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`,
776
847
  `JobHostAttachField`, `JobHostAttachFailure`, `JobInterviewJson`,
777
848
  `JobInterviewRecord`, `JobInterviewDiagnostic`, `JobInterviewDiagnostics` and
package/docs/WORKFLOWS.md CHANGED
@@ -501,7 +501,7 @@ On the view you are inspecting, choose **Comment · C (n)**, drag over the detai
501
501
 
502
502
  The four-stage navigator preserves this entry and its explicit save behavior. Compiled sessions reuse the atlas surface read-only; see [Four inspection stages](PANELS.md#four-inspection-stages).
503
503
 
504
- The managed front forwards only the trusted stage-atlas frame query (`stageEmbed=1`, `lang=en|ko`, and a required `side=a|b` for compare; no side for single). Unknown or duplicate keys are refused; the frame carries no filesystem path, command or capability. Stage navigation never changes CLI arguments or package bindings.
504
+ The managed front forwards a query only to the landing page; every other route refuses one. Stage navigation never changes CLI arguments or package bindings.
505
505
 
506
506
  ## Embedded semantic jobs
507
507
 
@@ -715,6 +715,38 @@ to the joined command. The post must explicitly name the selected
715
715
  printed feedback command, including the project, rig, post and picks arguments,
716
716
  to export from that session.
717
717
 
718
+ ### Open an interview before a draft or review package exists
719
+
720
+ Create the dedicated picks output directory first, then open the same project
721
+ root in both operand positions:
722
+
723
+ ```sh
724
+ mkdir -p /path/to/project/scratch/review-picks
725
+ rig-review open /path/to/project \
726
+ --project /path/to/project --picks-dir scratch/review-picks
727
+ ```
728
+
729
+ This form is limited to the interview stage with no recorded draft and no
730
+ non-null `versions[].review_package`. Versions containing only demo/build
731
+ records are permitted, as is unrelated derived evidence. A `derived/` directory
732
+ is not required. Explicit version/draft selectors never fall back to this form.
733
+ Both roots must resolve to the same project; the dedicated picks directory must
734
+ exist and not overlap an input. Other inspection flags and multiple targets
735
+ are refused for this form. `feedback` and `control` retain their existing syntax.
736
+
737
+ The interview opens and closes as a modal over the existing Review workspace.
738
+ The workspace reports model-dependent sections as `MODEL_UNAVAILABLE` and
739
+ creates no model, review package or package session. Reads preserve project and
740
+ input bytes. Changed project, option or source bytes require reopening, with
741
+ `INTERVIEW_OPTIONS_STALE`. Interview choices and inline Other text use the same list | image | survey
742
+ answer builder as the standing record dialog. There is no interview Note input;
743
+ existing saved or historical notes remain readable as read-only text and are
744
+ carried unchanged. Joined picks omit `note` when absent; job acts retain their
745
+ required string field. Historical records remain readable and the
746
+ picks-file schema is unchanged. The active standing live-job cycle above
747
+ still uses semantic acts and the trusted consumer; this inspection form does
748
+ not authorize an agent to manufacture or carry picks files.
749
+
718
750
  ### Open a recorded draft before rig review
719
751
 
720
752
  In the active standing live-job cycle ([Standing live job workflow](#standing-live-job-workflow), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184)), draft parts and mesh verdicts are submitted as `parts-verdict` acts over the semantic job API and fetched directly by the Create writer. The `--picks-dir`, `--parts-verdict-dir` and `--picks-file` commands below are preserved as legacy/history one-shot handoffs and are bypass findings if used in the active cycle.
@@ -741,15 +773,8 @@ package is unavailable. Reopen with a rig version once Create records one.
741
773
 
742
774
  When the recorded draft entry includes `config`, `parts`, `rig` and `check` directories and the draft is editable (`parts` or `parts-review` stage without an effective `parts-review` sign-off, and not `--view-only`), **1 Parts + mesh** also offers the Chest regions, Mesh parameters and Edit Mesh instruments for mesh-bearing parts regardless of whether `--parts-verdict-dir` is supplied. Selecting an instrument opens the Setup inspector for that part while direct selection of **3 Rig + animation** remains refused with `RIG_VERSION_UNAVAILABLE`. Apply runs the installed producer and compiler in scratch under the existing discovery and operation-capability floors while keeping the recorded draft producer as provenance, and returning to **1 Parts + mesh** or running Undo or Reset updates the displayed mesh and report readings from the active build (verdict saving remains read-only on scratch builds and when `--parts-verdict-dir` is omitted).
743
775
 
744
- From a create project with retained choice sets, create a dedicated output
745
- directory and open the foreground Stage 2 view:
746
-
747
- ```sh
748
- mkdir -p scratch/review-picks
749
- rig-review interview . --picks-dir scratch/review-picks
750
- ```
751
-
752
- Open the printed loopback URL. Select a question and inspect its bound parts
776
+ The interview opens over the review screen of a joined workspace (the `open`
777
+ command above with `--picks-dir`): choose **2 Interview**. Select a question and inspect its bound parts
753
778
  or source image. A direction set that binds only source inputs displays those
754
779
  inputs with the no-bound-parts notice. Each recommendation shows the retained
755
780
  reason and author/date. Choose an option for every prompt and save explicitly.
@@ -758,8 +783,11 @@ offered and picked. Auto stays pending until create has a covered agent
758
783
  decision. Historical choice sets are read-only.
759
784
 
760
785
  Each saved set has its own `<raw-set-sha256>.json` in the designated directory.
761
- Reopening restores picks and note for the same retained set. A new set starts
762
- without selections. The directory must exist inside the project and be
786
+ Reopening restores picks for the same retained set. Existing records keep their
787
+ original note field byte-for-byte, displayed as read-only text. The survey has
788
+ no Note input. A saved note takes precedence over a historical note, including
789
+ an empty saved string; when neither exists, the picks record omits `note`.
790
+ A new set starts without selections. The directory must exist inside the project and be
763
791
  separate from every bound input. A stale context, forged selection or
764
792
  superseded set is refused. Review writes only `rig-review/interview-picks@1`
765
793
  files. To ingest a file, run create separately from the project root:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "2.12.0",
3
+ "version": "2.13.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -10,6 +10,7 @@
10
10
  "check:demo": "bun run check -- examples/demo/review.json",
11
11
  "demo": "bun src/entry.ts examples/demo/review.json --view-only",
12
12
  "check:readme": "bun scripts/check-readme.ts",
13
+ "check:screen-copies": "bun scripts/screen-copies.ts",
13
14
  "typecheck": "tsc --noEmit",
14
15
  "test": "bun test",
15
16
  "build": "bun src/build.ts",
@@ -10,6 +10,35 @@ 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
+ ### Interview-stage project without a package
14
+
15
+ When the designated project is at the interview stage and has neither a
16
+ recorded draft nor a non-null `versions[].review_package`, the approved
17
+ single-target form is:
18
+
19
+ ```sh
20
+ rig-review open /path/to/project --project /path/to/project --picks-dir scratch/review-picks
21
+ ```
22
+
23
+ The picks directory must already exist and be disjoint from declared inputs.
24
+ Both root operands must resolve to the same project. Demo/build version records
25
+ and unrelated derived evidence are allowed; `derived/` may be absent. Explicit
26
+ version/draft selectors stay strict and never fall back. This form takes no
27
+ additional inspection flags and adds no `feedback` or `control` grammar.
28
+
29
+ The existing Review workspace hosts the interview in its existing modal.
30
+ Model-dependent capabilities are named unavailable (`MODEL_UNAVAILABLE`); no
31
+ manifest, model or package session is synthesized. Project, option-set and input
32
+ hashes bind the inspection, and changed bytes require reopening
33
+ (`INTERVIEW_OPTIONS_STALE`). The joined dialog and standing record form use one shared list | image | survey
34
+ answer builder. There is no interview Note input. Existing saved or historical
35
+ notes remain readable as read-only text and are carried unchanged. Joined picks
36
+ omit `note` when none exists; the job act retains its required string field.
37
+ Historical records, picks/act/verdict schemas and explicit
38
+ version/draft joins retain their existing readers and checks. Use the
39
+ semantic standing cycle for active consumer ingestion; do not construct or
40
+ carry picks files to bypass it. See [project opening stability](https://github.com/rig-c/review/blob/main/docs/STABILITY.md#interview-stage-project-opening).
41
+
13
42
  ## Open one owner workspace
14
43
 
15
44
  For folder inspections, use **N rigs → one invocation, one owner link**.
@@ -174,7 +203,6 @@ The stage buttons navigate within that source binding.
174
203
  standalone inspection and named limits on direct correction.
175
204
  2. **Interview.** In the joined draft workspace choose **2 Interview**. For
176
205
  choices bound to a recorded rig, open its package with the Stage 3 command.
177
- The standalone entry is `rig-review interview <project> --picks-dir <picks-dir>`.
178
206
  Beside the bound parts or source image, the person chooses among the saved
179
207
  options with the agent's recommendation and rationale, then uses
180
208
  **Save explicit picks**. Read the `rig-review/interview-picks@1` file for the
package/src/build.ts CHANGED
@@ -6,9 +6,17 @@ export function playBuildConditions(root:string=appRoot):string[] {
6
6
  try{return /[\\/]src[\\/]index\.ts$/.test(Bun.resolveSync('@rig-c/play',root))?[PLAY_SOURCE_CONDITION]:[];}
7
7
  catch{return [];}
8
8
  }
9
- export async function buildWeb(mode:'single'|'compare'|'parts'|'interview'|'workspace'|'job-hub'='single',root:string=appRoot):Promise<Blob> {
9
+ /** #706: the one entry (`web/index.html`) marked for a screen that opens in Setup with the parts mode only. The marker
10
+ * and asset names are trusted constants; no request or package data is interpolated. */
11
+ export async function setupEntryHtml(screen:'parts'|'stage-parts',assets:{script:string;styles:string}={script:'main.js',styles:'styles.css'},root:string=appRoot):Promise<string> {
12
+ const html=await Bun.file(join(root,'web/index.html')).text();
13
+ const marked=html.replace('<div id="app"></div>',`<div id="app" data-review-screen="${screen}"></div>`).replace('href="styles.css"',`href="${assets.styles}"`).replace('src="main.js"',`src="${assets.script}"`);
14
+ if(marked===html||!marked.includes(`data-review-screen="${screen}"`))throw new Error('SETUP_ENTRY_MARKER_MISSING');
15
+ return marked;
16
+ }
17
+ export async function buildWeb(mode:'single'|'compare'|'parts'|'workspace'|'job-hub'='single',root:string=appRoot):Promise<Blob> {
10
18
  const conditions=playBuildConditions(root);
11
- const entry=join(root,mode==='job-hub'?'web/job-hub.ts':mode==='workspace'?'web/owner-workspace.ts':mode==='compare'?'web/compare.ts':mode==='parts'?'web/parts-page.ts':mode==='interview'?'web/interview.ts':'web/main.ts');
19
+ const entry=join(root,mode==='job-hub'?'web/job-hub.ts':mode==='workspace'?'web/owner-workspace.ts':mode==='compare'?'web/compare.ts':'web/main.ts');
12
20
  const result=await Bun.build({entrypoints:[entry],target:'browser',format:'esm',minify:false,...(conditions.length?{conditions}:{})});
13
21
  if(!result.success)throw new Error(result.logs.map(v=>v.message).join('\n'));
14
22
  const output=result.outputs.find(v=>v.path.endsWith('.js'));if(!output)throw new Error('frontend bundle: JavaScript output missing');return output;
package/src/cli.ts CHANGED
@@ -18,14 +18,14 @@ import { readFeedbackSession, readFeedbackCompareSession } from './session-histo
18
18
  import { startServer } from './server.ts';
19
19
  import { loadCompare } from './compare.ts';
20
20
  import { startCompareServer } from './compare-server.ts';
21
- import { loadPartsView, readVerdict, readPartsVerdictForCli, readPartsVerdictJson, exportPartsVerdict, exportPartsCorrection, assertPartsUnchanged, type PartsViewOptions } from './parts-view.ts';
21
+ import { loadPartsView, readVerdict, readPartsVerdictForCli, readPartsVerdictJson, exportPartsVerdict, exportPartsCorrection, assertPartsUnchanged, assertPartsCanOpen, type PartsViewOptions } from './parts-view.ts';
22
22
  import { startPartsServer } from './parts-server.ts';
23
23
  import { readSession, parseSession, sessionFile, type Feedback } from './session.ts';
24
24
  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> [<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 rig-review <dir> <dir> ... [--animation <name>] [--animation-for <index> <name>] [--port 4318] [--reference <video>] [--view-only] [--control] '+handoffUsage+'\n Foreground multi owns a new workspace in this CLI process; a compatible existing owner is joined and the launcher exits. Multi --port accepts 1..65535; single foreground keeps 4317 and --port 0.\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>] [--by <name>] [--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 rig-review <dir> <dir> ... [--animation <name>] [--animation-for <index> <name>] [--port 4318] [--reference <video>] [--view-only] [--control] '+handoffUsage+'\n Foreground multi owns a new workspace in this CLI process; a compatible existing owner is joined and the launcher exits. Multi --port accepts 1..65535; single foreground keeps 4317 and --port 0.\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>] [--by <name>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--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;
@@ -48,23 +48,24 @@ function handoffOption(flag:string):(typeof HANDOFF_FLAGS)[number]|null {const n
48
48
  const projectFlags = ['--project','--project-version','--picks-dir','--post-version','--project-draft','--parts-verdict-dir'];
49
49
  /** The retrieval words for the handoff flags, in their fixed order. */
50
50
  const projectWords=(inputs:OpenInputs)=>{const p=inputs.project;return p?[
51
- '--project',p.root,...(p.draftId===undefined?['--project-version',String(p.version)]:['--project-draft',p.draftId]),'--picks-dir',p.picksDir,
51
+ '--project',p.root,...(p.draftId!==undefined?['--project-draft',p.draftId]:p.version!==undefined?['--project-version',String(p.version)]:[]),'--picks-dir',p.picksDir,
52
52
  ...(p.partsVerdictDir===undefined?[]:['--parts-verdict-dir',p.partsVerdictDir]),
53
53
  ...(p.postVersion===undefined?[]:['--post-version',String(p.postVersion)]),
54
54
  ]:[];};
55
55
  const handoffWords=(inputs:OpenInputs)=>HANDOFF_FLAGS.flatMap(f=>inputs[f]!==undefined?['--'+f,inputs[f]!]:[]);
56
- export function parseOpenInputs(args:string[]):OpenInputs {
56
+ export function parseOpenInputs(args:string[],options:{interview?:boolean}={}):OpenInputs {
57
57
  const input=args.shift();if(!input||input.startsWith('--'))throw new Error(usage);const result:OpenInputs={input},seen=new Set<string>();
58
58
  let root:string|undefined,version:string|undefined,postVersion:string|undefined,picksDir:string|undefined,draftId:string|undefined,partsVerdictDir:string|undefined;
59
59
  while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`OPEN_OPTION_INVALID ${flag}: Duplicate open option ${flag}`);seen.add(flag);if(flag==='--control'){result.control=true;continue;}if(flag==='--direct'){result.direct=true;continue;}if(flag==='--view-only'){result.viewOnly=true;continue;}const value=args.shift();if(value===undefined||value==='')throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);if(flag==='--reference')result.reference=value;else if(flag==='--compare')result.compare=value;else if(flag==='--animation')result.animation=value;else if(flag==='--project')root=value;else if(flag==='--project-version')version=value;else if(flag==='--picks-dir')picksDir=value;else if(flag==='--project-draft')draftId=value;else if(flag==='--parts-verdict-dir')partsVerdictDir=value;else if(flag==='--post-version')postVersion=value;else if(handoffOption(flag))result[handoffOption(flag)!]=value;else throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);}
60
60
  if(root!==undefined||version!==undefined||picksDir!==undefined||postVersion!==undefined||draftId!==undefined||partsVerdictDir!==undefined){
61
- if(!root||!picksDir||(Boolean(version)===Boolean(draftId))||result.compare!==undefined||version!==undefined&&(!/^\d+$/.test(version)||!Number.isSafeInteger(Number(version))||Number(version)<1))
61
+ if(!root||!picksDir||(Boolean(version)&&Boolean(draftId))||options.interview===false&&!version&&!draftId||result.compare!==undefined||version!==undefined&&(!/^\d+$/.test(version)||!Number.isSafeInteger(Number(version))||Number(version)<1))
62
62
  throw new Error('OPEN_OPTION_INVALID --project: single-package open requires --project, --picks-dir and one of --project-version or --project-draft together');
63
63
  if(postVersion!==undefined&&(!/^\d+$/.test(postVersion)||!Number.isSafeInteger(Number(postVersion))||Number(postVersion)<1))
64
64
  throw new Error('OPEN_OPTION_INVALID --post-version: expected a positive Create post version');
65
- if(draftId&&postVersion)throw new Error('OPEN_OPTION_INVALID --post-version: requires --project-version');
65
+ if(!version&&postVersion)throw new Error('OPEN_OPTION_INVALID --post-version: requires --project-version');
66
66
  if(partsVerdictDir&&(!draftId||result.viewOnly))throw new Error('OPEN_OPTION_INVALID --parts-verdict-dir: requires a writable --project-draft');
67
- result.project=draftId?{root,draftId,picksDir,...(partsVerdictDir?{partsVerdictDir}:{})}:{root,version:Number(version),picksDir,...(postVersion!==undefined?{postVersion:Number(postVersion)}:{})};
67
+ if(!version&&!draftId&&(result.reference!==undefined||result.animation!==undefined||result.control||result.direct||result.viewOnly||handoffFlags(result)))throw new Error('OPEN_OPTION_INVALID --project: interview-only open takes only the project root, --project and --picks-dir');
68
+ result.project=!version&&!draftId?{root,picksDir}:draftId?{root,draftId,picksDir,...(partsVerdictDir?{partsVerdictDir}:{})}:{root,version:Number(version),picksDir,...(postVersion!==undefined?{postVersion:Number(postVersion)}:{})};
68
69
  }
69
70
  const problem=checkHandoffFlags(result);if(problem)throw new Error(`OPEN_OPTION_INVALID ${problem.split(':')[0]}: ${problem.slice(problem.indexOf(':')+2)}`);
70
71
  if(result.compare!==undefined&&handoffFlags(result))throw new Error('OPEN_OPTION_INVALID --config: compare takes no producer handoff; open one package with --config');
@@ -105,6 +106,7 @@ export function parseOpenTargets(args: readonly string[]): OpenInputs[] {
105
106
  if (target > inputs.length) throw new Error(`OPEN_OPTION_INVALID --animation-for: target index ${target} exceeds ${inputs.length} input(s)`);
106
107
  }
107
108
  const targets = inputs.map(input => parseOpenInputs([input, ...common]));
109
+ if(targets.length>1&&targets.some(target=>target.project&&target.project.version===undefined&&target.project.draftId===undefined))throw new Error('OPEN_OPTION_INVALID --project: interview-only open requires exactly one project root');
108
110
  if (targets.length > 1 && targets.some(target => target.compare !== undefined)) {
109
111
  throw new Error('OPEN_OPTION_INVALID --compare: multi-target open requires exactly one primary input for comparison');
110
112
  }
@@ -161,7 +163,7 @@ async function controlCommand(args:string[],stateDir?:string){
161
163
  else if(flag==='--command'){if(value.length>8192)throw new Error('--command: JSON exceeds 8 KiB');options.command=parseControlCommand(JSON.parse(value));}
162
164
  else throw new Error(`Unknown control option ${flag}`);
163
165
  }
164
- if(projectOptions.length)inputs.project=parseOpenInputs([input,...projectOptions]).project;
166
+ if(projectOptions.length)inputs.project=parseOpenInputs([input,...projectOptions],{interview:false}).project;
165
167
  const result=await controlReview(inputs,options);console.log(JSON.stringify(result,null,2));if(options.command&&(result as {status?:string}).status!=='applied')process.exitCode=2;
166
168
  }
167
169
  /** Formatting is CLI-only; session lookup/save contracts remain unchanged. */
@@ -201,8 +203,8 @@ function commandHelpRequested(args:readonly string[],command:'open'|'review'|'ch
201
203
  }
202
204
  return false;
203
205
  }
204
- const partsUsage='Usage: rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--by <name>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n A directory holding parts.json (or a build root whose rig/ holds it) opens in parts mode, before rigging; a review package or check/ folder opens its atlas.\n The sign-off is written to parts-review.json beside parts.json (or the model), or to --verdict.';
205
- /** `rig-review parts` (#348): the parts and atlas view, served in the foreground; exits when its last tab closes. */
206
+ const partsUsage='Usage: rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--by <name>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n A directory holding parts.json (or a build root whose rig/ holds it) opens in parts mode, before rigging. Atlas-only inputs refuse PARTS_ATLAS_NOT_CARRIED; open the rig review for inspection.\n --format json|issue still reads saved parts or atlas verdicts. The sign-off is written to parts-review.json beside parts.json, or to --verdict.';
207
+ /** `rig-review parts` (#348): parts inspection in the foreground, or read-only parts/atlas verdict export. */
206
208
  async function partsCommand(args:string[]){
207
209
  const input=args.shift();if(!input||input==='--help'||input==='-h'){console.log(partsUsage);return;}
208
210
  const options:PartsViewOptions={};let port=4317,format:'json'|'issue'|null=null;const seen=new Set<string>();
@@ -226,6 +228,7 @@ async function partsCommand(args:string[]){
226
228
  }
227
229
  if(format==='json'){process.stdout.write(await readPartsVerdictJson(pkg));return;}
228
230
  if(format){const verdict=await readPartsVerdictForCli(pkg);if(!verdict)throw new Error('PARTS_VERDICT_UNAVAILABLE: save a verdict first');process.stdout.write(exportPartsVerdict(verdict,format));return;}
231
+ assertPartsCanOpen(pkg);
229
232
  const capability=randomBytes(32).toString('hex');
230
233
  let outputFailure: Error | null = null;
231
234
  let rejectWrite: ((error: Error) => void) | undefined;
@@ -288,7 +291,6 @@ export async function main(args:string[],options:{stateDir?:string}={}){
288
291
  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.
289
292
  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;}
290
293
  if(args[0]==='parts')return partsCommand(args.slice(1));
291
- if(args[0]==='interview')return (await import('./interview-server.ts')).interviewCommand(args.slice(1));
292
294
  if(args[0]==='strip'){args.shift();if(args.includes('--help')){console.log(usage+'\nStrip: strip <package> --reference <declared-video-id> --animation <name> (--frames FIRST:LAST | --all-feedback) [--json] [--out path]\n strip compare <a> <b> --reference <video> --animation <name> --basis a|b (--frames FIRST:LAST | --all-feedback) [--json] [--out path]');return;}return stripCommand(args,options);}let command:'review'|'check'|'feedback'='review';if(args[0]==='check'||args[0]==='feedback'){command=args.shift() as 'check'|'feedback';}
293
295
  if(args[0]==='--help'||args[0]==='-h'){console.log(usage);return;}
294
296
  const foreground = command === 'review' && args[0] !== 'compare' ? parseForegroundTargets(args) : null;
@@ -328,7 +330,7 @@ export async function main(args:string[],options:{stateDir?:string}={}){
328
330
  const input=args.shift();if(!input)throw new Error(usage);let port=4317;let checkpoint:string|undefined,reference:string|undefined,compare:string|undefined,animation:string|undefined,viewOnly=false;const handoff:OpenInputs={input},projectOptions:string[]=[];
329
331
  while(args.length){const flag=args.shift();if(flag==='--view-only'){if(command!=='review')throw new Error(`Unknown option ${flag}\n${usage}`);viewOnly=true;continue;}const value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);if(command==='feedback'&&projectFlags.includes(flag!)){projectOptions.push(flag!,value);continue;}if(handoffOption(flag!)){handoff[handoffOption(flag!)!]=value;continue;}if(flag==='--port'){port=Number(value);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('--port: expected integer 0…65535');}else if(flag==='--checkpoint')checkpoint=value;else if(flag==='--reference')reference=value;else if(flag==='--compare')compare=value;else if(flag==='--animation')animation=value;else throw new Error(`Unknown option ${flag}\n${usage}`);}
330
332
  const handoffProblem=checkHandoffFlags(handoff);if(handoffProblem)throw new Error(handoffProblem);if(compare&&handoffFlags(handoff))throw new Error('--config: compare takes no producer handoff');
331
- if(projectOptions.length)handoff.project=parseOpenInputs([input,...projectOptions,...(compare?['--compare',compare]:[])]).project;
333
+ if(projectOptions.length)handoff.project=parseOpenInputs([input,...projectOptions,...(compare?['--compare',compare]:[])],{interview:false}).project;
332
334
  if(compare){if(correctionId)throw new Error('CORRECTION_COMPARE_UNSUPPORTED: select a single reviewed package');if(command!=='feedback')throw new Error('--compare: use open or feedback');const loaded=await loadOpenPackage({input,compare,reference,animation});if(loaded.mode!=='compare')throw new Error('Expected comparison');printFeedback(await readFeedbackCompareSession(loaded.p,options.stateDir));return;}
333
335
  const base=await loadReferencedReview(input,reference,handoffFlags(handoff));
334
336
  const joined=handoff.project?joinProject(base,handoff.project):undefined,p=joined?.review??base;