spine-rigc 0.9.0 → 0.11.0

package/README.md

@@ -30,6 +30,8 @@ parser and a list of named assertions all come back green.
 | You have | You run | You get |
 | --- | --- | --- |
 | part PNGs, a rig spec and a motion spec | `rigc build` | `skeleton.json` + `skeleton.atlas` — or a failure named by rule, and **nothing on disk** |
+| the same, and one texture instead of many | `rigc build --pack` | the parts arranged onto shared atlas pages, written beside the skeleton — losslessly, so the picture is the picture |
+| a pack somebody already made | `rigc build --atlas-in` | the same skeleton, with every part resolved to a region of that atlas — or a named refusal, never a part that silently does not draw |
 | a compiled rig | `rigc render` | every animation as PNG frames, plus one labelled contact sheet of the whole shot |
 | a compiled rig | `rigc preview` | one self-contained `.html` that plays it in Spine's own web player |
 | two to four compiled rigs | `rigc vote` | one ballot page a human picks from, and the answer checked into a ledger |
@@ -81,10 +83,11 @@ run a list of named assertions, and **write nothing unless all of them are green
 
 ## Install
 
-📦 **rigc measures loose PNGs directly — one atlas page per image.** It is not an
-atlas packer: packing several regions onto one page is tracked as
-[issue #4](https://github.com/firejune/rigc/issues/4), not something the tool does
-today.
+📦 **rigc measures loose PNGs directly, and emits one atlas page per image unless
+you ask otherwise.** `rigc build --pack` arranges every part onto shared pages and
+writes them into `--out`; `--atlas-in` builds against a pack somebody else made.
+Both are opt-in and both are narrow — no trimming, no rotation, no scaling — and
+[AUTHORING §0.1–§0.2](docs/AUTHORING.md) states the limits before you hit them.
 
 rigc runs on [Bun](https://bun.sh). The package ships its TypeScript sources and
 Bun runs them, so there is no build step and no `dist/` that can drift from the
@@ -370,6 +373,22 @@ A part that matches nowhere is refused by name, two near-equal placements are re
 as both, and nothing it prints is a score. Fields, the coordinate contract and the
 limits: [AUTHORING.md §11](docs/AUTHORING.md).
 
+## The gallery — four complete rigs over art that ships with them
+
+Each directory in [`gallery/`](https://github.com/firejune/rigc/tree/main/gallery) is
+one rig spec, one motion spec and the PNGs they name, small enough to read in one
+sitting. Each stars a single feature, so *how do I do X* has a working answer rather
+than a field table, and each README carries the frame rate it was authored at, what
+was verified, and what writing it cost. Repository material: a clone and
+`bun install` runs them.
+
+| Example | Stars | What it is |
+| --- | --- | --- |
+| [`gallery/walk`](https://github.com/firejune/rigc/tree/main/gallery/walk) | `ik` constraints + **`ik` timelines** | Two two-bone leg chains solved to foot targets — the planted leg nailed down, the swinging one let go at the top of its lift |
+| [`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash) | **`deform` timelines** | A ball squashed about its contact point and stretched along its travel, from two affine transforms written out in the README |
+| [`gallery/flex`](https://github.com/firejune/rigc/tree/main/gallery/flex) | **`contour` meshes** | A swallow-tailed banner and a serrated leaf: four meshes traced off their own alpha, waved by bone timelines and rippled by a `deform` |
+| [`gallery/ride`](https://github.com/firejune/rigc/tree/main/gallery/ride) | `path` attachments + **path constraints** | A trolley coasting down a drawn rail and rolling back, driven by a `position` timeline, with `groups` + `stagger` keying the wheels and the ears |
+
 ## Commands
 
 Every command takes its paths explicitly. `rigc <command> --help` prints its flags, and
@@ -379,6 +398,8 @@ commands take it and what its default is.
 | Command | Does |
 | --- | --- |
 | `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained |
+| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
+| `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/` |
@@ -413,6 +434,7 @@ the art. Its shape is under
 | --- | --- |
 | 📘 **[docs/AUTHORING.md](docs/AUTHORING.md)** | **the format guide, and the one to read before writing a spec.** Both input files field by field with a complete minimal example each, every field with its Spine meaning, the rules that decide what is emitted, the build → read the report → fix → repeat loop, the map from every named failure to the file that has to change, and the features rigc refuses by name so you do not spend a loop discovering them. It travels **inside the npm package**, at `node_modules/spine-rigc/docs/AUTHORING.md` |
 | 🎞️ **[docs/MOTION.md](docs/MOTION.md)** | **the key-pose recipe.** How to get two poses, what a pair of poses does and does not fix, the in-betweening rules and where each comes from, and how to spread candidates so a ballot informs. Ships in the package too |
+| 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
 | 🤖 **[docs/PROMPTING.md](docs/PROMPTING.md)** | **handing the authoring to an AI agent** — the prompt clauses a measured pilot run paid for, and what you can leave unsaid. Ships in the package too |
 | 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | Spine 4.3's full export surface against what rigc emits and what the official examples measurably use, with the ordered gap list |
 | 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 36 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
@@ -424,21 +446,27 @@ rigc is measured against **Spine's own official example projects** — the
 `1-weight-and-mass` … `8-follow-through` series as a difficulty ladder, with spineboy
 as the graduation exam.
 
-🎓 **The ladder was completed 2026-08-28.** All eight numbered rungs and the
-spineboy graduation exam cleared under gate v2.1 and held under **v2.2**, every clause PASS or SKIP:
+🎓 **The ladder is complete, 2026-08-28.** All eight numbered rungs and the
+spineboy graduation exam are cleared and hold under the current gate, **v2.3**, every clause PASS or SKIP:
 worst attributable slot drift **5.55 px** against a 6.0 px bar, and **0 of 124**
 frame-change disagreements. Recompiling the same spec in a different session
 reproduced every field of the measurement record **to the digit**. The rungs stay
 in place as regression gates.
 
-⚠️ **Current state, 2026-09-02: seven of the eight hold, and rung 7 is open.**
-`check`'s extent tolerance ([PR #254](https://github.com/firejune/rigc/pull/254))
-changed which box a set is measured in, and rung 7's stored candidate fails **G2**
+🗓️ **One rung's pass was withdrawn and restored on 2026-09-02, and both are dated
+facts.** `check`'s extent tolerance ([PR #254](https://github.com/firejune/rigc/pull/254))
+changed which box a set is measured in, and rung 7's stored candidate failed **G2**
 under it — one of its three slots draws in every set and is attributable in none,
-and no read-down kind survives the framing change. **Rungs 1–6 and 8 and the
-graduation exam are unaffected**: each reproduces its gated figures to the digit,
-and the 5.55 px and 0-of-124 figures above are among them. Verdict and reasoning
-in [docs/LADDER.md](docs/LADDER.md)'s *PR #254 instrument re-inspection*.
+and no read-down ground survived the framing change. The gate then answered the two
+clause questions that exposed, as **v2.3**: a read-down names the framing of its
+evidence, and a slot whose attributability is **measured** to be capped below the bar
+reads down when everything observable about it is independently verified strict. That
+rung's third attempt clears on those grounds, on the candidate it already had.
+**Rungs 1–6 and 8 and the graduation exam were unaffected throughout**: each reproduces
+its gated figures to the digit, and the 5.55 px and 0-of-124 figures above are among
+them. Both verdicts, and the sweep of every candidate under the new gate, are in
+[docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md)'s *PR #254 instrument re-inspection* and *gate-v2.3
+re-inspection*.
 
 ⚠️ **What that certifies, stated exactly.** That **the tool, the guide and the
 protocol reach the bar across a bounded series of honest attempts, each residual

package/cli.ts

@@ -48,10 +48,19 @@ import {
   type BallotCandidateInput,
   type BallotInput,
 } from './src/ballot.ts';
+import {
+  boneDistance,
+  BONEDIST_SPEC,
+  boneDistLines,
+  BoneDistError,
+  IDENTITY_CORRESPONDENCE,
+  type BoneDistReport,
+} from './src/bonedist.ts';
 import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
 import { compile, CompileError, type CompileOptions } from './src/compile.ts';
-import { diffLines, diffSkeletons, sectionFigures, type DiffReport } from './src/diff.ts';
+import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
 import { copyAtlasImages } from './src/emit.ts';
+import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
 import {
@@ -152,7 +161,7 @@ function repositoryUrl(): string {
  * flag": inferring it would turn `--out --json report.json` — a real typo, a
  * missing value — into a silently accepted switch plus a stray positional.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'help', 'copy-images', 'again']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'help', 'copy-images', 'again', 'pack']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -276,6 +285,7 @@ function resolveCut(flags: Record<string, string>): { label: string; opts: Compi
     };
     if (flags.manifest !== undefined) opts.manifestPath = resolve(flags.manifest);
     if (flags.images !== undefined) opts.imagesDir = resolve(flags.images);
+    if (flags['atlas-in'] !== undefined) opts.atlasInPath = resolve(flags['atlas-in']);
     return { label: flags.rig, opts };
   }
   if (flags.cut === undefined) throw new UsageError('give either --cut <name> --cuts <cuts.json>, or --rig/--motion/--out');
@@ -287,7 +297,13 @@ function resolveCut(flags: Record<string, string>): { label: string; opts: Compi
       `unknown cut ${JSON.stringify(flags.cut)} in ${resolve(flags.cuts)}. known: ${Object.keys(table).join(', ') || '(none)'}`,
     );
   }
-  return { label: flags.cut, opts: entryToOptions(dir, flags.cut, entry) };
+  const opts = entryToOptions(dir, flags.cut, entry);
+  // `--atlas-in` is not part of the cuts table: a cut names its rig, motion and
+  // manifest, and where the pixels are delivered from is a property of the BUILD.
+  // Resolved against the working directory, like every other path on the command
+  // line, rather than against the table's directory.
+  if (flags['atlas-in'] !== undefined) opts.atlasInPath = resolve(flags['atlas-in']);
+  return { label: flags.cut, opts };
 }
 
 // ---------------------------------------------------------------------------
@@ -311,15 +327,35 @@ function readProfile(flags: Record<string, string>): ValidateProfile {
   return found;
 }
 
-function runGate(result: CompileResult, opts: CompileOptions, profile: ValidateProfile): number {
+/**
+ * An atlas text to gate INSTEAD of the compile's own, with the second, independent
+ * emit A18 compares it against.
+ *
+ * `--pack` is the only caller. A packed build is gated twice on purpose — once as
+ * compiled (which is the gate that reads the loose PNGs, so `A06`'s size-vs-file
+ * clause still measures the art R5 measures) and once as packed (which is the pair
+ * that actually ships). Handing the second pass its texts rather than re-deriving
+ * them here keeps `runGate` ignorant of what a pack is.
+ */
+interface AtlasOverride {
+  text: string;
+  again: string;
+}
+
+function runGate(
+  result: CompileResult,
+  opts: CompileOptions,
+  profile: ValidateProfile,
+  atlas?: AtlasOverride,
+): number {
   // The determinism check compares a second, independent compile.
   const again = compile(opts);
   const report = validate({
     skeletonText: result.skeletonText,
-    atlasText: result.atlasText,
+    atlasText: atlas ? atlas.text : result.atlasText,
     atlasDir: opts.outDir,
     declaredDurations: result.declaredDurations,
-    reEmit: { skeletonText: again.skeletonText, atlasText: again.atlasText },
+    reEmit: { skeletonText: again.skeletonText, atlasText: atlas ? atlas.again : again.atlasText },
     rig: result.rig,
     profile,
   });
@@ -346,15 +382,88 @@ const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> =
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
-/** What a contour mesh measured about its own fit, or nothing for the others. */
+/**
+ * What a mesh measured about its own fit against the art it names, or nothing
+ * for a mesh with no art to measure against.
+ *
+ * Printed for authored geometry as well as for a `contour` (issue #277): the
+ * figure is a measurement between the emitted triangles and the PNG, so it means
+ * the same thing whoever drew the vertices, and the silence was the defect —
+ * an octagon rim placed on a round part's silhouette clips its own ink outline
+ * at 94.31% and used to print nothing at all.
+ *
+ * The hole is appended only when there is one, so the common line is unchanged.
+ * It is the one figure in the report that a hole moves: `coverage` and
+ * `overshoot` are both measured against the FILLED silhouette, so spanning an
+ * interior hole is neither missing coverage nor reaching past anything, and an
+ * unintentional hole — a gap in the art, a stroke that failed to join — bought
+ * fill over transparent pixels with nothing anywhere saying so (issue #275).
+ */
 function meshFit(m: CompileResult['meshes'][number]): string {
   if (m.coverage === undefined) return '';
-  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it`;
+  const hole = m.holePixels ? `, enclosing ${m.holePixels}px of hole` : '';
+  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it${hole}`;
+}
+
+/**
+ * The triangle budget a `MESH` line is read against: the rig's, or nothing.
+ *
+ * 📐 It used to be the literal `80`, which was nobody's budget — the rig quoted
+ * in issue #275 declared 64, `A13_MESH_BUDGET` measured against that 64
+ * correctly, and the line an author actually reads printed 80. Under the default
+ * `--profile spine` `A13` is `PROF`, so the printed number is the only budget
+ * figure in the output and it has to be the declared one. A rig that declares
+ * none says so in the same words `A13` SKIPs in, rather than being given a wall.
+ */
+function meshBudget(rig: CompileResult['rig']): string {
+  return rig.meshTriangleBudget === null ? '(no budget declared)' : `(budget ${rig.meshTriangleBudget})`;
+}
+
+/**
+ * Read one non-negative integer flag, or its default.
+ *
+ * A usage error rather than a `NaN` that reaches the packer: `--padding two`
+ * would otherwise place every region at NaN and write a blank page, which is a
+ * green build and an empty picture.
+ */
+function readIntFlag(flags: Record<string, string>, name: string, fallback: number): number {
+  const raw = flags[name];
+  if (raw === undefined) return fallback;
+  if (!/^\d+$/.test(raw)) throw new UsageError(`--${name} takes a non-negative integer, got ${JSON.stringify(raw)}`);
+  return Number(raw);
 }
 
 function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
+  const packing = flags.pack !== undefined;
+  // Three combinations are refused rather than silently resolved, because in each
+  // one the two flags disagree about a single question and there is no answer
+  // that is not a guess about which the caller meant.
+  if (packing && opts.atlasInPath !== undefined) {
+    throw new UsageError(
+      '--pack and --atlas-in are opposite directions through the same door: --pack MAKES an atlas out of the ' +
+        'loose parts, --atlas-in resolves the parts against one somebody already made. Pick one',
+    );
+  }
+  if (packing && flags['copy-images'] !== undefined) {
+    throw new UsageError(
+      '--pack already writes self-contained pages into --out (that is what packing is), and --copy-images copies ' +
+        'the loose part PNGs, which a packed atlas does not reference. Drop --copy-images',
+    );
+  }
+  if (packing && profile === 'spine-html') {
+    throw new UsageError(
+      "--profile spine-html asserts one part per page (A06's full-page coverage clause), which is rigc's unpacked " +
+        'convention and exactly what --pack stops being true. A packed atlas is valid Spine — build it under the ' +
+        'default --profile spine',
+    );
+  }
+  if (!packing) {
+    for (const name of ['page-size', 'padding'] as const) {
+      if (flags[name] !== undefined) throw new UsageError(`--${name} only means something with --pack`);
+    }
+  }
   console.log(`rigc build ${label}`);
   // Named explicitly and on their own lines rather than folded into the header
   // above: with two input files, a header that names only one of them (the rig,
@@ -364,12 +473,26 @@ function cmdBuild(flags: Record<string, string>): void {
   console.log(`  ..    motion ${opts.motionPath}`);
   const result = compile(opts);
 
+  if (opts.atlasInPath !== undefined) console.log(`  ..    atlas-in ${opts.atlasInPath}`);
   console.log(`  ..    ${result.images.length} part page(s):`);
   for (const img of result.images) {
-    console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${img.page}`);
+    // An imported part says where on the page it came from, because "resolved
+    // against a region" is the claim `--atlas-in` makes and a line that only
+    // repeated the page filename would look identical for all of them. A page
+    // that declares a `scale:` also says so and shows the texels it was read
+    // from: the size on the left is the DRAWING's and the rectangle is the
+    // pack's, and issue #267 is the report that printed the second as the first.
+    const where =
+      img.atlas === undefined
+        ? img.page
+        : `${img.page} @ ${img.atlas.x},${img.atlas.y}${img.atlas.degrees ? ` rotate ${img.atlas.degrees}` : ''}` +
+          (img.atlasScale === undefined
+            ? ''
+            : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`);
+    console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${where}`);
   }
   for (const d of result.droppedStates) {
-    console.log(`  DROP  ${d.slot}/${d.state}: no PNG at ${d.path} (state not emitted)`);
+    console.log(`  DROP  ${d.slot}/${d.state}: ${d.why ?? `no PNG at ${d.path}`} (state not emitted)`);
   }
   // "The optional slots are optional" is a claim about this code path, so this
   // code path says which ones it left out rather than being silently right.
@@ -379,7 +502,7 @@ function cmdBuild(flags: Record<string, string>): void {
   for (const m of result.meshes) {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-        `(budget 80)  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
+        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
     );
   }
   for (const ph of result.physics) {
@@ -414,6 +537,64 @@ function cmdBuild(flags: Record<string, string>): void {
     }
   }
 
+  // `--pack`: the parts go onto shared pages, which are written here as real
+  // PNGs, so `--out` is self-contained by construction. The atlas above stays
+  // the one the gate just read — packing changes only the ARRANGEMENT of the
+  // bytes, and the sizes in `result.images` are still the ones measured off the
+  // loose PNGs (see src/atlas.ts's header).
+  if (packing) {
+    const packOpts = {
+      pageSize: readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE),
+      padding: readIntFlag(flags, 'padding', DEFAULT_PADDING),
+      pageStem: 'skeleton',
+    };
+    const inputs = result.images.map((img) => ({
+      region: img.region,
+      absPath: img.absPath,
+      width: img.width,
+      height: img.height,
+    }));
+    const packed = packAtlas(inputs, packOpts);
+    atlasText = packed.atlasText;
+    for (const page of packed.pages) {
+      page.plate.writePng(join(opts.outDir, page.name));
+      console.log(
+        `  ..    pack: ${page.name} ${page.width}x${page.height}, ` +
+          `${packed.placements.filter((p) => packed.pages[p.page].name === page.name).length} region(s), ` +
+          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}`,
+      );
+    }
+    for (const place of packed.placements) {
+      console.log(
+        `  ..      ${place.region.padEnd(24)} ${place.width}x${place.height} -> ` +
+          `${packed.pages[place.page].name} @ ${place.x},${place.y}`,
+      );
+    }
+    // The pages are on disk now, so the packed pair can be gated as an artifact
+    // rather than trusted as a construction: A17 stats every page, A06 reads its
+    // IHDR back, A07 re-reads the text shape, A08 re-joins every attachment onto
+    // a region, and A18 compares a second independent compile+pack. Two gates on
+    // one build is the cost of shipping a second atlas shape.
+    console.log('  ..    validate (packed atlas, pages on disk)');
+    const packAgain = packAtlas(
+      compile(opts).images.map((img) => ({
+        region: img.region,
+        absPath: img.absPath,
+        width: img.width,
+        height: img.height,
+      })),
+      packOpts,
+    );
+    const packFailures = runGate(result, opts, profile, { text: atlasText, again: packAgain.atlasText });
+    if (packFailures > 0) {
+      console.error(
+        `rigc: ${packFailures} assertion(s) failed on the PACKED atlas — the pages were written to ` +
+          `${opts.outDir}, the skeleton/atlas pair was not`,
+      );
+      process.exit(1);
+    }
+  }
+
   writeFileSync(join(opts.outDir, 'skeleton.json'), result.skeletonText);
   writeFileSync(join(opts.outDir, 'skeleton.atlas'), atlasText);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
@@ -1172,6 +1353,38 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
     diffs.push({ skeleton, reference: referencePath, report: diff });
   }
 
+  // Stage 3, optional and behind a flag because the correspondence is an INPUT:
+  // a candidate is entitled to its own bone names, so there is nothing sensible
+  // to default to and a derived mapping would be a guess reported as a
+  // measurement (issue #8). Nothing here gates, and without the flag the report
+  // above is unchanged to the byte.
+  const boneDists: Array<{ skeleton: RungSkeleton; report: BoneDistReport }> = [];
+  if (flags.bones !== undefined) {
+    for (const skeleton of rung.skeletons) {
+      const referencePath = join(exportDir, skeleton.file);
+      if (!existsSync(referencePath)) continue;
+      console.log(`  ── bonedist vs ${rung.example}/${skeleton.label} (stage 3) ──`);
+      const boneDist = boneDistance({
+        candidateSkeleton: skeletonPath,
+        candidateAtlas: atlasPath,
+        candidateAtlasDir: dirname(atlasPath),
+        referenceSkeleton: referencePath,
+        referenceAtlas: join(exportDir, skeleton.atlas),
+        referenceAtlasDir: exportDir,
+        bones: flags.bones,
+        // Deliberately NOT `flags.fps`. Inside `bench` that flag already means
+        // "the rate this frame set was recorded at, for a set with no sidecar",
+        // and one flag doing two unrelated things in one command is how a
+        // reader ends up quoting a figure measured at a rate they did not ask
+        // for. A run wanting another sampling rate calls `rigc bonedist`, where
+        // `--fps` has exactly one meaning.
+      });
+      for (const line of boneDistLines(boneDist, { allBones: flags['all-bones'] !== undefined })) console.log(`  ${line}`);
+      console.log('');
+      boneDists.push({ skeleton, report: boneDist });
+    }
+  }
+
   // Third, optional and third for a reason: is it the same MOTION? `diff`
   // compares structure, and a reversed easing is the same key count and the same
   // curve kind — so a row of this ladder carrying only `validate` and `diff`
@@ -1197,6 +1410,13 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
     // name-agnostic figure printed beside — issue #21.
     const split = d.report.sections.filter((s) => s.nameAgnostic !== undefined);
     if (split.length > 0) console.log(`  ${''.padEnd(10)} ${split.map(sectionFigures).join('   ')}`);
+    // A third line, for the same reason the second one is not folded into the
+    // first: the reported measures are unobservable by construction, so they
+    // roll into no mean at all and cannot be shown as one. Each is named with
+    // its own figure — a per-section digest would be the mean this block exists
+    // to refuse.
+    const reported = reportedFigures(d.report);
+    if (reported !== null) console.log(`  ${''.padEnd(10)} reported: ${reported}`);
   }
   if (check) {
     // The framing goes first because it is upstream of every MAE below it: a
@@ -1271,6 +1491,19 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
     console.log('  check      not run — pass --frames <dir> to compare against the rendered reference frames.');
     console.log('             Without it this report says nothing about whether the ANIMATION is right.');
   }
+  if (boneDists.length > 0) {
+    for (const b of boneDists) {
+      const w = b.report.worst;
+      console.log(
+        `  ${b.skeleton.label.padEnd(10)} bonedist worst position ${w.position.value.toFixed(6)} skeleton-size(s), ` +
+          `rotation ${w.rotation.value.toFixed(4)}°, scale ${w.scale.value.toFixed(6)}, linear ${w.linear.value.toFixed(6)}  ` +
+          `over ${b.report.animations.reduce((n, a) => n + a.compared, 0)} frame(s) × ${b.report.correspondence.pairs} bone pair(s)`,
+      );
+    }
+  } else {
+    console.log('  bonedist   not run — pass --bones <correspondence.json | identity> for the stage-3 per-frame');
+    console.log('             bone world-transform distance. It reports and gates nothing.');
+  }
   console.log('  Section figures are means of their own measures. There is no rung score:');
   console.log('  a rung is cleared by a person reading the measures, and docs/LADDER.md records it.');
 
@@ -1298,6 +1531,12 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
         ...d.report,
       })),
       check,
+      // Absent rather than null when the flag was not passed: `bonedist: null`
+      // in a stored record would read as "measured, nothing to report", and
+      // that is the opposite of "not measured".
+      ...(boneDists.length === 0
+        ? {}
+        : { boneDists: boneDists.map((b) => ({ label: b.skeleton.label, role: b.skeleton.role, ...b.report })) }),
     });
   }
 
@@ -1307,6 +1546,39 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
   }
 }
 
+/**
+ * bonedist — the ladder's stage 3, run on its own.
+ *
+ * ⚠️ It reads BOTH skeletons, so it is a finish-line instrument like `bench` and
+ * unlike `check`. Every convention behind every figure is printed above the
+ * tables, and there is no score — see [`src/bonedist.ts`](src/bonedist.ts).
+ */
+function cmdBoneDist(flags: Record<string, string>): void {
+  if (flags.candidate === undefined) throw new UsageError('bonedist needs --candidate <dir | skeleton.json>');
+  if (flags.reference === undefined) throw new UsageError('bonedist needs --reference <skeleton.json>');
+  if (flags.bones === undefined) {
+    throw new UsageError(
+      `bonedist needs --bones <correspondence.json | ${IDENTITY_CORRESPONDENCE}> — a candidate is entitled to its own bone ` +
+        'names, so the mapping is an input and never a guess; pass `identity` to state that the two use the same names',
+    );
+  }
+  const candidate = resolveArtifacts(flags.candidate, flags.atlas);
+  const reference = resolveArtifacts(flags.reference, flags['reference-atlas']);
+  const report = boneDistance({
+    candidateSkeleton: candidate.skeletonPath,
+    candidateAtlas: candidate.atlasPath,
+    candidateAtlasDir: dirname(candidate.atlasPath),
+    referenceSkeleton: reference.skeletonPath,
+    referenceAtlas: reference.atlasPath,
+    referenceAtlasDir: dirname(reference.atlasPath),
+    bones: flags.bones,
+    ...(flags.fps === undefined ? {} : { fps: Number(flags.fps) }),
+  });
+  console.log('rigc bonedist — per-frame bone world-transform distance (the ladder\'s stage 3)');
+  for (const line of boneDistLines(report, { allBones: flags['all-bones'] !== undefined })) console.log(line);
+  if (flags.json !== undefined) writeJson(flags.json, report);
+}
+
 function cmdExplain(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   console.log(`rigc explain ${label}`);
@@ -1522,7 +1794,8 @@ function cmdExplain(flags: Record<string, string>): void {
     for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);
     for (const m of result.meshes) {
       console.log(
-        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
+        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
+          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
       );
     }
   }
@@ -1555,12 +1828,29 @@ const FLAG_MEANINGS: Record<string, string> = {
   'copy-images':
     'also copy every referenced page PNG into --out and rewrite the atlas to the copies, so the directory is ' +
     'self-contained enough to zip or commit on its own (default: page paths still point at the source art)',
+  pack: 'arrange every part PNG onto shared atlas page(s) written into --out as real PNGs, instead of one page ' +
+    'per part. Lossless: every region is a byte-for-byte copy and nothing is resampled, trimmed or rotated ' +
+    '(default: one part, one page, pointing at the source art)',
+  'page-size': `largest page edge, --pack only (default ${DEFAULT_PAGE_SIZE}); pages are powers of two and the ` +
+    'one written is the smallest that holds the pack, spilling to more pages only when the set will not fit',
+  padding: `gutter each region reserves on every side, --pack only (default ${DEFAULT_PADDING}); it is filled by ` +
+    "extending the region's own edge pixels outwards, which is what stops a neighbour bleeding in",
+  'atlas-in':
+    'resolve every part against the regions of this pre-packed .atlas instead of against loose PNGs — region ' +
+    'geometry (bounds/offsets/rotate) is read from the file and the atlas is re-emitted into --out, re-anchored',
   cut: 'look up a named cut in --cuts <cuts.json>, instead of --rig/--motion/--out',
   cuts: 'the cuts.json --cut names',
   profile:
     'which rulebook to check against (default: spine) — spine = valid Spine 4.3 that any runtime plays ' +
     "correctly; spine-html = also this project's renderer/archetype policy",
   atlas: "the candidate's atlas, when it is not beside the skeleton",
+  reference: 'the reference skeleton to pose beside the candidate — a directory or a skeleton.json path',
+  'reference-atlas': "the reference's atlas, when it is not beside the reference skeleton",
+  bones: `a bone correspondence — { "spec": "${BONEDIST_SPEC}", "bones": { "<candidate bone>": "<reference bone>" }, ` +
+    '"animations"?: { … } } — or `identity` to state that the two skeletons use the same names. An INPUT, never ' +
+    'derived: a candidate is entitled to its own vocabulary, so a mapping worked out here would be a guess reported ' +
+    'as a measurement',
+  'all-bones': 'print every bone pair, not just the worst by position',
   'texture-from':
     "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
     'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
@@ -1600,7 +1890,13 @@ const FLAG_VALUES: Record<string, string> = {
   cuts: '<path>',
   profile: 'spine|spine-html',
   atlas: '<path>',
+  'atlas-in': '<file.atlas>',
+  'page-size': '<px>',
+  padding: '<px>',
   'texture-from': '<path>',
+  reference: '<dir|skeleton.json>',
+  'reference-atlas': '<path>',
+  bones: `<correspondence.json|${IDENTITY_CORRESPONDENCE}>`,
   candidate: '<dir|skeleton.json>',
   frames: '<dir>',
   fps: '<n>',
@@ -1646,9 +1942,25 @@ const COMMANDS: CommandDoc[] = [
     name: 'build',
     usage: [
       'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]',
+      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}]   (parts onto shared pages, written into --out)`,
+      'rigc build … --atlas-in <skeleton.atlas>                    (resolve the parts against a pack somebody already made)',
       'rigc build --cut <name> --cuts <cuts.json>',
     ],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'copy-images', 'cut', 'cuts', 'profile'],
+    flags: [
+      'rig',
+      'motion',
+      'out',
+      'manifest',
+      'images',
+      'copy-images',
+      'pack',
+      'page-size',
+      'padding',
+      'atlas-in',
+      'cut',
+      'cuts',
+      'profile',
+    ],
   },
   {
     name: 'explain',
@@ -1676,7 +1988,25 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'bench',
     usage: [`rigc bench <${RUNG_IDS.join(' | ')}> --candidate <dir | skeleton.json> [--frames <dir>] [flags]`],
-    flags: ['candidate', 'atlas', 'frames', 'profile', 'all-frames', 'json'],
+    flags: ['candidate', 'atlas', 'frames', 'profile', 'bones', 'all-frames', 'all-bones', 'json'],
+    overrides: {
+      bones: {
+        meaning:
+          'also run the stage-3 per-frame bone world-transform distance against each of the rung\'s reference ' +
+          `skeletons, with this correspondence (or \`identity\`), at ${PROTOCOL_FPS} fps. Reports; gates nothing — ` +
+          'for another sampling rate call `rigc bonedist` directly, where --fps means only that',
+      },
+    },
+  },
+  {
+    name: 'bonedist',
+    usage: [
+      `rigc bonedist --candidate <dir | skeleton.json> --reference <dir | skeleton.json> --bones <path | ${IDENTITY_CORRESPONDENCE}> [--fps ${PROTOCOL_FPS}] [--all-bones] [--json <out>]`,
+    ],
+    flags: ['candidate', 'atlas', 'reference', 'reference-atlas', 'bones', 'fps', 'all-bones', 'json'],
+    overrides: {
+      fps: { meaning: `the rate both skeletons are sampled at, from t=0 over their own durations (default ${PROTOCOL_FPS})` },
+    },
   },
   {
     name: 'render',
@@ -1843,6 +2173,7 @@ try {
   else if (command === 'diff') cmdDiff(flags, positional);
   else if (command === 'check') cmdCheck(flags);
   else if (command === 'bench') cmdBench(flags, positional);
+  else if (command === 'bonedist') cmdBoneDist(flags);
   else if (command === 'render') cmdRender(flags);
   else if (command === 'preview') cmdPreview(flags);
   else if (command === 'pose') cmdPose(flags);
@@ -1866,6 +2197,10 @@ try {
     console.error(`rigc check error: ${err.message}`);
     process.exit(1);
   }
+  if (err instanceof BoneDistError) {
+    console.error(`rigc bonedist error: ${err.message}`);
+    process.exit(1);
+  }
   // Like a usage error in kind — a missing directory, an unreadable frame — but
   // its messages name a path and a reason, and reprinting the whole usage under
   // them buries that.