spine-rigc 0.2.1 → 0.4.0

package/src/check.ts

@@ -77,6 +77,10 @@ import {
   PAD,
   FRAMES_SIDECAR,
   FRAMES_SPEC,
+  SHEET_COLUMNS,
+  SHEET_FILE,
+  SHEET_GAP,
+  type Footprint,
   type Frame,
   type FramesSidecar,
   type FrameSet,
@@ -93,18 +97,38 @@ import {
   fitIsSettled,
   fitSeparation,
   frameContentBox,
+  offsetIsWorthApplying,
+  OffsetScan,
+  shiftViewport,
+  unionBoxes,
   isContent,
   BACKGROUND_TOLERANCE,
   CYCLE_PIXELS,
+  REFINE_MIN_GAIN,
+  REFINE_MIN_GAIN_MAE,
+  REFINE_RADIUS,
   type BoxPair,
   type ContentBox,
   type FramingFit,
+  type OffsetGain,
 } from './framing.ts';
-import { componentsOf, isAttributable, matchSlots, type SlotTrack } from './slots.ts';
+import { componentField, isAttributable, matchSlots, searchRadius, type SlotTrack } from './slots.ts';
+import { chainsOf, type BoneChain } from './chains.ts';
 import { readPlate, type Plate, type RGBA } from '../tools/plate.ts';
-
-export { componentsOf, matchSlots, searchRadius, type Component, type MatchMethod, type SlotTrack } from './slots.ts';
-export type { BoxPair, ContentBox, FramingFit } from './framing.ts';
+import { GLYPH_H, textWidth } from '../tools/font5x7.ts';
+
+export {
+  componentField,
+  componentsOf,
+  matchSlots,
+  searchRadius,
+  type Component,
+  type ComponentField,
+  type MatchMethod,
+  type SlotTrack,
+} from './slots.ts';
+export { chainsOf, chainBySlot, type BoneChain } from './chains.ts';
+export type { BoxPair, ContentBox, FramingFit, OffsetGain } from './framing.ts';
 
 // ---------------------------------------------------------------------------
 // the reference side — frames only, and mechanically so
@@ -259,6 +283,25 @@ export interface FrameCheck {
   file: string;
   /** Mean absolute RGB difference over the union alpha, 0..255. */
   mae: number;
+  /**
+   * The same total difference over the REFERENCE's own drawn pixels alone.
+   *
+   * ⭐ The figure to optimise against, and the reason is the denominator. `mae`
+   * divides by the pixels either side drew, and the candidate owns half of that:
+   * drawing something large and mostly transparent adds many cheap pixels to the
+   * union and the *mean falls*, so an optimiser can buy a better score by growing
+   * (issue #119 — a muzzle flare walked its own scale to 13x doing exactly this).
+   * This denominator is the reference's, which nothing the candidate does can
+   * move, so the only way down is to draw the reference's picture.
+   *
+   * ⚠️ Not bounded by 255, and deliberately: a candidate that draws far more than
+   * the reference has more absolute error than the reference has pixels to carry
+   * it, and the figure says so instead of saturating.
+   *
+   * `mae` is still the right figure for comparing two builds of the same rig,
+   * where the union is near enough the same on both sides.
+   */
+  maeReference: number;
   /**
    * The same difference averaged over the WHOLE frame, background included.
    *
@@ -285,6 +328,111 @@ export interface FrameCheck {
   change: FrameChange | null;
 }
 
+/**
+ * One bone chain's slice of a set — the row an author reads before deciding what
+ * to re-key.
+ *
+ * The chains come from the CANDIDATE's bone tree (`src/chains.ts` owns the rule
+ * and the reasoning); the reference stays pixels, so this is a decomposition of
+ * your own figure and never a reading of the answer.
+ */
+export interface ChainCheck {
+  /** The chain, named as `src/chains.ts` names it. */
+  chain: string;
+  /** How many slots it owns. */
+  slots: number;
+  /** How many of those drew anything in at least one compared frame. */
+  drewSlots: number;
+  /** The worst attributable slot drift anywhere in it, in frame pixels. */
+  worstDrift: number;
+  /** Which slot that was, and in which frame — `null`/`-1` when none was attributable. */
+  worstDriftSlot: string | null;
+  worstDriftFrame: number;
+  /** The mean of every attributable slot drift in it, over `driftSamples` of them. */
+  meanDrift: number;
+  driftSamples: number;
+  /** How many frames contributed at least one of those samples. */
+  driftFrames: number;
+  /**
+   * The absolute RGB difference attributed to this chain, summed over the
+   * REFERENCE's own drawn pixels — never over the union.
+   *
+   * ⭐ The denominator lesson from issue #119, applied to a share. A reference
+   * pixel goes to the chain whose ink is nearest to it, so the chains partition
+   * the reference's drawn pixels and the shares add up to the whole. What the
+   * candidate controls is only *which* chain a pixel lands in, and growing a
+   * chain's ink pulls MORE of the reference's pixels — and their error — into it.
+   * There is no move here that makes a chain look better by drawing more, which is
+   * exactly what the union MAE could not say.
+   */
+  error: number;
+  /** How many reference-drawn pixels it took, summed over frames. */
+  referencePixels: number;
+  /**
+   * `error` per pixel it took — the MAE *inside* this chain, 0..255.
+   *
+   * Printed beside the share because the share alone confounds being wrong with
+   * being big: spineboy's head, goggles, eye and mouth are one chain covering a
+   * lot of the figure, so it can carry a third of the error at a per-pixel figure
+   * below the run's own mean. The share says where the error IS; this says whether
+   * the chain is actually worse than the rest of the figure.
+   */
+  mae: number;
+  /** `error` over the set's own total, 0..1 — see `AnimationCheck.chainDenominator`. */
+  maeShare: number;
+}
+
+/**
+ * The whole shot against the contact sheet beside it — the frames `check` has no
+ * file for.
+ *
+ * ## Why a sheet is a frame set and not a picture of one
+ *
+ * A long shot does not commit 311 near-duplicate PNGs. It commits a couple of
+ * stills and folds every sampled frame into one `contact.png`, and `check` used to
+ * read the two stills, say `2 compared`, and mean it — an honest number with a hole
+ * behind it: nothing whatever was measured about the other 309 frames, so a clean
+ * table said nothing about the shot (issue #36). A sheet is the same thing a frame
+ * is, at a smaller scale and with a frame number burned into the corner, and
+ * reading it reads no reference skeleton.
+ *
+ * So the candidate is sampled at the set's own rate, rendered into the same world
+ * box the set was framed in at the sheet's own scale, and each frame is compared
+ * against its own tile. The prototype this replaces was written in-run by the
+ * second rung-2 attempt, which found with it what the two-still table could not:
+ * flat MAE 4.85–4.95 over all 1,244 frames of four shots, no spikes — evidence
+ * that trajectories, ring rates and attachment swaps land where and when they
+ * should.
+ *
+ * ## What it deliberately does not measure: the per-frame change
+ *
+ * The tiles are adjacent, so `FrameChange` looks reachable here, and it is not:
+ * `CHANGE_EXCESS` is two dozen pixels at frame scale, and a quarter-scale tile has
+ * a sixteenth of the pixels to move. The thresholds would have to be re-derived
+ * against sheets before that column could mean anything, and a figure printed at
+ * the wrong scale is worse than one not printed. MAE only, and the report says so.
+ */
+export interface SheetCheck {
+  /** The sheet itself, so a worst-tile line is openable. */
+  file: string;
+  /** The grid, measured off the sheet — see `sheetGeometry`. */
+  columns: number;
+  tileWidth: number;
+  tileHeight: number;
+  /** Frame pixels per tile pixel: how much smaller a tile is than a frame. */
+  tileScale: number;
+  /** How many tiles the sheet holds, and how many the candidate could be compared on. */
+  tiles: number;
+  compared: number;
+  /** Mean and worst over the tiles, in the same two denominators the frames use. */
+  meanMae: number;
+  meanMaeReference: number;
+  worstMae: number;
+  worstTile: number;
+  /** The worst tiles by MAE, worst first — at most `WORST_FRAMES` of them. */
+  worst: Array<{ index: number; mae: number }>;
+}
+
 export interface AnimationCheck {
   dir: string;
   /** The animation the frames show, per the sidecar. */
@@ -296,6 +444,18 @@ export interface AnimationCheck {
   candidateFrames: number;
   compared: number;
   meanMae: number;
+  /** Mean of the per-frame reference-denominator MAE — see `FrameCheck.maeReference`. */
+  meanMaeReference: number;
+  /**
+   * How much this set draws, against how much the reference draws: the mean over
+   * its frames of `candidatePixels / referencePixels`.
+   *
+   * 1 means the two shots put ink on the same amount of the frame. Above 1 the
+   * candidate is drawing more than the reference does, which is the move that
+   * makes the union MAE cheaper — see `OVERDRAW_RATIO`, which is where the
+   * threshold and the corpus it came from are written down.
+   */
+  drawnRatio: number;
   /** Mean of the per-frame whole-frame MAE — see `FrameCheck.maeFrame`. */
   meanMaeFrame: number;
   worstMae: number;
@@ -311,7 +471,44 @@ export interface AnimationCheck {
   changeDisagreements: number;
   /** The widest of those disagreements, and `-1` when there is none. */
   worstChangeFrame: number;
+  /**
+   * This set, broken down by the candidate's own bone chains — see `ChainCheck`.
+   *
+   * Chains that own no slot at all are left out: they have nothing to attribute.
+   * They are still in `CheckReport.chains`, so the roster stays a complete account
+   * of where every bone went.
+   */
+  chains: ChainCheck[];
+  /**
+   * The set's whole difference over the reference's own drawn pixels — the
+   * denominator every `ChainCheck.maeShare` divides by.
+   *
+   * The same numerator `meanMaeReference` averages, kept as a total because a
+   * share needs the total and a mean has already divided it away.
+   */
+  chainDenominator: number;
+  /** The part of it no chain could take, because the candidate drew nothing at all. */
+  unattributedError: number;
   frames: FrameCheck[];
+  /**
+   * The box THIS set's candidate frames were rendered into.
+   *
+   * Under the default per-shot scope every set carries its own, and they are
+   * different boxes; under `--framing shared` they are all the same one. Either
+   * way it is here rather than only at the top of the report, because it is
+   * upstream of every number in this row.
+   */
+  viewport: Framing;
+  /** How this set's box was chosen — see `FramingSource`. */
+  framing: FramingHow;
+  /** Where this set's drawn pixels ended up against the reference's. */
+  framingFit: FramingReport | null;
+  /**
+   * The whole shot against the contact sheet, when the set ships one and does not
+   * ship every frame — see `SheetCheck`. `null` when there is nothing to add: no
+   * sheet, or every sampled frame already on disk as a frame of its own.
+   */
+  sheet: SheetCheck | null;
   notes: string[];
 }
 
@@ -339,9 +536,56 @@ export interface Framing {
  */
 export type FramingSource = 'derived' | 'declared' | 'pinned';
 
+/** The same three, named for the report line rather than for the code path. */
+export type FramingHow = 'candidate-pixels' | 'frames-viewport' | 'viewport-flag';
+
+/**
+ * Whether the framing is decided per frame set, or once across every set.
+ *
+ * ## What `per-shot` actually scopes, and why only that
+ *
+ * A framing is decided over the frames it is measured on, so pointing `check` at a
+ * skeleton root used to decide ONE for every set under it — and one badly-framed
+ * shot was then paid for by all the others. Measured on the spineboy rung, 8 shots
+ * and 147 frames: `idle` read **41.59** MAE at the root against the **18.77** it
+ * reads on its own frames, with not one key different (issue #100).
+ *
+ * `per-shot` moves exactly one decision into the set: **whether the box
+ * `frames.json` records is this set's box too.** That decision is a measurement
+ * with no floor — either the set's own drawn pixels land in the declared box or
+ * they do not — and over the union one shot that does not can put the pooled
+ * correction over `COINCIDENT_PIXELS` and take every other shot down with it. Per
+ * set, the ones that qualify read exactly what pinning by hand reads.
+ *
+ * ⚠️ It does NOT fit a separate chain per set, and that is a measured decision
+ * rather than a simplification. Per-set FITTING is worse: `fitFraming` registers
+ * extent, extent is not alignment, and one shot's frames do not constrain that
+ * enough — spineboy's `hit` reads 92.36 fitted on its own against 60.59 in the
+ * shared fit, and its two-frame `shoot@30fps` set reads 101.94 against 42.98. So a
+ * set that cannot take the declared box is measured in the shared framing, where
+ * every frame in the run constrains the answer.
+ *
+ * `shared` is the old behaviour, and it answers one question well: *does a single
+ * box serve every set?* The report prints that fit either way — see
+ * `CheckReport.sharedFraming`.
+ *
+ * ⚠️ The two are different measurements and their absolute numbers are not
+ * comparable across builds. The report says which one it did.
+ */
+export type FramingScope = 'per-shot' | 'shared';
+
 /** What the framing pass concluded, and how sure it is of it. */
 export interface FramingReport {
-  /** The residual fit measured at the viewport that was used. */
+  /**
+   * The residual fit measured at the box the framing chain chose.
+   *
+   * ⚠️ **Before** the MAE-refined pass below it, when that pass moved the box —
+   * and deliberately, because the two answer different questions and both are
+   * worth printing: this says how far the two *extents* were from registering,
+   * `refinement` says how far the *pictures* were from each other after that. Its
+   * `settled` / `agrees` / `cycled` words describe the chain that reached the box,
+   * which is a fact about the chain and does not change afterwards.
+   */
   fit: FramingFit;
   /** How many render/measure/correct passes ran. */
   passes: number;
@@ -389,6 +633,70 @@ export interface FramingReport {
    * what it does and does not mean attached.
    */
   units: { candidate: Extent; reference: Extent; ratio: number } | null;
+  /**
+   * What the MAE-refined final pass found, and whether it moved the box.
+   *
+   * `null` when nothing could be searched (no frame with reference ink). See
+   * `FramingRefinement`.
+   */
+  refinement: FramingRefinement | null;
+}
+
+/**
+ * The final framing pass, which asks a different question from every pass above
+ * it: not *do the two extents register?* but *is a constant pixel of this set's
+ * MAE a framing offset?*
+ *
+ * ## Why it exists, and why it is the last thing that happens
+ *
+ * Issue #146 measured the answer on the spineboy candidates: a **constant**
+ * translation of one or two pixels is worth 12 % of `death`'s headline
+ * reference-denominator MAE and up to 30 % of a fitted set's, while what is left
+ * after it is taken out is per-frame and small. That is `fitFraming`'s documented
+ * "extent is not alignment" floor arriving as a tenth of the number an author is
+ * reading as motion. `OffsetScan` searches whole-pixel offsets against the MAE
+ * itself, so it cannot walk off the answer the way the extent refinement measured
+ * and rejected in `frameByDeclaredBox` did — the figure it minimises is the figure
+ * the report prints.
+ *
+ * ## ⭐ Where it is allowed to move the box, and where it only reports
+ *
+ * **A fitted box is an estimate and gets corrected. An exact box does not.**
+ *
+ * - `derived` — the box came from a fit of extents, so a constant pixel in it is
+ *   the estimator's own floor. The offset is applied.
+ * - `declared` — `frames.json`'s box is not an estimate of where the frames were
+ *   drawn, it is where they were drawn (`frameByDeclaredBox`). A constant pixel
+ *   *there* is the candidate's own figure sitting a pixel off inside the right
+ *   box, which is a finding an author can act on and the framing must not absorb.
+ *   Searched, reported, never applied — and measured: over the committed corpus
+ *   every declared-box set's best offset is the exact identity, so this branch
+ *   has cost nothing so far and would only ever fire on a real offset.
+ * - `pinned` — `--viewport` is the author's claim about their own coordinates and
+ *   nothing here overrides it, exactly as the fit above is measured and not
+ *   applied.
+ */
+export interface FramingRefinement {
+  /** The best whole-pixel offset found, in frame pixels. `0, 0` means none was. */
+  dx: number;
+  dy: number;
+  /** Was it applied to the box the set was measured in? */
+  applied: boolean;
+  /** The set's mean reference-denominator MAE at the box the framing chose... */
+  before: number;
+  /** ...and at `dx, dy`, which is the same figure with the constant taken out. */
+  after: number;
+  /** How far the search looked, and how many frames it pooled. */
+  radius: number;
+  frames: number;
+  /**
+   * Why the offset was not applied — `null` when it was.
+   *
+   * `identity` is the answer this pass gives on a set whose framing is already
+   * where the picture is, and it is a measurement rather than a default: the
+   * search ran over the whole window and the identity won it.
+   */
+  declined: 'identity' | 'below-threshold' | 'box-is-exact' | 'pinned' | null;
 }
 
 /** A width and a height in world units. */
@@ -401,12 +709,35 @@ export interface CheckReport {
   candidate: { skeleton: string; atlas: string };
   framesDir: string;
   framesRoot: string;
-  /** How the candidate's own world box was chosen. */
-  framing: 'candidate-pixels' | 'frames-viewport' | 'viewport-flag';
+  /** One framing per set, or one across every set — see `FramingScope`. */
+  framingScope: FramingScope;
+  /**
+   * How the candidate's own world box was chosen, when ONE box covers the run.
+   *
+   * `null` under a per-shot scope with more than one set compared: there is no
+   * single answer then, and each `AnimationCheck` carries its own. A run that
+   * compared exactly one set fills these in whatever the scope, because for one
+   * set the two scopes are the same measurement.
+   */
+  framing: FramingHow | null;
   /** The box the CANDIDATE was rendered into, at the reference's pixel size. */
-  viewport: Framing;
+  viewport: Framing | null;
   /** Where the candidate's drawn pixels ended up against the reference's. */
   framingFit: FramingReport | null;
+  /**
+   * The framing ONE shared box gives across every set compared.
+   *
+   * Under `per-shot` it is both reported and used: every set that cannot take the
+   * frames' own declared box is measured in it. It is also the figure that says
+   * *why* a whole-root run is a different measurement — a set that reads well in
+   * the declared box and badly here is a set the old whole-root run was measuring
+   * through somebody else's silhouette, which is what `idle` reading 41.59 against
+   * 18.77 was (issue #100).
+   *
+   * `null` when the scope is already shared — `framingFit` is that number then —
+   * and when only one set was compared, where the two scopes are the same thing.
+   */
+  sharedFraming: FramingReport | null;
   /**
    * The box the REFERENCE was rendered into, when the sidecar records one.
    *
@@ -416,6 +747,14 @@ export interface CheckReport {
    */
   referenceViewport: Framing | null;
   background: RGBA;
+  /**
+   * The candidate's bone tree, cut into chains — the roster the report prints.
+   *
+   * Printed rather than assumed, because a decomposition an author has to guess at
+   * is one they will read wrong: the table says `front-thigh` and the roster says
+   * which bones and which slots that name covers. `src/chains.ts` owns the rule.
+   */
+  chains: BoneChain[];
   animations: AnimationCheck[];
   notes: string[];
 }
@@ -443,6 +782,15 @@ export interface CheckOptions {
   viewport?: { x: number; y: number; width: number; height: number };
   /** Play this candidate animation against the frames, when the names differ. */
   as?: string;
+  /**
+   * Fit one framing per frame set, or one across every set compared.
+   *
+   * Defaults to `per-shot`. See `FramingScope` for what the choice costs and why
+   * this is the default; it has no effect when only one set is compared, and none
+   * when `viewport` pins the box (a pin is a claim about the candidate's own
+   * coordinates, and those do not change between shots).
+   */
+  framing?: FramingScope;
 }
 
 // ---------------------------------------------------------------------------
@@ -572,34 +920,62 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   const referenceBoxes =
     pairs.length === 0 ? [] : referenceContentBoxes(located.root, pairs, background, level, pixelWidth, pixelHeight);
 
-  let viewport: Viewport;
-  let framingFit: FramingReport | null = null;
+  const scope: FramingScope = options.framing ?? 'per-shot';
+  const slices = sliceBySet(prepared, referenceBoxes);
+  /** One per prepared set, in `prepared` order. */
+  const framings: SetFraming[] = [];
+  let topViewport: Viewport | null = null;
+  let topHow: FramingHow | null = null;
+  let topFit: FramingReport | null = null;
+  let sharedFraming: FramingReport | null = null;
+
+  const reportFor = (fit: FramingFit, at: Viewport, over: Omit<FramingReport, 'units' | 'fit'>): FramingReport => ({
+    ...over,
+    fit,
+    units: extentsOf(fit, at.scale, referenceViewport),
+  });
+
   if (options.viewport) {
+    // A pin is a claim about the CANDIDATE's own coordinates, and those do not
+    // change between shots — so one box covers the run whatever the scope. The
+    // per-set fits below are free: every frame is measured in that one box once,
+    // and splitting the result per set costs nothing.
     const v = options.viewport;
-    viewport = viewportOfSize(v.x, v.y, v.width, v.height, maxSide / Math.max(v.width, v.height), pixelWidth, pixelHeight);
+    const pinned = viewportOfSize(v.x, v.y, v.width, v.height, maxSide / Math.max(v.width, v.height), pixelWidth, pixelHeight);
     notes.push(
       `the candidate's world box was pinned by --viewport ${v.x},${v.y},${v.width},${v.height} rather than derived ` +
         "from its own pixels — that is a claim about the candidate's coordinates, and nothing here checks it. The " +
         'framing line below is still measured, so it says what the pin cost.',
     );
-    const boxes = pairUpBoxes(prepared, posable.pages, viewport, background, level, referenceBoxes);
-    if (boxes.length > 0) {
-      const fit = fitFraming(boxes);
-      framingFit = {
-        fit,
-        passes: 1,
-        settled: false,
-        source: 'pinned',
-        cycled: false,
-        agrees: fitDistance(fit) <= COINCIDENT_PIXELS,
-        applied: false,
-        units: extentsOf(fit, viewport.scale, referenceViewport),
-      };
+    const pinnedShape = { passes: 1, settled: false, source: 'pinned' as const, cycled: false, applied: false };
+    // A pin is one claim for the whole run, so the refined pass is measured over
+    // the run as a whole — and never applied, for the same reason the fit is not.
+    const refinement = refinementOf(scanOffsets(located.root, prepared, posable.pages, pinned, background), 'pinned');
+    const perSet = prepared.map((p, i) =>
+      pairUpBoxes([p], posable.pages, pinned, background, level, slices[i]),
+    );
+    for (const boxes of perSet) {
+      const fit = boxes.length === 0 ? null : fitFraming(boxes);
+      framings.push({
+        viewport: pinned,
+        how: 'viewport-flag',
+        fit:
+          fit === null
+            ? null
+            : reportFor(fit, pinned, { ...pinnedShape, agrees: fitDistance(fit) <= COINCIDENT_PIXELS, refinement }),
+        notes: [],
+      });
     }
-  } else {
-    if (referenceBoxes.every((b) => b === null)) {
-      throw new CheckError('no reference frame could be compared, so there is nothing to frame against');
+    const all = perSet.flat();
+    topViewport = pinned;
+    topHow = 'viewport-flag';
+    if (all.length > 0) {
+      const fit = fitFraming(all);
+      topFit = reportFor(fit, pinned, { ...pinnedShape, agrees: fitDistance(fit) <= COINCIDENT_PIXELS, refinement });
     }
+  } else if (referenceBoxes.every((b) => b === null)) {
+    throw new CheckError('no reference frame could be compared, so there is nothing to frame against');
+  } else if (scope === 'shared' || prepared.length === 1) {
     const framed = frameCandidate(
       prepared,
       posable.pages,
@@ -610,14 +986,136 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
       pixelHeight,
       referenceViewport,
     );
-    viewport = framed.viewport;
-    framingFit = { ...framed.report, units: extentsOf(framed.report.fit, viewport.scale, referenceViewport) };
+    // One box for the run, so one refined pass over every frame in it: a single
+    // shared framing that each set nudged its own way would not be a shared one.
+    const refinement = refinementOf(
+      scanOffsets(located.root, prepared, posable.pages, framed.viewport, background),
+      framed.report.source,
+    );
+    const viewport =
+      refinement !== null && refinement.applied
+        ? shiftViewport(framed.viewport, refinement.dx, refinement.dy, pixelWidth, pixelHeight)
+        : framed.viewport;
+    const fit = {
+      ...framed.report,
+      units: extentsOf(framed.report.fit, framed.viewport.scale, referenceViewport),
+      refinement,
+    };
+    const how = HOW_BY_SOURCE[framed.report.source];
+    for (let i = 0; i < prepared.length; i++) framings.push({ viewport, how, fit, notes: [] });
+    topViewport = viewport;
+    topHow = how;
+    topFit = fit;
     notes.push(...framingNotes(framed.report));
+    if (prepared.length > 1) {
+      notes.push(
+        `one framing was fitted across all ${prepared.length} frame set(s) (--framing shared). Its absolute numbers ` +
+          'are not comparable with a per-shot run, and one badly-fitted set moves every other set in it.',
+      );
+    }
+  } else {
+    // Per shot: the DECLARED BOX is decided per set, and every set that does not
+    // qualify for it is measured in the one shared framing.
+    //
+    // ## Why the split falls exactly there, and not "fit each set on its own"
+    //
+    // The obvious reading of issue #100 is that each set should get its own fitted
+    // framing. It was written that way and measured, and it is worse — on the
+    // spineboy rung, per-set fitting reads `hit` **92.36** against the shared
+    // fit's 60.59 and `shoot@30fps` **101.94** against 42.98 (a two-frame set,
+    // framed 24 % off). The reason is `fitFraming`'s own: it registers **extent**,
+    // and extent is not alignment, so on a shot whose silhouette genuinely differs
+    // the chain has a local minimum of the correction that is not a minimum of the
+    // difference. More frames constrain that; one shot's worth does not.
+    //
+    // What actually produced the good column in that run is the other half — the
+    // box `frames.json` records, which is not an estimate of anything and has no
+    // floor. Over the union it was refused, because ONE badly-fitted shot put the
+    // pooled correction over `COINCIDENT_PIXELS` and the whole root fell back to a
+    // fit. Per set, the four sets that ARE in the frames' coordinates take it and
+    // read exactly what pinning by hand reads: `idle` **18.77** against 41.59,
+    // `walk` 32.00 against 45.33.
+    //
+    // So a set is framed by the frames' own box when its OWN pixels land there,
+    // and by the shared fit otherwise. Every set is then at least as well framed
+    // as a whole-root run framed it, and four of spineboy's sixteen much better.
+    const shared = frameCandidate(
+      prepared,
+      posable.pages,
+      referenceBoxes,
+      background,
+      level,
+      pixelWidth,
+      pixelHeight,
+      referenceViewport,
+    );
+    const sharedShape: SetFraming = {
+      viewport: shared.viewport,
+      how: HOW_BY_SOURCE[shared.report.source],
+      fit: { ...shared.report, units: extentsOf(shared.report.fit, shared.viewport.scale, referenceViewport) },
+      notes: [],
+    };
+    sharedFraming = sharedShape.fit;
+    let own = 0;
+    for (let i = 0; i < prepared.length; i++) {
+      const p = prepared[i];
+      const declared =
+        p.pairs.length === 0
+          ? null
+          : frameByDeclaredBox(
+              [p],
+              posable.pages,
+              slices[i],
+              background,
+              level,
+              pixelWidth,
+              pixelHeight,
+              referenceViewport,
+            );
+      const chosen: SetFraming = declared
+        ? {
+            viewport: declared.viewport,
+            how: HOW_BY_SOURCE[declared.report.source],
+            fit: {
+              ...declared.report,
+              units: extentsOf(declared.report.fit, declared.viewport.scale, referenceViewport),
+            },
+            notes: framingNotes(declared.report),
+          }
+        : { ...sharedShape, notes: framingNotes(shared.report) };
+      if (declared) own++;
+      // Per set, because the constant this pass removes is per set: issue #146
+      // measured spineboy's `death` wanting (−1, +1) and its `jump` (0, −1) in the
+      // same run and the same shared box. That is not the per-set *fitting* this
+      // scope rejects — the offset is measured against the MAE itself, where one
+      // shot's frames constrain the answer completely.
+      framings.push(refined(located.root, [p], posable.pages, chosen, background, pixelWidth, pixelHeight));
+    }
+    notes.push(
+      `the framing was decided per frame set: ${own} of ${prepared.length} set(s) were measured in ` +
+        `${FRAMES_SIDECAR}'s own box because their own pixels land there, and the rest in the one shared framing on ` +
+        'the "shared box" line. A set framed by the frames\' own box cannot be moved by any other set. --framing ' +
+        'shared measures every set in the shared framing instead, which is a different measurement and not ' +
+        'comparable with this one.',
+    );
   }
 
+  // The candidate's own decomposition, derived once and used by every set — see
+  // `src/chains.ts`. Reading the CANDIDATE's tree is what keeps this on the right
+  // side of the honesty rule: the reference is still nothing but pixels.
+  const chains = chainsOf(
+    posable.data.bones.map((bone) => ({ name: bone.name, parent: bone.parent === null ? null : bone.parent.name })),
+    posable.data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
+  );
+  const chainOfSlot = new Map<string, number>();
+  chains.forEach((chain, index) => {
+    for (const slot of chain.slots) chainOfSlot.set(slot, index);
+  });
+
   const animations: AnimationCheck[] = [];
-  for (const p of prepared) {
-    animations.push(checkOneSet(located.root, p, posable, viewport, background));
+  for (let i = 0; i < prepared.length; i++) {
+    const f = framings[i];
+    animations.push(checkOneSet(located.root, prepared[i], posable, f, background, chains, chainOfSlot));
   }
 
   return {
@@ -627,28 +1125,64 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
     },
     framesDir: resolve(options.framesDir),
     framesRoot: located.root,
-    framing: options.viewport
-      ? 'viewport-flag'
-      : framingFit?.source === 'declared'
-        ? 'frames-viewport'
-        : 'candidate-pixels',
-    viewport: {
-      x: viewport.minX,
-      y: viewport.minY,
-      width: viewport.maxX - viewport.minX,
-      height: viewport.maxY - viewport.minY,
-      scale: viewport.scale,
-      pixelWidth: viewport.width,
-      pixelHeight: viewport.height,
-    },
-    framingFit,
+    framingScope: scope,
+    framing: topHow,
+    viewport: topViewport === null ? null : framingOfViewport(topViewport),
+    framingFit: topFit,
+    sharedFraming,
     referenceViewport,
     background,
+    chains,
     animations,
     notes,
   };
 }
 
+/** The framing one prepared set was measured in. */
+interface SetFraming {
+  viewport: Viewport;
+  how: FramingHow;
+  fit: FramingReport | null;
+  notes: string[];
+}
+
+/** `FramingSource` said in the report's own words. */
+const HOW_BY_SOURCE: Record<FramingSource, FramingHow> = {
+  derived: 'candidate-pixels',
+  declared: 'frames-viewport',
+  pinned: 'viewport-flag',
+};
+
+/**
+ * `referenceBoxes` cut into one array per prepared set, in `prepared` order.
+ *
+ * The array is built by `prepared.flatMap((p) => p.pairs)`, so this is the inverse
+ * of that flatten and nothing else. It exists because a per-shot framing measures
+ * one set at a time and `frameCandidate` indexes its boxes the flat way.
+ */
+function sliceBySet(prepared: PreparedSet[], referenceBoxes: Array<ContentBox | null>): Array<Array<ContentBox | null>> {
+  const out: Array<Array<ContentBox | null>> = [];
+  let at = 0;
+  for (const p of prepared) {
+    out.push(referenceBoxes.slice(at, at + p.pairs.length));
+    at += p.pairs.length;
+  }
+  return out;
+}
+
+/** A rendering viewport as the report states it. */
+function framingOfViewport(v: Viewport): Framing {
+  return {
+    x: v.minX,
+    y: v.minY,
+    width: v.maxX - v.minX,
+    height: v.maxY - v.minY,
+    scale: v.scale,
+    pixelWidth: v.width,
+    pixelHeight: v.height,
+  };
+}
+
 function readPlateFrom(root: string, file: string): Plate {
   readFrameFile(root, file); // the guard; readPlate does the decoding
   return readPlate(file);
@@ -793,6 +1327,12 @@ interface FramingPass {
   distance: number;
 }
 
+/** A framing for one run of sets: the box, and what it still leaves over. */
+interface FramedSets {
+  viewport: Viewport;
+  report: Omit<FramingReport, 'units'>;
+}
+
 /** A chain of passes and why it stopped. */
 interface FramingChain {
   passes: FramingPass[];
@@ -898,7 +1438,7 @@ function frameCandidate(
   pixelWidth: number,
   pixelHeight: number,
   referenceViewport: Framing | null,
-): { viewport: Viewport; report: Omit<FramingReport, 'units'> } {
+): FramedSets {
   const declared = frameByDeclaredBox(
     prepared,
     pages,
@@ -909,34 +1449,14 @@ function frameCandidate(
     pixelHeight,
     referenceViewport,
   );
+  // The declared-box probe measures every frame in `frames.json`'s own box
+  // whether or not it ends up being used, and that measurement is the only one
+  // taken in a box every set shares. Handing it back is what lets a per-shot run
+  // report `sharedFit` without a second render — see `CheckReport.sharedFit`.
   if (declared) return declared;
 
-  const quads = trimmedUnionBounds(
-    prepared.map((p) => p.pairs.map((pair) => pair.frame)),
-    pages,
-  );
-  if (!Number.isFinite(quads.minX)) {
-    throw new CheckError('the candidate posed no drawable attachment in any frame that was compared');
-  }
-  const pad = Math.max(quads.maxX - quads.minX, quads.maxY - quads.minY) * PAD;
-  const world = {
-    minX: quads.minX - pad,
-    minY: quads.minY - pad,
-    maxX: quads.maxX + pad,
-    maxY: quads.maxY + pad,
-  };
-  const maxSide = Math.max(pixelWidth, pixelHeight);
-  const seed = viewportOfSize(
-    world.minX,
-    world.minY,
-    world.maxX - world.minX,
-    world.maxY - world.minY,
-    maxSide / Math.max(world.maxX - world.minX, world.maxY - world.minY),
-    pixelWidth,
-    pixelHeight,
-  );
   const chain = runFramingChain(
-    seed,
+    seedFromGeometry(prepared, pages, referenceBoxes, pixelWidth, pixelHeight),
     prepared,
     pages,
     referenceBoxes,
@@ -960,10 +1480,94 @@ function frameCandidate(
       cycled: chain.cycled,
       agrees: chosen.distance <= COINCIDENT_PIXELS,
       applied: true,
+      // Filled in by the refined pass, which runs once the box is decided.
+      refinement: null,
     },
   };
 }
 
+/**
+ * The starting viewport, from the candidate's own posed geometry laid onto the
+ * reference's own drawn extent.
+ *
+ * ## Why the reference's extent and not the frame
+ *
+ * The seed used to scale the candidate's trimmed quads to **fill the frame**, and
+ * that is an assumption about the reference: that the shot its frames show was
+ * framed around itself. Over a whole skeleton root it holds well enough, because
+ * the sidecar's one box was chosen to hold every set. Over one SHORT set it can be
+ * badly wrong — rung 3's `light` covers about half of the box its frames were
+ * rendered in, so filling the frame starts it near 2x too large, and the chain
+ * walks that back by only a few per cent a pass: `--frames <root>/light` on a
+ * candidate in its own coordinates read **MAE 141** with a framing 65 % off, after
+ * spending its whole pass budget (issue #100).
+ *
+ * The reference's own content box is already measured, on the same frames, with
+ * the same predicate — it is what the fit is trying to reach. Starting there costs
+ * nothing and starts the chain where it used to end up: the same shot now settles
+ * on the first or second pass.
+ *
+ * The scale matches the two boxes by **area** rather than by either side, because
+ * a candidate whose silhouette differs has two different side ratios and picking
+ * one of them would seed the chain with that difference as a scale error.
+ *
+ * ⚠️ Falls back to filling the frame when there is no reference box to aim at —
+ * every frame unreadable, or a set with nothing on disk.
+ */
+function seedFromGeometry(
+  prepared: PreparedSet[],
+  pages: Map<string, Plate>,
+  referenceBoxes: Array<ContentBox | null>,
+  pixelWidth: number,
+  pixelHeight: number,
+): Viewport {
+  const quads = trimmedUnionBounds(
+    prepared.map((p) => p.pairs.map((pair) => pair.frame)),
+    pages,
+  );
+  if (!Number.isFinite(quads.minX)) {
+    throw new CheckError('the candidate posed no drawable attachment in any frame that was compared');
+  }
+  const pad = Math.max(quads.maxX - quads.minX, quads.maxY - quads.minY) * PAD;
+  const world = {
+    minX: quads.minX - pad,
+    minY: quads.minY - pad,
+    maxX: quads.maxX + pad,
+    maxY: quads.maxY + pad,
+  };
+  const worldWidth = world.maxX - world.minX;
+  const worldHeight = world.maxY - world.minY;
+
+  let reference: ContentBox | null = null;
+  for (const box of referenceBoxes) reference = unionBoxes(reference, box);
+  if (reference !== null && boxWidth(reference) > 0 && boxHeight(reference) > 0) {
+    // The reference's box is the trimmed content, so pad it the same way the
+    // candidate's is before the two are matched — otherwise the pad is a scale
+    // error the chain then has to undo.
+    const refWidth = boxWidth(reference) * (1 + 2 * PAD);
+    const refHeight = boxHeight(reference) * (1 + 2 * PAD);
+    const scale = Math.sqrt((refWidth * refHeight) / (worldWidth * worldHeight));
+    const left = reference.left - boxWidth(reference) * PAD;
+    const top = reference.top - boxHeight(reference) * PAD;
+    // `projector` is px = (wx - minX)·k and py = (maxY - wy)·k, so putting the
+    // candidate's padded box on the reference's is one subtraction per axis.
+    const minX = world.minX - left / scale;
+    const maxY = world.maxY + top / scale;
+    return viewportOfSize(minX, maxY - pixelHeight / scale, pixelWidth / scale, pixelHeight / scale, scale, pixelWidth, pixelHeight);
+  }
+
+  const maxSide = Math.max(pixelWidth, pixelHeight);
+  return viewportOfSize(
+    world.minX,
+    world.minY,
+    worldWidth,
+    worldHeight,
+    maxSide / Math.max(worldWidth, worldHeight),
+    pixelWidth,
+    pixelHeight,
+  );
+}
+
 /**
  * The box `frames.json` records, used as the candidate's own — when, and only
  * when, the candidate's pixels are measured to land in it.
@@ -1056,10 +1660,91 @@ function frameByDeclaredBox(
       cycled: false,
       agrees: true,
       applied: true,
+      refinement: null,
     },
   };
 }
 
+// ---------------------------------------------------------------------------
+// the MAE-refined final pass — see `FramingRefinement`
+// ---------------------------------------------------------------------------
+
+/**
+ * The reference-denominator MAE of these sets at every whole-pixel offset in a
+ * ±`REFINE_RADIUS` window, in the box they were framed in.
+ *
+ * One render per frame, whatever the window's size: `OffsetScan` owns why that is
+ * exact for whole pixels. The reference plates are read again here and again by
+ * `checkOneSet`; decoding a PNG twice is cheaper than holding a set's frames in
+ * memory, which on the ladder's largest set is a quarter of a gigabyte.
+ */
+function scanOffsets(
+  root: string,
+  prepared: PreparedSet[],
+  pages: Map<string, Plate>,
+  viewport: Viewport,
+  background: RGBA,
+): OffsetGain | null {
+  const scan = new OffsetScan(REFINE_RADIUS);
+  for (const p of prepared) {
+    for (const pair of p.pairs) {
+      scan.add(
+        renderFrame(pair.frame, pages, viewport, background),
+        frameGeometry(pair.frame, pages, viewport).coverage,
+        readPlateFrom(root, pair.file),
+        background,
+      );
+    }
+  }
+  return scan.best();
+}
+
+/**
+ * What to do with the offset a scan found, given how the box was chosen.
+ *
+ * The whole judgement of `FramingRefinement` in one function, so that "a fitted
+ * box is corrected and an exact one is only reported" is a single readable rule
+ * rather than a condition spread over three call sites.
+ */
+function refinementOf(gain: OffsetGain | null, source: FramingSource): FramingRefinement | null {
+  if (gain === null) return null;
+  const shape = {
+    dx: gain.dx,
+    dy: gain.dy,
+    before: gain.identity,
+    after: gain.best,
+    radius: gain.radius,
+    frames: gain.frames,
+  };
+  if (gain.dx === 0 && gain.dy === 0) return { ...shape, applied: false, declined: 'identity' };
+  if (!offsetIsWorthApplying(gain)) return { ...shape, applied: false, declined: 'below-threshold' };
+  if (source === 'pinned') return { ...shape, applied: false, declined: 'pinned' };
+  if (source === 'declared') return { ...shape, applied: false, declined: 'box-is-exact' };
+  return { ...shape, applied: true, declined: null };
+}
+
+/** One set's framing with the refined pass run over it, and applied if it may be. */
+function refined(
+  root: string,
+  prepared: PreparedSet[],
+  pages: Map<string, Plate>,
+  framing: SetFraming,
+  background: RGBA,
+  pixelWidth: number,
+  pixelHeight: number,
+): SetFraming {
+  if (framing.fit === null) return framing;
+  const refinement = refinementOf(
+    scanOffsets(root, prepared, pages, framing.viewport, background),
+    framing.fit.source,
+  );
+  const viewport =
+    refinement !== null && refinement.applied
+      ? shiftViewport(framing.viewport, refinement.dx, refinement.dy, pixelWidth, pixelHeight)
+      : framing.viewport;
+  return { ...framing, viewport, fit: { ...framing.fit, refinement } };
+}
+
 /**
  * What the framing pass concluded, in the words that tell the three cases apart.
  *
@@ -1114,6 +1799,16 @@ interface PreparedSet {
   candidateFrames: number;
   referenceFrames: number;
   pairs: FramePair[];
+  /**
+   * Every frame the candidate sampled, in index order — not only the ones a file
+   * on disk pairs with.
+   *
+   * The contact sheet holds a tile for every SAMPLED frame, so a set that commits
+   * two stills out of 311 needs all 311 poses to be compared against it
+   * (`SheetCheck`). Kept as poses rather than plates: a `Frame` is geometry, and
+   * holding 311 rendered plates of a busy shot is a quarter of a gigabyte.
+   */
+  frames: Frame[];
   notes: string[];
   /** Set when nothing could be compared at all, saying why. */
   missing: string | null;
@@ -1137,6 +1832,7 @@ function prepareSet(
       candidateFrames: 0,
       referenceFrames: disk.length,
       pairs: [],
+      frames: [],
       notes: [],
       missing:
         `the candidate has no animation called ${JSON.stringify(wanted)} — it has [${have.join(', ') || 'none'}]. ` +
@@ -1184,6 +1880,7 @@ function prepareSet(
     candidateFrames: candidateFrames.length,
     referenceFrames: disk.length,
     pairs,
+    frames: candidateFrames,
     notes,
     missing: null,
   };
@@ -1193,10 +1890,14 @@ function checkOneSet(
   root: string,
   prepared: PreparedSet,
   posable: ReturnType<typeof posableFromText>,
-  viewport: Viewport,
+  framing: SetFraming,
   background: RGBA,
+  chains: BoneChain[],
+  /** Slot name → its index in `chains`. */
+  chainOfSlot: Map<string, number>,
 ): AnimationCheck {
   const { set } = prepared;
+  const viewport = framing.viewport;
   const blank: AnimationCheck = {
     dir: set.dir,
     animation: set.animation,
@@ -1206,6 +1907,8 @@ function checkOneSet(
     candidateFrames: prepared.candidateFrames,
     compared: 0,
     meanMae: 0,
+    meanMaeReference: 0,
+    drawnRatio: 1,
     meanMaeFrame: 0,
     worstMae: 0,
     worstMaeFrame: -1,
@@ -1216,13 +1919,22 @@ function checkOneSet(
     changePairs: 0,
     changeDisagreements: 0,
     worstChangeFrame: -1,
+    chains: [],
+    chainDenominator: 0,
+    unattributedError: 0,
     frames: [],
-    notes: prepared.missing ? [prepared.missing] : prepared.notes,
+    viewport: framingOfViewport(viewport),
+    framing: framing.how,
+    framingFit: framing.fit,
+    sheet: null,
+    notes: prepared.missing ? [prepared.missing] : [...framing.notes, ...prepared.notes],
   };
   if (prepared.missing !== null || prepared.pairs.length === 0) return blank;
 
   const frames: FrameCheck[] = [];
   let maeSum = 0;
+  let maeReferenceSum = 0;
+  let drawnRatioSum = 0;
   let maeFrameSum = 0;
   let worstMae = 0;
   let worstMaeFrame = -1;
@@ -1238,15 +1950,34 @@ function checkOneSet(
   // ITSELF a frame earlier. Both are already rendered or read for this frame, so
   // holding one frame of each costs one extra plate and no extra work.
   let previous: { index: number; candidate: Plate; reference: Plate } | null = null;
+  const tally: ChainTally = {
+    error: new Array<number>(chains.length).fill(0),
+    pixels: new Array<number>(chains.length).fill(0),
+    unattributed: 0,
+    total: 0,
+  };
 
   for (const { index, file, frame } of prepared.pairs) {
     const reference = readPlateFrom(root, file);
     const rendered = renderFrame(frame, posable.pages, viewport, background);
-    const check = checkOneFrame(index, file, frame, posable.pages, viewport, background, reference, rendered);
+    const check = checkOneFrame(
+      index,
+      file,
+      frame,
+      posable.pages,
+      viewport,
+      background,
+      reference,
+      rendered,
+      chainOfSlot,
+      tally,
+    );
     check.change = previous && previous.index === index - 1 ? frameChange(previous, rendered, reference) : null;
     previous = { index, candidate: rendered, reference };
     frames.push(check);
     maeSum += check.mae;
+    maeReferenceSum += check.maeReference;
+    drawnRatioSum += check.referencePixels === 0 ? 1 : check.candidatePixels / check.referencePixels;
     maeFrameSum += check.maeFrame;
     if (check.attributed === 0) framesWithoutDrift++;
     if (check.change) {
@@ -1271,10 +2002,21 @@ function checkOneSet(
     }
   }
 
+  // The frames the set does not commit as files, against the sheet that holds
+  // them — see `SheetCheck`. After the frame loop, because it is measured in the
+  // box that loop was measured in.
+  const sheet = checkAgainstSheet(root, prepared, posable, viewport, background);
+
   return {
     ...blank,
     compared: frames.length,
+    sheet: sheet.sheet,
+    chains: chainChecks(chains, frames, tally),
+    chainDenominator: tally.total,
+    unattributedError: tally.unattributed,
     meanMae: maeSum / frames.length,
+    meanMaeReference: maeReferenceSum / frames.length,
+    drawnRatio: drawnRatioSum / frames.length,
     meanMaeFrame: maeFrameSum / frames.length,
     worstMae,
     worstMaeFrame,
@@ -1286,7 +2028,7 @@ function checkOneSet(
     changeDisagreements,
     worstChangeFrame,
     frames,
-    notes: prepared.notes,
+    notes: [...framing.notes, ...prepared.notes, ...sheet.notes],
   };
 }
 
@@ -1393,6 +2135,176 @@ function plateDelta(before: Plate, after: Plate): { pixels: number; mae: number
   return { pixels, mae: sum / 3 / count };
 }
 
+/**
+ * Roll a set's frames up into one row per chain — the dashboard's rows.
+ *
+ * A chain that owns no slot is left out: it has nothing to attribute, and a row of
+ * dashes in every set is noise in a table read sixteen times. The roster at the
+ * foot of the report still lists it, so the account of where every bone went stays
+ * complete.
+ */
+function chainChecks(chains: BoneChain[], frames: FrameCheck[], tally: ChainTally): ChainCheck[] {
+  const out: ChainCheck[] = [];
+  chains.forEach((chain, index) => {
+    if (chain.slots.length === 0) return;
+    const own = new Set(chain.slots);
+    const drew = new Set<string>();
+    let worstDrift = 0;
+    let worstDriftSlot: string | null = null;
+    let worstDriftFrame = -1;
+    let driftSum = 0;
+    let driftSamples = 0;
+    let driftFrames = 0;
+    for (const frame of frames) {
+      let sampled = false;
+      for (const track of frame.slots) {
+        if (!own.has(track.slot)) continue;
+        if (track.candidate !== null) drew.add(track.slot);
+        if (!isAttributable(track)) continue;
+        const drift = track.drift as number;
+        driftSum += drift;
+        driftSamples++;
+        sampled = true;
+        if (drift > worstDrift) {
+          worstDrift = drift;
+          worstDriftSlot = track.slot;
+          worstDriftFrame = frame.index;
+        }
+      }
+      if (sampled) driftFrames++;
+    }
+    out.push({
+      chain: chain.name,
+      slots: chain.slots.length,
+      drewSlots: drew.size,
+      worstDrift,
+      worstDriftSlot,
+      worstDriftFrame,
+      meanDrift: driftSamples === 0 ? 0 : driftSum / driftSamples,
+      driftSamples,
+      driftFrames,
+      error: tally.error[index],
+      referencePixels: tally.pixels[index],
+      mae: tally.pixels[index] === 0 ? 0 : tally.error[index] / tally.pixels[index],
+      maeShare: tally.total === 0 ? 0 : tally.error[index] / tally.total,
+    });
+  });
+  return out;
+}
+
+/**
+ * A set's error, being split between the candidate's chains as its frames are read.
+ *
+ * Carried across frames rather than parked on each `FrameCheck` because a share is
+ * a fact about the SET — and because a per-frame array of it would land in every
+ * `--json` report and every `bench.json` for a number nobody reads per frame.
+ */
+interface ChainTally {
+  /** Absolute difference over reference-drawn pixels attributed to each chain. */
+  error: number[];
+  /** How many such pixels each chain took. */
+  pixels: number[];
+  /** The same, over reference pixels no chain could take — the candidate drew nothing. */
+  unattributed: number;
+  /** Every reference-drawn pixel's difference, chain or not: the share's denominator. */
+  total: number;
+}
+
+/** How much a diagonal step costs the chamfer pass below. */
+const DIAGONAL_STEP = Math.SQRT2;
+
+/**
+ * Give every pixel of the frame the chain whose ink is nearest to it.
+ *
+ * Two chamfer passes over the owner mask — forward then backward, propagating
+ * (distance, label) together. It is an approximate Euclidean transform and that is
+ * enough: what it decides is which of a handful of well-separated regions a pixel
+ * belongs to, not a distance anybody reads.
+ *
+ * ⚠️ Nearest **ink the candidate drew**, so a chain that draws nothing seeds
+ * nothing and is handed no pixels at all — its share reads 0 % while its slots are
+ * missing entirely. That is why the table prints `drewSlots` beside the share: 0 %
+ * on `0/3 slots` is the loudest row here, not the quietest one.
+ *
+ * The distance comes back with the label because the caller bounds it — see
+ * `chainRadii`.
+ */
+function nearestOwner(owner: Int32Array, width: number, height: number): { label: Int32Array; dist: Float32Array } {
+  const label = Int32Array.from(owner);
+  const dist = new Float32Array(width * height);
+  for (let i = 0; i < label.length; i++) dist[i] = label[i] >= 0 ? 0 : Infinity;
+  const relax = (at: number, from: number, step: number): void => {
+    const reach = dist[from] + step;
+    if (reach >= dist[at]) return;
+    dist[at] = reach;
+    label[at] = label[from];
+  };
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const at = y * width + x;
+      if (x > 0) relax(at, at - 1, 1);
+      if (y > 0) {
+        relax(at, at - width, 1);
+        if (x > 0) relax(at, at - width - 1, DIAGONAL_STEP);
+        if (x + 1 < width) relax(at, at - width + 1, DIAGONAL_STEP);
+      }
+    }
+  }
+  for (let y = height - 1; y >= 0; y--) {
+    for (let x = width - 1; x >= 0; x--) {
+      const at = y * width + x;
+      if (x + 1 < width) relax(at, at + 1, 1);
+      if (y + 1 < height) {
+        relax(at, at + width, 1);
+        if (x + 1 < width) relax(at, at + width + 1, DIAGONAL_STEP);
+        if (x > 0) relax(at, at + width - 1, DIAGONAL_STEP);
+      }
+    }
+  }
+  return { label, dist };
+}
+
+/**
+ * How far each chain's attribution may reach, in frame pixels.
+ *
+ * The same judgement `src/slots.ts` makes about a slot — *past about its own long
+ * side a part no longer overlaps where it was, and something out there is another
+ * object rather than this one moved* — applied to the chain's own drawn box. Past
+ * it, reference ink is left **unattributed** instead of being handed to whichever
+ * chain happens to be nearest.
+ *
+ * ⚠️ This is the bound that keeps the dashboard honest about its own limits, and
+ * it is a bound rather than a fix. Nothing candidate-side can know which part of
+ * the REFERENCE a pixel belonged to; nearest-ink is a good guess while the figure
+ * is roughly in place and a bad one once a part has left. So a part displaced past
+ * its own size stops being blamed on its neighbour and starts showing up in the
+ * `(unattributed)` row, next to the `reference component(s) no slot reaches` count
+ * that says the same thing a different way.
+ */
+function chainRadii(
+  footprints: Map<string, Footprint>,
+  chainOfSlot: Map<string, number>,
+  chains: number,
+): Float64Array {
+  const minX = new Float64Array(chains).fill(Infinity);
+  const minY = new Float64Array(chains).fill(Infinity);
+  const maxX = new Float64Array(chains).fill(-Infinity);
+  const maxY = new Float64Array(chains).fill(-Infinity);
+  for (const [slot, foot] of footprints) {
+    const chain = chainOfSlot.get(slot);
+    if (chain === undefined || foot.pixels === 0) continue;
+    if (foot.minX < minX[chain]) minX[chain] = foot.minX;
+    if (foot.minY < minY[chain]) minY[chain] = foot.minY;
+    if (foot.maxX > maxX[chain]) maxX[chain] = foot.maxX;
+    if (foot.maxY > maxY[chain]) maxY[chain] = foot.maxY;
+  }
+  const out = new Float64Array(chains);
+  for (let i = 0; i < chains; i++) {
+    out[i] = maxX[i] < minX[i] ? -1 : searchRadius(maxX[i] - minX[i], maxY[i] - minY[i]);
+  }
+  return out;
+}
+
 function checkOneFrame(
   index: number,
   file: string,
@@ -1403,8 +2315,16 @@ function checkOneFrame(
   reference: Plate,
   /** The candidate's own frame, rendered by the caller — it needs it too. */
   rendered: Plate,
+  /** Slot name → chain index, for the per-chain split. */
+  chainOfSlot: Map<string, number>,
+  /** Accumulated across the set by the caller — see `ChainTally`. */
+  tally: ChainTally,
 ): FrameCheck {
-  const { coverage, footprints } = frameGeometry(frame, pages, viewport);
+  const { coverage, footprints, owner } = frameGeometry(frame, pages, viewport, chainOfSlot);
+  // Only worth the transform when something was drawn to be nearest TO.
+  const nearest =
+    owner !== null && owner.some((at) => at >= 0) ? nearestOwner(owner, viewport.width, viewport.height) : null;
+  const radii = chainRadii(footprints, chainOfSlot, tally.error.length);
 
   let union = 0;
   let candidatePixels = 0;
@@ -1421,14 +2341,29 @@ function checkOneFrame(
       const b = reference.get(x, y);
       const delta = (Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2])) / 3;
       sumAll += delta;
+      if (inReference) {
+        // The share's denominator is the reference's own drawn pixels, and the
+        // split is over exactly those — issue #119's lesson, as a partition.
+        tally.total += delta;
+        const at = y * viewport.width + x;
+        const found = nearest === null ? -1 : nearest.label[at];
+        const chain = found >= 0 && nearest !== null && nearest.dist[at] <= radii[found] ? found : -1;
+        if (chain >= 0) {
+          tally.error[chain] += delta;
+          tally.pixels[chain]++;
+        } else {
+          tally.unattributed += delta;
+        }
+      }
       if (!inCandidate && !inReference) continue;
       union++;
       sum += delta;
     }
   }
 
-  const components = componentsOf(reference, background);
-  const { tracks, matchedComponents } = matchSlots(footprints, components, {
+  const field = componentField(reference, background);
+  const components = field.components;
+  const { tracks, matchedComponents } = matchSlots(footprints, field, {
     frame,
     pages,
     viewport,
@@ -1454,6 +2389,10 @@ function checkOneFrame(
     index,
     file,
     mae: union === 0 ? 0 : sum / union,
+    // The same numerator over a denominator the candidate does not control — see
+    // `FrameCheck.maeReference`. Both figures are already in hand here, which is
+    // why the second one costs nothing to publish.
+    maeReference: referencePixels === 0 ? 0 : sum / referencePixels,
     maeFrame: sumAll / (viewport.width * viewport.height),
     unionPixels: union,
     candidatePixels,
@@ -1471,10 +2410,261 @@ function checkOneFrame(
   };
 }
 
+// ---------------------------------------------------------------------------
+// the contact sheet — see `SheetCheck`
+// ---------------------------------------------------------------------------
+
+/** A sheet's grid, in the terms the tiles are cut out with. */
+interface SheetGeometry {
+  columns: number;
+  rows: number;
+  tileWidth: number;
+  tileHeight: number;
+  /** Tile pixels per frame pixel. */
+  tileScale: number;
+}
+
+/**
+ * A sheet's grid, **measured off the sheet** rather than taken on trust.
+ *
+ * `frames.json` records the frame count and the world box; it does not record the
+ * tile size, because `--tile` is a per-run choice and the sheet's own dimensions
+ * state the answer exactly. With `n` tiles in `c` columns the sheet is
+ * `c·(w+1)+1` by `ceil(n/c)·(h+1)+1`, so a column count either divides both
+ * dimensions exactly or is wrong — and the surviving candidate has to agree with
+ * the frames' own aspect ratio as well, since both tile sides came from one scale.
+ *
+ * `SHEET_COLUMNS` is tried first because it is the contract
+ * `bench/render_reference.ts` writes; the search behind it is what keeps a sheet
+ * rendered by something else readable, and what makes a mismatch a **named
+ * refusal** rather than a silent misread of somebody's grid.
+ */
+export function sheetGeometry(
+  sheet: Plate,
+  tiles: number,
+  pixelWidth: number,
+  pixelHeight: number,
+): SheetGeometry | null {
+  if (tiles <= 0 || pixelWidth <= 0 || pixelHeight <= 0) return null;
+  const candidates = [SHEET_COLUMNS, ...Array.from({ length: Math.min(tiles, 64) }, (_, i) => i + 1)];
+  const slack = 1 / Math.max(pixelWidth, pixelHeight);
+  let best: { geometry: SheetGeometry; error: number } | null = null;
+  for (const columns of candidates) {
+    if (columns > tiles) continue;
+    const across = sheet.width - SHEET_GAP;
+    const rows = Math.ceil(tiles / columns);
+    const down = sheet.height - SHEET_GAP;
+    if (across % columns !== 0 || down % rows !== 0) continue;
+    const tileWidth = across / columns - SHEET_GAP;
+    const tileHeight = down / rows - SHEET_GAP;
+    if (tileWidth < 1 || tileHeight < 1) continue;
+    // Both tile sides are one scale, rounded — so the two ratios agree to within
+    // the rounding, and a grid that does not is a different grid.
+    const error = Math.abs(tileWidth / pixelWidth - tileHeight / pixelHeight);
+    if (error > slack) continue;
+    const geometry = { columns, rows, tileWidth, tileHeight, tileScale: tileWidth / pixelWidth };
+    if (best === null || error < best.error) best = { geometry, error };
+    if (columns === SHEET_COLUMNS) break;
+  }
+  return best === null ? null : best.geometry;
+}
+
+/**
+ * The label burned into a tile's corner, as a box to leave out of the comparison.
+ *
+ * `bench/render_reference.ts` paints the frame's index at `(2, 2)` in the tile at
+ * scale 1, and the candidate does not draw it. Left in, it would add the same
+ * constant to every tile and a bigger one to four-digit frames than to one-digit
+ * ones — a difference that is a fact about the labeller. The box is derived from
+ * the font's own metrics, with a pixel of margin, rather than measured once and
+ * written down.
+ */
+function labelBox(index: number): { width: number; height: number } {
+  return { width: 2 + textWidth(String(index), 1) + 1, height: 2 + GLYPH_H + 1 };
+}
+
+/**
+ * One frame set against its contact sheet, tile by tile.
+ *
+ * The candidate is rendered into the SAME world box the set was framed in, at the
+ * sheet's own scale — so a set framed by `frames.json`'s own box is compared here
+ * with no correction at all, and a set framed by a fit carries that fit (which,
+ * for a stills-plus-sheet set, was measured on the stills). The report says which.
+ */
+function checkAgainstSheet(
+  root: string,
+  prepared: PreparedSet,
+  posable: ReturnType<typeof posableFromText>,
+  viewport: Viewport,
+  background: RGBA,
+): { sheet: SheetCheck | null; notes: string[] } {
+  const { set } = prepared;
+  const file = join(root, set.dir, SHEET_FILE);
+  if (!existsSync(file)) return { sheet: null, notes: [] };
+  const onDisk = framesOnDisk(root, set.dir).length;
+  // Every sampled frame already has a file of its own: the sheet is the same
+  // pictures again, smaller, and measuring them twice would just report the
+  // resampling.
+  if (onDisk >= set.sampled) return { sheet: null, notes: [] };
+  if (prepared.frames.length === 0) return { sheet: null, notes: [] };
+
+  const plate = readPlateFrom(root, file);
+  const geometry = sheetGeometry(plate, set.sampled, viewport.width, viewport.height);
+  if (geometry === null) {
+    return {
+      sheet: null,
+      notes: [
+        `${file} is ${plate.width}x${plate.height} px, which is not a grid of ${set.sampled} tile(s) at the ` +
+          `${viewport.width}x${viewport.height} aspect of these frames — so the whole shot was NOT compared, only ` +
+          `the ${onDisk} still(s) on disk. Re-render the set with bench/render_reference.ts if the sheet is stale.`,
+      ],
+    };
+  }
+
+  const { columns, tileWidth, tileHeight, tileScale } = geometry;
+  const tileViewport = viewportOfSize(
+    viewport.minX,
+    viewport.minY,
+    viewport.maxX - viewport.minX,
+    viewport.maxY - viewport.minY,
+    viewport.scale * tileScale,
+    tileWidth,
+    tileHeight,
+  );
+  const compared = Math.min(set.sampled, prepared.frames.length);
+  let maeSum = 0;
+  let maeReferenceSum = 0;
+  let worstMae = 0;
+  let worstTile = -1;
+  const per: Array<{ index: number; mae: number }> = [];
+  for (let index = 0; index < compared; index++) {
+    const frame = prepared.frames[index];
+    const rendered = renderFrame(frame, posable.pages, tileViewport, background);
+    const ox = SHEET_GAP + (index % columns) * (tileWidth + SHEET_GAP);
+    const oy = SHEET_GAP + Math.floor(index / columns) * (tileHeight + SHEET_GAP);
+    const label = labelBox(index);
+    let union = 0;
+    let referencePixels = 0;
+    let sum = 0;
+    for (let y = 0; y < tileHeight; y++) {
+      for (let x = 0; x < tileWidth; x++) {
+        if (y < label.height && x < label.width) continue;
+        const sx = ox + x;
+        const sy = oy + y;
+        if (sx >= plate.width || sy >= plate.height) continue;
+        const inReference = isContent(plate, sx, sy, background);
+        const inCandidate = isContent(rendered, x, y, background);
+        if (inReference) referencePixels++;
+        if (!inReference && !inCandidate) continue;
+        const a = rendered.get(x, y);
+        const b = plate.get(sx, sy);
+        union++;
+        sum += (Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2])) / 3;
+      }
+    }
+    const mae = union === 0 ? 0 : sum / union;
+    maeSum += mae;
+    maeReferenceSum += referencePixels === 0 ? 0 : sum / referencePixels;
+    per.push({ index, mae });
+    if (mae > worstMae) {
+      worstMae = mae;
+      worstTile = index;
+    }
+  }
+  per.sort((a, b) => b.mae - a.mae);
+  return {
+    sheet: {
+      file,
+      columns,
+      tileWidth,
+      tileHeight,
+      tileScale,
+      tiles: set.sampled,
+      compared,
+      meanMae: compared === 0 ? 0 : maeSum / compared,
+      meanMaeReference: compared === 0 ? 0 : maeReferenceSum / compared,
+      worstMae,
+      worstTile,
+      worst: per.slice(0, WORST_FRAMES),
+    },
+    notes: [],
+  };
+}
+
+/** The sheet block, as the lines an author reads after the frame table. */
+function sheetLines(sheet: SheetCheck | null): string[] {
+  if (sheet === null) return [];
+  const worst = sheet.worst
+    .map((tile) => `f${String(tile.index).padStart(4, '0')}=${tile.mae.toFixed(1)}`)
+    .join('  ');
+  return [
+    `     sheet      ${sheet.compared} of ${sheet.tiles} tile(s) of ${basename(sheet.file)} at ` +
+      `${sheet.tileWidth}x${sheet.tileHeight}px in ${sheet.columns} column(s)   MAE mean ${f2(sheet.meanMae)}  ` +
+      `worst ${f2(sheet.worstMae)} at f${String(sheet.worstTile).padStart(4, '0')}   ` +
+      `(over the reference's own pixels, mean ${f2(sheet.meanMaeReference)})`,
+    '                ⤷ the frames this set does not commit as files. The candidate is sampled at the set\'s own ' +
+      "rate and rendered into the same box the frames above were, at the sheet's scale. Read the " +
+      'series, not the mean: flat is framing or art, a spike is timing at that moment.',
+    `                ⤷ worst ${sheet.worst.length}: ${worst}`,
+  ];
+}
+
 // ---------------------------------------------------------------------------
 // the report
 // ---------------------------------------------------------------------------
 
+/**
+ * How much more than the reference a set may draw before `check` calls it
+ * overdraw, as a ratio of drawn pixels.
+ *
+ * ## Why this direction needs its own warning
+ *
+ * `mae` divides by the pixels **either side drew** — the union — and the
+ * candidate owns half of that denominator. A large, mostly transparent sprite
+ * adds many cheap pixels to it and the *mean falls*, so anything optimising
+ * against `mae` can buy a better score by drawing more, which is the opposite of
+ * fidelity. Issue #119: spineboy-2's muzzle flare walked its own scale to 13x
+ * doing exactly this, and cost every set in that run its framing. Reproduced
+ * here, that candidate's `shoot` reads union MAE **39.65 against the honest
+ * build's 47.20** — the metric calls the flare an improvement — while the same
+ * difference over the reference's own pixels reads **73.06 against 52.54**.
+ *
+ * ⭐ Asymmetric on purpose. A candidate that draws LESS than the reference is
+ * being punished by the MAE, not rewarded, and needs no warning to find out.
+ *
+ * ## Where 1.5 comes from
+ *
+ * Measured over the corpus rather than picked. Across the twelve committed
+ * candidates in `bench/runs/` — 64 compared sets, 1 to 121 frames each — the
+ * ratio spans **0.852 … 1.069** on 62 of them, and the two above that are both
+ * the same shot on the same character: spineboy-1's `shoot@30fps` at 1.154 and
+ * spineboy-2's at **1.274**, two-frame stills sets where the muzzle flare lands
+ * a frame off. Rung 8's ball reads 1.041, rung 3's candidate 0.993.
+ *
+ * The 13x flare reads **1.850** on `shoot` and **3.199** on `shoot@30fps`, and
+ * 0.94–1.01 on the fourteen sets that do not draw it — so the warning names the
+ * shot the overdraw is in rather than colouring the whole run.
+ *
+ * 1.5 is the geometric middle of the gap between the widest honest reading and
+ * the weakest defective one (1.274 · 1.850 ≈ 1.535²): half again as much ink as
+ * the reference put down, which no honest candidate in the corpus approaches and
+ * which the case this was built for clears on both its sets.
+ *
+ * ## What was measured and rejected: the content boxes
+ *
+ * Issue #119 suggests the two content boxes, and `check` has both. Measured, that
+ * test is defeated by the framing it is measured through. `fitFraming` absorbs a
+ * uniform scale on purpose, so a candidate that draws everything too big reads a
+ * box growth of **−3.4 %** while its union MAE falls 137.6 → 36.0 — the fit
+ * simply shrinks it back. It also fires where nothing is overdrawn: the
+ * time-reversed fixture, whose ink is right and whose *timing* is wrong, reads
+ * **+14.1 %** because sampling a reversed shot lands on different poses. Counting
+ * ink is blind to both — that same reversed fixture draws **1.30–1.39x**, under
+ * the bar, and a bloated one draws what it drew whatever the framing does with it
+ * afterwards. C08 and C09 hold both ends of that.
+ */
+export const OVERDRAW_RATIO = 1.5;
+
 /** How many worst frames a set prints when the whole set is too long to list. */
 export const WORST_FRAMES = 8;
 /** Sets no longer than this print every frame. */
@@ -1487,17 +2677,15 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
   lines.push(`  candidate  ${report.candidate.skeleton}`);
   lines.push(`  atlas      ${report.candidate.atlas}`);
   lines.push(`  frames     ${report.framesDir}`);
-  const v = report.viewport;
-  const how =
-    report.framing === 'candidate-pixels'
-      ? "fitted to the candidate's own drawn pixels"
-      : report.framing === 'frames-viewport'
-        ? `${FRAMES_SIDECAR}'s own box — the candidate measured into it`
-        : '--viewport';
   lines.push(
-    `  framed to  ${v.pixelWidth}x${v.pixelHeight}px  ${v.scale.toFixed(6)} px/unit  ` +
-      `world x[${v.x.toFixed(1)} .. ${(v.x + v.width).toFixed(1)}] y[${v.y.toFixed(1)} .. ${(v.y + v.height).toFixed(1)}]  (${how})`,
+    `  scope      ${
+      report.framingScope === 'per-shot'
+        ? "the framing decided per frame set (--framing shared measures every set in one shared framing)"
+        : "one framing across every frame set (--framing per-shot lets a set take frames.json's own box instead)"
+    }`,
   );
+  const v = report.viewport;
+  if (v !== null) lines.push(...framedToLines(v, report.framing));
   const r = report.referenceViewport;
   if (r) {
     lines.push(
@@ -1506,7 +2694,21 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
     );
     lines.push('             ⤷ the two world boxes are different coordinate systems and do not compare; the pixel grid does.');
   }
-  for (const line of framingLines(report)) lines.push(line);
+  for (const line of framingLines(report.framingFit)) lines.push(line);
+  if (report.sharedFraming) {
+    const shared = report.sharedFraming;
+    const f = shared.fit;
+    const signed = (n: number): string => `${n >= 0 ? '+' : ''}${n.toFixed(2)}`;
+    lines.push(
+      `  shared box one box for all ${report.animations.length} set(s) leaves x${f.scale.toFixed(6)}  offset ` +
+        `${signed(f.dx)}, ${signed(f.dy)} px   rms ${f.rms.toFixed(2)} px over ${f.frames * 4} edge(s)  ` +
+        `(${shared.source}; used for every set that could not take the frames' own box)`,
+    );
+    lines.push(
+      "             ⤷ how far one shared framing is from serving every set. A set below that took the frames' own " +
+        'box instead is measured with no such correction at all; --framing shared measures every set here.',
+    );
+  }
   for (const note of report.notes) lines.push(`  ⚠️ ${note}`);
   lines.push('');
 
@@ -1521,6 +2723,13 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
     lines.push(
       `     frames     ${anim.referenceFrames} on disk, candidate samples ${anim.candidateFrames}, ${anim.compared} compared`,
     );
+    // Only when this set has a framing of its own: under a shared scope, or a pin,
+    // the header already printed the one box every set was measured in, and
+    // repeating it per set would read as though they differed.
+    if (report.framingScope === 'per-shot' && report.viewport === null) {
+      for (const line of framedToLines(anim.viewport, anim.framing, '   ')) lines.push(line);
+      for (const line of framingLines(anim.framingFit, '   ')) lines.push(line);
+    }
     for (const note of anim.notes) lines.push(`     ⚠️ ${note}`);
     if (anim.compared === 0) {
       lines.push('');
@@ -1530,6 +2739,21 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
       `     MAE        mean ${f2(anim.meanMae)}  worst ${f2(anim.worstMae)} at f${String(anim.worstMaeFrame).padStart(4, '0')}` +
         `   (0..255 over the union alpha; over the whole frame, mean ${f2(anim.meanMaeFrame)})`,
     );
+    lines.push(
+      `                ⤷ over the REFERENCE's own drawn pixels, mean ${f2(anim.meanMaeReference)} — the union figure ` +
+        'compares two builds of the same rig; this one is the one to optimise against, because the union is yours to grow.',
+    );
+    if (anim.drawnRatio > OVERDRAW_RATIO) {
+      const mine = Math.round(anim.frames.reduce((sum, f) => sum + f.candidatePixels, 0) / anim.frames.length);
+      const theirs = Math.round(anim.frames.reduce((sum, f) => sum + f.referencePixels, 0) / anim.frames.length);
+      lines.push(
+        `                ⚠️ overdraw: this shot draws ${mine.toLocaleString('en-US')} px a frame where the reference ` +
+          `draws ${theirs.toLocaleString('en-US')} — ${anim.drawnRatio.toFixed(2)}x as much ink, past the ` +
+          `${OVERDRAW_RATIO}x no committed candidate reaches. Most of that excess lands in the MAE's own ` +
+          'denominator and makes the figure above cheaper without moving a pixel closer, so read the one under it. ' +
+          'Something here is drawn that should not be, or is far too big.',
+      );
+    }
     const blind =
       anim.framesWithoutDrift === 0
         ? ''
@@ -1541,6 +2765,8 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
           `f${String(anim.worstDriftFrame).padStart(4, '0')}${blind}`,
     );
     lines.push(changeSummary(anim));
+    for (const line of sheetLines(anim.sheet)) lines.push(line);
+    for (const line of chainTable(anim)) lines.push(line);
     lines.push('');
 
     const listed = framesToList(anim, opts?.allFrames === true);
@@ -1574,14 +2800,22 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
     lines.push('');
   }
 
+  for (const line of chainFoot(report)) lines.push(line);
+
   lines.push('  MAE is the mean absolute RGB difference over the pixels either side covers, so it is');
   lines.push('  read against 255 and not against a threshold: there is no pass mark here any more than');
-  lines.push('  there is one in `diff`. Read the framing line first: it is upstream of every number');
+  lines.push('  there is one in `diff`. The figure under it divides the same difference by the pixels the');
+  lines.push('  REFERENCE drew — a denominator you cannot grow, which is what makes it the one to author');
+  lines.push('  against; it is not bounded by 255. Read the framing line first: it is upstream of every number');
   lines.push('  below, and a residual much wider than a pixel moves all of them at once.');
   lines.push('  The slots column is how many of the drawn slots could be attributed at all. A drift');
   lines.push('  marked `tmpl` was correlated against the slot’s own pixels because the reference');
   lines.push('  merged it into a neighbour; the number beside it is how much better that match was');
   lines.push('  than its best rival, and a slot that matched nothing at all is left out of the count.');
+  lines.push('  A `sheet` line is the frames a set does not commit as files: the candidate sampled at the');
+  lines.push("  set's own rate against the tiles of its contact.png, in the same box the frame table used.");
+  lines.push('  Read it as a series — flat is framing or art, a spike is timing at that moment — and note');
+  lines.push('  that it is MAE only: the change columns below are pixel counts at frame scale.');
   lines.push('  `Δpx` and `ref Δ` are how many pixels each side moved since ITS OWN previous frame —');
   lines.push('  not against each other. They are the only columns that can see a held pose that is');
   lines.push('  not held, or a one-frame event that never fired: both are small in every frame and');
@@ -1589,6 +2823,164 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
   return lines;
 }
 
+/** One drift, as the table says it: distance, slot, frame. */
+function driftPhrase(drift: number, slot: string | null, frame: number): string {
+  if (slot === null) return 'no slot attributable';
+  return `${drift.toFixed(1)} px ${JSON.stringify(slot)} f${String(frame).padStart(4, '0')}`;
+}
+
+/** One set, broken down by chain — see `ChainCheck`. */
+function chainTable(anim: AnimationCheck): string[] {
+  if (anim.chains.length === 0) return [];
+  const out: string[] = [];
+  out.push(
+    `     chains     ${anim.chains.length} from the candidate's own bone tree — the roster is at the foot of the report`,
+  );
+  out.push(
+    `       ${'chain'.padEnd(20)} ${'slots'.padStart(6)}   ${'worst slot drift'.padEnd(33)} ` +
+      `${'mean'.padStart(8)}   ${'MAE in it'.padStart(9)}   ${'share'.padStart(6)}`,
+  );
+  // Derivation order rather than worst-first, so the same row is in the same place
+  // in every set's table and a run can be read down a column.
+  for (const chain of anim.chains) {
+    const mean = chain.driftSamples === 0 ? '—' : `${chain.meanDrift.toFixed(1)} px`;
+    out.push(
+      `       ${chain.chain.padEnd(20)} ${`${chain.drewSlots}/${chain.slots}`.padStart(6)}   ` +
+        `${driftPhrase(chain.worstDrift, chain.worstDriftSlot, chain.worstDriftFrame).padEnd(33)} ` +
+        `${mean.padStart(8)}   ${f2(chain.mae).padStart(9)}   ${`${(chain.maeShare * 100).toFixed(1)}%`.padStart(6)}`,
+    );
+  }
+  if (anim.unattributedError > 0 && anim.chainDenominator > 0) {
+    const share = (anim.unattributedError / anim.chainDenominator) * 100;
+    out.push(
+      `       ${'(unattributed)'.padEnd(20)} ${'—'.padStart(6)}   ${'—'.padEnd(33)} ${'—'.padStart(8)}   ` +
+        `${'—'.padStart(9)}   ${`${share.toFixed(1)}%`.padStart(6)}`,
+    );
+  }
+  out.push(
+    "                ⤷ share is of this set's own difference over the REFERENCE's drawn pixels, split by nearest ink; " +
+      '`MAE in it` is that same error per pixel. The rule, the denominator and what a 0 % row means are under ' +
+      '"chains" at the foot of the report.',
+  );
+  return out;
+}
+
+/** One line per chain across every set, plus the roster the names refer to. */
+function chainFoot(report: CheckReport): string[] {
+  if (report.chains.length === 0) return [];
+  const out: string[] = [];
+  out.push('  ── chains ──');
+  out.push(
+    "  Cut from the CANDIDATE's own bone tree at every branch point: a chain runs from a root or a fork down to the",
+  );
+  out.push(
+    '  next fork, a single-bone chain that is itself a fork folds into its parent, and each is named after the first',
+  );
+  out.push(
+    '  bone in it that carries a slot. The reference is still nothing but pixels — this is your figure decomposed,',
+  );
+  out.push('  not the reference’s, which is what keeps it inside the ladder’s honesty rule.');
+  out.push('');
+  out.push("  MAE share divides the difference over the REFERENCE's own drawn pixels — the denominator from the MAE");
+  out.push('  line above, which nothing you draw can grow — and splits it by giving each of those pixels to the chain');
+  out.push('  whose ink is NEAREST it. So the shares are a partition and add to the whole, and no chain can look');
+  out.push('  better by drawing more: growing its ink only pulls more of the reference’s pixels, and their error,');
+  out.push('  into it. `MAE in it` is the same error per pixel it took, and it is the column that separates a chain');
+  out.push('  that is WRONG from one that is merely large — a head and its features cover a lot of a figure and can');
+  out.push('  carry a third of the error at a below-average figure per pixel.');
+  out.push('');
+  out.push('  ⚠️ Two things the split cannot do, both of which show rather than hide. Reference ink further from your');
+  out.push('  ink than the part’s own size is left `(unattributed)` instead of blamed on a neighbour, so a part that');
+  out.push('  has left its place stops being charged to whatever is next to it. And a chain that draws NOTHING seeds');
+  out.push('  nothing and reads 0 % — which is why the slots column is beside the share: 0 % on 0 slots drawn is the');
+  out.push('  loudest row here, not the quietest.');
+  out.push(`    ${'chain'.padEnd(20)} ${'bones'.padEnd(57)} slots`);
+  for (const chain of report.chains) {
+    out.push(
+      `    ${chain.name.padEnd(20)} ${chain.bones.join(', ').padEnd(57)} ` +
+        `${chain.slots.length === 0 ? '(draws nothing)' : chain.slots.join(', ')}`,
+    );
+  }
+  const rows = chainRollup(report);
+  if (rows.length === 0) return out;
+  out.push('');
+  out.push(
+    `    ${'chain'.padEnd(20)} ${'worst slot drift across every set'.padEnd(56)} ` +
+      `${'mean'.padStart(8)}   ${'MAE in it'.padStart(9)}   ${'share'.padStart(6)}`,
+  );
+  for (const row of rows) {
+    const where = row.set === null ? '' : ` in ${row.set}/f${String(row.frame).padStart(4, '0')}`;
+    const worst =
+      row.slot === null ? 'no slot attributable in any set' : `${row.drift.toFixed(1)} px ${JSON.stringify(row.slot)}${where}`;
+    const mean = row.samples === 0 ? '—' : `${row.mean.toFixed(1)} px`;
+    out.push(
+      `    ${row.chain.padEnd(20)} ${worst.padEnd(56)} ${mean.padStart(8)}   ` +
+        `${(row.pixels === 0 ? 0 : row.error / row.pixels).toFixed(2).padStart(9)}   ` +
+        `${`${(row.share * 100).toFixed(1)}%`.padStart(6)}`,
+    );
+  }
+  out.push('');
+  return out;
+}
+
+interface ChainRollup {
+  chain: string;
+  drift: number;
+  slot: string | null;
+  set: string | null;
+  frame: number;
+  mean: number;
+  samples: number;
+  error: number;
+  pixels: number;
+  share: number;
+}
+
+/**
+ * Each chain's worst reading anywhere in the run, worst share first.
+ *
+ * Worst-first here and derivation order in the per-set tables, deliberately: this
+ * is the line a run’s README quotes, so it is ranked by what to fix, while a table
+ * printed once per set is ranked so the sets line up.
+ */
+function chainRollup(report: CheckReport): ChainRollup[] {
+  const rows = new Map<string, ChainRollup>();
+  let denominator = 0;
+  for (const anim of report.animations) {
+    if (anim.compared === 0) continue;
+    denominator += anim.chainDenominator;
+    for (const chain of anim.chains) {
+      const row = rows.get(chain.chain) ?? {
+        chain: chain.chain,
+        drift: 0,
+        slot: null,
+        set: null,
+        frame: -1,
+        mean: 0,
+        samples: 0,
+        error: 0,
+        pixels: 0,
+        share: 0,
+      };
+      if (chain.worstDriftSlot !== null && chain.worstDrift > row.drift) {
+        row.drift = chain.worstDrift;
+        row.slot = chain.worstDriftSlot;
+        row.set = anim.dir;
+        row.frame = chain.worstDriftFrame;
+      }
+      row.mean = row.mean * row.samples + chain.meanDrift * chain.driftSamples;
+      row.samples += chain.driftSamples;
+      row.mean = row.samples === 0 ? 0 : row.mean / row.samples;
+      row.error += chain.error;
+      row.pixels += chain.referencePixels;
+      rows.set(chain.chain, row);
+    }
+  }
+  const out = [...rows.values()];
+  for (const row of out) row.share = denominator === 0 ? 0 : row.error / denominator;
+  return out.sort((a, b) => b.share - a.share);
+}
+
 /**
  * The frames worth printing: the worst by MAE, plus every change disagreement.
  *
@@ -1659,8 +3051,72 @@ function convergence(framing: FramingReport): string {
 }
 
 /** The framing, as the line an author reads before anything else. */
-function framingLines(report: CheckReport): string[] {
-  const framing = report.framingFit;
+/** The `framed to` line: the box that was rendered into, and how it was chosen. */
+function framedToLines(v: Framing, how: FramingHow | null, indent = ''): string[] {
+  const said =
+    how === 'candidate-pixels'
+      ? "fitted to the candidate's own drawn pixels"
+      : how === 'frames-viewport'
+        ? `${FRAMES_SIDECAR}'s own box — the candidate measured into it`
+        : '--viewport';
+  return [
+    `${indent}  framed to  ${v.pixelWidth}x${v.pixelHeight}px  ${v.scale.toFixed(6)} px/unit  ` +
+      `world x[${v.x.toFixed(1)} .. ${(v.x + v.width).toFixed(1)}] y[${v.y.toFixed(1)} .. ${(v.y + v.height).toFixed(1)}]  (${said})`,
+  ];
+}
+
+/**
+ * What the MAE-refined pass found, in the words that separate its four answers.
+ *
+ * All four are printed, the identity included, because "the framing is already
+ * where the picture is" is a measurement this pass makes and not a default it
+ * falls back to — the same reason an assertion with nothing to measure reports
+ * SKIP here rather than a pass. The two that decline a real offset are the loud
+ * ones: they say the constant pixel is in the candidate rather than in the box.
+ */
+function refinementLines(refinement: FramingRefinement | null, indent = ''): string[] {
+  if (refinement === null) return [];
+  const { dx, dy, before, after, radius, frames } = refinement;
+  const at = `${dx >= 0 ? '+' : ''}${dx}, ${dy >= 0 ? '+' : ''}${dy} px`;
+  const worth =
+    `${f2(before)} → ${f2(after)} over the reference's own pixels` +
+    (before > 0 ? ` (${(((before - after) / before) * 100).toFixed(1)}% of the figure)` : '');
+  const searched = `±${radius} px over ${frames} frame(s)`;
+  if (refinement.declined === 'identity') {
+    return [
+      `${indent}             ⤷ MAE-refined pass: searched ${searched} and the identity won, so no part of this set's ` +
+        'figure is a constant offset.',
+    ];
+  }
+  if (refinement.declined === 'below-threshold') {
+    return [
+      `${indent}             ⤷ MAE-refined pass: the best offset in ${searched} was ${at}, worth ${worth} — under the ` +
+        `${(REFINE_MIN_GAIN * 100).toFixed(0)}% / ${REFINE_MIN_GAIN_MAE.toFixed(2)} MAE this pass moves a box for, so ` +
+        'the box was left alone.',
+    ];
+  }
+  if (refinement.declined === 'box-is-exact') {
+    return [
+      `${indent}             ⚠️ a constant ${at} would take this set ${worth} — and it was NOT applied, because this ` +
+        `box is ${FRAMES_SIDECAR}'s own and is not an estimate of anything. A constant pixel inside the box the ` +
+        'frames were drawn at is your own figure sitting a pixel off, which is a thing to fix rather than to frame ' +
+        'away. Read it beside the drift below.',
+    ];
+  }
+  if (refinement.declined === 'pinned') {
+    return [
+      `${indent}             ⤷ a constant ${at} would take this set ${worth} — measured, NOT applied, because ` +
+        '--viewport pinned the box.',
+    ];
+  }
+  return [
+    `${indent}             ⭐ MAE-refined by ${at}: ${worth}. The fit above registers the two extents, and the best ` +
+      'fit of two extents is not the best alignment of two pictures — this pass takes that difference out, so the ' +
+      'figures below are what is left after it rather than a constant offset read as motion.',
+  ];
+}
+
+function framingLines(framing: FramingReport | null, indent = ''): string[] {
   if (!framing) return [];
   const { fit } = framing;
   const c = fit.candidate;
@@ -1670,8 +3126,8 @@ function framingLines(report: CheckReport): string[] {
     `${boxWidth(b).toFixed(1)}x${boxHeight(b).toFixed(1)}px at (${b.left.toFixed(1)}, ${b.top.toFixed(1)})`;
   const signed = (n: number): string => `${n >= 0 ? '+' : ''}${n.toFixed(2)}`;
   const out = [
-    `  content    candidate ${box(c)}   reference ${box(r)}   (union over ${fit.frames} frame(s))`,
-    `             ⤷ fit x${fit.scale.toFixed(6)}  offset ${signed(fit.dx)}, ${signed(fit.dy)} px   ` +
+    `${indent}  content    candidate ${box(c)}   reference ${box(r)}   (union over ${fit.frames} frame(s))`,
+    `${indent}             ⤷ fit x${fit.scale.toFixed(6)}  offset ${signed(fit.dx)}, ${signed(fit.dy)} px   ` +
       `rms ${fit.rms.toFixed(2)} px over ${fit.frames * 4} edge(s)   ` +
       `union residual ${signed(fit.residualWidth)} x ${signed(fit.residualHeight)} px   ` +
       `aspect ${percent(fit.aspectError)}` +
@@ -1679,11 +3135,12 @@ function framingLines(report: CheckReport): string[] {
         ? `  (${framing.source}, ${framing.passes} pass(es), ${convergence(framing)})`
         : '  (measured, NOT applied — --viewport pinned)'),
   ];
+  out.push(...refinementLines(framing.refinement, indent));
   const spread = Math.max(Math.abs(fit.residualWidth), Math.abs(fit.residualHeight));
   if (spread > 1) {
     const axis = fit.residualWidth > 0 ? 'wider' : 'narrower';
     out.push(
-      `             ⚠️ after the fit your shot still covers ${Math.abs(fit.residualWidth).toFixed(1)} px ` +
+      `${indent}             ⚠️ after the fit your shot still covers ${Math.abs(fit.residualWidth).toFixed(1)} px ` +
         `${axis} and ${Math.abs(fit.residualHeight).toFixed(1)} px ` +
         `${fit.residualHeight > 0 ? 'taller' : 'shorter'} than the reference's. One uniform scale cannot absorb ` +
         'that: something reaches somewhere nothing in the frames does, or is a different size. Read it before ' +
@@ -1692,7 +3149,7 @@ function framingLines(report: CheckReport): string[] {
   }
   if (fit.rms > 1) {
     out.push(
-      `             ⚠️ the fit leaves ${fit.rms.toFixed(2)} px rms across the frames' edges, so no single ` +
+      `${indent}             ⚠️ the fit leaves ${fit.rms.toFixed(2)} px rms across the frames' edges, so no single ` +
         'scale and offset puts the two shots on each other — they are different shapes, not the same shape ' +
         'misframed.',
     );
@@ -1700,12 +3157,12 @@ function framingLines(report: CheckReport): string[] {
   const units = framing.units;
   if (units) {
     out.push(
-      `  in units   candidate ${units.candidate.width.toFixed(1)} x ${units.candidate.height.toFixed(1)}   ` +
+      `${indent}  in units   candidate ${units.candidate.width.toFixed(1)} x ${units.candidate.height.toFixed(1)}   ` +
         `reference ${units.reference.width.toFixed(1)} x ${units.reference.height.toFixed(1)}   ` +
         `x${units.ratio.toFixed(4)}`,
     );
     out.push(
-      '             ⤷ the same two boxes in world units. The framing absorbs a difference of pure scale on ' +
+      `${indent}             ⤷ the same two boxes in world units. The framing absorbs a difference of pure scale on ` +
         'purpose — a rig is authored in its own coordinates — so this is the only place one shows. It compares ' +
         'only if you measured the shot in the frames’ own units.',
     );