@rig-c/review 0.13.0 → 0.14.0

package/docs/REVIEW_PACKAGE.md

@@ -5,8 +5,9 @@ Adapter**. Review supplies human inspection and feedback bound to the exact
 reviewed sources; it neither replaces Core's build validation nor authors motion.
 The app uses the published `@rig-c/play` loader/player to preview artifacts during
 that inspection. This conceptual delivery order is not an import/dependency
-order. Adapter means downstream consumer integration, not a newly introduced or
-unreleased adapter contract. Existing producer formats and playback dependencies
+order. Adapter means downstream consumer integration through the published
+`@rig-c/pixi`, `@rig-c/phaser` and `@rig-c/three` packages; Review does not depend
+on them. Existing producer formats and playback dependencies
 remain authoritative.
 
 The CLI also accepts an existing output directory. It reads a root `review.json` when present. Otherwise it constructs this contract in memory: optional root `skeleton.model.json`, otherwise the fixed rigc build path `build/skeleton.model.json`; read-only `skeleton.*`, `motion.json` and `report.json` links; root videos (`mp4`, `webm`, `mov`); image filenames containing strip/contact/sheet/filmstrip/띠; and canonical `*pose*.json` references. The root compiled model takes precedence over the build path. These are the only two automatically recognized model paths; discovery never searches recursively. One fixed layout redirects instead (#149): a folder with neither model path that is a `rig-parts build` output root — regular `parts.json` and `rig/rig.json`, a real (not symlinked) `check/` directory, and an existing `check/build/skeleton.model.json` entry — opens as its `check/` package. The package root is then `check/`, exactly as if `check/` had been opened: the same manifest, source hash, `reviewedSource`, session and open key. A folder missing any of those files is not a build root and is refused or adapted as before; a build root that also holds a model of its own opens as itself. The opened directory remains the package root, so root motion/references accompany the build model and its model-relative pages. An existing selected model with an invalid type, dangling symlink, escaping symlink or invalid model envelope is refused rather than skipped. Each reference is shown separately; no source relationship, FPS or video synchronization is inferred. It never inserts or rewrites a manifest or motion file in the source folder. Raw Spine JSON/skel remains read-only evidence with playback unavailable. The folder revision is `folder-adapter/1`; actual changed file bytes are distinguished by the source hash.
@@ -105,6 +106,29 @@ Both session responses include server-derived `feedbackWarnings:[{id,error}]`. R
 The state filename is a digest of identity, revision, source hash and reviewed artifact/tool identity, so package names cannot select arbitrary filesystem paths. Writes are atomic and source files remain untouched. Review/session load and save stream-hash the declared inputs; changed bytes produce HTTP 409 and require restart. Asset reads do not rehash an entire video: single byte ranges return 206 and invalid ranges 416. Asset documents receive a sandbox CSP with no scripts or same-origin permission, so delivered authoring HTML cannot approve its own package. No network listener beyond loopback or cross-origin mutation is offered.
 
 
+### Turn inspection context
+
+`context.turn`, when present, is a closed, bounded record:
+`{schema:"rig-review-turn/1", values:{yaw?,pitch?,body?}, held:boolean, smoothing:number}`.
+Values are the applied dial values, not pending pointer targets. Smoothing is the
+normalized-pointer spring frequency (0 disables it, otherwise at most 100 s⁻¹).
+Only the model's supported actual sliders supply the permitted axes and ranges;
+all offered axes must be present, each finite and within its range. Unknown keys,
+missing axes, unsupported models and out-of-range values refuse with `TURN_*`.
+A comparison validates against both source-bound models' common axes and range
+intersection, irrespective of the feedback's selected side. Model metadata comes
+from the same bytes hashed into `reviewedSource`; there is no filesystem parameter
+or producer-config discovery in this field. Session source rehashing, identity,
+Origin and payload limits still apply. Historical records retain warnings under
+the ordinary legacy-read policy; a fresh save cannot bypass this validation.
+If a scratch rebuild changes supported axes or expands a range, submission still
+uses the original inspected catalog: newly supported values are refused by name
+(`TURN_UNAVAILABLE` or `TURN_STATE_MODEL_MISMATCH`), rather than silently certified
+as inspected inputs. Authoritative scratch-dial validation is outside this field.
+The optional inspection bookmark `selection.turn` has this same shape and is
+checked against the active pad before transactional restoration. It restores
+applied values, not the pointer's pending travel. No package or motion bytes change.
+
 ## Feedback export
 
 The frontend downloads `rig-review-feedback/1` JSON with `id`, `revision`, `sourceHash`, review status, `feedback[]`, and issue-ready `issues[]` entries containing title/body/labels. It also offers Markdown. Each issue contains the frame interval, target, category, summary and package binding. Exports stay local; no issue is posted automatically. These are review annotations, not motion or correction-key artifacts.
@@ -176,7 +200,7 @@ Every edit card states its edit as one config patch; review applies it to a scra
 - `rig-review-applied/2` (patch): `{schema, buildId, patch, patchSha256, configHash, producer:{package,version}, compiler:{package,version}, line, check, diff, modelHash}` — the exact patch (whose `config_sha256` equals `configHash`), its hash, the producer's last line, check's summary and the rig.json diff. Since #136 the record adds `op`, the producer op that ran: `"rig"` or `"retune"` for a `rig` patch, `"remesh"` for a remesh patch (anything else is refused); the job carries the same `op` and its lines name the command. Records without `op` stay valid. Since #111 `op` may be `"cloth"` for a `rig` patch whose ops all lie under `/cloth`, and exactly then the record adds `cloth: {route:"build"|"rig", keypoints:{path, sha256}, written:{count, paths[≤200]}}` — how the config propose wrote was built, the keypoint file it read and where the written config differs from the patched one — and, when the route is `build`, `assembled` as below; the export's `Applied:` line names the written diff and the route. Since #115 `op` may be `"build"` for a `rig` patch, and exactly then the record adds `assembled: {wallMs, recomposite:{before, after}, partsChanged[], seamPairs[≤64]}` — the build's wall clock for that Apply, the recomposite figures, the parts whose PNG changed against the handoff's and the `seam pair` lines; the issue export's `Applied:` line names the wall clock (`· build 118.0 s · parts changed: bottomwear, ribbon_r · recomposite error px 8194 → 8194`). A remesh patch from the Mesh panel (#106) adds `mesh: {part, before:{vertices, triangles, hull}, after:{vertices, triangles, hull}}` — the revision's `remesh.json` counts; `part` must be the part the patch's `remesh --part` names. Since #125 the record adds `files: {documents:[{file, count, paths}], images:{changed, unchanged, names}}` (or `null`) — the scratch rig against the inspected rig, every document the producer writes: `documents` in the order `rig.json`, `motion.json`, `sets.json`, `mesh_report.json` (each `file` at most once; a document neither side has is left out), `count` the number of RFC 6901 pointers at which it differs and `paths` the first ≤ 200 of them (`""` — the whole document — when only one side has it or a side is not JSON, unless the bytes are equal); `images` compares `images/*` by SHA-256 only: `changed` (including an image only one side has, its `images/<name>` in `names`, ≤ 200) and `unchanged`. `diff` stays rig.json's entry as before. Records without `files` (written before #125) stay valid. The list of documents is `PRODUCER_DOCUMENTS` in `src/producer-files.ts`, the same list the baseline compares. The Apply status line and the export state it per file: `motion.json differs at 2 path(s) · rig.json, sets.json, mesh_report.json unchanged · 31 images unchanged`.
 - `rig-review-applied/3` (#135, Edit Mesh's delta): `{schema, buildId, part, delta, deltaSha256, configHash, producer, compiler, line, op, files, mesh?, modelHash}` — the `rig-review-mesh-edit/1` document as sent (basis `"setup"`, `slot` the part, at most 300 ops), the SHA-256 of its bytes, the producer's last line, `op` always `"remesh"`, the per-file diff as above (or `null`) and the part's `remesh.json` counts (`mesh.part` must be `part`). No `check`: `rig-parts remesh` holds check on the revision itself (`REMESH_CHECK_HELD`). See *Mesh edit export*.
 
-**Readings (#108).** `POST /api/readings` (single review; same-origin, capability, 64 KiB) takes exactly `{animation, readings:[1–8], environment}`: each reading is `{kind:"folds"}`, `{kind:"overlaps"}`, `{kind:"pass-through", cloth, leg}`, `{kind:"seam", a, b}` or `{kind:"angle-range", bone, relative}`, every name a slot or bone name without `:` or `,` (whether the rig has it is rigc's to say), no reading twice; `environment` is `null`, `{wind:[x,y], gravity:[x,y]}` (x right, y down) or, with *Use for readings* on (#112), the exported `rigc-environment/1` schedule as data. Malformed: HTTP 400 `READINGS_REQUEST_INVALID`. Outcomes (HTTP 200 `{status:"refused", error}`): `READINGS_COMPILER_NOT_INSTALLED` (rig-c beside `@rig-c/parts`, else beside the package or review), `READINGS_COMPILER_TOO_OLD <found> 2.63.0`, `READINGS_NO_MODEL`, `READINGS_STATE_INSIDE_PACKAGE`, `READINGS_BUSY`. The job (`GET /api/readings/<id>`, the id hashed from the package, the request, the inspected model's bytes, the scratch build id, the compiler and whether the schedule was passed): `{schema:"rig-review-readings/1", id, status:"running"|"done"|"failed", error, request, environment:{requested, flag, passed}, compiler, runs:[{build:"inspected"|"scratch", id, modelHash, results[]}]}`. Each result is `{reading, label, status:"read"|"refused"|"failed", fps, frames[] (every frame the reading's JSON lists: folds' meshes' frames, pass-through's frames, seam's opens, overlaps' moving pairs' runs; angle-range's lowest and highest frame from its printed line), source:"json"|"line", worst:{frame, figure, line}|null, items[] (per mesh or pair), lines[] (rigc's printed rows for the reading), refusal (rigc's `rigc: …` line verbatim), exitCode, wallMs}`. The inspected build is `--candidate <the directory of the manifest's model>`; the scratch build is the session's latest built Apply. Each reading runs as `rigc render --candidate <build> --animation <animation> [--environment environment.json] <flag> --out render` in `<state>/readings/<package hash>/<inspected-<model sha256>|scratch-<build id>>/<key>/`, keeps `result.json`, the reading's JSON and `frames.json`, and removes the rendered frames. The schedule `{spec:"rigc-environment/1", steps:[{t:0, wind, gravity}]}` is passed only when `rigc render --help` lists `--environment`. A schedule sent in the request is written as sent (re-serialized, one-space JSON and a newline).
+**Readings (#108).** `POST /api/readings` (single review; same-origin, capability, 64 KiB) takes exactly `{animation, readings:[1–8], environment}`: each reading is `{kind:"folds"}`, `{kind:"overlaps"}`, `{kind:"pass-through", cloth, leg}`, `{kind:"seam", a, b}` or `{kind:"angle-range", bone, relative}`, every name a slot or bone name without `:` or `,` (whether the rig has it is rigc's to say), no reading twice; `environment` is `null`, `{wind:[x,y], gravity:[x,y]}` (x right, y down) or, with *Use for readings* on (#112), the exported `rigc-environment/1` schedule as data. Malformed: HTTP 400 `READINGS_REQUEST_INVALID`. Outcomes (HTTP 200 `{status:"refused", error}`): `READINGS_COMPILER_NOT_INSTALLED` (`@rig-c/core` first, legacy `rig-c` only when absent, beside `@rig-c/parts`, else beside the package or review), `READINGS_COMPILER_TOO_OLD <found> 2.63.0`, `READINGS_NO_MODEL`, `READINGS_STATE_INSIDE_PACKAGE`, `READINGS_BUSY`. The job (`GET /api/readings/<id>`, the id hashed from the package, the request, the inspected model's bytes, the scratch build id, the compiler and whether the schedule was passed): `{schema:"rig-review-readings/1", id, status:"running"|"done"|"failed", error, request, environment:{requested, flag, passed}, compiler, runs:[{build:"inspected"|"scratch", id, modelHash, results[]}]}`. Each result is `{reading, label, status:"read"|"refused"|"failed", fps, frames[] (every frame the reading's JSON lists: folds' meshes' frames, pass-through's frames, seam's opens, overlaps' moving pairs' runs; angle-range's lowest and highest frame from its printed line), source:"json"|"line", worst:{frame, figure, line}|null, items[] (per mesh or pair), lines[] (rigc's printed rows for the reading), refusal (rigc's `rigc: …` line verbatim), exitCode, wallMs}`. The inspected build is `--candidate <the directory of the manifest's model>`; the scratch build is the session's latest built Apply. Each reading runs as `rigc render --candidate <build> --animation <animation> [--environment environment.json] <flag> --out render` in `<state>/readings/<package hash>/<inspected-<model sha256>|scratch-<build id>>/<key>/`, keeps `result.json`, the reading's JSON and `frames.json`, and removes the rendered frames. The schedule `{spec:"rigc-environment/1", steps:[{t:0, wind, gravity}]}` is passed only when `rigc render --help` lists `--environment`. A schedule sent in the request is written as sent (re-serialized, one-space JSON and a newline).
 
 **Environment schedule (#112).** The Animate Environment block exports its controls as a `rigc-environment/1` schedule (`src/environment-schedule.ts`): `{spec:"rigc-environment/1", steps:[{t, wind?:[x,y], gravity?:[x,y]}]}`, x right, y down, t = 0 at the clip's first frame, written as one-space JSON and a newline (the bytes downloaded, sent and hashed). With neither breeze nor a repeating gust it is the step form, one step `{t:0, wind:[base,0], gravity:[0,g]}` (#108's standing schedule) — exact. With breeze or repeat on it is the sampled form: one step per frame at 12 fps (rigc render's default and check's IDLE_FPS) from 0 to the clip's last frame (`round(duration·12)`; rigc refuses a step after it), each the panel's wind at that time from a fresh clock (a repeating gust starts at 0, every `max(6, duration + 0.6)` s, turned when the base is negative), a step equal to the one before left out, gravity on the first step. rigc sets a step before the physics step that ends on its frame, as the page sets the wind before the player's step, so the schedule equals the panel's wind at every frame time; between frames rigc holds the frame's value, within `max|dw/dt| / 12` of the panel's (`(breeze ? 8.48 : 0) + (repeat ? peak·π/duration : 0)`, over 12). A one-off Gust (Repeat off) is not in the schedule. Refused by name: `ENVIRONMENT_NOT_APPLIED` (the controls are not engaged; check and render without `--environment` already read the runtime's world), `ENVIRONMENT_SCHEDULE_NO_CLIP`, `ENVIRONMENT_SCHEDULE_TOO_LONG` (more than 600 steps). *Use for readings* sends the drawn clip's schedule with readings and the checked clip's (`idle` when the rig has one) with Apply, and restarts the wind clock with the clip (and at each idle loop) so the person watches the world rigc reads. *Export schedule* downloads `rigc-environment.json`.
 
@@ -190,7 +214,7 @@ Every edit card states its edit as one config patch; review applies it to a scra
 
 **Self-targeted requirements (#142).** The panel refuses before Add, as `REQUIREMENTS_SELF_TARGET`, a `contact` whose target is its own bone and point and an `aim` whose target bone is the aimed bone: both measure 0 in every frame and the producer reports them as PASS (its own refusal is rig-c/parts#540). A bone's tip against its own origin is not refused; it measures the bone's length. A fresh contact or aim form proposes a target bone other than the subject (the next bone in rig order).
 
-**Retarget (#114).** `GET /api/rebuild` adds `retarget: {available, reason, producer, compiler, rig, sequences:[{id, label, path, cleaned, frames, people[]}], bones[], animations[]}`: the installed `@rig-c/pose` (found as `@rig-c/parts` is: the nearest `node_modules` from the package, then from review's working directory; `RETARGET_PRODUCER_NOT_INSTALLED` when absent, never installed) and the `rig-c` beside it (`RETARGET_COMPILER_NOT_INSTALLED`), the package's declared `rig-pose-sequence/1` pose references, and the handoff rig's bone and animation names (`RETARGET_SEQUENCE_UNAVAILABLE` when the package declares no sequence). `POST /api/rebuild` with exactly `{retarget: {sequence, map, flags, configHash}}` (same-origin, capability, 64 KiB): `sequence` a declared pose reference id; `map` a `rig-pose-map/1` document of at most 32 KiB whose chains each hold a name and 1–32 bones and joints (everything else is the producer's to judge); `flags` exactly `{animation, person, clean, minScore, flip, short, bends, bendTolerance, legScale, plantFeet, stance, raisedByHead, carryIdle}`, `clean` null or exactly `{loop, legs, rest, hold, hipsInferred}` (windows 1, or odd and 5–61). Malformed: HTTP 400 `RETARGET_REQUEST_INVALID`. Refused before anything runs: `REBUILD_CONFIG_STALE`, `RETARGET_SEQUENCE_UNKNOWN`, `RETARGET_SEQUENCE_UNSUPPORTED` (a static pose), the handoff and state-directory refusals, `REBUILD_BUSY`. The server maps the flags to argv (`op.args` for retarget, `op.clean` for clean, only what the flags state) and runs, in `<state>/rebuild/<package hash>/<retarget id>/`, `rig-pose clean --pose pose.json --out pose.clean.json <op.clean>` (unless `clean` is null) and `rig-pose retarget --rig <handoff rig> --map map.json --sequence <pose.clean.json | pose.json> --out motion.json <op.args>`, copies the handoff rig's regular files (motion.json excepted) and `images/` to `rig/` with `rig/motion.json` the retarget's, then the shared tail: the per-file diff and `rigc build --rig rig/rig.json --motion rig/motion.json --out build --profile rig-play --pack --page-edges free --pack-shape polygon`. The retarget id hashes the package, the handoff config, the record's bytes and both tool versions (no clock); an identical retarget reuses its build. The job (`GET /api/rebuild/<id>`): `{schema:"rig-review-rebuild/1", kind:"retarget", op:"retarget", id, status, reused, request:{record, recordSha256, configHash}, producer, compiler, lines[], producerLine, refusals[] (every FAIL line of the step that refused, verbatim), exitCode, wallMs:{clean, retarget, compile}, files, motion:{animation, animations[], kept, changed[], animationSha256, motionSha256}, readings:[{code, line, frame, time}], build}`. `readings` are the retarget's FEET, STANCE, FLIP, SHORT, END-ON, LEG-SCALE and REACH lines (at most 200), each with the first frame it names and that frame's key time from the run's report `frameTimes` (else the line's `t=`). The record, `rig-review-retarget/1`: `{schema, config_sha256, rig:{path, sha256 (rig.json)}, sequence:{reference, path, sha256}, map, map_sha256 (the bytes of map.json as written: one-space JSON and a newline), flags, producer:{name, version}, op:{cmd:"retarget", args, clean}}`; a reader checks that `op` is its flags' own argv. The applied context of a built retarget is `rig-review-applied/4`: `{schema, buildId, retarget, recordSha256, configHash, producer, compiler, line, motion, files, readings, modelHash}`.
+**Retarget (#114).** `GET /api/rebuild` adds `retarget: {available, reason, producer, compiler, rig, sequences:[{id, label, path, cleaned, frames, people[]}], bones[], animations[]}`: the installed `@rig-c/pose` (found as `@rig-c/parts` is: the nearest `node_modules` from the package, then from review's working directory; `RETARGET_PRODUCER_NOT_INSTALLED` when absent, never installed) and the `@rig-c/core` beside it (legacy `rig-c` only when the scoped package is absent; `RETARGET_COMPILER_NOT_INSTALLED`). The `compiler` record identifies the selected package and version; the remaining inputs are the package's declared `rig-pose-sequence/1` pose references, and the handoff rig's bone and animation names (`RETARGET_SEQUENCE_UNAVAILABLE` when the package declares no sequence). `POST /api/rebuild` with exactly `{retarget: {sequence, map, flags, configHash}}` (same-origin, capability, 64 KiB): `sequence` a declared pose reference id; `map` a `rig-pose-map/1` document of at most 32 KiB whose chains each hold a name and 1–32 bones and joints (everything else is the producer's to judge); `flags` exactly `{animation, person, clean, minScore, flip, short, bends, bendTolerance, legScale, plantFeet, stance, raisedByHead, carryIdle}`, `clean` null or exactly `{loop, legs, rest, hold, hipsInferred}` (windows 1, or odd and 5–61). Malformed: HTTP 400 `RETARGET_REQUEST_INVALID`. Refused before anything runs: `REBUILD_CONFIG_STALE`, `RETARGET_SEQUENCE_UNKNOWN`, `RETARGET_SEQUENCE_UNSUPPORTED` (a static pose), the handoff and state-directory refusals, `REBUILD_BUSY`. The server maps the flags to argv (`op.args` for retarget, `op.clean` for clean, only what the flags state) and runs, in `<state>/rebuild/<package hash>/<retarget id>/`, `rig-pose clean --pose pose.json --out pose.clean.json <op.clean>` (unless `clean` is null) and `rig-pose retarget --rig <handoff rig> --map map.json --sequence <pose.clean.json | pose.json> --out motion.json <op.args>`, copies the handoff rig's regular files (motion.json excepted) and `images/` to `rig/` with `rig/motion.json` the retarget's, then the shared tail: the per-file diff and `rigc build --rig rig/rig.json --motion rig/motion.json --out build --profile rig-play --pack --page-edges free --pack-shape polygon`. The retarget id hashes the package, the handoff config, the record's bytes and both tool versions (no clock); an identical retarget reuses its build. The job (`GET /api/rebuild/<id>`): `{schema:"rig-review-rebuild/1", kind:"retarget", op:"retarget", id, status, reused, request:{record, recordSha256, configHash}, producer, compiler, lines[], producerLine, refusals[] (every FAIL line of the step that refused, verbatim), exitCode, wallMs:{clean, retarget, compile}, files, motion:{animation, animations[], kept, changed[], animationSha256, motionSha256}, readings:[{code, line, frame, time}], build}`. `readings` are the retarget's FEET, STANCE, FLIP, SHORT, END-ON, LEG-SCALE and REACH lines (at most 200), each with the first frame it names and that frame's key time from the run's report `frameTimes` (else the line's `t=`). The record, `rig-review-retarget/1`: `{schema, config_sha256, rig:{path, sha256 (rig.json)}, sequence:{reference, path, sha256}, map, map_sha256 (the bytes of map.json as written: one-space JSON and a newline), flags, producer:{name, version}, op:{cmd:"retarget", args, clean}}`; a reader checks that `op` is its flags' own argv. The applied context of a built retarget is `rig-review-applied/4`: `{schema, buildId, retarget, recordSha256, configHash, producer, compiler, line, motion, files, readings, modelHash}`.
 
 **`context.environmentSchedule`.** Feedback written while the Environment controls are applied carries the drawn clip's exported schedule by hash and content: `{schema:"rig-review-environment-schedule/1", sha256, size, text, usedForReadings}` — `text` is exactly the exported bytes (a `rigc-environment/1` schedule), `sha256` and `size` are recomputed over it on save, `usedForReadings` says whether readings and Apply read it. Absent and `null` stay valid. The issue export adds an `Environment schedule:` line.
 
@@ -563,7 +587,7 @@ Browser players retain play's default DOM mode and default mesh backend. Rigid
 parts remain DOM images; a WebGL mesh label does not claim full-frame GL drawing.
 WebGL is requested by the published default, with Canvas2D as the supported mesh
 fallback. Accurate public actual-flush telemetry requires play 1.11.1 or later;
-this checkout consumes pinned 1.11.2. The consumer does not probe GL or inspect
+this checkout consumes pinned 1.14.0. The consumer does not probe GL or inspect
 private renderer state. The separate Node strip exporter remains Canvas2D.
 
 The backend badge is sampled only after successful draw/frame calls. Fresh mesh

package/docs/WORKFLOWS.md

@@ -0,0 +1,337 @@
+# Inspection workflows
+
+See [workspace panels](PANELS.md) for the controls, or [Start](../README.md#start) for installation.
+
+## Existing output handoff
+
+Open the current output folder directly, without changing the producing agent or inserting a manifest:
+
+```sh
+bun run check -- /absolute/path/to/output
+bun run review -- /absolute/path/to/output
+```
+
+The adapter recognizes root `skeleton.model.json` or the fixed rigc build layout `build/skeleton.model.json` (root model takes precedence), root `motion.json`, `report.json`, `skeleton.json`/`.skel`/`.atlas`, source videos (`.mp4`, `.webm`, `.mov`), image filenames containing `strip`, `contact`, `sheet`, `filmstrip` or `띠`, and canonical `*pose*.json` sequences. Model discovery checks only those two named paths; it never recursively searches directories. A `rig-parts build` output root (`out/`: regular `parts.json` and `rig/rig.json`, a real `check/` directory and `check/build/skeleton.model.json`) that has neither model path itself opens as its `check/` package — the same package, identity and session as opening `out/check` — so `rig-review open <out>` works on a fresh build without copying `check/build` anywhere. Model page images resolve relative to the selected model, while motion and references remain relative to the opened folder. It builds the normalized review manifest in memory and reads source files without changing them. Motion/report/skeleton evidence links are read only. A recognized `rig-pose-report/1` also supplies read-only event markers: frame-only events retain their producer interval and explicitly lack seek until a declared clock is present; explicit event seconds can seek. Empty reported categories show none, while missing fields remain missing. Report markers prefill known feedback coordinates and actual bone/slot names without creating a review decision or motion keys. It exposes each matching video/strip separately, without guessing synchronization or source-to-rig bindings.
+
+When the report declares `fps` plus `frame0` (seconds offset) and a frame count, or exact `frameTimes[]`, the matching animation also shows a producer-frame readout and frame seek controls. Without a bounded declared clock it shows `rate unknown`; current unchanged v19 has no clock. Sample times come only from the report, and feedback context records the recalculated frame or null.
+
+A raw `skeleton.json`/`.skel` can still be inspected as evidence, but cannot play through the compiled-model runtime. Playback requires an upstream gated rigc build's `skeleton.model.json` with portable local page images inside the opened folder. `check` validates the delivery contract and model envelope, not the upstream compiler gate or visual quality.
+
+For a curated handoff, [REVIEW_PACKAGE.md](REVIEW_PACKAGE.md) documents optional `review.json` with named checkpoints, references and angle axes:
+
+```sh
+bun run review -- /absolute/path/to/package/review.json --checkpoint silhouette
+```
+
+The server prints the exact link, for example `http://127.0.0.1:4317/?checkpoint=silhouette#cap=…`. The `#cap=` fragment is this server's write capability (see [Managed front and write capability](#managed-front-and-write-capability)). `--port 0` selects a free port. It binds only `127.0.0.1` and never opens a browser automatically. A folder containing `review.json` uses that explicit manifest.
+
+## Compare two outputs
+
+Open two compiled packages against one explicitly selected local reference video:
+
+```sh
+bun run review -- compare /absolute/output-a /absolute/output-b --reference /absolute/reference.mp4 --animation dance
+bun run check -- compare /absolute/output-a /absolute/output-b --reference /absolute/reference.mp4 --animation dance
+bun run feedback -- compare /absolute/output-a /absolute/output-b --reference /absolute/reference.mp4 --animation dance
+```
+
+Both models must contain the named animation. The video is a separate read-only CLI input, served only through a fixed endpoint; it is never inserted into either package. A separate compare page uses one video playhead to seek both rigs at the same time. Frame readouts use each side's explicit producer clock; no video FPS or missing clock is inferred.
+
+Compare feedback requires side `a` or `b` and carries both package source hashes, both exact rig/motion identities, the shared video hash and animation. A changed input on either side or in the video refuses saved feedback until restart. State stays outside all source inputs. Single-package commands and sessions retain their existing contract. See [the comparison contract](REVIEW_PACKAGE.md#two-package-comparison).
+
+## Feedback ownership
+
+Opening leaves status **pending**. The person explicitly saves **approved**, **changes-requested**, or **pending**, checkpoint outcomes/notes, and feedback containing an inclusive frame interval, a bone/slot/rig target, defect/quality category and one-line summary. Frame numbers are entered explicitly; the app does not invent a source FPS. **Write review**, at the top right, opens the review dialog: review status, reviewed source, selected checkpoint, structured feedback and the frame-strip export. Its **Submit review** saves that explicit status and feedback; closing the dialog keeps the unsubmitted draft. The page has no feedback export buttons: `rig-review feedback --format json` and `--format issue` (below) are the export path, and carry the original source binding and reproducible inspection context. Each submission records `reviewedSource`: package revision, actual viewer/runtime versions, and separate exact-byte SHA-256 plus path for the reviewed rig and motion; an absent artifact stays null. An active compiled model is the rig identity; raw skeleton JSON is evidence with playback unavailable.
+
+New submissions validate bone/slot names against the exact loaded model; the target field offers those names. A rig target names the package id. Source-only packages cannot validate a bone/slot target and say so explicitly. When a matching animation has a declared producer clock, the inclusive interval cannot end beyond the last declared sample at or before the actual clip end. Unknown clocks keep manual frame intervals without inventing a limit. `context.interval` records the chosen interval; inspection `time`/`frame` remain separate. Older invalid feedback stays readable with per-row warnings and exports its original evidence, but cannot be resubmitted until corrected or removed.
+
+Feedback lives under `~/.local/state/rig-c-review/`, separate from delivered files. Identity, revision and a streaming SHA-256 of the normalized manifest plus declared files/model pages bind each saved session. Changed content starts a new pending session, even without a revision bump. Restart the server after changing inputs. Saving or exporting feedback never modifies a model, authors correction keys, writes motion output or publishes an issue automatically.
+
+After the person submits, the producing agent retrieves the stored review without needing the hashed state filename:
+
+```sh
+bun run feedback -- /absolute/path/to/output
+# Or the same explicit review.json originally opened:
+bun run feedback -- /absolute/path/to/package/review.json
+```
+
+This read-only command prints the session JSON, including reviewed artifact identity and feedback. The exact current-tool session wins when present. After a viewer/runtime upgrade, if that exact session is absent, the CLI can retrieve the latest saved submission over the same content with its original recorded versions and `retrieval: {kind:"prior-tools", toolsChangedSince:true, matchingSubmissions, currentTools}`. It does not migrate approval into the current UI or change saved bytes. Changed inputs still return a fresh pending session; a prior submission is never borrowed across content, revision or reviewed-artifact changes. The same lookup applies to `feedback compare`, preserving both recorded side bindings, reference identity and animation. See [historical retrieval](REVIEW_PACKAGE.md#historical-feedback-retrieval) for selection and validation rules.
+
+
+For grouped issue-ready text, use the same input/reference binding with `--format issue`:
+
+```sh
+rig-review feedback /absolute/output --reference /absolute/original.mp4 --format issue
+rig-review feedback /absolute/a --compare /absolute/b --reference /absolute/original.mp4 --animation dance --format issue
+```
+
+The header counts feedback records by defect/quality and by build; blocks group by category, then exact target kind/name. Overlapping intervals and A/B sides remain distinct items. Each block retains its id, inclusive interval, one-line summary and selected/full paired provenance. Historical tool identities and validation warnings remain visible; output never migrates approval, writes state or publishes an issue. Default output and `--format json` remain the existing session JSON. Only feedback accepts `--format`, with `json` or `issue` as its value. These two formats are how submitted feedback leaves the tool; the browser page offers no JSON or Markdown download.
+
+## Frame strip export
+
+The strip panel exports the explicitly entered inclusive feedback interval, or all current in-memory feedback intervals, as a PNG or JSON download. Batch selections include unsaved annotations; they do not submit or approve a review. Choose a declared reference video in single-package mode and an explicit clock basis A/B in compare mode. Every selected feedback interval must identify the selected animation. Separate intervals remain separate strip groups, including overlaps.
+
+The same export is available without a browser:
+
+```sh
+bun src/cli.ts strip /absolute/package/review.json --reference source-video --animation dance --frames 176:184 --out /absolute/external/strip.png
+bun src/cli.ts strip compare /absolute/a /absolute/b --reference /absolute/reference.mp4 --animation dance --basis b --frames 176:184 --out /absolute/external/compare.png
+bun src/cli.ts strip /absolute/package/review.json --reference source-video --animation dance --all-feedback --json
+```
+
+Single `--reference` is a declared video **id**; compare uses the explicitly selected local video path. `--all-feedback` reads only the exact current saved session, and retains each item's side/interval. `--json` produces a selection/provenance plan without rendering; optionally add `--out`. PNG writes an additional `.png.json` provenance sidecar with the actual decoded samples and PNG hash. Destinations must be new files outside every input package, in existing directories without symlink parents. The server exposes download blobs, never a destination-path API.
+
+Strip times require the selected report's exact `frameTimes` and matching animation. Missing or uniform-only clocks refuse PNG with `Report has no frameTimes — regenerate with pose 0.30.0 or later`; JSON retains requested frames with `time:null`. The other compare side may lack a clock: it can still be posed at the common seconds, while its frame label stays unknown. No frame rate is inferred from frame count, duration or video metadata.
+
+PNG export uses the pinned published `@rig-c/play` canvas player and real Node Canvas2D, with `ffmpeg` (5.1 or later, for `-fps_mode`) and `ffprobe` available on PATH for reference decoding. Missing capabilities fail by name. Each requested sample chooses the nearest actual decoded reference PTS (ties earlier); both rigs seek that actual PTS using the viewer's fixed step. JSON distinguishes requested time, actual PTS, delta, decoded frame index, actual player times and independently known producer frames. Requests outside the common domain refuse instead of clamping. The PNG shows source rows, chronological frame columns, and full source hashes/revisions/tool and renderer versions. Batch groups stack vertically. Exports are bounded to64 intervals,256 total frames,64 megapixels and16384 pixels per dimension; larger selections must be split.
+
+The footer fits its measured text while retaining full hashes. RGB/dark-tint features unsupported by the published Canvas2D path refuse with `STRIP_UNSUPPORTED_TINT`; they are not silently omitted.
+
+## One-command owner handoff
+
+`open` validates and hashes an existing folder, starts a background loopback
+instance or reuses the exact matching one, prints its hash-bound URL, and exits.
+By default the URL goes through the managed front at `127.0.0.1:4318`; `--direct`
+prints the instance's own port instead (see [Managed front and write capability](#managed-front-and-write-capability)):
+
+```sh
+bun run open -- /absolute/output --reference /absolute/original.mp4
+# Installed executable mapping:
+rig-review open /absolute/output --reference /absolute/original.mp4 --animation dance
+rig-review feedback /absolute/output --reference /absolute/original.mp4
+rig-review open /absolute/a --compare /absolute/b --reference /absolute/original.mp4 --animation dance
+rig-review feedback /absolute/a --compare /absolute/b --reference /absolute/original.mp4 --animation dance
+# Producer handoff (single review only): the config, parts and inspected rig an Apply rebuilds from
+rig-review open /absolute/output --config /absolute/output/rig/config.json [--parts /absolute/output/rig/out] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]
+rig-review feedback /absolute/output --config /absolute/output/rig/config.json
+```
+
+`--config`, `--parts`, `--source`, `--full`, `--head` and `--keypoints` declare the producer
+handoff (see `docs/REVIEW_PACKAGE.md`, *Producer handoff*). They win over the
+review.json `producer` block, which wins over discovery (`config.json`, then
+`rig/config.json` inside the opened folder, then `../config.json` beside an opened
+`out/`, named as discovered outside the folder). For the `check/` package of a
+`rig-parts build` output the next places are the build's own config: `config.json`
+in the build root, else beside it (`<out>/../config.json`, where `rig-parts build
+--config <dir>/config.json --out <dir>/out` leaves it); the parts directory is the
+build root. Declaring `--config` at exactly one of those two files is taken the same
+way, and that file's folder is then the root for the other flags. Every other path must sit inside the
+package root; a path outside it or a symlink that leaves it is refused by name.
+The handoff files are hashed into the reviewed identity, so `feedback` and
+`control` take the same flags to retrieve the same session, and changing the
+config bytes starts a new pending review. `--keypoints` (#111) is the body-18 keypoint
+file a cloth recipe Apply hands to `rig-parts propose`; it is hashed into the identity
+only when declared, so a handoff without it keeps its identity. `--parts`,
+`--source`/`--full`/`--head` and `--keypoints` need `--config`; `--source` and `--full` go together; compare takes none of them.
+
+`open` chooses an explicit `--animation` first, then the normalized report's
+`animation` after validating actual model membership, then a unique actual clip
+(or unique common clip in compare). Thus `rig-review open /absolute/output
+--reference /absolute/original.mp4` opens a report-bound `dance` without the flag
+and prints `animation: dance (from report.json)` on stderr. Conflicting A/B reports,
+a stale report name or multiple clips without a report refuse by name; no first
+entry, filename or frame rate supplies a guess. Explicit invalid names never fall
+back. The selected clip actually initializes single playback, while an explicit
+checkpoint link or later manual choice takes priority. Incompatible automatic
+checkpoints do not apply another clip's time or axis. Static/source-only packages
+remain inspectable without claiming clip selection; explicit unvalidatable clips
+refuse. Single review sessions remain package-wide; animation selection does not
+create an animation-specific approval identity. Opening never
+approves a review. The command prints the matching feedback retrieval command on
+stderr; stdout contains the URL alone. A selected external video takes precedence
+at automatic startup; an explicit checkpoint link or manual checkpoint selection
+still chooses that checkpoint's reference.
+
+The selected video is a separate CLI capability, not a manifest path escape or a
+file copied into the source package. Its name and streaming byte hash, plus the
+base package hash, appear as `referenceBinding` in single review responses,
+sessions and feedback exports. Use the same `--reference` when retrieving that
+submission; omitting it reads the separate reference-free identity. Changed
+package or reference bytes start pending state. Existing historical retrieval
+preserves earlier recorded tool versions over exactly the same reference content.
+
+The single strip panel can export the selected external video using that same
+binding. Headless equivalent (the original declared-reference form stays valid):
+
+```sh
+rig-review strip /absolute/output --reference-video /absolute/original.mp4 --animation dance --frames 176:184 --out /absolute/external/strip.png
+```
+
+Only tool-owned instances with matching content, canonical input locations, tool
+fingerprint and a private capability handshake are reused. The URL hash is
+checked before serving the app; a stale link never selects another instance's
+package. Input hashes are freshly computed, not trusted from mtime caches. Idle
+open-managed workers stop after 30 minutes. Their private registry, requests and
+logs live beside feedback under `~/.local/state/rig-c-review/open/`; nothing is
+written into supplied folders. `RIG_REVIEW_STATE_DIR` selects another state root
+outside all input packages, judged by its canonical location (symlinks in the path
+and its existing ancestors resolved). Existing foreground review commands still work.
+
+No browser is opened, no LAN listener is added, and no misleading phone/QR URL is
+printed: every current instance binds only `127.0.0.1`.
+
+The printed feedback retrieval command uses POSIX shell quoting for literal path
+arguments. It is not a PowerShell or cmd.exe command string.
+
+### Launcher contract
+
+A launcher may start `rig-review open` as a child process and rely on its stdout,
+stderr and exit code alone:
+
+1. On success stdout is exactly one line, the URL. `open` never writes anything
+   else to stdout.
+2. On success stderr carries the human lines in this fixed order: for the `check/`
+   package of a `rig-parts build` output, `Package: rig-parts build check package <path>`
+   and the handoff line (`Handoff <how>: <config path> sha256 <hash> · parts <dir>`, or
+   `Handoff: <refusal>`); the animation diagnostic (when a clip is selected), the control notice (with `--control`),
+   then the copyable retrieval line `Review started|reused; feedback: rig-review feedback …`.
+3. A refusal exits with code 1, writes nothing to stdout, and its first stderr line
+   starts with a name, followed by a colon and the explanation:
+   - `OPEN_INPUT_MISSING <path>`: the input or `--compare` path does not exist, or is neither a directory nor a regular file.
+   - `OPEN_INPUT_UNRECOGNIZED <path>`: the folder holds no recognized model, skeleton, motion, report, reference or pose sequence and is not a `rig-parts build` output root, or the file is not a JSON manifest.
+   - `OPEN_REFERENCE_REQUIRED`: `--compare` was given without an explicit `--reference`.
+   - `OPEN_ANIMATION_UNKNOWN <name>`: the explicit or report-named clip (JSON-quoted) is not in the compiled model.
+   - `OPEN_ANIMATION_AMBIGUOUS`: no flag or report selects one clip, or the A/B reports conflict.
+   - `OPEN_ANIMATION_UNVALIDATABLE`: a clip was requested but no compiled model can validate it.
+   - `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`.
+   - `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.
+   - `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.
+4. Exit codes: 0 applied, 1 refused. (`control` keeps its own exit 2 for an
+   unapplied command.)
+
+Package validation and worker startup refusals keep their existing messages; the
+named refusals above are decided before any state is written.
+
+### Managed front and write capability
+
+`open` is **managed by default**. It ensures one detached loopback front at
+`127.0.0.1:4318` (`RIG_REVIEW_FRONT_PORT` overrides) for the state directory and
+prints `http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…`. Every
+inspection therefore shares one stable browser origin, so Settings, panel sizes and
+source-bound drafts survive a reopen. The front only routes: it takes the worker
+address from that key's private open record, allows a closed per-method route
+list, bounds bodies (16 KiB control, 1 MiB session/strip) and upstream time,
+limits concurrent upstream streams, re-verifies the worker's nonce on every
+request, and refuses an unknown, expired or replaced instance by name
+(`FRONT_INSTANCE_UNKNOWN`, `FRONT_INSTANCE_EXPIRED`, `FRONT_INSTANCE_REPLACED`).
+Worker error text is not passed through; failures become named `FRONT_*` codes.
+Package assets keep their `sandbox` CSP through the front. It never reads packages.
+Idle fronts exit after 30 minutes once no live instance remains.
+
+If another listener holds the front port, `open` fails with
+`FRONT_PORT_BUSY: 127.0.0.1:4318 is held by another listener; use --direct` and
+does not fall back silently. `open --direct` keeps the per-instance port and
+prints that worker's own URL.
+
+One origin cannot isolate scripts that run on it, so writes are bound to a
+per-instance capability rather than to the page's origin or the key in its path.
+Each worker mints a 256-bit capability kept only in its private 0600 open record.
+`open` (managed or direct) and the foreground `review`/`review compare` commands
+print it in the `#cap=` fragment, which browsers never send to a server. That
+printed link goes only to the terminal of the command that started the instance.
+Output meant for a log does not carry it: the install smoke (`bun run smoke`, whose output CI publishes) prints the same
+URL as `#cap=<redacted>` and fails if any capability value reaches its stdout. The page
+moves it into memory and that tab's `sessionStorage`, then removes the fragment
+from the address bar. Every mutation sends it as `X-Review-Capability`; the front
+checks it before forwarding and the worker compares it again in constant time
+before its existing same-origin check. No endpoint returns it, so a page opened
+for one instance cannot submit to another. A copied view link (without the
+fragment) opens read-only and says *Read-only view: reopen with rig-review open to
+edit*; run `open` again for a writable link.
+
+## Control the current inspection page
+
+Opt in once when opening a fixed package, then keep that page open:
+
+```sh
+rig-review open /absolute/output --reference /absolute/original.mp4 --control
+rig-review control /absolute/output --reference /absolute/original.mp4
+```
+
+The second command reads the connected page's actual inspection state and its
+`pageId`/`revision`; it does not open a browser or start another worker. A page
+learns from `GET /api/access` (`control: true|false`) whether its instance serves
+control; an instance opened without `--control` is never asked for
+`/api/control/config`. To change
+that page, use the observed values and a closed inspection command:
+
+```sh
+rig-review control /absolute/output --reference /absolute/original.mp4 --page '<pageId>' --expected-revision 0 --request-id theme-1 --command '{"type":"theme","value":"light"}'
+```
+
+Use the same reference/compare/animation inputs as the controlled `open`. Multiple
+pages require an explicit `--page`. The URL and source binding stay unchanged;
+existing ordinary servers do not become controllable. Starting the opt-in worker
+is a one-time handoff, not a new link for each parameter change.
+
+Commands cover appearance, automatic layout, synchronized or independent pane
+cameras, playback, single animation, time and actual inspection layers. Camera
+pan is measured in viewport CSS pixels (right/down positive). New inspections
+start with camera sync on: zoom relative to fit and pan normalized by each pane's
+viewport move all visible measurable reference/rig panes together. Turn sync off
+with `{"type":"camera-sync","value":false}` to inspect each pane independently;
+turning it off preserves current views. Turning it on aligns the visible panes
+to the last active pane. Camera/fit targets are `rig|reference` in single review
+and `a|b|reference` in compare. For legacy clients, compare `target:"rig"` explicitly
+moves both A/B even when sync is off; its CSS readback aliases A. Comparison retains its
+fixed animation and actual video-master seek path. A single-video time request
+uses the actual decoded timestamp for both reference and rig; the applied
+acknowledgement reports that time, which may differ from the requested seconds.
+Unsupported features, stale
+page/source/revision, unsubmitted feedback drafts and out-of-range values refuse
+by name. No command changes a package/reference, authors motion, or submits or
+approves feedback. Local controls and remote readback use the same inspection
+state. A live view-link/history change supersedes pending remote work, and
+commands refuse while that view is being restored.
+
+Remote inspection readback also includes versioned numeric `view` coordinates
+when the page can measure them: rig/world center and zoom, reference/image center
+and zoom, each panel's current CSS viewport size and visible rectangle. World
+coordinates use Y up; reference image coordinates use Y down. Compare reports
+actual A and B rectangles separately; unavailable measurements are null. The
+canonical view also reports `cameraSync` and `activeCamera`. These
+are the same current cameras used by the local controls, rather than a second
+simulated view. Camera commands still use the documented viewport CSS pan.
+
+The CLI waits up to10 seconds for the page's actual acknowledgment. `queued` or
+`dispatched` is not success; non-applied commands exit2 and may carry
+`timedOut:true`. Reuse the same `--request-id` and original request to obtain its
+receipt without applying it twice. `--wait-ms 0` returns the queued receipt;
+`--wait-ms` is bounded to30000. A timeout does not mean an already delivered action
+was rolled back. Tokens stay in private tool state, not URLs or command output.
+
+## Keep and share an inspection
+
+The view link stores the current numeric inspection in a bounded, versioned
+`#review=` fragment. It includes the exact loaded source/model binding, selected
+animation/time and reference selection, appearance/layers, camera sync and the
+active pane, and each canonical camera center with visible bounds. Reloading a matching link restores a paused view;
+it does not restart an idle loop or submit a review. Coordinates adapt to the
+current viewport instead of replaying another window's CSS pan offsets.
+Historical links without a sync mode restore with sync off to preserve their
+saved views; fresh inspections start with sync on. The page keeps the current
+fragment in the address bar as you inspect, so copying the address copies the
+view; there is no separate copy button. Legacy modeling/motion
+workspace selections are accepted without restoring a top-level workspace switch. A link
+for a different source binding is refused.
+
+Ordinary form inputs, selected panels, view state and unsent feedback/checkpoint
+choices are kept in browser local storage for the same source. The draft scope
+includes the source hash (`single:<id>:<sourceHash>`; compare uses both sides'
+id and hash), so two revisions of one package keep separate drafts. Opening a page
+deletes no draft; saving evicts the least-recently-written drafts beyond 32, but
+never one written within the last 24 hours. Browser
+Settings (below) remain, while a source-bound appearance override does not
+carry over. URL view state takes precedence over the locally saved view. Each
+Inspector section's own scroll position is part of this source-bound draft.
+
+Local recovery compares the original submitted server-session fingerprint,
+including its update time. It cannot replace a newer server review: conflicting
+or corrupt saved data remains available to download, with an explicit warning;
+recovering a conflicting draft requires choosing a pending review. Storage
+errors never count as a successful save. Nothing is written to the server or
+input package merely by restoring a page. Browser storage is convenient local
+recovery, not a durable backup; submit the review (and retrieve it with
+`rig-review feedback`) when it must be kept.
+Control capabilities are excluded from links and browser persistence.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/review",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "Local human rig inspection and structured feedback export",
   "license": "MIT",
@@ -8,6 +8,7 @@
     "review": "bun src/cli.ts",
     "check": "bun src/cli.ts check",
     "demo": "bun src/cli.ts examples/demo/review.json",
+    "check:readme": "bun scripts/check-readme.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "build": "bun src/build.ts",
@@ -35,6 +36,8 @@
     "web",
     "examples/demo",
     "docs/REVIEW_PACKAGE.md",
+    "docs/WORKFLOWS.md",
+    "docs/PANELS.md",
     "docs/DESIGN.md",
     "docs/ANIMATION_INSPECTION.md",
     "docs/LIVE_FIXTURE.md",

package/src/compare-session.ts

@@ -1,3 +1,4 @@
+import {sharedTurnDials} from './turn-pad.ts';
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -17,7 +18,8 @@ export function parseCompareSession(input:unknown,p:ComparePackage,strict=true):
   if(value.corrections!==undefined)throw new Error('compare session.corrections: motion authoring proposals are not accepted');
   if(!Array.isArray(value.feedback)||value.feedback.length>1000)throw new Error('compare session.feedback: expected array <= 1000');
   const feedbackWarnings:FeedbackWarning[]=[];
-  const feedback:CompareFeedback[]=value.feedback.map((item:unknown)=>{const side=choice(object(item,'feedback').side,['a','b'] as const,'feedback.side'),parsed=parseFeedback(item,strict);if(strict)return {...validatePackageFeedback(parsed,p[side],p.response.animation),side};const read=readPackageFeedback(parsed,p[side],p.response.animation);if(read.warning)feedbackWarnings.push(read.warning);return {...read.feedback,side};});
+  const turnDials=sharedTurnDials(p.a.feedbackCatalog.turnDials??[],p.b.feedbackCatalog.turnDials??[]);
+  const feedback:CompareFeedback[]=value.feedback.map((item:unknown)=>{const side=choice(object(item,'feedback').side,['a','b'] as const,'feedback.side'),parsed=parseFeedback(item,strict);if(strict)return {...validatePackageFeedback(parsed,p[side],p.response.animation,turnDials),side};const read=readPackageFeedback(parsed,p[side],p.response.animation,turnDials);if(read.warning)feedbackWarnings.push(read.warning);return {...read.feedback,side};});
   if(new Set(feedback.map(f=>f.id)).size!==feedback.length)throw new Error('compare session.feedback: duplicate ids');
   return {...fresh,status:choice(value.status,['pending','approved','changes-requested'] as const,'compare session.status'),feedback,feedbackWarnings,updatedAt:new Date().toISOString()};
 }

package/src/feedback-validation.ts

@@ -1,3 +1,4 @@
+import type {TurnDial} from './turn-pad.ts';
 import { lastFrame, timeAtFrame, type FrameClock } from './frame-clock.ts';
 
 /** Null names mean unavailable metadata; an empty list means known empty. */
@@ -5,6 +6,7 @@ export interface FeedbackCatalog {
   rig:string;bones:string[]|null;slots:string[]|null;
   animations:{name:string;duration:number}[]|null;
   clock:FrameClock|null;clockAnimation:string|null;
+  turnDials?:TurnDial[];
 }
 export type FeedbackTargetKind='bone'|'slot'|'rig';
 export interface FeedbackSelection {frameStart:number;frameEnd:number;target:{kind:FeedbackTargetKind;name:string};animation:string|null}

package/src/manifest.ts

@@ -1,3 +1,4 @@
+import {discoverTurnDials} from './turn-pad.ts';
 import { createHash } from 'node:crypto';
 import { toolVersions } from './versions.ts';
 import type { FeedbackCatalog } from './feedback-validation.ts';
@@ -114,7 +115,7 @@ export async function loadReview(input: string, options: { handoff?: HandoffFlag
   // #192: the root is `check/` whether the folder or its review.json was opened, so the build root is kept either way.
   const buildRoot=basename(root)==='check'&&await isBuildRoot(dirname(root))?dirname(root):undefined;
   const reviewedSource:ReviewedSource={packageRevision:manifest.revision,...await toolVersions(),rig:rigPath?{path:rigPath,sha256:fileHashes.get(rigPath)!}:null,motion:motionPath?{path:motionPath,sha256:fileHashes.get(motionPath)!}:null,...(handoff?{handoff:handoff.record}:{})};
-  const feedbackCatalog:FeedbackCatalog={rig:manifest.id,bones:modelNames(modelMetadata,'bones'),slots:modelNames(modelMetadata,'slots'),animations:modelAnimations(modelMetadata),clock:report?.clock??null,clockAnimation:report?.animation??null};
+  const feedbackCatalog:FeedbackCatalog={rig:manifest.id,bones:modelNames(modelMetadata,'bones'),slots:modelNames(modelMetadata,'slots'),animations:modelAnimations(modelMetadata),clock:report?.clock??null,clockAnimation:report?.animation??null,...(discoverTurnDials(modelMetadata).length?{turnDials:discoverTurnDials(modelMetadata)}:{})};
   return {root,manifestPath,manifest,sourceHash:hash.digest('hex'),reviewedSource,files,report,feedbackCatalog,handoff,handoffReason,...(handoff?.flags?{handoffInputs:handoff.flags}:{}),...(buildRoot?{buildRoot}:{})};
 }
 

package/src/producer.ts

@@ -1,5 +1,5 @@
 /**
- * The installed producer (`@rig-c/parts`' `rig-parts`) and the compiler it gates with (`rig-c`'s `rigc`), resolved the
+ * The installed producer (`@rig-c/parts`' `rig-parts`) and the compiler it gates with (`@rig-c/core`'s `rigc`, or legacy `rig-c`), resolved the
  * way `rigc review` resolves `rig-review`: the package's own `package.json` under the nearest `node_modules` walking
  * up from each start directory, its `bin` entry read from that manifest. No PATH lookup, no install, no prompt.
  * Review builds nothing itself: it runs these binaries as child processes with arguments it composes from a typed
@@ -10,7 +10,8 @@ import { dirname, join, resolve } from 'node:path';
 
 export const PRODUCER_PACKAGE = '@rig-c/parts';
 export const PRODUCER_BIN = 'rig-parts';
-export const COMPILER_PACKAGE = 'rig-c';
+export const COMPILER_PACKAGE = '@rig-c/core';
+const LEGACY_COMPILER_PACKAGE = 'rig-c';
 export const COMPILER_BIN = 'rigc';
 /** The first `@rig-c/parts` release with `rig-parts remesh` (its CHANGELOG: 1.40.0, "remesh: re-fit one part of a gated rig"). */
 export const REMESH_SINCE = '1.40.0';
@@ -39,6 +40,11 @@ export function findPackage(name: string, starts: readonly string[], exists: (pa
   return null;
 }
 
+/** Prefer the canonical package across the search roots; use the legacy name only when it is absent. */
+function findCompiler(starts: readonly string[], exists: (path: string) => boolean): string | null {
+  return findPackage(COMPILER_PACKAGE, starts, exists) ?? findPackage(LEGACY_COMPILER_PACKAGE, starts, exists);
+}
+
 /** `X.Y.Z` → [X, Y, Z]; anything else is null (a pre-release tag is not compared, it is refused as unread). */
 export function parseVersion(text: unknown): [number, number, number] | null {
   const match = typeof text === 'string' ? /^(\d+)\.(\d+)\.(\d+)$/.exec(text.trim()) : null;
@@ -72,7 +78,7 @@ export function resolveProducer(starts: readonly string[], exists: (path: string
   const producer = readTool(manifest, PRODUCER_BIN);
   if ('error' in producer) return { ok: false, error: `${MODELING_PRODUCER_NOT_INSTALLED} (${producer.error})` };
   if (!versionAtLeast(producer.version, REMESH_SINCE)) return { ok: false, error: modelingProducerTooOld(producer.version || 'unknown', REMESH_SINCE) };
-  const compilerManifest = findPackage(COMPILER_PACKAGE, [producer.root], exists);
+  const compilerManifest = findCompiler([producer.root], exists);
   if (!compilerManifest) return { ok: false, error: MODELING_COMPILER_NOT_INSTALLED };
   const compiler = readTool(compilerManifest, COMPILER_BIN);
   if ('error' in compiler) return { ok: false, error: `${MODELING_COMPILER_NOT_INSTALLED} (${compiler.error})` };
@@ -129,7 +135,7 @@ export const readingsCompilerTooOld = (found: string, required: string) => `READ
 export function resolveCompiler(starts: readonly string[], since: string, exists: (path: string) => boolean = existsSync): { ok: true; compiler: InstalledTool } | { ok: false; error: string } {
   const pair = resolveProducer(starts, exists);
   let compiler: InstalledTool | { error: string } | null = pair.ok ? pair.compiler : null;
-  if (!compiler) { const manifest = findPackage(COMPILER_PACKAGE, starts, exists); compiler = manifest ? readTool(manifest, COMPILER_BIN) : null; }
+  if (!compiler) { const manifest = findCompiler(starts, exists); compiler = manifest ? readTool(manifest, COMPILER_BIN) : null; }
   if (!compiler) return { ok: false, error: READINGS_COMPILER_NOT_INSTALLED };
   if ('error' in compiler) return { ok: false, error: `${READINGS_COMPILER_NOT_INSTALLED} (${compiler.error})` };
   if (!versionAtLeast(compiler.version, since)) return { ok: false, error: readingsCompilerTooOld(compiler.version || 'unknown', since) };
@@ -150,7 +156,7 @@ export function resolvePose(starts: readonly string[], exists: (path: string) =>
   if (!manifest) return { ok: false, error: RETARGET_PRODUCER_NOT_INSTALLED };
   const producer = readTool(manifest, POSE_BIN);
   if ('error' in producer) return { ok: false, error: `${RETARGET_PRODUCER_NOT_INSTALLED} (${producer.error})` };
-  const compilerManifest = findPackage(COMPILER_PACKAGE, [producer.root], exists);
+  const compilerManifest = findCompiler([producer.root], exists);
   if (!compilerManifest) return { ok: false, error: RETARGET_COMPILER_NOT_INSTALLED };
   const compiler = readTool(compilerManifest, COMPILER_BIN);
   if ('error' in compiler) return { ok: false, error: `${RETARGET_COMPILER_NOT_INSTALLED} (${compiler.error})` };

package/src/session.ts

@@ -1,3 +1,4 @@
+import {TurnState,type TurnDial} from './turn-pad.ts';
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -24,7 +25,7 @@ export function parseFeedback(item:unknown,strict=true):Feedback {
 export interface FeedbackWarning {id:string;error:string}
 
 /** Derive the annotated interval, retaining inspection context as separate data. */
-export function validatePackageFeedback(feedback:Feedback,p:ReviewPackage,animation?:string):Feedback {
+export function validatePackageFeedback(feedback:Feedback,p:ReviewPackage,animation?:string,turnDials:readonly TurnDial[]=p.feedbackCatalog.turnDials??[]):Feedback {
   const context=feedback.context===undefined?{}:object(feedback.context,'feedback.context');
   const interval={frameStart:feedback.frameStart,frameEnd:feedback.frameEnd,inclusive:true};
   if(context.interval!==undefined&&!isDeepStrictEqual(context.interval,interval))throw new Error('feedback.context.interval: must match chosen inclusive frameStart/frameEnd');
@@ -40,12 +41,13 @@ export function validatePackageFeedback(feedback:Feedback,p:ReviewPackage,animat
   if(context.requirements!==undefined)parseRequirementsContext(context.requirements,text=>createHash('sha256').update(text).digest('hex'));
   // The exported environment schedule (#112): absent or null stays valid; a present record carries its bytes and their sha256, recomputed here.
   if(context.environmentSchedule!==undefined)parseScheduleContext(context.environmentSchedule,text=>createHash('sha256').update(text).digest('hex'));
+  if(context.turn!==undefined){if(!turnDials.length)throw new Error('TURN_UNAVAILABLE: this inspected model has no supported turn dials');new TurnState(turnDials).validate(context.turn);}
   const selected=animation??(typeof context.animation==='string'?context.animation:null);
   validateFeedbackSelection(p.feedbackCatalog,{frameStart:feedback.frameStart,frameEnd:feedback.frameEnd,target:feedback.target,animation:selected});
   return {...feedback,context:{...context,...(animation===undefined?{}:{animation}),interval} as Json};
 }
-export function readPackageFeedback(feedback:Feedback,p:ReviewPackage,animation?:string):{feedback:Feedback;warning?:FeedbackWarning} {
-  try{return {feedback:validatePackageFeedback(feedback,p,animation)};}catch(e){
+export function readPackageFeedback(feedback:Feedback,p:ReviewPackage,animation?:string,turnDials?:readonly TurnDial[]):{feedback:Feedback;warning?:FeedbackWarning} {
+  try{return {feedback:validatePackageFeedback(feedback,p,animation,turnDials)};}catch(e){
     // Old submitted evidence remains readable. Only add a missing derived
     // interval; contradictory supplied evidence is preserved with its warning.
     const context=feedback.context;const normalized=context===undefined?{interval:{frameStart:feedback.frameStart,frameEnd:feedback.frameEnd,inclusive:true}}:context&&typeof context==='object'&&!Array.isArray(context)&&!('interval' in context)?{...context,interval:{frameStart:feedback.frameStart,frameEnd:feedback.frameEnd,inclusive:true}}:context;