spine-rigc 1.1.0 → 1.2.0

package/docs/AUTHORING.md

@@ -123,6 +123,8 @@ bun cli.ts check \
 # …and if nobody gave you frames, LOOK at it instead — neither needs a reference:
 bun cli.ts render  --candidate path/to/spine    # PNG frames + a contact sheet grid
 bun cli.ts preview --candidate path/to/spine    # one .html that plays it in Spine's own player
+#   ↳ a green build ends by naming this command for its own --out; repeat
+#     --candidate for a pane per candidate on one page
 
 # …and where you have several green candidates and no instrument that separates
 # them, ask a human — the one loop step this toolchain cannot run for you:
@@ -141,6 +143,27 @@ the animation is the one in the frames, and there is no assertion that could —
 §9. The two run in that order because `check` needs artifacts on disk and `build`
 only writes them when the gate is green.
 
+🎞️ **When the source is a foreign player — a Live2D model, a Unity scene, a video —
+make the reference frames first, from the source.** rigc reads none of those
+formats and will not ([FACE.md](FACE.md#11-non-goals--stated-so-nobody-proposes-them-as-gaps)
+§11, the paragraph that opens *No Live2D file is read or written*); what it reads
+is the pictures they produce. Render the source at the rate you will check at into
+one directory of `f0000.png`, `f0001.png`… named after the candidate animation it
+shows (or pair the two with `--as`): `check` accepts a set with no `frames.json`
+and takes its rate from `--fps` (§9). What that set cannot carry is its
+**background**, which the sidecar would have recorded — so render it onto an
+**opaque** background of the colour `check`'s no-`frames.json` note names
+(`232, 232, 232, 255` in this release). The content box is found against that
+colour and alpha is not read: measured on the 24 frames of `gallery/look`'s `turn`,
+the same drawn pixels read MAE mean **2.25** over that grey, **5.19** over white and
+**20.37** over a transparent background, where the fit took the whole 234×256
+frame for the figure — all three at exit 0 with the same notes. A port with no
+reference frames is **unmeasured, not finished**: green from `build` says the file
+is valid and nothing about whether it is the source's picture. And the parts are
+the source's own texture cut along its drawables, **never a screenshot of it** — a
+screenshot is the composed result, so a part cut from it carries every part under
+it, which is what the first of the three questions under *LOOK* below finds.
+
 🚨 **Read `check`'s per-frame column before its MAE.** The table's headline figures
 are the MAE and the slot drift, and a reader who came for those will skip the
 `per-frame` line printed under them — but that line is the only thing in this
@@ -159,7 +182,7 @@ What the flags mean:
 | --- | --- |
 | `--rig` | the rig spec — skeleton structure |
 | `--motion` | the motion spec — time |
-| `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths and `skeleton.images` are written relative to it |
+| `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths and `skeleton.images` are written relative to it. On `check` it is a directory of **pictures** instead: one per frame the table lists (every compared frame under `--all-frames`), reference · candidate · difference · overlay at the comparison grid's native size, as `<dir>/<set>/f####.png` beside a `frames.json` that says what they are pictures of. Each `<dir>/<set>/` is cleared first; a file at `<dir>`, or a directory that is or holds `--frames`, is refused by name — **§9.2.1** |
 | `--copy-images` | `build` only: also copies every page **the emitted atlas names** into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own, and points `skeleton.images` at `--out` itself so the editor's import finds the parts beside the skeleton (§3.1 says why it is spelled `../<out>/` and not `./`). Under `--atlas-in` those pages are the pack's, not one per part (**§0.2**). Without it, page paths point at the source art |
 | `--pack` | `build` only: arrange every part onto **shared** atlas page(s), written into `--out` as real PNGs, instead of one page per part. Lossless — nothing is resampled, trimmed or rotated. The default is one page per part — **§0.1** |
 | `--page-size` | `build --pack` only: the largest page edge (default `2048`). A ceiling, not the size: page edges are powers of two and the one written is the smallest that holds the pack — **§0.1** |
@@ -170,8 +193,8 @@ What the flags mean:
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
 | `--profile` | `spine` = the 34 validity rules (**the default**) · `spine-html` = all 49, opt-in |
-| `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
-| `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview`, and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote`, so is a name that only *some* candidates have |
+| `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
+| `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
 | `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
@@ -749,7 +772,8 @@ bun cli.ts diff     candidate.json reference.json [--as <candidate>=<reference>]
 bun cli.ts check    --candidate path/to/spine --frames path/to/frames [--skin …]
 bun cli.ts bench    3 --candidate path/to/spine [--frames path/to/frames]
 bun cli.ts render   --candidate path/to/spine [--animation …] [--skin …] [--fps 12] [--max 256]
-bun cli.ts preview  --candidate path/to/spine [--animation …] [--out preview.html]
+bun cli.ts render   --candidate path/to/spine --slot <name,…> | --hide <name,…>   # part of the rig, same grid
+bun cli.ts preview  --candidate path/to/spine [--candidate path/to/another …] [--animation …] [--out preview.html]
 bun cli.ts vote     --candidate path/to/a --candidate path/to/b [--out ballot.html]
 bun cli.ts vote     --record vote-<id>.json [--ballot ballot.html] [--ledger votes.jsonl]
 bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
@@ -824,12 +848,39 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   gate can know you did not mean them. `render` writes
   `render/<animation>/f0000.png…` with a `contact.png` grid of **every** frame
   beside them (open that one first — spacing is a comparison across frames) and a
-  `frames.json` sidecar naming the world box they are pictures of. `preview`
+  `frames.json` sidecar naming the world box they are pictures of. `contact.png`
+  is for spacing across frames; a defect is read on **one frame at full size**,
+  because a tile is too small to say which part a pixel belongs to. When a frame
+  looks wrong, render it again with `--hide <slot>` — the **largest attachment**
+  first, since it covers the most and is the likeliest to hide what is under it —
+  and compare the two frames: `--hide` and `--slot <name,…>` draw a subset of the
+  slots on the **same grid** as the whole rig (the viewport is still fitted to
+  every slot), so the frames overlay pixel for pixel and the difference is the
+  part. Three questions to ask of that full-size frame, each answered that way.
+  **Is any picture drawn twice?** Hide the largest attachment and look for a second
+  copy of what it covered, since a ghost under an opaque part is invisible until the
+  part is gone. **Is there a straight edge where the art has none?** A part cut as a
+  rectangle carries a border its drawing never had, and `--slot <that slot>` shows it
+  alone. **Does a part cover a feature the art shows?** An eye slot drawn over the
+  eye is found by hiding the slot and watching the feature come back. A name the skeleton does not declare is refused with every slot it does,
+  in draw order; a slot whose art lives only under another skin is refused naming
+  that skin (pass `--skin`); the two flags together are refused. `frames.json`
+  records the subset as `slots` or `hidden`, and **`check` refuses such a set as
+  a reference** (§9). `preview`
   writes one self-contained `.html`: your skeleton, atlas and page PNGs are
   embedded in it as data URIs and played by the official **Spine Web Player**, so
   double-clicking it is also the interop proof — what plays there was played by
   Esoteric Software's runtime, not by rigc's. The player is loaded from a CDN
-  rather than copied into the file, so the first open needs a network.
+  rather than copied into the file, so the first open needs a network. Its
+  header carries the gate's line for the candidate — the `N assertions: …`
+  summary `rigc validate <dir>` prints for the same files, and its first `FAIL`
+  line when there is one — with the rigc version, measured when the page is
+  written; a refused candidate is still previewed, because looking at a red
+  build is what the page is for. Note that it is the **bare-directory** reading:
+  with no rig spec and no second compile beside the files, `A09` and `A18` report
+  SKIP there, so its counts are not the ones `build` printed. It takes
+  neither `--slot` nor `--hide` — the player draws what the skeleton draws — and
+  refuses both by name rather than playing the whole rig as if it had obeyed.
 - 📐 **`pose` is the only command here that reads an INPUT rather than a result.**
   Everything else takes a spec or a build and tells you something about it; `pose`
   takes a picture the user already has — a key pose — and reports where each loose
@@ -6018,7 +6069,8 @@ rather than the rig (**§9.2**'s atlas floor — and note that it is *not* `--at
 which re-seats your geometry on that atlas's packing), `--skin <name>` to pose
 your candidate under one of its skins (below), `--all-frames` to list
 every frame instead of the worst by MAE, `--json <out>` for the whole per-frame,
-per-slot report.
+per-slot report, `--out <dir>` for the picture each listed frame's figures came from
+(**§9.2.1**).
 
 🚨 **What `check` certifies is the DEFAULT skin, unless you pass `--skin`.** With no `--skin` no skin is set at all, which is `spine-core`'s own
 initial state: every slot resolves through `SkeletonData.defaultSkin` alone, and a
@@ -6056,6 +6108,21 @@ remember:
 A skin name the candidate does not declare is refused with the ones it does —
 `the candidate declares no skin "path"; it declares [default, patch, torn]`.
 
+🚫 **A frame set of PART of a rig is not a reference.** `render --slot`/`--hide`
+(§0) records the subset in `frames.json`, and `check` refuses any set that carries
+`slots` or `hidden`, before posing anything:
+
+```
+rigc check error: --frames frames/ records a slot subset (hidden: head) in frames.json; a partial render is not a reference set — render the reference without --slot/--hide
+```
+
+It is the skin clause one step stronger: two skins are two pictures of one rig,
+while a reference with a part left out is not a picture of the whole rig at all,
+and scoring a whole candidate against it would print a real figure about art the
+reference never drew. There is no flag that makes it comparable. A set with
+neither key — every set rendered without the flags, and every set written before
+they existed — is compared exactly as before.
+
 📌 **Deform measurement needs no such flag, because the timeline carries the
 name.** `A39` and the `DEFORM` block pose each key with the skin that key is keyed
 on — a deform timeline's address is a `skin / slot / attachment` triple — so a
@@ -7001,6 +7068,66 @@ slots column is a parenthesis rather than a fraction, the deformation it carries
 already being scored inside the chain that owns the slot, and the row is telling you
 about your bone tree rather than about a hole in your figure.
 
+#### 9.2.1 Reading the pictures — `--out`
+
+```bash
+bun cli.ts check --candidate path/to/spine --frames path/to/reference/frames --out check-pictures
+```
+
+The table says **how much** a frame differs; `--out <dir>` writes **where**. For
+every frame the table lists — the frames worth reading, or every compared frame
+under `--all-frames` — it writes `<dir>/<set>/f####.png`, and beside them a
+`frames.json` recording what they are pictures of: the candidate, the frames
+directory, both skins, the framing scope, the grid, and per set the box it was
+framed in and which frames were written. Each picture is four panes, left to right:
+
+| Pane | What it is | The figure in its label |
+| --- | --- | --- |
+| `REFERENCE` | the frame as read from `--frames` | `REF D` — the table's `ref Δ`: pixels the reference moved since its own previous frame (`-` when that frame was not compared) |
+| `CANDIDATE` | your candidate exactly as `check` rendered it onto that grid — same framing, same skin, same texture | `DPX` — the table's `Δpx`, the same count on your side |
+| `DIFFERENCE` | per pixel, the largest of the three channel differences between the two, on a **fixed** grey ramp: 0 is black, 255 is white. Drawn over exactly the pixels the MAE averages over — what your geometry covers or the reference drew — and transparent everywhere else | `MAE` — the frame's MAE, as the table prints it |
+| `OVERLAY` | the two at 50 % each, so a displaced edge reads as a double line and a part drawn twice reads as a ghost | `UNION` — the table's `union px` |
+
+Under the panes, one row per slot of that frame: its drift at the table's
+precision and how it was matched, or why it has none (`not drawn`, `no attributable
+drift`). The frame's worst slot — the one its table row names — is marked `>`. The
+text is the tree's 5x7 bitmap font, so it prints in capitals, and a character the
+font does not carry draws as a solid block rather than disappearing.
+
+- **The ramp is fixed, and deliberately not stretched to the frame's own maximum.**
+  Two runs' pictures are then comparable by eye, and a quiet frame looks quiet. The
+  cost is the other side of the same choice: a frame whose MAE is a texture floor
+  of a few points reads as a **near-black silhouette** of the union, because 7 of
+  255 is dark. That silhouette is not nothing — it is where the two sides drew —
+  and the grey you have to find is the difference you have to fix.
+- **Every pane is at the grid's native size, and there is no upscaling option.** An
+  upscaled difference is a difference the instrument invented: a resampling filter
+  spreads ink into pixels the comparison never measured. Open the file and zoom in
+  your viewer instead, where the magnification is yours and visibly not the data.
+- **Nothing in a picture is a new number.** Every figure in it is one the report
+  already holds. The rasters are the ones the figures were computed on, kept at the
+  moment they were compared rather than rendered again.
+
+What a picture cannot tell you, and does not try to:
+
+- **Which side is right.** The difference pane is symmetric. A pixel lit there is
+  a pixel the two disagree about; whether yours or the reference's is the one to
+  move is yours to read off the other panes.
+- **Anything about a frame it does not show.** The set is the table's listing, so
+  a frame outside it was not pictured — not pictured clean. `--all-frames` widens
+  the set to every compared frame when the listing is not enough.
+
+`<dir>/<set>/` is cleared and rewritten, as `render` clears its own, and nothing
+else under `<dir>` is touched. Two things are refused before anything is compared:
+a **file** at `<dir>` (`check: --out <path> is a file; it names a directory`), and a
+directory that **is `--frames` or holds it** (`check: --out <path> is --frames …` /
+`… holds --frames …`), because clearing a set directory there deletes the frames the
+pictures are of. And a `check --out` directory is not a frame set: pointed at by
+`--frames`, it is refused by the field that says so —
+`` frames.json carries "comparison": it was written by `rigc check --out` `` and the
+rest of the sentence names the frames it was made against. The reference pane inside each
+picture is a frame; the file is four panes and a table.
+
 ### 9.3 What it still cannot see
 
 - **Anything a frame does not contain.** Bone `length`, the setup `inherit` mode,

package/docs/MOTION.md

@@ -1007,6 +1007,7 @@ rigc build --rig semaphore.rig.json --motion semaphore.motion.json --images part
   ..    pages=3 regions=3 bones=4 slots=3 animations=1 version=4.3.13 regionAttachments=3 meshAttachments=0 physicsConstraints=0 rig=semaphore profile=spine
 rigc: wrote …/semaphore/spine/skeleton.json
 rigc: wrote …/semaphore/spine/skeleton.atlas
+rigc: look at it: rigc preview --candidate …/semaphore/spine
 ```
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rigc
-description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output through a spine-core round-trip before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
+description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output through a spine-core round-trip before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later. The tool is the npm package spine-rigc (bunx spine-rigc, or bun add -d spine-rigc); the command it installs is rigc.
 ---
@@ -55,15 +55,38 @@ skill the package ships there, and `rigc skills --help` says what it refuses.
    §4.11.2.
 4. `rigc render --candidate <out>` or `rigc preview --candidate <out>` — look at
    it. A rig with its head off its torso passes the gate; looking is what catches it.
-5. `rigc check --candidate <out> --frames <dir>` when you have reference pictures;
+   Open one frame at full size, not only `contact.png`: the sheet is for spacing
+   across frames, and a defect is read on a frame. Ask it three things — is any
+   picture drawn twice, is there a straight edge where the art has none, does a part
+   cover a feature the art shows — and answer each with `render --hide <slot>` (or
+   `--slot <slot,…>`), which draws the frame again without that part on the same
+   grid, so the two frames say which part a pixel is. AUTHORING §0 holds the three.
+5. `rigc check --candidate <out> --frames <dir>` when you have reference pictures
+   (`--out <dir>` writes the picture each of its numbers came from — open the worst);
    `rigc vote --candidate <a> --candidate <b>` when several candidates are green and
    only a person can choose between them.
 6. `rigc validate <out>` re-gates artifacts already on disk, and
    `rigc <command> --help` is each command's own flag table.
+7. Every finished unit ends with `rigc preview --candidate <out>`, and the report
+   names the `.html` it wrote. The hand-off to a person is part of the work.
 
 The loop in full, with `pose` before it and `chainfit` after the first build:
 AUTHORING §0.
 
+## When the source is not loose PNGs
+
+A Live2D model, a Unity scene or a video is a player, not a set of parts. Make the
+reference frames first: render the source at the rate you will check at, into one
+directory of `f0000.png`, `f0001.png`…, and `rigc check --frames <that dir> --fps <rate>`
+reads them with no `frames.json`. A port with no reference frames is unmeasured,
+not finished. The parts are the source's own texture cut along its drawables, never
+a screenshot: a screenshot is the composed result, and a part cut from it carries
+every part under it. rigc reads none of those formats — FACE §11, the paragraph
+that opens *No Live2D file is read or written*
+([FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md#11-non-goals--stated-so-nobody-proposes-them-as-gaps)) —
+only the pictures they produce. The rule, the background those frames need and
+what a wrong one costs: AUTHORING §0, *When the source is a foreign player*.
+
 ## Which guide, for which need
 
 Read [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) first, whatever the need: the two

package/src/ballot.ts

@@ -63,6 +63,9 @@ import {
   dataUri,
   embeddedJson,
   escapeHtml,
+  PANE_STAGE_CSS,
+  paneGridCss,
+  paneSection,
   PLAYER_LINE,
   PLAYER_SCRIPT_URL,
   PLAYER_STYLE_URL,
@@ -592,14 +595,10 @@ export function buildBallot(input: BallotInput): { html: string; manifest: Ballo
     },
   };
 
-  const panes = manifest.candidates
-    .map(
-      (c) => `<section class="pane">
-  <h2>${c.label}</h2>
-  <div class="stage" id="rigc-player-${c.label}"></div>
-</section>`,
-    )
-    .join('\n');
+  // The pane markup and its grid are `preview.ts`'s since issue #837, which
+  // borrowed them for a page of panes that asks nothing; the bytes here are
+  // the ones this page always wrote.
+  const panes = manifest.candidates.map((c) => paneSection(`rigc-player-${c.label}`, `<h2>${c.label}</h2>`)).join('\n');
 
   const choices = [...labels, TIE]
     .map(
@@ -649,11 +648,9 @@ export function buildBallot(input: BallotInput): { html: string; manifest: Ballo
   button { font: inherit; padding: 4px 12px; border: 1px solid rgba(0, 0, 0, 0.35); border-radius: 4px; background: rgba(255, 255, 255, 0.6); cursor: pointer; }
   button:hover { background: rgba(255, 255, 255, 0.95); }
   button[aria-pressed="true"] { background: #1a1a1a; color: #fff; border-color: #1a1a1a; }
-  #panes { display: grid; grid-template-columns: repeat(${manifest.candidates.length}, minmax(0, 1fr)); gap: 1px; background: rgba(0, 0, 0, 0.15); }
-  @media (max-width: 720px) { #panes { grid-template-columns: minmax(0, 1fr); } }
-  .pane { background: ${backgroundHex()}; display: flex; flex-direction: column; min-width: 0; }
+${paneGridCss(manifest.candidates.length)}
   .pane h2 { margin: 0; padding: 6px 14px; font-size: 15px; letter-spacing: 0.12em; }
-  .stage { height: 52vh; min-height: 260px; }
+${PANE_STAGE_CSS}
   #vote { border-top: 1px solid rgba(0, 0, 0, 0.15); display: flex; flex-direction: column; gap: 10px; }
   .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
   .row > label, .caption { opacity: 0.65; }

package/src/check.ts

@@ -214,6 +214,17 @@ function readSidecar(root: string): FramesSidecar | null {
   const raw = readFrameFile(root, join(root, FRAMES_SIDECAR)).toString('utf8');
   const parsed: unknown = JSON.parse(raw);
   if (typeof parsed !== 'object' || parsed === null) return null;
+  // Before the spec, because it is the more specific answer: a `check --out`
+  // directory carries this build's own spec, and what is wrong with it is not
+  // its version but what it is a picture OF — see `COMPARISON_FIELD`.
+  if (Object.prototype.hasOwnProperty.call(parsed, COMPARISON_FIELD)) {
+    throw new CheckError(
+      `${join(root, FRAMES_SIDECAR)} carries ${JSON.stringify(COMPARISON_FIELD)}: it was written by \`rigc check ` +
+        '--out`, and a check\'s pictures are a comparison, not a reference frame set — each one holds a reference ' +
+        'pane, but the file is four panes and a table. Point --frames at the frames that comparison was made ' +
+        `against, which its ${JSON.stringify(COMPARISON_FIELD)}.frames names.`,
+    );
+  }
   const sidecar = parsed as FramesSidecar;
   if (sidecar.spec !== FRAMES_SPEC) {
     throw new CheckError(
@@ -1006,6 +1017,12 @@ export interface CheckOptions {
    * this adds a second render per compared frame beside them.
    */
   textureFrom?: { atlasText: string; atlasDir: string; label: string };
+  /**
+   * Keep the rasters behind the frames the report will list, for `--out` — see
+   * `CheckPlates`. Nothing about the report changes when this is set: it is filled
+   * in beside the comparison, from the plates the comparison was computed on.
+   */
+  plates?: CheckPlates;
 }
 
 // ---------------------------------------------------------------------------
@@ -1056,6 +1073,22 @@ export interface CheckOptions {
  */
 export function checkAgainstFrames(options: CheckOptions): CheckReport {
   const located = locateFrames(options.framesDir);
+  // A frame set `render --slot`/`--hide` wrote is a picture of PART of a rig
+  // (issue #835), and it is refused before anything is posed. The clause is the
+  // skin mismatch's below, one step stronger: there two skins are two pictures
+  // of one rig, here the reference is not a picture of a whole rig at all, so a
+  // whole candidate compared against it would print a real figure about art the
+  // reference leaves out. No flag makes that comparable — a warning would still
+  // print the figure — so there is no remedy here but the reference's own.
+  const subsetKey = located.sidecar?.slots !== undefined ? 'slots' : located.sidecar?.hidden !== undefined ? 'hidden' : null;
+  if (subsetKey !== null) {
+    const recorded = located.sidecar?.[subsetKey];
+    throw new CheckError(
+      `--frames ${options.framesDir} records a slot subset (${subsetKey}: ${
+        Array.isArray(recorded) ? recorded.join(', ') : JSON.stringify(recorded)
+      }) in ${FRAMES_SIDECAR}; a partial render is not a reference set — render the reference without --slot/--hide`,
+    );
+  }
   const notes: string[] = [];
 
   const posable = posableFromText(options.skeletonText, options.atlasText, options.atlasDir);
@@ -1404,7 +1437,18 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   for (let i = 0; i < prepared.length; i++) {
     const f = framings[i];
     animations.push(
-      checkOneSet(located.root, prepared[i], posable, f, background, chains, chainOfSlot, substitution, unmatched),
+      checkOneSet(
+        located.root,
+        prepared[i],
+        posable,
+        f,
+        background,
+        chains,
+        chainOfSlot,
+        substitution,
+        unmatched,
+        options.plates ?? null,
+      ),
     );
   }
 
@@ -2367,6 +2411,8 @@ function checkOneSet(
   substitution: TextureSubstitution | null,
   /** Region names it could not reach, unioned across every set by the caller. */
   unmatched: Set<string>,
+  /** Where to keep the rasters of the frames the report will list — `null` keeps none. */
+  plates: CheckPlates | null,
 ): AnimationCheck {
   const { set } = prepared;
   const viewport = framing.viewport;
@@ -2437,6 +2483,7 @@ function checkOneSet(
   // because `substituteTexture` prefixes every name it writes.
   const floorPages = substitution === null ? null : new Map([...posable.pages, ...substitution.pages]);
   const floorSum = { floor: 0, aboveFloor: 0, floorReference: 0, aboveFloorReference: 0 };
+  plates?.begin(set.dir, prepared.pairs.length);
 
   for (const { index, file, frame } of prepared.pairs) {
     const reference = readPlateFrom(root, file);
@@ -2447,7 +2494,7 @@ function checkOneSet(
       for (const name of swapped.unmatched) unmatched.add(name);
       floorPlate = renderFrame(swapped.frame, floorPages, viewport, background);
     }
-    const check = checkOneFrame(
+    const { check, coverage } = checkOneFrame(
       index,
       file,
       frame,
@@ -2462,6 +2509,9 @@ function checkOneSet(
     );
     check.change = previous && previous.index === index - 1 ? frameChange(previous, rendered, reference) : null;
     previous = { index, candidate: rendered, reference };
+    // After the change is known, because whether a frame will be listed depends
+    // on it — see `CheckPlates.offer`.
+    plates?.offer(set.dir, check, { reference, candidate: rendered, coverage });
     frames.push(check);
     maeSum += check.mae;
     maeReferenceSum += check.maeReference;
@@ -2827,7 +2877,7 @@ function checkOneFrame(
    * see `TextureFloor`. `null` is the ordinary case and costs nothing.
    */
   floorPlate: Plate | null,
-): FrameCheck {
+): { check: FrameCheck; coverage: Uint8Array } {
   const { coverage, footprints, owner } = frameGeometry(frame, pages, viewport, chainOfSlot);
   // Only worth the transform when something was drawn to be nearest TO.
   const nearest =
@@ -2911,7 +2961,7 @@ function checkOneFrame(
     }
   }
 
-  return {
+  const check: FrameCheck = {
     index,
     file,
     mae: union === 0 ? 0 : sum / union,
@@ -2943,6 +2993,9 @@ function checkOneFrame(
             aboveFloorReference: referencePixels === 0 ? 0 : aboveReferenceSum / referencePixels,
           },
   };
+  // The coverage goes back beside the figures because the union it defines is the
+  // one a `--out` difference pane is drawn over — see `CheckPlates`.
+  return { check, coverage };
 }
 
 // ---------------------------------------------------------------------------
@@ -3653,7 +3706,7 @@ function chainRollup(report: CheckReport): ChainRollup[] {
  * ranked by MAE is exactly the listing that leaves them out. Rung 6's f65–f68 sit
  * near the bottom of that ranking.
  */
-function framesToList(anim: AnimationCheck, allFrames: boolean): FrameCheck[] {
+export function framesToList(anim: AnimationCheck, allFrames: boolean): FrameCheck[] {
   if (allFrames || anim.frames.length <= LIST_EVERY) return anim.frames;
   const chosen = new Set(
     [...anim.frames]
@@ -3665,6 +3718,129 @@ function framesToList(anim: AnimationCheck, allFrames: boolean): FrameCheck[] {
   return anim.frames.filter((f) => chosen.has(f.index));
 }
 
+/**
+ * The field of a `frames.json` that says the directory is `check --out`'s
+ * pictures and not a frame set — see `src/checkpics.ts`. `check --frames`
+ * refuses a sidecar carrying it, by this name.
+ */
+export const COMPARISON_FIELD = 'comparison';
+
+/** The three rasters one frame's figures were computed on. */
+export interface ComparedPlates {
+  /** The reference frame, as read from `--frames`. */
+  reference: Plate;
+  /** The candidate, rendered onto the reference's grid over the frames' background. */
+  candidate: Plate;
+  /** Which pixels the candidate's geometry covers, 1 or 0 — half of the union alpha. */
+  coverage: Uint8Array;
+}
+
+/**
+ * The rasters behind the frames a report will list, kept at the moment they were
+ * compared — what `check --out` draws its pictures from.
+ *
+ * ## Why they have to be kept, and why not all of them
+ *
+ * `checkOneSet` holds a frame's two plates for exactly one iteration (and the
+ * previous frame's for the change measure); the difference is never a raster at
+ * all, only a running sum. And which frames are *worth reading* is not known
+ * until the set is finished, because it is the worst by MAE over all of them —
+ * `framesToList` decides it at print time. So the choice is between re-rendering
+ * the listed frames afterwards and keeping them now, and re-rendering is rejected:
+ * a second render that agreed with the first would be a claim about the picture,
+ * and this is meant to be the record of it.
+ *
+ * Keeping every frame is the other simple answer and it does not scale: one
+ * frame at 256x116 is 261 KiB of plates and coverage, and a 300-frame set at
+ * 512x512 would hold 675 MiB. So a set longer than the listing threshold keeps a
+ * running top `WORST_FRAMES` by MAE — ties to the earlier index, which is the
+ * order `framesToList`'s stable sort gives them — plus every frame whose change
+ * disagrees, and drops the rest as it goes. `--all-frames` keeps everything,
+ * because then everything is listed.
+ *
+ * 🔒 `framesToList` stays the one derivation of the listing. This only has to
+ * keep a superset of it, and `writeCheckPictures` refuses by name a listed frame
+ * it finds nothing kept for, so the two cannot disagree in silence.
+ */
+export class CheckPlates {
+  /** Whether every compared frame is kept — `--all-frames`. */
+  readonly every: boolean;
+  private readonly kept = new Map<string, Map<number, ComparedPlates>>();
+  /** Per set: whether the whole set will be listed, so everything is kept. */
+  private readonly whole = new Map<string, boolean>();
+  /** Per set: the running worst by MAE, worst first, at most `WORST_FRAMES`. */
+  private readonly ranked = new Map<string, Array<{ index: number; mae: number }>>();
+  /** Per set: frames kept because their change disagrees, whatever their MAE. */
+  private readonly disagreeing = new Map<string, Set<number>>();
+  private held = 0;
+  /** The most bytes of raster this held at any one time — the cost `--out` adds. */
+  peakBytes = 0;
+
+  constructor(opts: { allFrames: boolean }) {
+    this.every = opts.allFrames;
+  }
+
+  /** A set is about to be compared, over this many frame pairs. */
+  begin(dir: string, compared: number): void {
+    this.kept.set(dir, new Map());
+    this.whole.set(dir, this.every || compared <= LIST_EVERY);
+    this.ranked.set(dir, []);
+    this.disagreeing.set(dir, new Set());
+  }
+
+  /** One frame has been compared: keep its plates if it can be listed. */
+  offer(dir: string, check: FrameCheck, plates: ComparedPlates): void {
+    const kept = this.kept.get(dir);
+    const ranked = this.ranked.get(dir);
+    const disagreeing = this.disagreeing.get(dir);
+    if (kept === undefined || ranked === undefined || disagreeing === undefined) {
+      throw new Error(`CheckPlates: set ${JSON.stringify(dir)} was offered a frame before it began`);
+    }
+    if (this.whole.get(dir) === true) {
+      this.keep(kept, check.index, plates);
+      return;
+    }
+    const disagrees = check.change !== null && check.change.verdict !== 'agrees';
+    if (disagrees) disagreeing.add(check.index);
+    // Frames arrive in index order, so a later frame that only ties the last
+    // ranked one loses to it — exactly as the stable sort would place them.
+    const enters = ranked.length < WORST_FRAMES || check.mae > ranked[ranked.length - 1].mae;
+    if (enters) {
+      let at = ranked.findIndex((r) => check.mae > r.mae);
+      if (at < 0) at = ranked.length;
+      ranked.splice(at, 0, { index: check.index, mae: check.mae });
+      if (ranked.length > WORST_FRAMES) {
+        const out = ranked.pop() as { index: number; mae: number };
+        if (!disagreeing.has(out.index)) this.drop(kept, out.index);
+      }
+    }
+    if (enters || disagrees) this.keep(kept, check.index, plates);
+  }
+
+  /** The plates kept for one frame of one set, if any. */
+  of(dir: string, index: number): ComparedPlates | undefined {
+    return this.kept.get(dir)?.get(index);
+  }
+
+  private keep(kept: Map<number, ComparedPlates>, index: number, plates: ComparedPlates): void {
+    if (kept.has(index)) return;
+    kept.set(index, plates);
+    this.held += bytesOf(plates);
+    if (this.held > this.peakBytes) this.peakBytes = this.held;
+  }
+
+  private drop(kept: Map<number, ComparedPlates>, index: number): void {
+    const plates = kept.get(index);
+    if (plates === undefined) return;
+    kept.delete(index);
+    this.held -= bytesOf(plates);
+  }
+}
+
+function bytesOf(plates: ComparedPlates): number {
+  return plates.reference.data.length + plates.candidate.data.length + plates.coverage.length;
+}
+
 /** The per-frame change measure, as the animation's own summary line. */
 function changeSummary(anim: AnimationCheck): string {
   if (anim.changePairs === 0) {