@rig-c/core 2.62.0 → 2.64.0

package/README.md

@@ -606,7 +606,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/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--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 |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--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. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — 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 |
 | `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 |
@@ -617,7 +617,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. An empty argument (`""`) is handed over only where the running Bun keeps one when it starts a process — Bun 1.2.0 drops it, measured by a probe rather than by version — and is otherwise refused by name, `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`, exit 2 |
+| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package; rigc does not depend on it and never installs it. `rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]` is `rig-review open <dir> …` with those flags 1:1 and prints the loopback URL to give a person; a first argument that is one of review's own words (`open`, `check`, `feedback`, `control`, `strip`, `compare`) or starts with `-` (`--help`, `--`) is handed over untouched. stdout is review's byte for byte, stderr review's plus the launcher's own refusals, the exit code review's. Refused by name, exit 2, before the bin starts: `REVIEW_OUTPUT_MISSING <path>` (the target is not a directory); `REVIEW_NOT_INSTALLED` with two lines, `bun add -d @rig-c/review` and `bunx @rig-c/review open <dir> …` carrying the flags given — the same on a terminal and off, with nothing installed or written; `REVIEW_BUN_TOO_OLD: Bun <found>, @rig-c/review needs <required>`, the floor read off the installed package's `engines.bun`; and an empty argument (`""`) under a Bun that drops one (Bun 1.2.0, measured by a probe), `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`. docs/AUTHORING.md lists every line |
 
 `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/bin/rigc.cjs

@@ -56,7 +56,15 @@ const entry = present === null ? 'cli_core.ts' : 'cli.ts';
 const args = process.argv.slice(2);
 const result = spawnSync('bun', [path.join(root, entry), ...args], { stdio: 'inherit' });
 
-if (!result.error && result.status === 0 && args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+// ⚠️ The exit and the signal are read before `error` (issue #1488): Bun 1.2.0 —
+// the declared minimum, and what runs this file as `bun bin/rigc.cjs` — sets
+// `error` on every child that exits non-zero, so reading it first answered the
+// CLI's own refusal (exit 2) with "could not launch bun" and exit 1. `error` is
+// a launch that failed only where the child left neither a status nor a signal.
+// Node never sets `error` beside a status, so under node nothing here changes.
+const launched = typeof result.status === 'number' || result.signal !== null;
+
+if (launched && result.status === 0 && args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
   process.stderr.write(
     present === null
       ? `entry: ${entry} — ${RUNTIME} absent — the round trip and the commands that need it are not available here; see --help\n`
@@ -64,20 +72,18 @@ if (!result.error && result.status === 0 && args.length === 1 && (args[0] === '-
   );
 }
 
-if (result.error) {
-  if (result.error.code === 'ENOENT') {
-    process.stderr.write('rigc runs on Bun, which was not found on PATH — install it from https://bun.sh\n');
-  } else {
-    process.stderr.write(`rigc: could not launch bun: ${result.error.message}\n`);
-  }
-  process.exit(1);
-}
-
-if (result.signal) {
+if (typeof result.status === 'number') {
+  process.exit(result.status);
+} else if (result.signal !== null) {
   // A signal (e.g. Ctrl-C) killed the child — die the same way instead of
   // inventing an exit code, so the caller sees the same thing it would have
   // seen running bun directly.
   process.kill(process.pid, result.signal);
 } else {
-  process.exit(typeof result.status === 'number' ? result.status : 1);
+  if (result.error && result.error.code === 'ENOENT') {
+    process.stderr.write('rigc runs on Bun, which was not found on PATH — install it from https://bun.sh\n');
+  } else if (result.error) {
+    process.stderr.write(`rigc: could not launch bun: ${result.error.message}\n`);
+  }
+  process.exit(1);
 }

package/docs/AUTHORING.md

@@ -143,9 +143,9 @@ bun cli.ts vote --candidate path/to/spine-a --candidate path/to/spine-b   # -> b
 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
+# between, hand it over: give the person the loopback URL this prints on stdout
+# (`rigc review <dir>` is `rig-review open <dir>`; rigc review --help is review's own usage):
+bun cli.ts review path/to/spine [--reference reference.mp4] [--animation <name>]
 ```
 
 `build` compiles, runs the named assertions — through a `@esotericsoftware/spine-core`
@@ -261,6 +261,7 @@ What the flags mean:
 | `--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** |
+| `--overlaps` | `render` only: also read **which slot each frame drew over which**, and write an `overlaps.json` into each frame directory: per frame, every pair of slots where the slot drawn later covers pixels the earlier one drew (drawn at 128 of 255 or more, on the frames' own pixels), with the pixel count and the pixel box. One `OVERLAP` line per pair that covers anything — its frames as runs, how many of the set, and the most pixels and the frame of them — and one line counting the pairs that are layering the motion does not move. Each frame with a moving pair also gets an **outline plate**, `overlaps-f<NNNN>.png`: every slot in a moving pair as its contour in its own colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Every other file is byte for byte what the render writes without it, and `frames.json` gains each set's `overlaps` record. Refused beside `--slot`/`--hide` — **§8.9** |
 | `--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** |
@@ -325,6 +326,29 @@ the package's copy (<file> differs)`. A link to the package's own folder is not
 the way however it is spelled, so an absolute link somebody else made is kept and
 reported `already linked`.
 
+`review` is the third, and it is a launcher: its body is the `rig-review` bin of
+`@rig-c/review`, a separate package rigc does not depend on and **never installs**.
+`rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]`
+hands over `open <dir> …` with those flags 1:1; a first argument that is one of
+rig-review's own words — `open`, `check`, `feedback`, `control`, `strip`,
+`compare`, or anything starting with `-` (`--help`, `-h`, and `--`, which hands
+the rest over as it is) — is handed over untouched. Nothing else is added: no
+`--reference` is derived, because no build rigc writes records the clip it was
+retargeted from. What comes back is review's: **stdout is review's stdout byte for
+byte** (the URL line an agent gives a person), stderr is review's plus only the
+launcher's own refusals, and the exit code is review's. The launcher relies on
+review's side of that contract — the URL alone on stdout, its diagnostics on
+stderr, its own refusals in its own words — and does not restate it. Before the
+bin starts, it refuses by name, exit 2, nothing on stdout:
+
+| Line on stderr | When | What to do |
+| --- | --- | --- |
+| `rigc review: REVIEW_OUTPUT_MISSING <path>: nothing is there — …` (or `it is not a directory`) | the first argument was read as a target and is not a directory. Checked first, before the package is looked for | point it at the `--out` a green `build` wrote, or pass `--` first to hand the argument over as it is |
+| `rigc review: REVIEW_NOT_INSTALLED: @rig-c/review is not installed beside this project or beside rig-c, and rigc does not install it — …`, then `bun add -d @rig-c/review`, then `bunx @rig-c/review <what the bin would have been handed>` | the package resolves neither from the working directory up nor from rig-c's root up. The same three lines on a terminal and off one; nothing is installed, fetched or written, and `package.json` and `bun.lock` are untouched | run the first line to install it, or the second to run it once without installing (it fetches into Bun's cache — that is your choice to make, not rigc's) |
+| `rigc review: REVIEW_BUN_TOO_OLD: Bun <found>, @rig-c/review needs <required>` | the installed package's own `engines.bun` floor is above the running Bun. `<required>` is read off that manifest, not written in rigc | upgrade Bun |
+| `rigc review: REVIEW_BUN_RANGE_UNREAD: @rig-c/review declares engines.bun "<range>", and rigc reads only ">=X.Y.Z" — …` | the installed package's `engines.bun` is a range shape rigc does not read, so whether this Bun satisfies it was not guessed | run the bin yourself (`bunx rig-review …` from the project), or a rigc that reads that shape |
+| `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …` | an `""` argument under a Bun that would drop it (Bun 1.2.0), measured by a probe | give it a value, or run rigc under a Bun that keeps it |
+
 Pick the profile deliberately, and know which one you got by saying nothing. The
 default is `spine`: "is this valid Spine 4.3 that any runtime plays correctly",
 which is the question a rig authored anywhere is asking. `--profile rig-play`
@@ -1137,6 +1161,7 @@ bun cli.ts render   --candidate path/to/spine --geometry   # + geometry.json per
 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 --overlaps   # + overlaps.json and outline plates: which slot each frame drew over which
 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]
@@ -8879,6 +8904,107 @@ same file, and two runs write the same bytes (the selftest's `seam` suite).
 look at a frame it names, draw that set over the box it printed:
 `render --animation <name> --viewport <x,y,w,h> --max 400`.
 
+### 8.9 Which slot covers which — `render --overlaps`
+
+An arm the draw order puts behind the torso simply vanishes from the frames, on a
+build that passes every assertion and every check, and nothing in the frames names
+it. `--overlaps` reads it off the frames `render` draws: **who covers whom, on which
+frames, by how many pixels**. On the selftest's probe (`overlap_probe`,
+`fixtures/public.ts`: an opaque stage, a still body, and an arm drawn after the body
+slid along x across it and out the other side):
+
+```bash
+bun cli.ts render --candidate path/to/spine --animation cross --overlaps --max 160 [--skin …] [--fps 12]
+# rigc render
+#   ..    cross            25 frame(s), 2.000s + contact.png + overlaps.json (1 moving pair(s), 11 outline plate(s)) -> …/cross
+#   ..    overlap  "cross": 2 pair(s) cover on every frame by the same pixels, or with the slot in front drawn wholly on the one behind — layering the motion does not move; overlaps.json lists them
+#   ..    overlap  "cross": OVERLAP "body" under "arm": frames 7–17 (11 of 25), covered up to 135 px at frame 11
+```
+
+⭐ **The render reports what was drawn; who should be in front is the author's, and
+the draw-order key in the motion spec is the remedy** (§4.7, `drawOrder`). The same
+slide with a key that puts the arm before the body reads `OVERLAP "arm" under
+"body"` on the same frames and pixels (`OX02`). On `gallery/walk` at `--fps 20 --max
+288` the back arm reads `OVERLAP "arm_b" under "torso": frames 0–18 (19 of 19),
+covered up to 643 px at frame 15`; with `arm_b` moved after `torso` in the rig's
+slots, that line is gone and `OVERLAP "torso" under "arm_b"` reads the same 643 px at
+frame 15.
+
+**Which frames are read.** Every frame of every set drawn, in **that frame's own
+draw order** — the order its pieces are drawn in, so a draw-order key is honoured.
+
+**What covering means.** Every piece is rasterised in draw order on the render's own
+viewport, so a pixel here is a pixel of `f<NNNN>.png`. A pixel is drawn by a slot
+when the renderer paints it at half opacity or more (128 of 255) — the line every
+other reading draws outlines at. Each pixel keeps the slots that have drawn it so
+far; a slot drawing a pixel earlier slots already drew **covers** each of them there,
+one pixel to each (earlier, later) pair. `under` is the earlier-drawn slot, `over`
+the later-drawn one. Pairs are by slot name, so `a` under `b` and `b` under `a` —
+one draw-order key apart — are two pairs.
+
+**Layering the motion does not move.** A pair that covers on **every** frame, and on
+each either by the **same** pixel count or with the slot in front drawn **wholly on**
+the one behind (every pixel `over` draws is one `under` drew first), is static
+layering: a backdrop under a part that never leaves it, a face drawn over the head
+that carries it. It is counted on one line and listed in the file, never printed
+pair by pair. ⚠️ The pixel count alone was measured not to be enough: on
+`gallery/walk`, a part turning over the backdrop changes its pixel count from frame to
+frame by rasterisation alone, so none of its 35 pairs read as static and 14 backdrop lines (and the eyes over the head) buried the ones that mattered.
+Every other pair that covers anything prints one `OVERLAP` line; a pair that never
+covers prints nothing.
+
+**Blind spots, stated.** A fringe painted under half opacity covers nothing here
+although it tints the frame. A slot in front lying wholly on the one behind on every
+frame reads as layering however it moves across it — an arm swung over the torso
+without ever leaving it. A slot drawing more than one piece is one slot. And the
+counts are pixels at the render's `--max`: quote the size beside a figure.
+
+**The file.** `overlaps.json`, `rigc-overlaps/1`, beside each set's frames:
+`animation`, `skin` (absent when none was set), `fps`, `reading` (`drawnAlpha` 128,
+`unit` `"frame pixels"`, and `rule`, the definition above), `frames[]` — every
+frame, with `index`, `time` and `pairs[]` (`under`, `over`, `px`, and `box`
+`[x0, y0, x1, y1]`: frame pixels, x right, y down, both ends inclusive) — and
+`pairs[]`, one per pair that covers on any frame: `under`, `over`, `frames` (how
+many it covers on), `of` (the set's frames), `runs` (`[[first, last], …]`,
+inclusive), `most` (`{ index, px }`, the earliest on a tie), `inside` (the slot in
+front wholly on the one behind on every frame it covers on) and `varies` (`false`
+for static layering). Both lists are ordered by `under`, then `over`, by code unit.
+
+**The outline plate.** `overlaps-f<NNNN>.png`, numbered as the frames are, for each
+frame where a moving pair covers: a white plate of the frame's size; every slot in a
+moving pair drawn as its **contour** — a drawn pixel with an undrawn neighbour left,
+right, above or below — in its own colour, in draw order; a contour pixel some slot
+drawn later also drew is **dashed** (drawn where `(x + y) % 4 < 2`); and the slot's
+name, spelled as the lines spell it (`arm_b`, not `ARM_B`). Names are placed in draw
+order and no two touch: each takes the first free box, trying for every contour pixel
+in raster order (the first is the topmost, the leftmost on a tie) the box above it,
+below it, to its left and to its right; when none is free, the free spot nearest the
+topmost pixel, joined to it by a one-pixel leader line; every box clamped inside the
+plate. A plate with no free spot left prints the name at its first box anyway — the
+one case two names can meet. A slot keeps one colour across a set's plates (a fixed table of eight,
+by the slot's place among the set's moving slots in code-unit order); the colour
+means only "another slot" — the name says which.
+
+**`frames.json`.** Each set gains `overlaps`: `file`, `pairs` (how many cover on any
+frame), `static` (how many of those are layering), `plates`, and `moving[]` — each
+moving pair's `under`, `over`, `frames` and `most` — so a reader that cannot open a
+plate has the figures.
+
+**Refused, nothing written:** `--slot`/`--hide` beside the flag. A slot left out
+covers nothing, so the pairs it is in would vanish and the reading would describe a
+picture of part of the rig — run `render --overlaps` on the whole rig and the subset
+without it; both land on one grid.
+
+**Nothing else moves.** The PNGs, `contact.png` and every other file are byte for
+byte what the render writes without the flag, and `frames.json` differs only by
+each set's `overlaps` record (`OX05`); two runs and both posers write the same file
+and plates (`OX04`).
+
+**A reading, not a gate.** It never changes the exit status. Whether a covered arm
+is a defect is yours; when it is, the remedy is a `drawOrder` key in the motion
+spec (or the slot's place in the rig's `slots`), and the next render says whether
+the line moved.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -11706,6 +11832,7 @@ pixel (`IN09`).
 | 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 |
+| Which slot covers which in this animation? | `render --overlaps --animation <name>` (§8.9) | One `OVERLAP "<under>" under "<over>"` line per pair that moves: the frames it covers on, as runs, and the most pixels it covers and the frame of them; one line counting the layering the motion does not move. `overlaps.json` carries every frame's pairs with their pixel count and box, and `overlaps-f<NNNN>.png` draws each covered frame's contours, the covered part dashed. A reading, not a verdict — the draw-order key is the remedy |
 | 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.62.0",
+  "version": "2.64.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,8 @@ 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 type { Plate } from '../../tools/plate.ts';
+import { OVERLAPS_FILE, OverlapError, overlapLine, overlapPlate, overlapsFileOf, overlapsOf, overlapsPlateFile, overlapsText, plateParticipants, staticLine } from '../overlaps.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';
@@ -45,6 +47,7 @@ import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, fram
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
+import { writeWhole } from './write_whole.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.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';
@@ -704,6 +707,22 @@ export function cmdRender(flags: Record<string, string>): void {
     }
   }
 
+  // The overlap reading (issue #1480) is its own flag for --folds' reason, and refused beside a subset for
+  // --pass-through's: who covers whom is a fact of every slot the rig draws, and a subset drops some of them — a slot
+  // left out covers nothing, so the pairs it is in would vanish and the reading would describe a picture of part of the rig.
+  const overlaps = flags.overlaps !== undefined;
+  if (overlaps) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--overlaps takes no --${flag}: it reads which slot covers which as the whole rig draws them, and a subset of the ` +
+            `drawn slots would drop the pairs the slots left out are in. Run \`rigc render --overlaps\` on the whole rig for the reading, and --${flag} ${flags[flag]} ` +
+            'without --overlaps for the pictures — both land on the same grid',
+        );
+      }
+    }
+  }
+
   // 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;
@@ -913,9 +932,30 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings };
+    // The overlap reading, off the very pieces the frames are drawn from, in their draw order, on the frames' own
+    // viewport — one per set — and its outline plates, drawn here so a refusal leaves nothing written.
+    const overlapReadings = new Map<string, { file: ReturnType<typeof overlapsFileOf>; plates: Map<number, Plate> }>();
+    if (overlaps) {
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        try {
+          const reading = overlapsOf(frames, pages, viewport);
+          const participants = plateParticipants(reading.pairs);
+          const plates = new Map<number, Plate>();
+          for (const index of reading.plated.keys()) {
+            const plate = overlapPlate(reading, index, participants, viewport);
+            if (plate !== null) plates.set(index, plate);
+          }
+          overlapReadings.set(name, { file: overlapsFileOf(animation, fps, skin, reading), plates });
+        } catch (err) {
+          if (err instanceof OverlapError) throw new UsageError(`--overlaps, ${JSON.stringify(name)}: ${err.message}`);
+          throw err;
+        }
+      }
+    }
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings };
   });
-  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -969,6 +1009,11 @@ export function cmdRender(flags: Record<string, string>): void {
     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 overlapReading = overlapReadings.get(name);
+    if (overlapReading !== undefined) {
+      writeFileSync(join(dir, OVERLAPS_FILE), overlapsText(overlapReading.file));
+      for (const [index, plate] of overlapReading.plates) plate.writePng(join(dir, overlapsPlateFile(index)));
+    }
     const duration = frames[frames.length - 1].time;
     const physics = physicsDeclared.length === 0 ? undefined : physicsSteppedOf(frames, fps);
     sets.push({
@@ -980,6 +1025,7 @@ export function cmdRender(flags: Record<string, string>): void {
       stride: 1,
       duration,
       ...(physics === undefined ? {} : { physics: { stepped: physics.stepped.length, fps } }),
+      ...(overlapReading === undefined ? {} : { overlaps: overlapsRecord(overlapReading.file, overlapReading.plates.size) }),
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
@@ -988,7 +1034,11 @@ export function cmdRender(flags: Record<string, string>): void {
     const passNote = passReading === undefined ? '' : ` + ${PASS_THROUGH_FILE} (${passing} of ${passReading.pairs.length} pair(s) pass through)`;
     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}`;
+    const overlapNote =
+      overlapReading === undefined
+        ? ''
+        : ` + ${OVERLAPS_FILE} (${overlapReading.file.pairs.filter((p) => p.varies).length} moving pair(s), ${overlapReading.plates.size} outline plate(s))`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
     if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
     for (const mesh of foldReading?.meshes ?? []) {
@@ -1004,6 +1054,11 @@ export function cmdRender(flags: Record<string, string>): void {
       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)}`);
+    if (overlapReading !== undefined) {
+      const still = staticLine(overlapReading.file.animation, overlapReading.file.pairs);
+      if (still !== null) console.log(`  ..    overlap  ${still}`);
+      for (const pair of overlapReading.file.pairs) if (pair.varies) console.log(`  ..    overlap  ${overlapLine(overlapReading.file.animation, pair)}`);
+    }
     for (const reading of angleReadings.get(name) ?? []) {
       console.log(`  ..    angle    ${angleRangeLine(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, reading)}`);
     }
@@ -1036,6 +1091,21 @@ export function cmdRender(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
 }
 
+/**
+ * `frames.json`'s record of one set's overlap reading (issue #1480), so a reader that cannot open a plate still has
+ * the figures: the file, how many pairs cover anything, how many of them are static layering, how many plates were
+ * drawn, and every pair that moves with its frame count and its most pixels — the figures its line prints.
+ */
+export function overlapsRecord(file: ReturnType<typeof overlapsFileOf>, plates: number): NonNullable<FrameSet['overlaps']> {
+  return {
+    file: OVERLAPS_FILE,
+    pairs: file.pairs.length,
+    static: file.pairs.filter((p) => !p.varies).length,
+    plates,
+    moving: file.pairs.filter((p) => p.varies).map((p) => ({ under: p.under, over: p.over, frames: p.frames, most: p.most })),
+  };
+}
+
 /** `render`'s line for a rig that declares no physics constraint (issue #1467): nothing was stepped because nothing could be. */
 export const PHYSICS_NONE_LINE = 'physics: none in this rig — it declares no physics constraint, so no frame steps one';
 
@@ -2144,7 +2214,9 @@ export function cmdGuide(flags: Record<string, string>, positional: string[]): v
   }
   const answer = guideAnswer(positional[0], { guide: readFileSync(join(PACKAGE_ROOT, GUIDE_FILE), 'utf8'), elsewhere }, { all: flags.all !== undefined });
   if (!answer.ok) throw new GuideError(refusalLine(answer.rule, answer.detail));
-  for (const line of answer.lines) console.log(line);
+  // One write of the whole answer, not `console.log`: a §section with `--all` runs past 64 KiB, which Bun 1.2.0's
+  // console corrupts at a chunk boundary and a non-blocking pipe cuts short on every Bun (issue #1487, `writeWhole`).
+  writeWhole(1, answer.lines.map((line) => `${line}\n`).join(''));
 }
 
 // ---------------------------------------------------------------------------
@@ -2272,31 +2344,128 @@ export function emptyArgumentRefusal(pkg: string, raw: readonly string[], keeps:
   );
 }
 
+/**
+ * One argument as a POSIX shell reads it back (issue #1486): left bare when it is made only of characters no shell
+ * treats specially, otherwise single-quoted with each `'` spelled `'\''`. The empty argument is `''`. Deterministic
+ * — the same argument always prints the same word — so a guidance line naming the flags a caller gave is one string.
+ */
+export function shellWord(arg: string): string {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg)) return arg;
+  return `'${arg.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * What a delegating command hands its bin, and the build directory it was pointed at (issue #1486). A delegate that
+ * names a `bareTarget` subcommand treats a first argument that is none of its `subcommands` and does not start with
+ * `-` (`--help`, `-h`, `--` and every flag pass through) as a target: `rigc review <dir> …` hands over
+ * `open <dir> …`. Every other command line — no argument at all, an empty first argument, or a subcommand — is handed
+ * over as given, and `target` is `null`.
+ */
+export function delegateArguments(delegate: { subcommands?: readonly string[]; bareTarget?: string }, raw: readonly string[]): { argv: string[]; target: string | null } {
+  const first = raw[0];
+  if (delegate.bareTarget === undefined || first === undefined || first === '' || first.startsWith('-') || (delegate.subcommands ?? []).includes(first)) {
+    return { argv: [...raw], target: null };
+  }
+  return { argv: [delegate.bareTarget, ...raw], target: first };
+}
+
+/**
+ * The refusal for a delegated package that does not resolve (issue #1486): `REVIEW_NOT_INSTALLED` and two guidance
+ * lines — the command that installs it, and the one that runs it once without installing, carrying `argv` (what the
+ * bin would have been handed, a bare target already spelled `open <dir>`) word for word. With nothing to carry, the
+ * second line names the target it needs as `<output>`. Nothing reads the terminal, so it is the same on a TTY and
+ * off one, and rigc runs neither line: an install and a one-off fetch both change state the caller did not ask for.
+ */
+export function notInstalledRefusal(pkg: string, argv: readonly string[]): string {
+  const words = argv.length === 0 ? ['open', '<output>'] : argv.map(shellWord);
+  return (
+    `REVIEW_NOT_INSTALLED: ${pkg} is not installed beside this project or beside rig-c, and rigc does not install it — ` +
+    `install it, or run it once without installing:\n` +
+    `bun add -d ${pkg}\n` +
+    `bunx ${pkg} ${words.join(' ')}`
+  );
+}
+
+/**
+ * The refusal for a delegated package whose manifest declares a Bun floor the running Bun is under, or `null`
+ * (issue #1486). The floor is read off the resolved package's own `engines.bun`, never written here: a package that
+ * declares none has no floor to hold. Only `>=X.Y.Z` is read; any other range shape is refused by name rather than
+ * guessed at (`REVIEW_BUN_RANGE_UNREAD`). A running version with a pre-release tag is below its own release, as
+ * semver orders them.
+ */
+export function bunFloorRefusal(pkg: string, engines: unknown, running: string): string | null {
+  if (engines === undefined) return null;
+  const isObject = typeof engines === 'object' && engines !== null && !Array.isArray(engines);
+  const range = isObject ? (engines as Record<string, unknown>).bun : undefined;
+  if (isObject && range === undefined) return null;
+  const floor = typeof range === 'string' ? /^\s*>=\s*(\d+)\.(\d+)\.(\d+)\s*$/.exec(range) : null;
+  if (floor === null) {
+    const what = isObject ? `engines.bun ${JSON.stringify(range)}` : `engines ${JSON.stringify(engines)}`;
+    return `REVIEW_BUN_RANGE_UNREAD: ${pkg} declares ${what}, and rigc reads only ">=X.Y.Z" — it did not guess whether Bun ${running} satisfies it`;
+  }
+  const found = /^(\d+)\.(\d+)\.(\d+)(-\S*)?/.exec(running);
+  const below = ((): boolean => {
+    if (found === null) return true;
+    for (let i = 1; i <= 3; i++) {
+      const a = Number(found[i]);
+      const b = Number(floor[i]);
+      if (a !== b) return a < b;
+    }
+    return found[4] !== undefined;
+  })();
+  return below ? `REVIEW_BUN_TOO_OLD: Bun ${running}, ${pkg} needs ${range as string}` : 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.
+ * — with 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: stdout is the bin's byte for byte, stderr the bin's plus only the
+ * launcher's own refusals, the exit code the bin's.
+ *
+ * Issue #1486 put four things in front of the spawn, in this order, each a
+ * refusal by name with exit 2 and nothing on stdout: a bare target that is not a
+ * directory (`REVIEW_OUTPUT_MISSING <path>`, read before the install because a
+ * guidance line pointing at nothing is no guidance); the package absent
+ * (`REVIEW_NOT_INSTALLED` and two guidance lines — never an install, never a
+ * `bunx`); a Bun below the package's declared floor (`REVIEW_BUN_TOO_OLD`); an
+ * empty argument this Bun would drop (issue #1465). The argument list is the
+ * caller's, a bare target prefixed with `open`, and nothing else: no
+ * `--reference` is derived, because no build rigc writes records the clip it was
+ * retargeted from.
  */
 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 { argv, target } = delegateArguments(delegate, raw);
+  if (target !== null && !(existsSync(target) && statSync(target).isDirectory())) {
+    throw new DelegateError(
+      `REVIEW_OUTPUT_MISSING ${target}: ${existsSync(target) ? 'it is not a directory' : 'nothing is there'} — \`rigc review <dir>\` opens a build's output directory, ` +
+        `and the first argument is read as one because it is none of ${(delegate.subcommands ?? []).join(', ')} and does not start with "-" (\`rigc review -- <arg>\` hands it over as it is)`,
+      2,
+    );
+  }
   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;
+  if (manifest === null) throw new DelegateError(notInstalledRefusal(delegate.package, argv), 2);
+  const read = readJsonFile(manifest) as { bin?: unknown; engines?: unknown };
+  const bins = read.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}`,
+      `${delegate.package} at ${dirname(manifest)} ${bin === null ? `declares no "${delegate.bin}" bin` : `declares the "${delegate.bin}" bin ${String(relativeBin)}, which is not there`} — bun add -d ${delegate.package}`,
       2,
     );
   }
-  const dropped = emptyArgumentRefusal(delegate.package, raw, spawnKeepsEmptyArguments, process.versions.bun ?? 'unknown');
+  const old = bunFloorRefusal(delegate.package, read.engines, process.versions.bun ?? 'unknown');
+  if (old !== null) throw new DelegateError(old, 2);
+  const dropped = emptyArgumentRefusal(delegate.package, argv, spawnKeepsEmptyArguments, process.versions.bun ?? 'unknown');
   if (dropped !== null) throw new DelegateError(dropped, 2);
-  const ran = spawnSync(process.execPath, [bin, ...raw], { stdio: 'inherit' });
+  // 🔒 The `--` is Bun's, not the bin's: Bun 1.2.0 and 1.4.2 alike drop one `--` standing right after the script, so
+  // `rigc review -- <dir>` reached the bin as `<dir>` (measured, issue #1486). One given here is the one dropped, and
+  // the arguments after it arrive as they were.
+  const ran = spawnSync(process.execPath, [bin, '--', ...argv], { 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.