@rig-c/core 2.58.1 → 2.60.0

package/README.md

@@ -603,7 +603,7 @@ commands take it and what its default is.
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](docs/AUTHORING.md)) |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box — a reading, not a gate; the exit status never moves. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
@@ -614,6 +614,7 @@ commands take it and what its default is.
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
 | `guide <RULE>` / `guide §<n>[.<m>[.<k>]] [--all]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal, `ingest` finding and coded compile error ends with ` (see rigc guide <RULE>)`; only legacy uncoded library errors point at `§5.1` — or a section's heading, own prose and subsection index, read from the installed `docs/AUTHORING.md` when it runs. `--all` includes the subsection bodies; a leaf prints its full text either way. Sizes describe full ledger spans. `--all` with a rule is refused, exit 2; an unknown name is refused with the nearest real ones, exit 1 |
 | `skills install [--dir …] [--copy]` | links every agent skill the package ships into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look. A second run has nothing to do; an entry already there that is not this command's is refused by name and nothing is written |
+| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package, with every argument untouched and its exit code returned: `rigc review open <dir>` prints a loopback URL to give a person, `check <dir>` validates the folder it would serve, `feedback <dir>` prints what they left, and `rigc review --help` is review's own usage. rigc does not depend on it: without it the command prints `rigc review: @rig-c/review is not installed — npm i -D @rig-c/review` and exits 2 |
 
 `diff`, `bonedist`, `check` and `bench` measure against something you were given; the
 first three work on any reference you have, and `bench` is a repository workflow that needs a clone

package/docs/AUTHORING.md

@@ -141,6 +141,11 @@ bun cli.ts inspect --candidate path/to/spine --show art,bones,names --dim --out
 # them, ask a human — the one loop step this toolchain cannot run for you:
 bun cli.ts vote --candidate path/to/spine-a --candidate path/to/spine-b   # -> ballot.html
 bun cli.ts vote --record vote-<id>.json                                   # -> votes.jsonl
+
+# …and when the build is for a person to look at rather than for you to choose
+# between, hand it over: with @rig-c/review installed beside rigc, give the person
+# the loopback URL this prints (rigc review --help is review's own usage):
+bun cli.ts review open path/to/spine
 ```
 
 `build` compiles, runs the named assertions — through a `@esotericsoftware/spine-core`
@@ -255,6 +260,7 @@ What the flags mean:
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
 | `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index, with their world box and setup-pose area. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
 | `--pass-through` | `render` only: `<cloth>:<leg>[,<cloth>:<leg>…]` — also read where each cloth slot **passes through** its leg slot, and write a `pass-through.json` into each frame directory: the frames where the cloth draws over the leg and its drawn side lies inside the leg's drawn outline by 2 steps or more, each with the depth and the world box. One printed line per pair, and one per frame that passes through. The first name must draw over the second for a frame to be read — the declared order, never both. A reading, not a gate. Every other file is byte for byte what the render writes without it. An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name, and so is `--slot`/`--hide` beside it — **§8.5** |
+| `--seam` | `render` only: `<slot>:<slot>[,<slot>:<slot>…]` — also read, for each pair, where the two drawings **stop meeting**, and write a `seam.json` into each frame directory: per pair, the frames with a **gap** (background inside the joint, where the two covered together at the setup pose) and the frames with a **ghost** (the overlap band of one showing where, from its partner's point of view, nothing was drawn), each with its cell count, area and world box, and as runs of frames with their times. One printed line per pair; a pair whose drawings share no cell at the setup pose is a **SKIP**. A reading, not a gate: the exit status never moves. Every other file is byte for byte what the render writes without it. An unknown slot, a slot with itself, a slot that draws on no frame, a malformed list and a pair named twice in either order are refused by name, and so is `--slot`/`--hide` beside it — **§8.8** |
 | `--angle-range` | `render` only: `<bone>:<relative-to>[,<bone>:<relative-to>…]` — also read, for each pair, the range of the first bone's world direction against the second's over each set's frames, and print one line per pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. A reading, not a gate: nothing is written, and every file is the bytes the render writes without it. An unknown bone (with the bones there are), a bone against itself, a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame — **§8.7** |
 | `--viewport`, `--viewport-from` | `render`: give the box every frame is drawn over instead of fitting one — `--viewport <x,y,w,h>`, a world box, y up, `x,y` its bottom-left corner, at the pixel size `--max` gives; or `--viewport-from <frames.json \| dir>`, an earlier render's grid exactly (its box, scale and pixel size), so two candidates land on one pixel grid. A slot that reaches past the box is named by set and frame, and `frames.json` records the box was given under `pinned`. The two together are refused, and so is `--max` beside `--viewport-from` — **§8.6**. On `check` and `inspect`, `--viewport` pins the box those commands draw over instead |
 | `--environment` | `render` only: the wind and gravity the rig's physics constraints answer, in time — a schedule file `{ "spec": "rigc-environment/1", "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, …] }`, x right and **y down**, each step holding from its `t` until the next. Both posers set each change before the step that poses the first frame at or after its `t`, and draw the same frames, `geometry.json` and `frames.json` (`RE01`). `frames.json` and `geometry.json` record it, and the framing reads it. A malformed file, a half no physics constraint answers, two steps on one frame and a step after every set's last frame are refused by name, exit 2, nothing written; `check` refuses a frame set drawn under one as a reference. Without it every file is the bytes it always was. An inspection of the response the rig states, not a scene — **§8.4** |
@@ -1130,6 +1136,7 @@ bun cli.ts render   --candidate path/to/spine --slot <name,…> | --hide <name,
 bun cli.ts render   --candidate path/to/spine --geometry   # + geometry.json per set: the numbers the frames were drawn from
 bun cli.ts render   --candidate path/to/spine --folds      # + folds.json per set: which mesh triangles turn over, and when
 bun cli.ts render   --candidate path/to/spine --pass-through skirt:leg   # + pass-through.json: where a cloth goes through a leg
+bun cli.ts render   --candidate path/to/spine --seam thigh:shin   # + seam.json: where two slots that meet open a gap or show a ghost
 bun cli.ts render   --candidate path/to/spine --angle-range tail:hip   # how far a bone turns against another, per animation
 bun cli.ts render   --candidate path/to/spine --viewport-from render/   # an earlier render's grid: two builds, one pixel grid
 bun cli.ts preview  --candidate path/to/spine [--candidate path/to/another …] [--animation …] [--out preview.html]
@@ -4518,6 +4525,17 @@ rest; a frame parent scaled unevenly, sheared or reflected, or such a bone
 between two links; a link below a bone a later stop generates; a `from` bone in
 the angles' path.
 
+On the first link that bound is |rest| + `outward`, where rest is the angle
+between the direction the link hangs in and the aim from its root at
+`<chain>_touch`, so where the point sits decides it as much as `outward` does.
+The refusal names the link, its root's world position and hang, the point's world
+position, rest, the end and the sum, and says what to move: `<chain>_touch` to
+within 180° − `outward` of the link's hang direction — below the root, for a link
+that hangs straight down and `outward` up to 90° — or `outward` down to
+180° − |rest|. A leg that rises from behind the cloth, as on a prone figure,
+runs its local +x up the screen, so `at` at its far end lands above the chain's
+root; put it at the knee, below the root (`LG34`).
+
 The stop decides nothing about *when* — it is what the object can do. Read it
 with `render --pass-through <cloth>:<leg>` (§8.5) on the motion that swung
 through before.
@@ -7352,7 +7370,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_STOP_LINK_UNDRIVEN"></a>`CE_STOP_LINK_UNDRIVEN` | “&lt;stop.who&gt;: links[&lt;k&gt;] "&lt;link&gt;" is written by no constraint of this rig spec — a stop holds a link something swings (a physics, ik, transform or path constraint in "constraints"), and its copy and clamp run right after that. A physics constraint in the motion spec's table is emitted after every rig constraint, past the clamp; declare it here” | Declare the swinging physics, ik, transform or path constraint in the rig spec's constraints before its stop clamp. |
 | <a id="CE_STOP_LINK_PARENT_CHAIN"></a>`CE_STOP_LINK_PARENT_CHAIN` | “&lt;stop.who&gt;: links[&lt;k&gt;] "&lt;links[k]&gt;" does not hang below "&lt;names.drawn[k - 1]&gt;", the drawn link of links[&lt;k - 1&gt;] — a chain's next link hangs from the drawn link above it, so the clamp that holds that one carries this one; parent it there” | Parent each lower link under the preceding generated drawn link. |
 | <a id="CE_STOP_AGAINST_MOVES_WITH_STOP"></a>`CE_STOP_AGAINST_MOVES_WITH_STOP` | “&lt;stop.who&gt;: "against" "&lt;stop.against&gt;" hangs below "&lt;under&gt;", which the stop moves — the point would swing with the chain it holds off; name the leg” | Name an against bone outside the subtree moved by the stop. |
-| <a id="CE_STOP_LOCAL_BOUND_RANGE"></a>`CE_STOP_LOCAL_BOUND_RANGE` | “&lt;stop.who&gt;: "&lt;field&gt;&lt;end&gt;" &lt;range[end]&gt; puts &lt;what&gt;'s bound at &lt;value&gt;°, past ±&lt;BOUND&gt;° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds”<br>Here the values named in the message include: “inward”, “outward”. | Adjust the printed limits so the local clamp bounds stay within its supported angular range. |
+| <a id="CE_STOP_LOCAL_BOUND_RANGE"></a>`CE_STOP_LOCAL_BOUND_RANGE` | “&lt;stop.who&gt;: "&lt;field&gt;&lt;end&gt;" &lt;range[end]&gt; puts &lt;what&gt;'s bound at &lt;value&gt;°, past ±&lt;BOUND&gt;° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds”<br>On the first link it goes on: “. "&lt;stop.links[0]&gt;" hangs at &lt;at.hang&gt;° from its root at [&lt;at.root&gt;], and "&lt;stop.names.point&gt;" ("at" [&lt;stop.at&gt;] on "&lt;stop.against&gt;") sits at [&lt;at.point&gt;] — Spine world, y up, at the setup pose — so the aim from that root to the point lies &lt;off&gt;° off the hang (rest &lt;rest&gt;°): \|rest\| &lt;off&gt;° + "&lt;end&gt;" &lt;e&gt;° is &lt;sum&gt;°”, then one of “, above &lt;BOUND&gt;°. Move "&lt;stop.names.point&gt;" to within &lt;BOUND − e&gt;° (&lt;BOUND&gt;° − "&lt;end&gt;") of the direction "&lt;stop.links[0]&gt;" hangs in from its root, &lt;at.hang&gt;°, or state "&lt;end&gt;" at most &lt;BOUND − off&gt;°”, “, above &lt;BOUND&gt;°, and no point lowers it: \|rest\| is above 0° for every point a stop accepts. State "&lt;end&gt;" below &lt;BOUND&gt;°”, “, below -&lt;BOUND&gt;°. State "&lt;end&gt;" at least &lt;−BOUND − off&gt;°”<br>Here the values named in the message include: “inward”, “outward”. | On the first link the bound is \|rest\| + the end, where rest is the angle from the link's hang to the aim at `<chain>_touch`, both read from the link's root: move `<chain>_touch` (its `at` on `against`) to within 180° − `outward` of the direction the link hangs in from its root — on a link hanging straight down with `outward` at most 90°, any point below the root — or lower `outward` to at most 180° − \|rest\|. A leg that rises from behind the cloth, as on a prone figure, puts a point at its far end above the root; put it at the knee. On a lower link, bring `lower`'s ends within ±180° of the link's own rest bend. |
 | <a id="CE_STOP_DEPENDENCY_ORDER"></a>`CE_STOP_DEPENDENCY_ORDER` | “&lt;who&gt;: "&lt;tip&gt;" hangs below "&lt;name&gt;", which a later stop generates — declare that stop first, so its angles are known when this one is read”<br>Also: “&lt;value&gt;: stop "&lt;value&gt;"” | Declare the stop generating the parent before the stop depending on it. |
 | <a id="CE_STOP_ANCESTOR_MANIFEST_POSITION"></a>`CE_STOP_ANCESTOR_MANIFEST_POSITION` | “&lt;who&gt;: "&lt;name&gt;" takes its place from the manifest ("from"), and a stop's angles are read off the setup pose this rig spec states — state its x, y and rotation”<br>Also: “&lt;value&gt;: stop "&lt;value&gt;"” | State x, y and rotation for the named setup-pose ancestor instead of from. |
 | <a id="CE_STOP_FRAME_PARENT_TRANSFORM"></a>`CE_STOP_FRAME_PARENT_TRANSFORM` | “&lt;who&gt;: "&lt;parent&gt;", where the frame hangs, is scaled unevenly, sheared or reflected at the setup pose — the frame's angles add to its parent's only through a rotation and an even scale, and inward is a turn's sense”<br>Also: “&lt;value&gt;: stop "&lt;value&gt;"” | Use a frame parent with rotation and even positive scale, without shear or reflection. |
@@ -8696,6 +8714,131 @@ one scaled to nothing — named with the frame.
 **A reading, not a gate.** Whether a range is too wide is yours; §4.6 says which
 values move it.
 
+### 8.8 Where two slots stop meeting — `render --seam`
+
+A cut rig can tear in motion: two pieces painted to overlap at a joint pull apart
+and the background shows between them, or one swings clear of the piece it was
+tucked under and the overlap it carries shows where nothing was. Both pass every
+assertion and every check, and either can be intended — so `--seam` names the
+frames and decides nothing. On the selftest's probe (`pass_through_probe`,
+`fixtures/public.ts`: a skirt whose hip swings 30° and back over a leg that hangs
+inside it, and a second copy of the leg on the same bone):
+
+```bash
+bun cli.ts render --candidate path/to/spine --animation swing --seam skirt:leg,leg_front:leg [--skin …] [--fps 12]
+# rigc render
+#   ..    swing            25 frame(s), 2.000s + contact.png + seam.json (1 of 2 pair(s) open) -> …/swing
+#   ..    seam     "swing": seam "skirt" | "leg" opens on 23 of 25 frame(s) read [1-23] at 12 fps, max 1606 px — gap on 13 frame(s) [6-18], worst frame 12 (t=1.0000s): 616 px (616.00 units² at 1.0000 units a px) in world box x [-7.00, 19.00] y [105.99, 196.00] (26.00 × 90.00); ghost on 23 frame(s) [1-23], worst frame 12 (t=1.0000s): 1606 px (1606.00 units² at 1.0000 units a px) in world box x [-27.00, 41.00] y [104.99, 198.00] (68.00 × 93.00)
+#   ..    seam     "swing": seam "leg_front" | "leg" stays closed on all 25 frame(s) read at 12 fps — no gap, no ghost
+```
+
+The skirt swinging off the leg opens background between the leg's right edge and
+the skirt's swung side (the gap, widest at the top of the swing), and uncovers the
+top of the leg the skirt hid at rest (the ghost). The two copies of the leg move
+on one bone and never open. A pair with nothing to read says so —
+`seam "a" | "b": SKIP — the two drawings share no cell at the setup pose on any of
+the N frame(s) both draw, so there is no band to read` — and a closed pair says
+`stays closed on all N frame(s) read`; the two are never the same line.
+
+**The frame of reference.** A seam is not read in the world: a limb that swings
+moves both of its pieces from where they were at the setup pose, and that is
+motion, not a tear. It is read **from each piece's own point of view**. A world
+point of a frame is carried back into a piece's setup pose by the affine map of
+that piece's triangle holding it as the frame poses it; outside the piece's mesh,
+by the map of the triangle it is least outside of (the largest smallest
+barycentric weight, the lowest index on a tie) — exact for a region and for any
+mesh one bone moves, the nearest affine piece of a skinned one. Two pieces that
+move together carry a point back to one place, so a pair moved whole reads nothing.
+
+**Every number, and where it comes from.** Nothing here is a threshold the rig
+did not declare; each figure is the posed vertices (`--geometry`'s), the rest
+table's vertices, and the atlas alpha:
+
+- **The cell** is one texel of the coarser of the two drawings at the setup pose,
+  in world units — the step `--pass-through` steps by (§8.5) — on multiples of it
+  from the world origin. `px` counts cells: on art drawn one texel to a unit, a
+  cell is a world unit and a px is a pixel of the art.
+- **Drawn** is the renderer painting a cell's centre at **128 of 255** or more —
+  the half-opacity line `--pass-through` draws outlines at, the frame's tint
+  included, the setup pose drawn at the same tint (so a slot faded out is not a
+  tear: it is faded in both). No other alpha enters.
+- **The band** is the cells both drawings draw at the setup pose — where the two
+  were painted to overlap. It has **no width of its own**: it is the overlap the
+  art states, dilated by nothing. A frame whose band is empty is not read; a pair
+  whose band is empty on every frame both draw is a SKIP.
+- **gap** — a cell inside the convex hull of the band's cell centres, carried to
+  the frame by both pieces (the region the joint occupies now, as both place it),
+  that neither piece draws at the frame, and that at least one piece, carrying it
+  back, finds drawn by either drawing at the setup pose: the two no longer cover
+  what they covered together. The hull is the joint's own extent, which is what
+  keeps a piece's far end swinging away from reading as a tear; the rest test is
+  what keeps a band that is concave at the setup pose from reading its own notch.
+- **ghost** — a cell one piece draws at the frame and the other does not, which
+  the drawing piece, carrying it back, lands in the band, and which the other,
+  carrying it back, finds neither drawing at at the setup pose: the overlap swung
+  clear of its partner.
+
+Draw order does not enter: a cell is covered or bare whichever piece is in front.
+
+**Its reach, stated.** A piece folded right back over its partner carries the band
+across the region it vacated, so a hull that wide reads the vacated cells its
+partner's view still finds drawn. And no size is too small to print: on
+`gallery/walk`, built as its README says, `--seam thigh_f:shin_f,arm_f:hand_f`
+reads gaps of 1–2 px on 5 of the 12 frames at the knee and of 1 px on 2 at the
+wrist — the wrist's, drawn at 20 pixels a unit, is the V where the two outlines
+meet at an angle, one cell deep. Whether that is a tear is yours.
+
+**The file.** `seam.json`, `rigc-seam/1`, beside each set's frames — the contract
+a consumer reads it by. Every unit is in this table; the file's own `reading`
+block carries the definitions above in words.
+
+| Field | Type | Unit | Meaning |
+| --- | --- | --- | --- |
+| `spec` | string | — | `"rigc-seam/1"` |
+| `animation` | string or `null` | — | the set's animation; `null` for a skeleton with none (its one frame is the setup pose) |
+| `skin` | string | — | the skin asked for; **absent** when none was |
+| `fps` | number | frames per second | the rate the set was sampled at |
+| `reading` | object | — | `read`, `cell`, `drawn`, `band`, `carried`, `gap`, `ghost`, `box`, `status`: the definitions, in words |
+| `pairs[]` | array | — | one per pair, in the flag's order |
+| `pairs[].a`, `pairs[].b` | string | — | the two slots, as the flag names them |
+| `pairs[].drawn` | integer | frames | frames on which both slots draw |
+| `pairs[].banded` | integer | frames | of those, frames whose two drawings share a cell at the setup pose — the frames read |
+| `pairs[].status` | `"read"` or `"skip"` | — | `skip` when `banded` is 0: nothing measured, which is **not** a seam that held |
+| `pairs[].opens` | integer[] | frame indices | every frame with a gap or a ghost, ascending |
+| `pairs[].maxPx` | integer | px (cells) | the most cells of either kind on any frame; 0 when none opens |
+| `pairs[].gap`, `pairs[].ghost` | object | — | one per kind, each `{ frames, spans, worst }` |
+| `<kind>.frames[]` | hit[] | — | only the frames with a cell of that kind, in frame order |
+| `<kind>.spans[]` | array | — | `<kind>.frames` as runs of consecutive indices: `{ frames: [first, last], times: [first, last], maxPx }` — frame indices, seconds, px |
+| `<kind>.worst` | hit or `null` | — | the frame with the most cells, the earliest on a tie; `null` when none |
+| hit `index` | integer | frame index | the frame — `f<index>.png`, zero-padded |
+| hit `time` | number | seconds | the frame's time |
+| hit `px` | integer | px (cells) | cells of that kind on the frame |
+| hit `cell` | number | world units | a cell's side |
+| hit `area` | number | world units² | `px × cell²` |
+| hit `box` | `[minX, minY, maxX, maxY]` | world units, y up | the counted cells' whole squares, in Spine world |
+
+A downstream warning is a projection of this file and needs nothing re-measured:
+one span of one kind is `{ pair: "<a>|<b>", frames: span.frames, times:
+span.times, maxPx: span.maxPx, kind }`, and one pair over one animation is
+`opens.length` frame(s) `[opens]`, max `maxPx` px — with `status: "skip"` the case
+to say SKIP for.
+
+**Refused, nothing written:** a slot the skeleton does not have (with the slots it
+does), an entry without exactly one `:`, an empty entry or name, a slot paired with
+itself (a seam is between two drawings), a pair named twice in either order (the
+reading is symmetric, so `b:a` is `a:b` again), a slot that draws on no frame of
+the sets drawn, a slot a clip cuts (its drawing is no longer its attachment's, so
+it cannot be carried back), and `--slot`/`--hide` beside the flag, for
+`--pass-through`'s reason.
+
+**Nothing else moves.** The PNGs, `contact.png`, `frames.json` and `geometry.json`
+are byte for byte what the render writes without the flag, both posers write the
+same file, and two runs write the same bytes (the selftest's `seam` suite).
+
+**A reading, not a gate.** It never changes the exit status, whatever it finds. To
+look at a frame it names, draw that set over the box it printed:
+`render --animation <name> --viewport <x,y,w,h> --max 400`.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -11522,6 +11665,7 @@ pixel (`IN09`).
 | What does this bone move? | `--show art,mesh,weights:<bone> --dim` | the bone's weight over every region and mesh it moves, as a heat: a pixel whose centre lies in a triangle is painted the ramp's colour at the blend of its corners' weights — blue near 0, yellow at 0.5, red at 1 (the stops are in the legend) — and a weight of 0 is not painted, so the art shows where the bone does not reach. A region and an unweighted mesh are moved whole by their slot's bone. The weights are read off `skeleton.json`, the file both posers skin from; a bone that weights nothing paints nothing and the run says so on a line of its own |
 | Does this part's edge follow that bone? | `--show art,weights:<bone>,mesh --overlay-slot <part> --zoom slot:<part>` | the part's own triangles and the bone's weight over them alone, over the whole painting. Where slots stack — a neck under the face, the hair, a collar — every mesh crossing the box is drawn and the heat is the union of every slot the bone moves, so the part's edge has no pixel of its own until the others are left out. The legend's `meshes[]` gives the part's weight for the bone at every vertex, so "does the top row follow the head" is read as numbers as well as colour |
 | Is this rig's density where its motion is? | `--show art,density --dim` | each region and mesh filled by its **ratio** — its triangles per world unit² over the figure's — on one ramp, log-scaled and centred on 1×: grey is as dense as the figure, pink to magenta denser (4×, 16×), light to dark green sparser (1/4×, 1/16×), clamped past the end stops (the stops are in the legend). A part's area is its posed mesh's own, the sum of its triangles' areas at the pose drawn, not the image's box; a region is two triangles over its quad. Where parts overlap the pixel is the part drawn last, as in the art, so a part under others is read with `--overlay-slot <part>`. The figure's totals are always over every slot the pose shows — the filter picks what is drawn and listed, never what the figure is — and the legend's `density` gives each slot's attachment, kind, vertices, triangles, hull, area, triangles per area, ratio and the bones it is weighted to, in draw order. A measurement, not a verdict: no bar is drawn, and `A13_MESH_BUDGET` stays the one gate on counts |
+| Does a joint tear in this animation? | `render --seam <a>:<b> --animation <name>` (§8.8) | One line per pair: the frames where background opens inside the joint (gap) or the overlap band of one piece shows past its partner (ghost), with the worst frame's cell count and world box; `seam.json` carries every frame and its time, and the runs of frames. A pair whose drawings never overlap is a SKIP, said by name. A reading, not a verdict — the exit status never moves |
 | Does anything fold in this animation? | `render --folds --animation <name>` (§8.3), then `inspect --show art,folds,mesh --animation <name> --at <the worst frame's time> --zoom folds` | `render --folds` prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count, which triangles, their world box at that frame and their setup-pose area. The view fills those triangles at the pose drawn — every pixel whose centre a folded triangle holds — in the colour the legend's `folds` states, and the legend's `folds[]` names, per mesh, the folded triangles by index with the same box and area, and the setup pose's degenerate and inverted ones, which are never counted. A fold is usually a sliver a few units across, invisible in a picture of the whole mesh: `--zoom folds` frames the picture to the folded triangles' box. A thin sliver still needs pixels — raise `--max` when the fill is a line. A reading, not a verdict |
 | How is this part triangulated? | `--show art,mesh,hull --zoom slot:<slot>` | each mesh's triangle edges, and over them its hull — vertex 0 to 1 to … to `hull − 1` and back. Regions are not drawn: a region is not a mesh. The legend lists every vertex in world units and in pixels |
 | Which is drawn over which? | `--show art,slots` | each slot that shows a region or mesh numbered by its place in the draw order **at the pose drawn** (0 is drawn first), on a white box at the centre of its attachment's box — so a `drawOrder` key (§4.7) shows from the first frame `render` draws it on |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.58.1",
+  "version": "2.60.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/cli/core_commands.ts

@@ -38,6 +38,7 @@ import { FOLDS_FILE, foldLine, foldsFileOf, foldsOf, foldsText, setupFaultLine }
 import { AngleRangeError, angleRangeLine, type AngleRangeReading, angleRangesOf, type BonePair, readBonePairs } from '../anglerange.ts';
 import { outsideLine, outsideViewport, pinnedRecord, readViewportBox, viewportOfFramesFile, ViewportError } from '../viewportpin.ts';
 import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passThroughFileOf, passThroughOf, passThroughText, PassThroughError, readPassPairs } from '../passthrough.ts';
+import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
@@ -45,9 +46,10 @@ import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
+import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 
 const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> = {
@@ -561,6 +563,23 @@ function readPassThroughFlag(raw: string | undefined, facts: SkeletonFacts): Pas
   }
 }
 
+/**
+ * `--seam <a>:<b>[,…]` read against the skeleton's slots (issue #1456,
+ * `../seam.ts`), or refused as a usage error before anything is posed: a
+ * malformed list, an empty name, a slot the skeleton does not have, a slot paired
+ * with itself, a pair named twice in either order — each by its entry.
+ * `undefined` without the flag.
+ */
+function readSeamFlag(raw: string | undefined, facts: SkeletonFacts): SeamPair[] | undefined {
+  if (raw === undefined) return undefined;
+  try {
+    return readSeamPairs(raw, facts.slots.map((slot) => slot.name));
+  } catch (err) {
+    if (err instanceof SeamError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
 /**
  * `--angle-range`'s pairs, read against the skeleton's bones (issue #1414,
  * `../anglerange.ts`), or refused as a usage error before anything is posed: a
@@ -685,6 +704,21 @@ export function cmdRender(flags: Record<string, string>): void {
     }
   }
 
+  // The seam reading (issue #1456) is its own flag for --folds' reason, and refused beside a subset for --pass-through's:
+  // it reads the two slots as the whole rig draws them.
+  const seam = flags.seam;
+  if (seam !== undefined) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--seam takes no --${flag}: it reads the two slots as the whole rig draws them, which a subset of the drawn slots ` +
+            `would change. Run \`rigc render --seam\` on the whole rig for the reading, and --${flag} ${flags[flag]} ` +
+            'without --seam for the pictures — both land on the same grid',
+        );
+      }
+    }
+  }
+
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
   console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
@@ -703,6 +737,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);
   const passPairs = readPassThroughFlag(passThrough, facts);
+  const seamPairs = readSeamFlag(seam, facts);
   // The angle reading (issue #1414) reads bones, which a subset of the drawn slots does not change, so it takes --slot/--hide.
   const anglePairs = readAngleRangeFlag(flags['angle-range'], facts);
   // One object, so the framing and the frames cannot be posed under two
@@ -774,7 +809,7 @@ export function cmdRender(flags: Record<string, string>): void {
     // the export's grid is this frame set's by construction.
     // The bones ride along for --geometry and --angle-range, the whole attachments for --geometry and the two readings off them.
     const wantsBones = geometry || anglePairs !== undefined;
-    const wantsGeometry = geometry || folds || passPairs !== undefined;
+    const wantsGeometry = geometry || folds || passPairs !== undefined || seamPairs !== undefined;
     const sampling = !wantsBones && !wantsGeometry ? pose : { ...pose, ...(wantsBones ? { bones: true } : {}), ...(wantsGeometry ? { geometry: true } : {}) };
     const sampled: Map<string, Frame[]> =
       only === undefined
@@ -828,6 +863,34 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
+    // The seam reading, off the very pieces the frames are drawn from — one per set, every pair the flag names. A pair
+    // whose slot draws on no frame of any set drawn is refused, as --pass-through refuses it, rather than read as a SKIP.
+    const seamReadings = new Map<string, ReturnType<typeof seamFileOf>>();
+    if (seamPairs !== undefined) {
+      const draws = new Set<string>();
+      for (const frames of sampled.values()) for (const frame of frames) for (const piece of frame.pieces) draws.add(piece.slot);
+      for (const pair of seamPairs) {
+        for (const slot of [pair.a, pair.b]) {
+          if (!draws.has(slot)) {
+            throw new UsageError(
+              `--seam: slot ${JSON.stringify(slot)} draws on no frame of [${[...sampled.keys()].join(', ')}]${skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`} ` +
+                '— it shows no region or mesh there, so it has no drawing to read a seam of',
+            );
+          }
+        }
+      }
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        const shown = frames.map((frame) => frame.attachments ?? []);
+        const read = frames.map((frame) => ({ index: frame.index, time: frame.time, pieces: frame.pieces, attachments: frame.attachments ?? [] }));
+        try {
+          seamReadings.set(name, seamFileOf(animation, fps, skin, seamsOf(seamPairs, poser.rest(skin, shown), read, pages)));
+        } catch (err) {
+          if (err instanceof SeamError) throw new UsageError(`--seam, ${JSON.stringify(name)}: ${err.message}`);
+          throw err;
+        }
+      }
+    }
     // The angle reading, off the very bones the frames were posed with — one per set, every pair the flag names.
     const angleReadings = new Map<string, AngleRangeReading[]>();
     if (anglePairs !== undefined) {
@@ -841,9 +904,9 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings };
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings };
   });
-  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -893,6 +956,8 @@ export function cmdRender(flags: Record<string, string>): void {
     if (foldReading !== undefined) writeFileSync(join(dir, FOLDS_FILE), foldsText(foldReading));
     const passReading = passReadings.get(name);
     if (passReading !== undefined) writeFileSync(join(dir, PASS_THROUGH_FILE), passThroughText(passReading));
+    const seamReading = seamReadings.get(name);
+    if (seamReading !== undefined) writeFileSync(join(dir, SEAM_FILE), seamText(seamReading));
     const duration = frames[frames.length - 1].time;
     sets.push({
       dir: dirName,
@@ -908,7 +973,9 @@ export function cmdRender(flags: Record<string, string>): void {
     const foldNote = foldReading === undefined ? '' : ` + ${FOLDS_FILE} (${folding} of ${foldReading.meshes.length} mesh(es) fold)`;
     const passing = passReading?.pairs.filter((p) => p.frames.length > 0).length ?? 0;
     const passNote = passReading === undefined ? '' : ` + ${PASS_THROUGH_FILE} (${passing} of ${passReading.pairs.length} pair(s) pass through)`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}`;
+    const opening = seamReading?.pairs.filter((p) => p.opens.length > 0).length ?? 0;
+    const seamNote = seamReading === undefined ? '' : ` + ${SEAM_FILE} (${opening} of ${seamReading.pairs.length} pair(s) open)`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
@@ -922,6 +989,7 @@ export function cmdRender(flags: Record<string, string>): void {
       console.log(`  ..    pass     ${passSummaryLine(passReading?.animation ?? null, fps, pair)}`);
       for (const frame of pair.frames) console.log(`  ..    pass     ${passFrameLine(passReading?.animation ?? null, pair, frame)}`);
     }
+    for (const pair of seamReading?.pairs ?? []) console.log(`  ..    seam     ${seamLine(seamReading?.animation ?? null, fps, pair)}`);
     for (const reading of angleReadings.get(name) ?? []) {
       console.log(`  ..    angle    ${angleRangeLine(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, reading)}`);
     }
@@ -2103,6 +2171,72 @@ export const MODEL_AND_TEXT_GATE: BuildGate = {
   look: (outDir) => `rigc: look at it: rigc render --candidate ${outDir}`,
 };
 
+/**
+ * Where a delegated package's `package.json` resolves, or `null` (issue #1457).
+ *
+ * ⚖️ Node's `node_modules` lookup — `<dir>/node_modules/<package>` for the
+ * directory and then each of its ancestors, nearest first — from two places in
+ * this order, the first answer winning:
+ *
+ *   1. the working directory — the project `npm i -D <package>` installed it
+ *      into, which is what the refusal tells a caller to run, so a project's
+ *      own install is the one its command line reaches;
+ *   2. this package's root — where an install of rig-c sits beside it in the
+ *      same `node_modules` and the command was run from somewhere else.
+ *
+ * 🚨 Walked here rather than asked of the runtime's resolver: Bun's resolves a
+ * package it cannot find, from a directory with no `node_modules` above it, by
+ * installing it on demand into its global cache — measured, a directory with
+ * none resolved `@rig-c/review` there — so "not installed" would never be
+ * refused, and asking would reach the network. `NODE_PATH` and the global
+ * folders are not read: what the refusal tells a caller to run never puts a
+ * package there. The bin is read off the `package.json` found, not resolved.
+ */
+function resolveDelegate(name: string): string | null {
+  for (const from of [process.cwd(), PACKAGE_ROOT]) {
+    for (let dir = resolve(from); ; dir = dirname(dir)) {
+      const manifest = join(dir, 'node_modules', name, 'package.json');
+      if (existsSync(manifest)) return manifest;
+      if (dirname(dir) === dir) break;
+    }
+  }
+  return null;
+}
+
+/**
+ * A delegating command's body (`CommandDoc.delegate`, issue #1457): resolve the
+ * package's bin and run it under the Bun running this — the bin is a Bun script
+ * — with every argument untouched and stdio inherited, then exit with its code,
+ * or die by its signal the way `bin/rigc.cjs` does, so a caller reads what it
+ * would have read running the bin itself. Not installed, it is refused by name
+ * with the one command that installs it, exit 2, and nothing else is printed.
+ */
+function cmdDelegate(command: string, raw: readonly string[]): void {
+  const delegate = COMMANDS.find((c) => c.name === command)?.delegate;
+  if (delegate === undefined) throw new Error(`internal: ${command} names no delegate`);
+  const manifest = resolveDelegate(delegate.package);
+  if (manifest === null) throw new DelegateError(`${delegate.package} is not installed — npm i -D ${delegate.package}`, 2);
+  const bins = (readJsonFile(manifest) as { bin?: unknown }).bin;
+  const relativeBin = typeof bins === 'object' && bins !== null ? (bins as Record<string, unknown>)[delegate.bin] : undefined;
+  const bin = typeof relativeBin === 'string' ? join(dirname(manifest), relativeBin) : null;
+  if (bin === null || !existsSync(bin)) {
+    throw new DelegateError(
+      `${delegate.package} at ${dirname(manifest)} ${bin === null ? `declares no "${delegate.bin}" bin` : `declares the "${delegate.bin}" bin ${String(relativeBin)}, which is not there`} — npm i -D ${delegate.package}`,
+      2,
+    );
+  }
+  const ran = spawnSync(process.execPath, [bin, ...raw], { stdio: 'inherit' });
+  // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 — the declared minimum — sets `error` on every
+  // child that exits non-zero, so reading it first refused review's own exit 7 as "could not run". `error` is a
+  // launch that failed only where the child left neither a status nor a signal.
+  if (typeof ran.status === 'number') process.exit(ran.status);
+  if (ran.signal !== null) {
+    process.kill(process.pid, ran.signal);
+    return;
+  }
+  throw new DelegateError(`could not run ${bin}: ${ran.error?.message ?? 'it left no exit status and no signal'}`, 1);
+}
+
 /**
  * split — one authored mesh's pieces, proposed as one mesh each (issue #1414).
  *
@@ -2182,4 +2316,5 @@ export const CORE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   chainfit: ({ flags }) => cmdChainFit(flags),
   guide: ({ flags, positional }) => cmdGuide(flags, positional),
   skills: ({ flags, positional }) => cmdSkills(flags, positional),
+  review: ({ raw }) => cmdDelegate('review', raw),
 };

package/src/cli/shared.ts

@@ -38,7 +38,8 @@ import { checkAgainstFrames, type CheckOptions, CheckPlates, type CheckReport }
 import { compile, CompileError, droppedStateReason, headerBoundsOf, type CompileOptions } from '../compile.ts';
 import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
 import { FOLDS_FILE } from '../folds.ts';
-import { PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
+import { DRAWN_ALPHA, PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
+import { SEAM_FILE } from '../seam.ts';
 import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
@@ -955,6 +956,21 @@ export class SkillsInstallError extends Error {}
 /** `guide` asked for a rule or a section the guide does not have (issue #1397): a refusal by `GUIDE_RULE_KNOWN` or `GUIDE_SECTION_KNOWN`, whose message is the whole line. Exit 1. */
 export class GuideError extends Error {}
 
+/**
+ * A delegating command (`CommandDoc.delegate`, issue #1457) that could not hand
+ * over: the package it delegates to does not resolve, or resolves without the
+ * bin it names. Nothing ran, so the exit is `status` (2) and the message is the
+ * whole of what is printed after `rigc <command>: `.
+ */
+export class DelegateError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // usage / per-command help
 // ---------------------------------------------------------------------------
@@ -1023,6 +1039,13 @@ const FLAG_MEANINGS: Record<string, string> = {
     'world units, one texel of the coarser drawing to a step — each with the depth and the world box. One line per pair, and one per frame that passes through. ' +
     'The order is the declaration: the first name must draw over the second for a frame to be read. A reading, not a gate. ' +
     'An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name. Not with --slot/--hide',
+  seam:
+    `also read, for each <slot>:<slot> pair, where the two drawings stop meeting, and write ${SEAM_FILE} into each frame directory: ` +
+    'per pair, the frames with a gap — background inside the hull of the band the two drawings share at the setup pose, carried to the frame by both — ' +
+    'and the frames with a ghost — the band of one drawing showing where, from its partner\'s point of view, nothing was drawn at the setup pose — each with ' +
+    `its cell count, area and world box. Cells are one texel of the coarser drawing, drawn at ${DRAWN_ALPHA} of 255 or more. One line per pair; a pair whose ` +
+    'drawings share no cell at the setup pose is a SKIP. A reading, not a gate: the exit status never moves. An unknown slot, a slot with itself, ' +
+    'a slot that draws on no frame, a malformed list and a pair named twice in either order are refused by name. Not with --slot/--hide',
   'angle-range':
     'also read, for each <bone>:<relative-to> pair, the range of the first bone\'s world direction against the second\'s over each set\'s ' +
     'frames — its rotationX less the other\'s, followed from frame to frame so a sweep past ±180° reads as itself — and print one line per ' +
@@ -1234,6 +1257,7 @@ const FLAG_VALUES: Record<string, string> = {
   poser: 'core|spine',
   environment: '<schedule.json>',
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
+  seam: '<slot>:<slot>[,<slot>:<slot>…]',
   'angle-range': '<bone>:<relative-to>[,…]',
   'viewport-from': '<frames.json|dir>',
   reference: '<dir|skeleton.json>',
@@ -1365,6 +1389,15 @@ interface CommandDoc {
    * `diff`) can be moved to another side in one place.
    */
   spineFormat: boolean;
+  /**
+   * A command whose body is another package's bin (issue #1457): the dispatch
+   * hands it every argument after the name untouched — nothing is parsed as a
+   * flag, `--help` included, so its page is the delegate's own — and the
+   * delegate's exit code is the command's. `flags` is empty for that reason:
+   * rigc documents no flag of a program it does not own. A control that reads
+   * a command's flag table off `--help` reads it off the commands without this.
+   */
+  delegate?: { package: string; bin: string };
 }
 
 export const COMMANDS: CommandDoc[] = [
@@ -1686,10 +1719,11 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
+      'rigc render … --seam <slot>:<slot>[,…]   (the frames where two slots that meet open a gap or show a ghost)',
       'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'angle-range', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'angle-range', 'environment', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: {
@@ -1891,6 +1925,16 @@ export const COMMANDS: CommandDoc[] = [
       '"Install it into your agent").',
     ],
   },
+  {
+    name: 'review',
+    runtime: false,
+    spineFormat: false,
+    delegate: { package: '@rig-c/review', bin: 'rig-review' },
+    usage: [
+      "rigc review <dir> [...]      (@rig-c/review's rig-review, installed beside: every argument handed over untouched, its exit code returned — `rigc review open <dir>` prints a loopback URL to give a person, `rigc review --help` is rig-review's own usage)",
+    ],
+    flags: [],
+  },
 ];
 
 /** Every command's name, in the order the usage lists them — what the full entry dispatches over. */
@@ -2731,6 +2775,8 @@ export interface CommandArgs {
   flags: Record<string, string>;
   lists: Record<string, string[]>;
   positional: string[];
+  /** Every argument after the command's name, as given — what a delegating command (`CommandDoc.delegate`) hands over. */
+  raw: readonly string[];
 }
 
 /** One command's body, as an entry registers it. */
@@ -2931,13 +2977,18 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
       if (elsewhere !== undefined) throw commandNeedsRuntime(elsewhere, known, rest);
       throw new UsageError(`unknown command: ${command}`);
     }
+    // A delegating command reads nothing here: not a flag, not `--help` (issue #1457).
+    if (docs.find((doc) => doc.name === command)?.delegate !== undefined) {
+      entry.runs[command]({ flags: {}, lists: {}, positional: [], raw: rest });
+      return;
+    }
 
     const { flags, lists, positional } = parseArgs([...rest], REPEATABLE_FLAGS[command]);
     if (flags.help !== undefined) {
       console.log(commandHelp(command, docs));
       process.exit(0);
     }
-    entry.runs[command]({ flags, lists, positional });
+    entry.runs[command]({ flags, lists, positional, raw: rest });
   } catch (err) {
     refuse(err, command, USAGE, entry);
   }
@@ -3107,5 +3158,11 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     console.error(err.message);
     process.exit(1);
   }
+  // A delegate that could not be handed the run (issue #1457): one line naming the package and what to run, nothing else —
+  // the usage under it would bury the one command that fixes it.
+  if (err instanceof DelegateError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(err.status);
+  }
   throw err;
 }