spine-rigc 1.1.0 → 1.2.0

package/README.md

@@ -323,6 +323,7 @@ the two files:
   ..    pages=3 regions=3 bones=4 slots=3 animations=1 version=4.3.13 regionAttachments=3 meshAttachments=0 physicsConstraints=0 rig=buoy profile=spine
 rigc: wrote …/buoy/spine/skeleton.json
 rigc: wrote …/buoy/spine/skeleton.atlas
+rigc: look at it: rigc preview --candidate …/buoy/spine
 ```
 
 `profile=spine` is the rulebook that judged it: *is this valid Spine 4.3 that any
@@ -532,14 +533,14 @@ commands take it and what its default is.
 | `validate <dir>` | re-gates artifacts already on disk |
 | `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 |
 | `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/` |
-| `preview --candidate <dir>` | one self-contained `.html` that plays it |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference |
+| `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 |
 | `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies. A bone with two or more anchored descendants is **determined** rather than searched, and the residual that over-determination leaves is reported |
 | `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
 | `bonedist --candidate … --reference … --bones …` | per-frame, per-bone world-transform distance against another skeleton — the ladder's stage 3, run on its own. `--bones <correspondence.json \| identity>` is required rather than defaulted: a candidate is entitled to its own bone names, so the pairing is stated |
-| `check --candidate <dir> --frames <dir>` | the candidate against reference pictures — the only instrument here that can see a *wrong animation* |
+| `check --candidate <dir> --frames <dir> [--out <dir>]` | the candidate against reference pictures — the only instrument here that can see a *wrong animation*. `--out` also writes, for every frame the table lists, the picture its figures came from: reference, candidate, difference and overlay at native size |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
 | `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 |
 

package/cli.ts

@@ -46,7 +46,7 @@ import {
   symlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import {
   BallotError,
   buildBallot,
@@ -70,7 +70,15 @@ import {
   IDENTITY_CORRESPONDENCE,
   type BoneDistReport,
 } from './src/bonedist.ts';
-import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
+import {
+  checkAgainstFrames,
+  checkLines,
+  CheckError,
+  CheckPlates,
+  type CheckOptions,
+  type CheckReport,
+} from './src/check.ts';
+import { writeCheckPictures } from './src/checkpics.ts';
 import { compile, CompileError, droppedStateReason, relativeImagesPath, type CompileOptions } from './src/compile.ts';
 import {
   skeletonDataFromText,
@@ -125,7 +133,7 @@ import {
   estimateChainFit,
   type ChainFitOptions,
 } from './src/chainfit.ts';
-import { buildPreview, PLAYER_LINE, type PreviewPage } from './src/preview.ts';
+import { buildPreview, buildPreviewPanes, PLAYER_LINE, type PreviewGate, type PreviewInput, type PreviewPage } from './src/preview.ts';
 import {
   atlasPageNames,
   BACKGROUND,
@@ -141,9 +149,13 @@ import {
   SETUP_POSE_DIR,
   SHEET_FILE,
   SHEET_TILE,
+  SlotSubsetError,
+  slotSubsetOf,
   type Frame,
   type FramesSidecar,
   type FrameSet,
+  type Posable,
+  type SlotSubset,
 } from './src/render.ts';
 import {
   assertionCountForProfile,
@@ -249,8 +261,9 @@ const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images',
  * The flags a command is allowed to spell more than once.
  *
  * `vote --candidate` is, because a ballot is *by definition* several
- * candidates, and `diff --as` is, because a skeleton has as many shots as it
- * has and one pairing per flag is the only spelling that keeps each pair a pair
+ * candidates; `preview --candidate` is, because a pane per candidate on one
+ * page is what an agent otherwise builds by hand (issue #837); and `diff --as`
+ * is, because a skeleton has as many shots as it has and one pairing per flag is the only spelling that keeps each pair a pair
  * (issue #720). Everywhere else a repeat is a mistake and is refused: `check
  * --candidate a --candidate b` used to take `b` silently, which is a report
  * about a rig the caller did not think they were asking about.
@@ -258,6 +271,7 @@ const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images',
 const REPEATABLE_FLAGS: Record<string, ReadonlySet<string>> = {
   vote: new Set(['candidate']),
   diff: new Set(['as']),
+  preview: new Set(['candidate']),
 };
 
 /**
@@ -1484,6 +1498,12 @@ function cmdBuild(flags: Record<string, string>): void {
   writeFileSync(join(opts.outDir, 'skeleton.atlas'), atlasText);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.atlas')}`);
+  // The next command is part of the message (issue #837). A green build is the
+  // moment somebody wants to see what came out, and the one page rigc writes
+  // for that is `preview` of exactly this directory — so the line names it,
+  // with the path already resolved. Printed only here: a red build wrote
+  // nothing, so there is nothing to look at and no line.
+  console.log(`rigc: look at it: rigc preview --candidate ${opts.outDir}`);
 }
 
 /**
@@ -1700,7 +1720,13 @@ function readCheckFlags(
   return out;
 }
 
-function runCheck(candidate: string, atlasFlag: string | undefined, framesDir: string, flags: Record<string, string>): CheckReport {
+function runCheck(
+  candidate: string,
+  atlasFlag: string | undefined,
+  framesDir: string,
+  flags: Record<string, string>,
+  plates?: CheckPlates,
+): CheckReport {
   const { skeletonPath, atlasPath } = resolveArtifacts(candidate, atlasFlag);
   return checkAgainstFrames({
     skeletonText: readFileSync(skeletonPath, 'utf8'),
@@ -1709,16 +1735,59 @@ function runCheck(candidate: string, atlasFlag: string | undefined, framesDir: s
     framesDir,
     labels: { skeleton: skeletonPath, atlas: atlasPath },
     ...readCheckFlags(flags),
+    ...(plates === undefined ? {} : { plates }),
   });
 }
 
+/**
+ * `check --out <dir>`, refused before anything is compared when it cannot be
+ * written — see `src/checkpics.ts` for what goes there.
+ *
+ * Two refusals and no others. A **file** at the path is not a directory of
+ * pictures, and saying so beats the `ENOTDIR` a write would throw after the
+ * whole comparison had run. And a directory that **is `--frames` or holds it**
+ * is refused because `<out>/<set>/` is cleared and `<out>/frames.json` written,
+ * as `render` does to its own: there, that is the reference set being deleted by
+ * the command that reads it — `check --frames render --out render` would clear
+ * `render/heavy` and put a picture sidecar where the frames' own was. A fresh
+ * path, and an existing directory anywhere else, are written to.
+ */
+function readCheckOut(outFlag: string, framesFlag: string): string {
+  const out = resolve(outFlag);
+  if (existsSync(out) && !statSync(out).isDirectory()) {
+    throw new UsageError(`check: --out ${out} is a file; it names a directory`);
+  }
+  const frames = resolve(framesFlag);
+  const within = relative(out, frames);
+  if (within === '' || (!within.startsWith('..') && !isAbsolute(within))) {
+    throw new UsageError(
+      `check: --out ${out} ${within === '' ? 'is' : 'holds'} --frames ${frames}; the pictures would be written ` +
+        'over the frames they are pictures of (each set directory under --out is cleared first) — name a directory ' +
+        'outside it',
+    );
+  }
+  return out;
+}
+
 function cmdCheck(flags: Record<string, string>): void {
   if (flags.candidate === undefined) throw new UsageError('check needs --candidate <dir | skeleton.json>');
   if (flags.frames === undefined) throw new UsageError('check needs --frames <dir> — a rendered reference frame set');
-  const report = runCheck(flags.candidate, flags.atlas, flags.frames, flags);
+  const out = flags.out === undefined ? null : readCheckOut(flags.out, flags.frames);
+  const allFrames = flags['all-frames'] !== undefined;
+  // Only asked for when there is somewhere to put the pictures: without --out
+  // nothing is kept, and the run is the run it was before --out existed.
+  const plates = out === null ? undefined : new CheckPlates({ allFrames });
+  const report = runCheck(flags.candidate, flags.atlas, flags.frames, flags, plates);
   console.log('rigc check');
-  for (const line of checkLines(report, { allFrames: flags['all-frames'] !== undefined })) console.log(line);
+  for (const line of checkLines(report, { allFrames })) console.log(line);
   if (flags.json !== undefined) writeJson(flags.json, report);
+  if (out !== null && plates !== undefined) {
+    for (const set of writeCheckPictures(out, report, plates, { allFrames })) {
+      const which = set.frames.length === 0 ? 'nothing compared' : set.every ? 'every compared frame' : 'the frames worth reading';
+      console.log(`  ..    ${set.dir.padEnd(16)} ${set.frames.length} picture(s), ${which} -> ${set.path}`);
+    }
+    console.log(`rigc: wrote ${join(out, FRAMES_SIDECAR)}`);
+  }
 }
 
 function writeJson(target: string, body: unknown): void {
@@ -1801,6 +1870,35 @@ function readSkinFlag(flags: Record<string, string>, declared: string[]): string
   return name;
 }
 
+/**
+ * `--slot` / `--hide`, resolved against the skeleton under the skin this run
+ * poses it in — or refused as a usage error, nothing written (issue #835).
+ *
+ * The rule itself is `slotSubsetOf`'s in `src/render.ts`, which `piecesOf`
+ * applies too: it is read here only so a miss exits 2 with the usage beside
+ * it before a directory is created, rather than surfacing from the sampler.
+ */
+function readSlotSubsetFlags(
+  flags: Record<string, string>,
+  data: Posable['data'],
+  skin: string | undefined,
+): SlotSubset | undefined {
+  const list = (raw: string | undefined): string[] | undefined =>
+    raw === undefined ? undefined : raw.split(',').map((name) => name.trim()).filter((name) => name !== '');
+  try {
+    return slotSubsetOf(data, { slots: list(flags.slot), hidden: list(flags.hide) }, skin);
+  } catch (err) {
+    if (err instanceof SlotSubsetError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
+/** A resolved subset as the one field it is spelled as, in `PoseOptions` and in `frames.json` alike. */
+function subsetFields(subset: SlotSubset | undefined): { slots?: string[]; hidden?: string[] } {
+  if (subset === undefined) return {};
+  return subset.mode === 'slots' ? { slots: subset.names } : { hidden: subset.names };
+}
+
 function readPositiveNumber(flags: Record<string, string>, key: string, fallback: number, least: number): number {
   const raw = flags[key];
   if (raw === undefined) return fallback;
@@ -1869,12 +1967,19 @@ function cmdRender(flags: Record<string, string>): void {
   const { data, pages } = loadPosable(skeletonPath, atlasPath, atlasDir);
   const only = readAnimationFlag(flags, data.animations.map((a) => a.name));
   const skin = readSkinFlag(flags, data.skins.map((s) => s.name));
+  const subset = readSlotSubsetFlags(flags, data, skin);
   // One object, so the framing and the frames cannot be posed under two
   // different skins — which would frame one shot with another shot's box.
   // Not annotated `PoseOptions`: that name is `src/pose.ts`'s in this file, and
   // `src/render.ts` has one of its own. The inferred shape is the render one.
-  const pose = skin === undefined ? undefined : { skin };
+  // The subset rides on the same object and `framingViewport` takes it off, so
+  // the frames draw the subset and the box is still the whole rig's.
+  const pose =
+    skin === undefined && subset === undefined
+      ? undefined
+      : { ...(skin === undefined ? {} : { skin }), ...subsetFields(subset) };
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
+  if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
 
   const viewport = framingViewport(data, maxSide, pose);
   if (!viewport) {
@@ -1936,6 +2041,9 @@ function cmdRender(flags: Record<string, string>): void {
     // which is both what this run did and what every frame set written before
     // #571 did. See `FramesSidecar.skin`.
     ...(skin === undefined ? {} : { skin }),
+    // Written only when a subset was asked for, for the same reason: a render of
+    // every slot says nothing and stays the bytes it always was (issue #835).
+    ...subsetFields(subset),
     background: BACKGROUND,
     viewport: {
       x: viewport.minX,
@@ -1969,6 +2077,29 @@ function skeletonAnimationNames(skeletonText: string, path: string): string[] {
   return Object.keys(animations);
 }
 
+/**
+ * The gate's reading of one candidate, taken the way `rigc validate <dir>`
+ * takes it (issue #837).
+ *
+ * ⭐ The same call `cmdValidate` makes on a bare directory: the two texts, the
+ * atlas's own directory, the default profile, and nothing a directory cannot
+ * supply — no rig spec, no declared durations, no second compile. So `A09` and
+ * `A18` report SKIP here exactly as they do there, and the line is the line
+ * that command prints for these files, not the one `build` printed for the
+ * compile that wrote them. Measured on every run, because the page must not
+ * carry a figure this run did not measure.
+ */
+function previewGate(skeletonText: string, atlasText: string, atlasDir: string): PreviewGate {
+  const lines = reportLines(validate({ skeletonText, atlasText, atlasDir, profile: CLI_DEFAULT_PROFILE }));
+  const refusal = lines.find((line) => line.startsWith('  FAIL  '));
+  return {
+    // `reportLines` ends on the summary by construction; the gutter is the
+    // report's layout, not part of what the gate said.
+    summary: lines[lines.length - 1].replace(/^ {2}\.\. {4}/, ''),
+    refusal: refusal === undefined ? null : refusal.trimStart(),
+  };
+}
+
 /**
  * preview — the artifact playing in Esoteric's own web player, as one file.
  *
@@ -1977,52 +2108,130 @@ function skeletonAnimationNames(skeletonText: string, path: string): string[] {
  * can draw rather than for the ones our own decoder reads — which is the right
  * direction for the command whose whole job is "just show me".
  */
-function cmdPreview(flags: Record<string, string>): void {
-  const { skeletonPath, atlasPath, atlasDir } = resolveViewable(flags);
-  const skeletonText = readFileSync(skeletonPath, 'utf8');
-  const atlasText = readFileSync(atlasPath, 'utf8');
-  const animations = skeletonAnimationNames(skeletonText, skeletonPath);
-  const chosen = readAnimationFlag(flags, animations);
+function cmdPreview(flags: Record<string, string>, candidates: string[]): void {
+  // Refused rather than ignored: a preview asked to hide `head` that plays the
+  // whole rig is a picture that answers a question it was not asked (issue #835).
+  for (const flag of ['slot', 'hide'] as const) {
+    if (flags[flag] !== undefined) {
+      throw new UsageError(
+        `preview takes no --${flag}: the Spine Web Player draws what the skeleton draws. A subset of the slots is ` +
+          `\`rigc render --${flag} ${flags[flag]}\`, on the whole rig's grid`,
+      );
+    }
+  }
+  const several = candidates.length > 1;
+  // `--atlas` names ONE atlas, and with several skeletons there is no
+  // unambiguous thing it could mean — the refusal `vote` makes, for the reason
+  // it makes it.
+  if (several && flags.atlas !== undefined) {
+    throw new UsageError(
+      `--atlas names one atlas and ${candidates.length} --candidate were given; each candidate's atlas has to sit ` +
+        'beside its skeleton, which is what `build --out` leaves behind',
+    );
+  }
+  const found = several
+    ? candidates.map((target) => {
+        const { skeletonPath, atlasPath } = resolveArtifacts(target, undefined);
+        for (const path of [skeletonPath, atlasPath]) {
+          if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
+        }
+        return { target, skeletonPath, atlasPath, atlasDir: dirname(atlasPath) };
+      })
+    : [{ target: flags.candidate, ...resolveViewable(flags) }];
+  // ⚠️ By the FILE each one resolves to, not by the text typed: `build/` and
+  // `build/skeleton.json` are two spellings of one candidate, and so are
+  // `/tmp/x` and `/private/tmp/x` on a machine where one is a link to the other
+  // — `resolve` alone left that pair unrefused, measured on macOS. A page
+  // showing one skeleton twice is two panes that look like a comparison of
+  // nothing. (`vote` accepts a repeat today, exit 0; that is its own card.)
+  const identities = found.map((f) => realpathSync(f.skeletonPath));
+  for (let i = 1; i < found.length; i++) {
+    const first = identities.indexOf(identities[i]);
+    if (first < i) {
+      throw new UsageError(
+        `--candidate ${JSON.stringify(found[i].target)} is ${identities[i]}, which --candidate ` +
+          `${JSON.stringify(found[first].target)} already names (candidates ${first + 1} and ${i + 1}); a pane per ` +
+          'candidate would show the same skeleton twice',
+      );
+    }
+  }
+
+  // Every candidate's texts and animation are read before a line is printed,
+  // so a refusal about any of them comes before the report, as it always has.
+  const loaded = found.map((f, i) => {
+    const skeletonText = readFileSync(f.skeletonPath, 'utf8');
+    const atlasText = readFileSync(f.atlasPath, 'utf8');
+    const animations = skeletonAnimationNames(skeletonText, f.skeletonPath);
+    let chosen: string | undefined;
+    try {
+      chosen = readAnimationFlag(flags, animations);
+    } catch (err) {
+      // With several candidates the refusal has to say WHICH one lacks it.
+      if (several && err instanceof UsageError) {
+        throw new UsageError(`candidate ${i + 1} (${f.skeletonPath}): ${err.message}`);
+      }
+      throw err;
+    }
+    return { ...f, skeletonText, atlasText, animations, chosen };
+  });
 
   // A directory for --out is taken as "put the default name in here", because
   // `--out render/` is what the sibling command means by the same flag and a
   // preview written OVER a directory is not a recoverable mistake.
   const target = resolve(flags.out ?? 'preview.html');
   const out = existsSync(target) && statSync(target).isDirectory() ? join(target, 'preview.html') : target;
+  const version = readVersion();
 
   console.log('rigc preview');
-  console.log(`  ..    skeleton ${skeletonPath}`);
-  console.log(`  ..    atlas    ${atlasPath}`);
-
-  const pages: PreviewPage[] = atlasPageNames(atlasText).map((name) => {
-    const path = join(atlasDir, name);
-    if (!existsSync(path)) {
-      throw new UsageError(
-        `the atlas declares page "${name}", which resolves to ${path} and is not there — ` +
-          'a page a preview cannot embed is a page the player could not have loaded either',
+  const inputs: PreviewInput[] = loaded.map((candidate, i) => {
+    const { skeletonPath, atlasPath, atlasDir, skeletonText, atlasText, animations, chosen } = candidate;
+    if (several) console.log(`  ..    pane ${i + 1} of ${loaded.length}`);
+    console.log(`  ..    skeleton ${skeletonPath}`);
+    console.log(`  ..    atlas    ${atlasPath}`);
+    const pages: PreviewPage[] = atlasPageNames(atlasText).map((name) => {
+      const path = join(atlasDir, name);
+      if (!existsSync(path)) {
+        throw new UsageError(
+          `the atlas declares page "${name}", which resolves to ${path} and is not there — ` +
+            'a page a preview cannot embed is a page the player could not have loaded either',
+        );
+      }
+      return { name, bytes: readFileSync(path) };
+    });
+    for (const page of pages) {
+      console.log(`  ..    page     ${page.name.padEnd(28)} ${(page.bytes.length / 1024).toFixed(1)} KiB`);
+    }
+    if (!declaresSetupStage(skeletonHeaderOf(skeletonText))) console.log(`  ..    ${STAGELESS_FRAMING.preview}`);
+    const gate = previewGate(skeletonText, atlasText, atlasDir);
+    console.log(`  ..    gate     ${gate.summary}`);
+    if (gate.refusal !== null) {
+      console.log(
+        `  ..    gate     refused — ${gate.refusal}. Previewed anyway: looking at a red build is what preview is ` +
+          'for, and the page header says the same',
       );
     }
-    return { name, bytes: readFileSync(path) };
+    return {
+      skeletonText,
+      atlasText,
+      pages,
+      animation: chosen ?? animations[0] ?? null,
+      animations,
+      label: skeletonPath,
+      version,
+      gate,
+    };
   });
-  for (const page of pages) {
-    console.log(`  ..    page     ${page.name.padEnd(28)} ${(page.bytes.length / 1024).toFixed(1)} KiB`);
-  }
-  if (!declaresSetupStage(skeletonHeaderOf(skeletonText))) console.log(`  ..    ${STAGELESS_FRAMING.preview}`);
 
-  const html = buildPreview({
-    skeletonText,
-    atlasText,
-    pages,
-    animation: chosen ?? animations[0] ?? null,
-    animations,
-    label: skeletonPath,
-    version: readVersion(),
-  });
+  const html = several ? buildPreviewPanes(inputs, version) : buildPreview(inputs[0]);
   mkdirSync(dirname(out), { recursive: true });
   writeFileSync(out, html);
+  const pageCount = inputs.reduce((n, input) => n + input.pages.length, 0);
   console.log(
-    `  ..    embedded ${pages.length} page(s) + the skeleton and atlas as data URIs; ` +
-      `the player itself loads from unpkg (@${PLAYER_LINE}), so the first open needs a network`,
+    several
+      ? `  ..    embedded ${pageCount} page(s) + ${inputs.length} skeletons and atlases as data URIs, one pane each; ` +
+          `the player itself loads from unpkg (@${PLAYER_LINE}), so the first open needs a network`
+      : `  ..    embedded ${pageCount} page(s) + the skeleton and atlas as data URIs; ` +
+          `the player itself loads from unpkg (@${PLAYER_LINE}), so the first open needs a network`,
   );
   console.log(`rigc: wrote ${out}  (${(html.length / 1024).toFixed(1)} KiB — open it in a browser)`);
 }
@@ -2195,8 +2404,8 @@ function cmdChainFit(flags: Record<string, string>): void {
 // choosing between results — vote
 // ---------------------------------------------------------------------------
 //
-// ⭐ `preview` shows one candidate; this shows two to four of them side by side
-// and takes an answer back. The rest of this toolchain is instruments, and it
+// ⭐ `preview` shows candidates and asks nothing; this shows two to four of them
+// side by side, hides where each came from, and takes an answer back. The rest of this toolchain is instruments, and it
 // should be — the vote opens only where the instruments have already run out.
 // See `src/ballot.ts` for why the ballot is ordered compile-first-vote-last,
 // why the labels are A and B, and why the record is hashes.
@@ -3594,6 +3803,14 @@ const FLAG_MEANINGS: Record<string, string> = {
     'through the default skin alone, so a slot whose art lives only in a named skin draws nothing. A name the ' +
     'skeleton does not declare is refused with the ones it does. `render` records the skin in frames.json and ' +
     '`check` reads it back, so a skin-A candidate is not scored against skin-B frames in silence',
+  slot:
+    'draw only these slots, comma-separated, in the skeleton\'s draw order, on the SAME grid as the whole rig: the ' +
+    'viewport is still fitted to every slot, so this frame overlays the full one pixel for pixel. A name the ' +
+    'skeleton does not declare is refused with every one it does; a slot whose art lives only under another skin ' +
+    'is refused naming that skin. frames.json records the subset, and `check` refuses such a set as a reference',
+  hide:
+    'draw every slot but these, comma-separated — `--slot` the other way round, on the same grid, recorded and ' +
+    'refused the same way. Not with `--slot`: the two are one statement',
   max: 'longest side of a rendered frame, in pixels (default 256)',
   record: 'a saved vote to check against its ballot and append to the ledger, instead of writing a ballot',
   ballot: `the ballot the --record'd vote answers (default \`${DEFAULT_BALLOT}\`); its embedded manifest is what the vote is checked against`,
@@ -3662,6 +3879,8 @@ const FLAG_VALUES: Record<string, string> = {
   'inward-lever': '<px>',
   animation: '<name>',
   skin: '<name>',
+  slot: '<name[,name…]>',
+  hide: '<name[,name…]>',
   max: '<px>',
   record: '<result.json>',
   ballot: '<ballot.html>',
@@ -3812,7 +4031,7 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'check',
     usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
-    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'all-frames', 'json'],
+    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'all-frames', 'json', 'out'],
     overrides: {
       skin: {
         meaning:
@@ -3821,6 +4040,16 @@ const COMMANDS: CommandDoc[] = [
           'contested art. The frames are checked back: a set whose frames.json records a different skin is ' +
           'REFUSED by name, and one that records none says so in the report rather than pretending to agree',
       },
+      out: {
+        value: '<dir>',
+        meaning:
+          'also write the PICTURE each listed frame\'s figures came from, as <dir>/<set>/f####.png: reference, ' +
+          'candidate, difference and overlay side by side at the comparison grid\'s native size, with the table\'s ' +
+          'figures burned in and one row per slot under them, beside a frames.json that says what they are pictures ' +
+          'of. The frames are the ones the table lists, so --all-frames writes every compared one. Each <dir>/<set>/ ' +
+          'is cleared first; a file at <dir>, or a directory that is or holds --frames, is refused. See ' +
+          'docs/AUTHORING.md §9.2.1',
+      },
     },
     notes: [
       'every figure here is a reporting threshold, not a pass bar. Nothing in this report',
@@ -3863,8 +4092,9 @@ const COMMANDS: CommandDoc[] = [
     name: 'render',
     usage: [
       'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--out render/]',
+      'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'fps', 'max', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
@@ -3872,9 +4102,22 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'preview',
-    usage: ['rigc preview --candidate <dir | skeleton.json> [--animation <name>] [--out preview.html]'],
+    usage: ['rigc preview --candidate <dir | skeleton.json> [--candidate <another> …] [--animation <name>] [--out preview.html]'],
     flags: ['candidate', 'atlas', 'animation', 'out'],
     overrides: {
+      candidate: {
+        value: '<dir|skeleton.json>',
+        meaning:
+          'a compiled skeleton: a directory holding skeleton.json + skeleton.atlas, or a skeleton.json path. Repeat it ' +
+          'for one page with a pane per candidate, in the order given; the same skeleton twice is refused. Each ' +
+          'header carries the line `rigc validate <dir>` prints for that candidate, measured when the page is written',
+      },
+      atlas: { meaning: "the candidate's atlas, when it is not beside the skeleton — one candidate only" },
+      animation: {
+        meaning:
+          "the animation to start on (default: each candidate's own first). With several candidates every one of " +
+          'them must have it, or the run is refused naming the one that does not',
+      },
       out: {
         value: '<file>',
         meaning: 'the .html file to write (default `preview.html`); a directory means "the default name in here"',
@@ -4128,7 +4371,7 @@ try {
   else if (command === 'bench') cmdBench(flags, positional);
   else if (command === 'bonedist') cmdBoneDist(flags);
   else if (command === 'render') cmdRender(flags);
-  else if (command === 'preview') cmdPreview(flags);
+  else if (command === 'preview') cmdPreview(flags, lists.candidate ?? []);
   else if (command === 'pose') cmdPose(flags);
   else if (command === 'chainfit') cmdChainFit(flags);
   else if (command === 'vote') cmdVote(flags, lists.candidate ?? []);