spine-rigc 1.0.2 → 1.2.0

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) {

package/src/checkpics.ts

@@ -0,0 +1,293 @@
+/**
+ * rigc check --out — the picture each of `check`'s numbers came from.
+ *
+ * ## Why this exists
+ *
+ * `check` renders the candidate onto the reference frames' own grid, subtracts,
+ * and prints the result as numbers. A number says *how much*; only a picture says
+ * *where*. An agent porting a sample drew the same face composite twice at a
+ * 20 px offset — a ghost hairline — with a green gate and a contact sheet of
+ * ~100 px tiles in hand, and did not see it (issue #834). The comparison that
+ * would have shown it was already computed and thrown away.
+ *
+ * So for every frame the report lists under *the frames worth reading* (every
+ * compared frame under `--all-frames`), this composes one image, left to right:
+ *
+ * 1. **reference** — the frame as read from `--frames`;
+ * 2. **candidate** — the candidate exactly as `check` rendered it onto that grid;
+ * 3. **difference** — per pixel, the largest of the three channel differences
+ *    `|candidate − reference|`, 0..255 on a fixed grey ramp, over the pixels the
+ *    MAE averages over (the union alpha) and transparent everywhere else;
+ * 4. **overlay** — the two at 50 % each, so a displaced edge reads as a double line.
+ *
+ * Each pane is at the grid's **native size**. An upscaled difference is a
+ * difference the instrument invented: a resampling filter moves ink into pixels
+ * the comparison never measured. The picture is only ever the comparison.
+ *
+ * ## 🔒 Nothing here is a new number
+ *
+ * Every figure burned into a picture is read off the `CheckReport` the table was
+ * printed from, at the precision the table prints it — the difference pane's MAE,
+ * the per-side change counts, the union — and the per-slot rows are the frame's
+ * own `slots`. The rasters are the ones the figures were computed on, kept by
+ * `CheckPlates` at the moment they were compared, not re-rendered afterwards: a
+ * second render that happened to agree would be a claim, and this is a record.
+ *
+ * ⚠️ Two things a picture cannot say, and it says neither: which side is right,
+ * and anything about a frame it does not show.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  COMPARISON_FIELD,
+  framesToList,
+  type AnimationCheck,
+  type CheckPlates,
+  type CheckReport,
+  type ComparedPlates,
+  type Framing,
+  type FrameCheck,
+} from './check.ts';
+import { FRAMES_SIDECAR, FRAMES_SPEC } from './render.ts';
+import { isContent } from './framing.ts';
+import { isAttributable } from './slots.ts';
+import { encodePng, Plate, type RGBA } from '../tools/plate.ts';
+import { GLYPH_H, textWidth } from '../tools/font5x7.ts';
+
+/** The four panes, left to right, by the names their labels carry. */
+export const PANES = ['reference', 'candidate', 'difference', 'overlay'] as const;
+export type Pane = (typeof PANES)[number];
+
+/** Transparent pixels between two panes, and between the panes and the slot rows. */
+export const PANE_GAP = 4;
+/** Pixels of strip around a line of text, above and below. */
+const TEXT_PAD = 2;
+/** One line of 5x7 text with its padding: the label strip, and each slot row. */
+export const TEXT_ROW = GLYPH_H + 2 * TEXT_PAD;
+/** The strips' own colour, and the text's — opaque, so the labels read on any viewer background. */
+const STRIP: RGBA = [0, 0, 0, 255];
+const INK: RGBA = [255, 255, 255, 255];
+
+const f2 = (n: number): string => n.toFixed(2);
+const frameName = (index: number): string => `f${String(index).padStart(4, '0')}`;
+
+/** Where one pane sits in a picture, in picture pixels. */
+export interface PaneRect {
+  pane: Pane;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * The geometry of one picture — exported so a reader can find a pane without
+ * knowing how the picture was drawn, which is what the selftest does.
+ *
+ * A column is as wide as its pane, or as its label when the label is wider: the
+ * PANE stays at native size either way, and a label clipped to fit a small grid
+ * would drop the one figure it exists to carry.
+ */
+export function pictureLayout(
+  gridWidth: number,
+  gridHeight: number,
+  labels: readonly string[],
+  rows: readonly string[],
+): { width: number; height: number; panes: PaneRect[]; rowsTop: number } {
+  const columns = labels.map((label) => Math.max(gridWidth, textWidth(label, 1) + 2 * TEXT_PAD));
+  const panes: PaneRect[] = [];
+  let x = 0;
+  PANES.forEach((pane, i) => {
+    panes.push({ pane, x, y: TEXT_ROW, width: gridWidth, height: gridHeight });
+    x += columns[i] + (i < PANES.length - 1 ? PANE_GAP : 0);
+  });
+  const widestRow = rows.reduce((w, row) => Math.max(w, textWidth(row, 1) + 2 * TEXT_PAD), 0);
+  const rowsTop = TEXT_ROW + gridHeight + PANE_GAP;
+  return { width: Math.max(x, widestRow), height: rowsTop + rows.length * TEXT_ROW, panes, rowsTop };
+}
+
+/** The label above each pane: the frame, the pane, and the pane's own figure from the table. */
+export function paneLabels(frame: FrameCheck): string[] {
+  const at = frameName(frame.index);
+  const moved = (n: number | undefined): string => (n === undefined ? '-' : String(n));
+  return [
+    // The table's `ref Δ` and `Δpx` columns: how far each side moved since its own previous frame.
+    `${at} reference ref d ${moved(frame.change?.reference)}`,
+    `${at} candidate dpx ${moved(frame.change?.candidate)}`,
+    `${at} difference mae ${f2(frame.mae)}`,
+    `${at} overlay union ${frame.unionPixels}`,
+  ];
+}
+
+/**
+ * One row per slot in the frame's own `slots`, in the order the report holds them.
+ *
+ * The drift is printed at the table's precision, and a slot with no attributable
+ * drift says which of the two reasons it is rather than printing a number — the
+ * rule `src/slots.ts` owns for every figure beside a part's name. The frame's
+ * worst slot, the one the table's row names, is marked `>`.
+ */
+export function slotRows(frame: FrameCheck): string[] {
+  return frame.slots.map((track) => {
+    const mark = track.slot === frame.worstSlot ? '>' : ' ';
+    if (!isAttributable(track)) {
+      return `${mark} ${track.slot} -  ${track.candidate === null ? 'not drawn' : 'no attributable drift'}`;
+    }
+    const how = track.method === 'template' ? `tmpl ${(track.confidence ?? 0).toFixed(2)}` : 'component';
+    return `${mark} ${track.slot} ${(track.drift as number).toFixed(1)} px  ${how}`;
+  });
+}
+
+/** Compose one frame's picture from the rasters its figures were computed on. */
+export function composePicture(frame: FrameCheck, plates: ComparedPlates, background: RGBA): Plate {
+  const { reference, candidate, coverage } = plates;
+  const w = reference.width;
+  const h = reference.height;
+  const labels = paneLabels(frame);
+  const rows = slotRows(frame);
+  const layout = pictureLayout(w, h, labels, rows);
+  const out = new Plate(layout.width, layout.height);
+
+  layout.panes.forEach((rect, i) => {
+    out.rect(rect.x, 0, Math.max(rect.width, textWidth(labels[i], 1) + 2 * TEXT_PAD), TEXT_ROW, STRIP);
+    out.text(labels[i], rect.x + TEXT_PAD, TEXT_PAD, 1, INK);
+  });
+  const [ref, cand, diff, over] = layout.panes;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const a = candidate.get(x, y);
+      const b = reference.get(x, y);
+      out.set(ref.x + x, ref.y + y, b);
+      out.set(cand.x + x, cand.y + y, a);
+      // The union `checkOneFrame` averages over: what the candidate's geometry
+      // covers, or what the reference drew — the same predicate, not a lookalike.
+      if (coverage[y * w + x] === 1 || isContent(reference, x, y, background)) {
+        const v = Math.max(Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]), Math.abs(a[2] - b[2]));
+        out.set(diff.x + x, diff.y + y, [v, v, v, 255]);
+      }
+      out.set(over.x + x, over.y + y, [
+        Math.round((a[0] + b[0]) / 2),
+        Math.round((a[1] + b[1]) / 2),
+        Math.round((a[2] + b[2]) / 2),
+        Math.round((a[3] + b[3]) / 2),
+      ]);
+    }
+  }
+  rows.forEach((row, i) => {
+    const top = layout.rowsTop + i * TEXT_ROW;
+    out.rect(0, top, layout.width, TEXT_ROW, STRIP);
+    out.text(row, TEXT_PAD, top + TEXT_PAD, 1, INK);
+  });
+  return out;
+}
+
+/** What `--out` wrote for one frame set. */
+export interface PicturesWritten {
+  /** The set's directory, as the report names it. */
+  dir: string;
+  /** Absolute path of the directory the pictures went into. */
+  path: string;
+  /** The frame indices written, in index order. */
+  frames: number[];
+  /** Whether that is every compared frame rather than the frames worth reading. */
+  every: boolean;
+}
+
+/**
+ * Write the pictures for a report into `outDir`, and `frames.json` beside them.
+ *
+ * `<outDir>/<set>/` is cleared and rewritten for every set the report holds, as
+ * `render` clears its own: a set that lists fewer frames this run would otherwise
+ * keep last run's pictures beside this run's, and a stale picture of a comparison
+ * is indistinguishable from a current one. Nothing else under `outDir` is touched.
+ *
+ * ⚠️ Throws, naming the frame, when `plates` does not hold a frame the report
+ * lists. That is not a reachable input: it is `CheckPlates`'s retention and
+ * `framesToList` disagreeing about which frames are worth reading, and a picture
+ * set with a hole in it would be the silent version of that disagreement.
+ */
+export function writeCheckPictures(
+  outDir: string,
+  report: CheckReport,
+  plates: CheckPlates,
+  opts: { allFrames: boolean },
+): PicturesWritten[] {
+  mkdirSync(outDir, { recursive: true });
+  const written: PicturesWritten[] = [];
+  for (const anim of report.animations) {
+    const dir = join(outDir, anim.dir);
+    if (existsSync(dir)) rmSync(dir, { recursive: true });
+    const listed = anim.compared === 0 ? [] : framesToList(anim, opts.allFrames);
+    if (listed.length > 0) mkdirSync(dir, { recursive: true });
+    for (const frame of listed) {
+      const held = plates.of(anim.dir, frame.index);
+      if (held === undefined) {
+        throw new Error(
+          `check --out: set ${JSON.stringify(anim.dir)} lists ${frameName(frame.index)} as worth reading and no ` +
+            'raster was kept for it — CheckPlates and framesToList disagree about the listing (a defect in rigc)',
+        );
+      }
+      const picture = composePicture(frame, held, report.background);
+      writeFileSync(join(dir, `${frameName(frame.index)}.png`), encodePng(picture.width, picture.height, picture.data));
+    }
+    written.push({
+      dir: anim.dir,
+      path: dir,
+      frames: listed.map((f) => f.index),
+      every: listed.length === anim.frames.length,
+    });
+  }
+  writeFileSync(join(outDir, FRAMES_SIDECAR), `${JSON.stringify(picturesSidecar(report, written, opts.allFrames), null, 2)}\n`);
+  return written;
+}
+
+/**
+ * What the pictures are OF — the file a reader opens first, under the name a
+ * frame set's sidecar has, so "what is this directory" is answered in the place
+ * it is always answered.
+ *
+ * 🔒 The field named by `COMPARISON_FIELD` is what makes it not a frame set, and
+ * `check --frames` refuses a sidecar that carries it, by that name: the reference
+ * pane inside each picture is a frame, but the file is a comparison, and scoring
+ * a candidate against a picture of a comparison is a number about the wrong
+ * thing. There is deliberately no top-level `viewport`: under the per-shot scope
+ * every set was measured in its own box, so the box is recorded per set, and one
+ * box at the top would be a claim the run did not make.
+ */
+function picturesSidecar(report: CheckReport, written: PicturesWritten[], allFrames: boolean): Record<string, unknown> {
+  return {
+    spec: FRAMES_SPEC,
+    [COMPARISON_FIELD]: {
+      candidate: report.candidate,
+      frames: report.framesDir,
+      skin: report.skin,
+      referenceSkin: report.referenceSkin,
+      framingScope: report.framingScope,
+      grid: gridOf(report),
+      panes: [...PANES],
+      listing: allFrames ? 'every compared frame (--all-frames)' : 'the frames worth reading',
+      textureFrom: report.textureFrom === null ? null : report.textureFrom.atlas,
+    },
+    background: report.background,
+    sets: report.animations.map((anim: AnimationCheck, i) => {
+      const viewport: Framing = anim.viewport;
+      return {
+        dir: anim.dir,
+        animation: anim.animation,
+        candidateAnimation: anim.candidateAnimation,
+        fps: anim.fps,
+        compared: anim.compared,
+        written: written[i].frames.length,
+        frames: written[i].frames,
+        framing: anim.framing,
+        viewport,
+      };
+    }),
+  };
+}
+
+/** The comparison grid — the reference frames' own pixel size, which every set shares. */
+function gridOf(report: CheckReport): { pixelWidth: number; pixelHeight: number } | null {
+  const v = report.referenceViewport ?? report.animations[0]?.viewport ?? null;
+  return v === null ? null : { pixelWidth: v.pixelWidth, pixelHeight: v.pixelHeight };
+}