rig-review 0.22.0 → 0.24.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
@@ -1,5 +1,11 @@
1
1
  <p align="center">
2
- <img src="https://raw.githubusercontent.com/rig-c/review/main/assets/banner.svg" alt="@rig-c/review — Local human rig inspection, reference comparison and feedback export" width="100%" />
2
+ <img src="https://raw.githubusercontent.com/rig-c/review/main/assets/banner.svg" alt="@rig-c/review" width="100%" />
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/@rig-c/review"><img src="https://img.shields.io/npm/v/@rig-c/review.svg?style=flat-square&color=FF6B4A" alt="version"/></a>
7
+ <a href="https://www.npmjs.com/package/@rig-c/review"><img src="https://img.shields.io/npm/dm/@rig-c/review.svg?style=flat-square&color=EC4899" alt="downloads"/></a>
8
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="MIT"/></a>
3
9
  </p>
4
10
 
5
11
  # review
@@ -24,7 +30,7 @@ existing compilation/playback dependencies.
24
30
 
25
31
  ## Start
26
32
 
27
- Install it beside the agent that produced the output, then open that output folder:
33
+ Install beside the producing agent and open the output folder:
28
34
 
29
35
  ```sh
30
36
  npm i -D @rig-c/review
@@ -88,3 +94,4 @@ Development and releasing: [Contributing workflows](https://github.com/rig-c/rev
88
94
  - [Product design](docs/DESIGN.md)
89
95
  - [Animation inspection](docs/ANIMATION_INSPECTION.md)
90
96
  - [Installed-producer fixture](docs/LIVE_FIXTURE.md)
97
+ - [Agent skill](skills/rig-review/SKILL.md)
package/docs/PANELS.md CHANGED
@@ -259,7 +259,7 @@ Rig pixels are the whole figure's frame, which is the crop frame the model's sta
259
259
  - **Inputs.** The producer handoff (`docs/REVIEW_PACKAGE.md`, *Producer handoff*): `open --config` (and `--parts`), else the review.json `producer` block, else `config.json`, then `rig/config.json` inside the opened folder, then `../config.json` beside an opened `out/`. The parts directory defaults to `out/` beside the config and holds `parts.json`, `parts/` and the inspected `rig/`. The editor bar shows, before any Apply, how the config was found (declared, discovered, or discovered outside the opened folder), its path and SHA-256, and the baseline. Without a handoff the bar shows `MODELING_INPUT_UNAVAILABLE: config.json — looked at …` and Apply refuses `MODELING_HANDOFF_MISSING`, naming `--config`. The request carries only `{part, regions, configHash}`; the server reads the config, replaces `meshes.<part>.contour.regions` with the designated regions (every other field as written) and runs `rig-parts remesh --rig <out>/rig --config <config> --parts <out> --part <part> --mesh mesh.json --out revision`, then `rigc build --profile rig-play --pack` with the revision's own `--page-edges` / `--pack-shape`, both with the scratch directory as working directory. A region row with equal semi-axes and no clip is sent as the config's circle, any other as the 32-sample polygon. An untouched editor starts from the config's own circle regions and contour numbers.
260
260
  - **Baseline.** Once per session, when the handoff and the producer both resolve, review runs `rig-parts rig --config <config> --parts <parts> --out <state>/baseline/<key>/baseline` and compares every file it writes (rig.json, motion.json, mesh_report.json, sets.json, images/*) with the inspected rig directory: `baseline: reproduced — rig.json <hash> = inspected <hash>`, or `baseline: not reproduced — <first differing path> · <what Apply can still do here>`. The key is the package hash, the handoff record and the producer versions (no clock), so a reopen reuses the result. Ops that rebuild the whole rig refuse `EDIT_BASELINE_MISMATCH <path>` unless the baseline reproduced; `remesh` keeps its own `REMESH_BASELINE_MISMATCH`. A build the config does not reproduce — a hand repair — is not open to every Apply (#148): retune carries a **mesh** repair over but holds every image, so a repair that redrew an image refuses every physics and idle edit (`RETUNE_REQUEST_HELD: images/<part>.png`); remesh from a config entry refuses the repaired parts and re-fits the others; a mesh edit is held to the inspected mesh, not the config; and remesh, its mesh edit and retune all refuse an inspected `rig.json` (or `mesh_report.json`, `motion.json`) that is not the writer's text (`…_INPUT_WRITTEN` — re-serialise it as rig writes it, JSON with one space of indent and a closing newline, in a copy). The baseline line and `EDIT_BASELINE_MISMATCH` name which of these hold here, and a producer refusal review can explain carries `review: …` after the producer's own line (docs/REVIEW_PACKAGE.md, *Baseline reach*). Once it reproduces, `rig-parts check` runs on the baseline output in the background (into `<state>/baseline/<key>/inspected-check/`, with Apply's default `--page-edges free --pack-shape polygon`) and its summary is stored beside the baseline record as `inspected-check.json`; that is the physics readout's BEFORE for the inspected build, and a reopen reads it instead of re-running.
261
261
  - **Scratch.** `<state>/rebuild/<package source hash>/<designation hash>/` under `RIG_REVIEW_STATE_DIR` (refused, by its canonical location, inside the package, its build root or the handoff root), named from the package, the config bytes, the part, the entry and both tool versions — no clock. The same designation again reuses its build and says so; a new one replaces the previous scratch build on the stage (the earlier applied records' builds are kept beside the scratch root for undo, at most eight per package). The inspected package's files are only read.
262
- - **Watching.** The producer's lines stream into the editor bar (the latest line and a short log); a refusal shows the producer's first named line verbatim (for example `FAIL REMESH_REQUEST_HELD: …`) and the stage is unchanged. On success the compiled scratch build (served read-only under `/rebuild/<id>/`, its model and pages hashed) replaces the drawn rig in place with the same camera, animation, time and part set; playback resumes with physics when it was running. **Reset** returns the stage to the inspected build. **Undo last Apply** (the *Applied records* list at the top of the Inspector, its depth in the label) returns the stage to the previous applied build, or to the inspected build when none is left; a predecessor whose build was evicted re-runs its recorded step and must come back byte for byte, else `UNDO_PREDECESSOR_CHANGED: <what>` (docs/REVIEW_PACKAGE.md, *Undo across Applies*). A change to the handoff config ends the session's undo stack (reopen): Undo is then refused `FRONT_INSTANCE_EXPIRED`. The Cuts and Cloth blocks mark a pending op applied only while the record on the stage holds it, so after an undo they show the predecessor's ops as applied, and none on the inspected build. The mark shows what the build on the stage carries, not every op applied so far: while a cloth build is on the stage, the Cuts block marks nothing.
262
+ - **Watching.** The producer's lines stream into the editor bar (the latest line and a short log); a refusal shows the producer's first named line verbatim (for example `FAIL REMESH_REQUEST_HELD: …`) and the stage is unchanged. On success the compiled scratch build (served read-only under `/rebuild/<id>/`, its model and pages hashed) replaces the drawn rig in place with the same camera, animation, time and part set; playback resumes with physics when it was running. **Reset** returns the stage to the inspected build. **Undo last Apply** (the *Applied records* list at the top of the Inspector, its depth in the label) returns the stage to the previous applied build, or to the inspected build when none is left; a predecessor whose build was evicted re-runs its recorded step and must come back byte for byte, else `UNDO_PREDECESSOR_CHANGED: <what>` (docs/REVIEW_PACKAGE.md, *Undo across Applies*). A change to the handoff config ends the session's undo stack (reopen): Undo is then refused `FRONT_INSTANCE_EXPIRED`. The Cuts and Cloth blocks mark a pending op applied only while the record on the stage holds it, so after an undo they show the predecessor's ops as applied, and none on the inspected build. The mark shows what the build on the stage carries, not every op applied so far: while a cloth build is on the stage, the Cuts block marks nothing. Whenever the stage holds an applied edit from another panel or job kind, each panel shows a plain-words statement beside its Apply button before the click (`This rebuild starts from the handoff and drops: …`), and after a second panel applies, the superseded panel stops reading as applied while keeping its in-panel edits for re-Apply.
263
263
  - **Record.** The last applied state (`rig-review-applied/1`: part, regions, for a Landmarks Apply also `bust` — the entry as sent, with `regions` its two derived circles — config hash, entry SHA-256, producer and compiler versions, the producer's line and the scratch model's SHA-256) stays in the inspection draft, and feedback added while that build is on the stage carries it as `context.applied`. The review's `reviewedSource` still names the inspected build.
264
264
  - **Config patch.** The same loop takes any config edit as data: `POST /api/rebuild {patch}` with a `rig-review-config-patch/1` document (JSON Pointer ops over the handoff config, refused `EDIT_PATCH_STALE` when made against other config bytes) rebuilds the whole rig (`rig`) or one part (`remesh`) into scratch, compiles it and runs `rig-parts check` on it; the page's `window.rigReviewEditor.applyPatch(patch)` streams, reloads and resets like Apply, and the draft and `context.applied` carry `rig-review-applied/2` (the patch, its hash, the producer's line, check's summary and the diff of every document the producer writes, per file, with the images by hash). Schema and refusals: `docs/REVIEW_PACKAGE.md`, *Config patch and Apply*.
265
265
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rig-review",
3
- "version": "0.22.0",
3
+ "version": "0.24.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -41,6 +41,7 @@
41
41
  "docs/DESIGN.md",
42
42
  "docs/ANIMATION_INSPECTION.md",
43
43
  "docs/LIVE_FIXTURE.md",
44
+ "skills",
44
45
  "README.md",
45
46
  "LICENSE"
46
47
  ],
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: rig-review
3
+ description: Hand a rig build or rig-parts/rig-pose output to a person for local inspection and retrieve their structured feedback with rig-review (@rig-c/review). Validate the delivery package (rig-review check), start or reuse a loopback inspection workspace and print its capability URL (rig-review open), read back submitted verdicts, frame intervals, stage-comment crop PNGs and applied producer edits (rig-review feedback --format json|issue), export comparison or feedback frame strips headlessly (rig-review strip), or steer an opted-in open page (rig-review control). Not for compiling a rig (use rigc or rig-parts) or grading a rig without a person's submission.
4
+ license: MIT
5
+ compatibility: Requires Bun 1.3.0 or later on PATH. The canonical npm package is @rig-c/review (npm i -D @rig-c/review, or bun add -d @rig-c/review; rig-review is the convenience install name); the command it installs is rig-review, and @rig-c/play is installed as a dependency.
6
+ ---
7
+
8
+ # rig-review — human inspection handoff and feedback retrieval
9
+
10
+ Load this when a rig or animation is **ready for a person to inspect**, or when
11
+ the person has submitted a review and you need to **read back what they asked to
12
+ change**. The workspace's reader is a person in a browser; this file states what
13
+ an agent can actually drive from the CLI, what only the person does, and where
14
+ every rule lives.
15
+
16
+ ## What an agent drives vs. what the person drives
17
+
18
+ 1. **Validate and hand off (agent):**
19
+ ```sh
20
+ npx rig-review check /absolute/path/to/output
21
+ npx rig-review open /absolute/path/to/output [--reference /abs/video.mp4] [--compare /abs/other] [--animation <name>] [--config /abs/config.json [--parts <dir>] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]] [--control]
22
+ ```
23
+ `check` verifies the delivery contract and source SHA-256 without starting a
24
+ server. `open` starts or reuses a loopback worker behind the managed front
25
+ (`127.0.0.1:4318`, or `--direct`), prints the writable `#cap=…` URL alone on
26
+ stdout for the person to open, and prints the exact matching
27
+ `rig-review feedback …` command on stderr — [Owner handoff](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#one-command-owner-handoff).
28
+ 2. **Inspect, rebuild in scratch and submit (person in the browser):**
29
+ `rig-review` never opens a browser itself. Only the person holding the
30
+ `#cap=…` tab can inspect panels, run `Apply · Rebuild` through the installed
31
+ producer (`rig-parts`, `rig-pose`) into scratch, drag **Comment · C** crops,
32
+ choose **approved** or **changes-requested** in **Write review**, and click
33
+ **Submit review** — [Feedback ownership](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#feedback-ownership).
34
+ 3. **Act on what comes back (agent):**
35
+ ```sh
36
+ npx rig-review feedback /absolute/path/to/output [...same flags as open...] [--format json|issue]
37
+ npx rig-review strip /absolute/path/to/output --reference-video /abs/video.mp4 --animation <name> (--frames FIRST:LAST | --all-feedback) [--json] [--out /abs/outside/strip.png]
38
+ ```
39
+ Read `status` (`pending` means the person has not submitted yet; opening
40
+ never approves), `reviewedSource` (rig/motion SHA-256 and tool versions),
41
+ `applied` (the exact config patches, pose-map/retarget flags and producer
42
+ lines the person applied in scratch), `feedback` (inclusive frame intervals,
43
+ bone/slot/rig targets, `defect`|`quality` category and summary), and
44
+ `comments` (pin/box coordinates, nearest drawn slots, and derived crop PNG
45
+ paths under `~/.local/state/rig-c-review/` that you can open directly without
46
+ a browser). Apply the requested fixes in the upstream producer (`rig-parts`,
47
+ `rig-pose` or `rigc`), rebuild, and run `rig-review open` again.
48
+ 4. **Optional live view steering (agent, only while the person's tab is open):**
49
+ When opened with `--control` and a browser tab is connected,
50
+ `npx rig-review control <dir> [...same flags...] [--page <id> --expected-revision <n> --request-id <id> --command <JSON>]`
51
+ reads or steers camera, time, animation and layers; it cannot submit or
52
+ approve a review or mutate source files — [Control](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#control-the-current-inspection-page).
53
+
54
+ ## Non-negotiables
55
+
56
+ - **Supplied packages and models stay immutable.** Review never edits
57
+ `motion.json`, `skeleton.model.json` or source art; producer edits run in
58
+ scratch and feedback is stored under `~/.local/state/rig-c-review/` (or
59
+ `RIG_REVIEW_STATE_DIR` outside every input package) bound to the exact content
60
+ SHA-256 — [REVIEW_PACKAGE.md](https://github.com/rig-c/review/blob/main/docs/REVIEW_PACKAGE.md).
61
+ - **Pass the exact handoff flags to `feedback` and `control`.** `--reference`,
62
+ `--compare`, `--animation` and `--config` (`--parts`, `--source`, `--full`,
63
+ `--head`, `--keypoints`) are hashed into the session identity; omitting one
64
+ reads a different session, and changing any input byte starts a fresh
65
+ `pending` session — [WORKFLOWS.md](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#one-command-owner-handoff).
66
+ - **Never leak the `#cap=` fragment into public logs or commits.** The fragment
67
+ is the per-instance 256-bit write capability; share it only with the person
68
+ reviewing on the local machine — [Managed front](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#managed-front-and-write-capability).
69
+ - **Strip outputs go outside every input package.** `rig-review strip --out`
70
+ refuses a path inside any reviewed package and requires `frameTimes` in the
71
+ report plus `ffmpeg` (≥ 5.1) and `ffprobe` on `PATH` for PNG video decoding —
72
+ [Frame strip export](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#frame-strip-export).
73
+
74
+ ## Read, in this order
75
+
76
+ 1. [docs/WORKFLOWS.md](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md) —
77
+ `open`, `check`, `compare`, `feedback` (`--format json|issue`), `strip`,
78
+ `control`, the launcher stdout/stderr/exit-code contract and `OPEN_*` /
79
+ `FRONT_*` refusal codes.
80
+ 2. [docs/REVIEW_PACKAGE.md](https://github.com/rig-c/review/blob/main/docs/REVIEW_PACKAGE.md) —
81
+ folder discovery (`skeleton.model.json`, `build/skeleton.model.json`, and
82
+ `rig-parts build` roots), `review.json`, producer handoff (`HANDOFF_*`),
83
+ session/feedback schema and historical retrieval.
84
+ 3. [docs/PANELS.md](https://github.com/rig-c/review/blob/main/docs/PANELS.md) and
85
+ [docs/ANIMATION_INSPECTION.md](https://github.com/rig-c/review/blob/main/docs/ANIMATION_INSPECTION.md) —
86
+ what each browser panel writes into `applied`, `feedback` and `comments`.
87
+
88
+ Every guide linked above ships in the installed package under
89
+ `node_modules/@rig-c/review/docs/`, matching the installed version.