spine-rigc 0.2.1 → 0.3.0

package/src/check.ts

@@ -77,6 +77,7 @@ import {
   PAD,
   FRAMES_SIDECAR,
   FRAMES_SPEC,
+  type Footprint,
   type Frame,
   type FramesSidecar,
   type FrameSet,
@@ -93,6 +94,7 @@ import {
   fitIsSettled,
   fitSeparation,
   frameContentBox,
+  unionBoxes,
   isContent,
   BACKGROUND_TOLERANCE,
   CYCLE_PIXELS,
@@ -100,10 +102,12 @@ import {
   type ContentBox,
   type FramingFit,
 } from './framing.ts';
-import { componentsOf, isAttributable, matchSlots, type SlotTrack } from './slots.ts';
+import { componentsOf, 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 { chainsOf, chainBySlot, type BoneChain } from './chains.ts';
 export type { BoxPair, ContentBox, FramingFit } from './framing.ts';
 
 // ---------------------------------------------------------------------------
@@ -259,6 +263,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 +308,60 @@ 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;
+}
+
 export interface AnimationCheck {
   dir: string;
   /** The animation the frames show, per the sidecar. */
@@ -296,6 +373,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 +400,38 @@ 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;
   notes: string[];
 }
 
@@ -339,6 +459,44 @@ 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. */
@@ -401,12 +559,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 +597,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 +632,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 +770,56 @@ 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 };
+    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 }),
+        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 });
     }
+  } 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 +830,115 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
       pixelHeight,
       referenceViewport,
     );
-    viewport = framed.viewport;
-    framingFit = { ...framed.report, units: extentsOf(framed.report.fit, viewport.scale, referenceViewport) };
+    const fit = { ...framed.report, units: extentsOf(framed.report.fit, framed.viewport.scale, referenceViewport) };
+    const how = HOW_BY_SOURCE[framed.report.source];
+    for (let i = 0; i < prepared.length; i++) framings.push({ viewport: framed.viewport, how, fit, notes: [] });
+    topViewport = framed.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,
+            );
+      if (!declared) {
+        framings.push({ ...sharedShape, notes: framingNotes(shared.report) });
+        continue;
+      }
+      own++;
+      framings.push({
+        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),
+      });
+    }
+    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 +948,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 +1150,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 +1261,7 @@ function frameCandidate(
   pixelWidth: number,
   pixelHeight: number,
   referenceViewport: Framing | null,
-): { viewport: Viewport; report: Omit<FramingReport, 'units'> } {
+): FramedSets {
   const declared = frameByDeclaredBox(
     prepared,
     pages,
@@ -909,34 +1272,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,
@@ -964,6 +1307,88 @@ function frameCandidate(
   };
 }
 
+/**
+ * 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.
@@ -1193,10 +1618,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 +1635,8 @@ function checkOneSet(
     candidateFrames: prepared.candidateFrames,
     compared: 0,
     meanMae: 0,
+    meanMaeReference: 0,
+    drawnRatio: 1,
     meanMaeFrame: 0,
     worstMae: 0,
     worstMaeFrame: -1,
@@ -1216,13 +1647,21 @@ 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,
+    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 +1677,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) {
@@ -1274,7 +1732,12 @@ function checkOneSet(
   return {
     ...blank,
     compared: frames.length,
+    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 +1749,7 @@ function checkOneSet(
     changeDisagreements,
     worstChangeFrame,
     frames,
-    notes: prepared.notes,
+    notes: [...framing.notes, ...prepared.notes],
   };
 }
 
@@ -1393,6 +1856,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 +2036,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,6 +2062,20 @@ 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;
@@ -1454,6 +2109,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,
@@ -1475,6 +2134,58 @@ function checkOneFrame(
 // 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 +2198,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 +2215,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 +2244,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 +2260,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 +2286,7 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
           `f${String(anim.worstDriftFrame).padStart(4, '0')}${blind}`,
     );
     lines.push(changeSummary(anim));
+    for (const line of chainTable(anim)) lines.push(line);
     lines.push('');
 
     const listed = framesToList(anim, opts?.allFrames === true);
@@ -1574,9 +2320,13 @@ 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');
@@ -1589,6 +2339,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 +2567,21 @@ 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})`,
+  ];
+}
+
+function framingLines(framing: FramingReport | null, indent = ''): string[] {
   if (!framing) return [];
   const { fit } = framing;
   const c = fit.candidate;
@@ -1670,8 +2591,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)}` +
@@ -1683,7 +2604,7 @@ function framingLines(report: CheckReport): string[] {
   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 +2613,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 +2621,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.',
     );