spine-rigc 0.25.5 → 0.25.6

package/README.md

@@ -413,8 +413,11 @@ that does not belong to it. See
   against frames of itself — is the floor the rest are read against, because
   `check` grades nothing and has no pass mark. It is the same instrument and the
   same commands; what changes is that the reference is a build of yours you have
-  already looked at, so what it measures is **what your edit did**. AUTHORING.md
-  §9.2 says what that floor reads and why it is not zero.
+  already looked at, so what it measures is **what your edit did**. Every drift
+  the report prints carries the bound its own match gives it on the line under
+  it, so a figure is read against that rather than against a number from a page;
+  AUTHORING.md §9.2 says what the two halves of that bound are and why the floor
+  is not zero.
 - [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) is the benchmark: the same job, from a brief
   and rendered frames, scored. [docs/PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) is how to run an
   agent through it and score what comes back.

package/cli.ts

@@ -68,8 +68,8 @@ import {
 } from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
 import { ingest, IngestError, INGEST_GUTTERS, type IngestStage } from './src/ingest.ts';
-import { copyAtlasImages } from './src/emit.ts';
-import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas } from './src/atlas.ts';
+import { copyAtlasPages } from './src/emit.ts';
+import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas, parseAtlasText } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
 import { KEY_TIME_EPSILON } from './src/timelines.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
@@ -117,6 +117,7 @@ import {
 } from './src/render.ts';
 import {
   assertionCountForProfile,
+  attachmentRegionJoins,
   CLI_DEFAULT_PROFILE,
   reportLines,
   validate,
@@ -148,6 +149,14 @@ export type CutTable = Record<string, CutEntry>;
 
 class UsageError extends Error {}
 
+/**
+ * `explain` refusing a pair it cannot pose — a usage error in kind, printed
+ * without the usage block for `PoseError`'s and `IngestError`'s reason: the
+ * message names an attachment, a region and two flags, and reprinting every
+ * command's usage under it buries the one line that says what to change.
+ */
+class ExplainError extends Error {}
+
 // ---------------------------------------------------------------------------
 // package metadata — the installed version and repository, for `--version`
 // and for naming a remedy `bench` can only give from a repo checkout.
@@ -1242,14 +1251,21 @@ function cmdBuild(flags: Record<string, string>): void {
   // correct for a build sitting beside the project it came from and breaks the
   // moment the directory is zipped, committed or moved on its own (issue #217).
   // Opt-in only: the default stays exactly what it has always been.
+  //
+  // What is copied is what the ATLAS names, not what the image list holds: under
+  // `--atlas-in` the two are different lists, and rebuilding the text from the
+  // second wrote a file the pack never contained — zero bytes for a rig that
+  // declares no parts, one fabricated page per part for a rig that does, both of
+  // them green here because the gate above had already read the compile's own
+  // text (issue #693, `src/emit.ts`).
   let atlasText = result.atlasText;
   if (flags['copy-images'] !== undefined) {
-    const copied = copyAtlasImages(result.images, opts.outDir);
+    const copied = copyAtlasPages(atlasText, opts.outDir);
     atlasText = copied.atlasText;
     console.log(`  ..    copy-images: ${copied.pages.length} page(s) copied into ${opts.outDir}`);
     for (const p of copied.pages) {
-      const note = p.to === basename(p.from) ? '' : `  (renamed from ${basename(p.from)} — basename collision)`;
-      console.log(`  ..      ${p.region.padEnd(24)} <- ${p.to}${note}`);
+      const note = p.to === basename(p.from) ? '' : '  (renamed — basename collision)';
+      console.log(`  ..      ${p.to.padEnd(24)} <- ${p.from}  (${p.regions} region(s))${note}`);
     }
   }
 
@@ -2434,6 +2450,81 @@ function cmdBoneDist(flags: Record<string, string>): void {
   if (flags.json !== undefined) writeJson(flags.json, report);
 }
 
+/**
+ * Refuse a compiled pair whose art `explain` cannot pose through, by name.
+ *
+ * 🚨 `explain` poses the rig — `deformReportLines` loads the emitted pair through
+ * `spine-core` to measure what each deform key did — and a pose resolves EVERY
+ * attachment against the atlas, whether or not anything deforms it. On the specs
+ * `ingest --art none` writes there is nothing to resolve against: the entries
+ * state a size and name no `image`, so the compile atlases nothing, and the load
+ * threw the runtime's own `Region not found in atlas: rear-upper-arm (attachment:
+ * rear-upper-arm)` with a spine-core stack trace under it and exit 1 (measured on
+ * `examples/spineboy/export/spineboy-ess.json`, issue #697). That is the tool
+ * telling an agent about its own internals instead of about the rig, on the one
+ * input `docs/INGEST.md` §2.0 documents as the route through a foreign skeleton.
+ *
+ * ⭐ Both halves of the join are rigc's own readers rather than a second opinion
+ * on somebody else's format: the walk is `attachmentRegionJoins`, which `PS127`
+ * measures against the loader's own `findRegion` calls, and the region names come
+ * from `parseAtlasText`, which is what `--atlas-in` already resolves against.
+ * Names are compared EXACTLY — as `A08` compares them and as `findRegion`
+ * matches them — so a padded region name is a miss on both sides.
+ *
+ * ⚠️ What it deliberately does not do is catch the pose. A blanket `try` around
+ * `skeletonDataFromText` would convert any exception the runtime raises into a
+ * sentence claiming the cause is missing art, and a rigc defect reported under
+ * somebody else's name is the doctrine's second bullet inverted. This refuses
+ * the case it can NAME, before a line of the report is printed, and leaves
+ * anything else to arrive as itself.
+ */
+function refuseUnposableArt(result: CompileResult, opts: CompileOptions): void {
+  const regionNames = parseAtlasText(result.atlasText).pages.flatMap((page) => page.regions.map((region) => region.name));
+  const have = new Set(regionNames);
+  const misses: Array<{ at: string; attachment: string; lookup: string }> = [];
+  let lookups = 0;
+  for (const join of attachmentRegionJoins(JSON.parse(result.skeletonText))) {
+    // A `sequence` this walk will not guess at names no region it can check, and
+    // `A08` passes over it for the same reason.
+    if (join.lookups === null) continue;
+    for (const lookup of join.lookups) {
+      lookups++;
+      if (!have.has(lookup)) {
+        misses.push({
+          at: `skin "${join.skin}" slot "${join.slot}" placeholder "${join.placeholder}"`,
+          attachment: join.name,
+          lookup,
+        });
+      }
+    }
+  }
+  if (misses.length === 0) return;
+  const first = misses[0];
+  // Reported because it was measured, and absent where there is none — `A08`'s
+  // own near-miss clause, in `A08`'s own words.
+  const near = regionNames.find((region) => region.trim().toLowerCase() === first.lookup.toLowerCase());
+  const has =
+    regionNames.length === 0
+      ? 'it declares no region at all'
+      : `it declares ${regionNames.length} region(s) and none of them is that${
+          near === undefined ? '' : `, though it does have ${JSON.stringify(near)}`
+        }`;
+  const remedy =
+    opts.atlasInPath === undefined
+      ? 'Art reaches a compile two ways and this run took neither: `--atlas-in <pack.atlas>` resolves the parts ' +
+        'against a pack somebody already made, and an "image" per attachment resolves them as loose PNGs under ' +
+        '`--images <dir>` — a spec that states a size and names no image is what `ingest --art none` writes, and ' +
+        '`--atlas-in` is what reads it'
+      : `Either the spec's region name or ${opts.atlasInPath} is the one that moved: fix the name, or point ` +
+        '`--atlas-in` at the pack that has it';
+  throw new ExplainError(
+    `${first.at}: attachment ${JSON.stringify(first.attachment)} wants region ${JSON.stringify(first.lookup)}, ` +
+      `which this build's atlas does not have (${has}). \`explain\` poses the rig to measure its deform keys and a ` +
+      `pose resolves every attachment against the atlas, so there is nothing to pose it against. ${remedy}. ` +
+      `${misses.length} of ${lookups} attachment lookup(s) here resolve to no region.`,
+  );
+}
+
 function cmdExplain(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   console.log(`rigc explain ${label}`);
@@ -2442,6 +2533,13 @@ function cmdExplain(flags: Record<string, string>): void {
   console.log(`  ..    rig    ${opts.rigPath}`);
   console.log(`  ..    motion ${opts.motionPath}`);
   const result = compile(opts);
+  // Before a line of the report, rather than at the pose two hundred lines in:
+  // the blocks that need the art — DEFORM, meshes, dropped states — all sit
+  // BELOW the pose, so a run that printed the bone and timeline dump and then
+  // refused would be a report missing everything the missing art decides, with
+  // the sentence saying so scrolled off the top. It is the invocation that has
+  // to change, so it is refused before the report it cannot finish (issue #697).
+  refuseUnposableArt(result, opts);
   // `compile` has already parsed this file, so the read below cannot fail — but
   // it goes through the same parser rather than a cast, because the cast was the
   // last one in the repository and issue #307 was about exactly that.
@@ -3108,8 +3206,20 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'explain',
-    usage: ['rigc explain  (same arguments as build, minus --profile — it never gates)'],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'cut', 'cuts'],
+    usage: [
+      'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>]   (it never gates, and writes nothing)',
+      'rigc explain … --atlas-in <skeleton.atlas>                  (resolve the parts against a pack somebody already made, as build does)',
+      'rigc explain --cut <name> --cuts <cuts.json>',
+    ],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts'],
+    notes: [
+      'this line said "the same arguments as build, minus --profile" and was false in both',
+      'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
+      'command read what `ingest --art none` writes was reachable and undocumented, while',
+      '--pack, --page-size, --padding and --copy-images are build\'s and do nothing here —',
+      'they decide what is WRITTEN, and this command writes nothing. What it takes is listed',
+      'above, and that is now the whole of it.',
+    ],
   },
   {
     name: 'validate',
@@ -3482,6 +3592,13 @@ try {
     console.error(`rigc pose: ${err.message}`);
     process.exit(2);
   }
+  // A refusal of the invocation, like the two below it, and exit 2 for the same
+  // reason: nothing was posed and nothing was written, so it is the command line
+  // that has to change (issue #697).
+  if (err instanceof ExplainError) {
+    console.error(`rigc explain: ${err.message}`);
+    process.exit(2);
+  }
   // Same kind as a PoseError, and printed the same way for the same reason: the
   // messages name a path, a bone or an attachment, and reprinting the whole
   // usage under them buries the one line that says what to change.

package/docs/AUTHORING.md

@@ -160,11 +160,11 @@ What the flags mean:
 | `--rig` | the rig spec — skeleton structure |
 | `--motion` | the motion spec — time |
 | `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths and `skeleton.images` are written relative to it |
-| `--copy-images` | `build` only: also copies every referenced page PNG into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own, and points `skeleton.images` at `--out` itself so the editor's import finds the parts beside the skeleton (issue #370; §3.1 says why it is spelled `../<out>/` and not `./`). Default is unchanged — page paths still point at the source art (issue #217) |
+| `--copy-images` | `build` only: also copies every page **the emitted atlas names** into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own, and points `skeleton.images` at `--out` itself so the editor's import finds the parts beside the skeleton (issue #370; §3.1 says why it is spelled `../<out>/` and not `./`). Under `--atlas-in` those pages are the pack's, not one per part (issue #693 — **§0.2**). Default is unchanged — page paths still point at the source art (issue #217) |
 | `--pack` | `build` only: arrange every part onto **shared** atlas page(s), written into `--out` as real PNGs, instead of one page per part. Lossless — nothing is resampled, trimmed or rotated. Default is unchanged (issue #4) — **§0.1** |
 | `--page-size` | `build --pack` only: the largest page edge (default `2048`). A ceiling, not the size: page edges are powers of two and the one written is the smallest that holds the pack — **§0.1** |
 | `--padding` | `build --pack` only: the gutter each region reserves on every side (default `2`), filled by extending the region's own edge pixels outwards. `0` is not a legal-but-tight choice, it is bleed — **§0.1** |
-| `--atlas-in` | `build` only: resolve every part against the **regions of a pre-packed `.atlas`** instead of against loose PNGs. Region geometry is read from the file and sizes are descaled by the page's `scale:`; the atlas is re-emitted into `--out`, re-anchored — **§0.2** |
+| `--atlas-in` | `build` and `explain`: resolve every part against the **regions of a pre-packed `.atlas`** instead of against loose PNGs. Region geometry is read from the file and sizes are descaled by the page's `scale:`; `build` re-emits the atlas into `--out`, re-anchored, and `explain` writes nothing and poses through it — **§0.2**. On `explain` it is the flag that makes a **size-only** spec readable at all (`ingest --art none`), because posing resolves every attachment against an atlas; without it that pair is refused by name rather than thrown through ([#697](https://github.com/firejune/rigc/issues/697), §5.1) |
 | `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order. For `chainfit` it is only where each attachment's image name **resolves**: the candidate decides what the parts are, so extra PNGs are unused and a missing name is refused by name (§12.3) |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
@@ -319,6 +319,17 @@ texel count beside it so both numbers are visible:
 measures the PNG. Reach for `--atlas-in` when the pack is what you were handed, or
 when drawing through the pack's own texels is the point.
 
+**What `--out` holds afterwards:** `skeleton.json` and a `skeleton.atlas` that is
+the pack, page paths pointing back at the pack's own PNGs — so `rigc validate
+<that directory>` reads it green with no flags, exactly as it reads a loose
+build's. Add `--copy-images` and the pack's page PNGs are copied in beside the
+skeleton and the page names become their basenames, which is the same directory
+with nothing outside it left to resolve. ⚠️ Until
+[#693](https://github.com/firejune/rigc/issues/693) that flag rebuilt the atlas
+from the parts the rig declared instead of from the pack, and a rebuild through
+`ingest --art none` declares none: the file written was **zero bytes**, on a build
+that printed `PASS` for all four atlas assertions.
+
 The emitted `skeleton.atlas` **is** the imported one, verbatim except for its page
 name lines, which are paths and have to be re-anchored to `--out`. Fields rigc
 does not re-serialise (`format:`, `repeat:`, and `scale:` itself) survive the trip
@@ -518,6 +529,17 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   extremes, how far each vertex moved and whether the winding survived
   (**§4.11.2**). It takes no `--profile`, it never gates, and it does not write
   anything — so the figures are readable on a build the gate is refusing.
+
+  ⭐ **It reads what `ingest` writes, given the pack** — `--atlas-in <pack.atlas>`,
+  with `build`'s meaning (§0.2). That matters more here than it looks: printing the
+  `DEFORM` block means **posing** the rig, a pose resolves *every* attachment
+  against the atlas whether or not anything deforms it, and a spec written by
+  `ingest --art none` states sizes and names no image. So the size-only pair
+  `build --atlas-in` gates green is readable here through the same flag, and
+  without it the pair is refused by name at exit 2 rather than posed
+  ([#697](https://github.com/firejune/rigc/issues/697), §5.1). ⚠️ `--profile`,
+  `--pack`, `--page-size`, `--padding` and `--copy-images` are `build`'s and are
+  not here: four of them decide what is *written*, and this command writes nothing.
 - **`diff`** compares two skeletons and reports **a ratio per measure** in six
   sections (bones, slots, attachments, constraints, animations, events). It
   deliberately does not combine them into a score: a rig with the right skeleton
@@ -964,6 +986,12 @@ A skin can also say which bones and constraints it **switches on**, and that nee
 one more level, so a skin entry has a second spelling — see §3.4.1. The short one
 above is unchanged and is what almost every rig wants.
 
+🔸 **`default` is a name, not a requirement.** A rig may put every attachment in
+named skins and declare no `default` at all, which is what an editor export of a
+multi-skin character gives back; rigc still emits a `default` skin, empty, because
+it always does. An animation keying such a slot resolves its attachment names
+against every skin there is — §4.4 states that rule and §5.1 the one refusal left.
+
 🔸 **A skin may fill no slot with anything that needs art, and that build is
 green.** The atlas is built out of what the skins reference, so a rig whose skins
 name no `image` — an empty `default`, or one carrying only a `boundingbox`, a
@@ -1213,7 +1241,7 @@ ends, so the deformation dies into the pinned rim instead of creasing against it
 | `inner` | **required.** Where the moving ring sits between the centre (`0`) and the hull (`1`), strictly inside that interval. No default: a ring with no number here is refused, not centred |
 | `size` | **required.** The part window, `[w, h]` in pixels, which the UVs and the emitted `width`/`height` are taken from |
 | `bias` | optional; absent means authority is radial only. `{ "axis_deg": <screen degrees, y down>, "ramp": [d0, d1] }` — a line through `center` at that angle, with control authority 0 on its negative side and 1 on its positive side, smoothstepped across the signed distances `d0 < d1`. It is what lets a mouth open downward with the upper lip left pinned |
-| `controls` | **required.** The control bones, by name, at least one. Each must be a bone the rig declares |
+| `controls` | **required.** The control bones, by name, at least one. Each must be a bone the rig declares. **More than one splits the ring by angle**, and the angle of each is measured from where the rig put that bone relative to `center` — so the split is a consequence of the skeleton and never a number you write here |
 
 ⚠️ **`size` is stated here, not measured.** A `contour` and a `grid` take the
 window off the attachment's own `image`; a `ring` and a `ribbon` are built from
@@ -1223,17 +1251,24 @@ drawing — measured: a 240x240 part declared `"size": [64, 64]` builds green un
 `--profile spine-html`. That is R1 rather than a gap: the compiler emits the
 number the spec states and does not re-measure a plate to overrule it.
 
-🚨 **On this route the FIRST control bone is the only one that moves the mesh.**
-Splitting a ring's authority between several grips needs each bone's angle about
-the aperture centre, and rigc measures that from where the rig put the bone — on
-the **manifest** route, which is the one that has a crop to measure in. A rig spec
-that lists two gets the single-bone geometry instead: `controls[0]` takes the
-whole of the control authority, the second name is still printed on the `MESH`
-line, and the gate is green. Measured on a two-control ring — 25 vertices, 40
-triangles, report line `bones=[box, grip_a, grip_b]`, and the emitted weighted run
-binds two bone indices, the slot bone and `grip_a`. Until that is closed, write
-one `controls` entry on this route and reach for the manifest when a ring needs
-several grips.
+⭐ **Several grips split the ring by where the rig put them, on this route as on
+the manifest one.** Each control bone's angle about `center` is measured from its
+own rest position — the window is centred on the slot bone (the ⭐ above), so a
+bone sitting below the aperture owns the arc below it — and authority is
+smoothstepped between the two bones either side of a vertex, so no grip creases
+against the next. Measured on a two-control ring whose grips sit 12px above and
+below the centre: 25 vertices, both grips bound, and of the 8 shared vertices off
+the centre line all 8 take more weight from the grip on their own side. Splitting
+**moves** authority rather than adding it: every vertex gives its controls the
+same total with one grip, two or three.
+
+⚠️ **This route used to bind only the first name**
+([#684](https://github.com/firejune/rigc/issues/684)). It passed no angles at all,
+so the split collapsed onto `controls[0]` and the rest of the names reached the
+`MESH` line, the bone list and nothing else — and the gate was green, because a
+bone no vertex binds is in no weight, no sum and no index. `A20_MESH_WEIGHTS_COHERENT`
+now names it, so a ring that declares a grip and does not use it is a failure
+rather than a quiet stiffness.
 
 **Stated limits, each a named refusal rather than a mesh that loads wrong:**
 
@@ -1245,6 +1280,8 @@ several grips.
 | a hull the centre cannot see all of | `hull is not star-shaped about the aperture centre; the inner ring would fold` — the inner ring is the hull scaled toward `center`, so an edge hidden from it crosses the rim and renders as folded meat |
 | a `bias` ramp that does not increase | `bias ramp must increase, got [16, 4]` |
 | a control bone the rig does not declare | `mesh bone "nobody" is not in the rig's bone list` |
+| two or more `controls`, one of them ON `center` | `control bone "iris_aperture" sits on the aperture centre, so it has no radial direction` — the position a lone control is supposed to occupy is the one position a split cannot use. With a single control it is never asked, so this refusal cannot fire on one |
+| two `controls` at the same angle about `center` | `two control bones share the angle 90 degrees about the aperture centre` — further out is not elsewhere: the arc between them is empty and one of them would bind nothing |
 
 #### `ribbon` — a strip of cross rows riding a bone chain
 
@@ -2871,6 +2908,36 @@ different curves. The same applies to `scale`/`scalex`/`scaley` and
 An `attachment` key carries no easing — attachment timelines are inherently
 stepped.
 
+🔑 **An attachment key resolves against every skin, not against `default` alone.**
+A slot's `attachment` timeline carries a name and **no skin** — the format has no
+field for one — so the names a key may use are the union of every skin's
+placeholders for that slot, the default skin's included.
+`Skeleton.getAttachment` resolves the keyed name at run time through the skin the
+skeleton is **wearing** and, failing that, through `defaultSkin` (spine-core
+4.3.13 `Skeleton.js:335-346`), so which skin's art a key lands on is the
+consumer's, decided by dressing the skeleton rather than by the animation.
+
+- **A name some skins fill and others do not is accepted, and that is the
+  format's own semantics** rather than a hole in the check: under a skin that
+  lacks it the slot shows nothing, which is exactly what a `null` key says and a
+  thing a rig may well mean. What is refused is a name **no** skin holds, and the
+  refusal says which skins were searched and what the slot does have (§5.1).
+- A rig with **no `default` skin at all** — every attachment in named skins,
+  which is the shape an editor export of a multi-skin character gives back — is
+  therefore a rig whose attachment keys work. Until
+  [#695](https://github.com/firejune/rigc/issues/695) it was not: keys were
+  checked against the default skin alone, so a named-skin name was refused as
+  unknown, and a rig with no default skin had **every** attachment key refused,
+  including ones whose art is in the first named skin. The setup pose resolved
+  across skins the whole time (§4.2), so the two halves of one slot disagreed —
+  `slots[].attachment: "plain"` was accepted and a key naming `plain` on that
+  same slot was not.
+- ⚠️ **A `deform` track is the other way round and names its skin outright**
+  (§4.11.5), because the format keys a deform timeline on a `skin/slot/attachment`
+  triple and a deform run is geometry for one attachment object. An attachment
+  timeline has no such field, which is why this one is a union and that one is a
+  lookup.
+
 ### 4.5 `keys` — times, values, curves
 
 - `t` is in seconds and **must strictly increase** after `lag`/`stagger` are added.
@@ -4395,6 +4462,7 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `motion spec names archetype "A" but the rig spec at … is called "B"` | make `archetype` equal the rig's `name` |
 | `animation "A" declares duration Ns but its last key is at Ms` | R7 — fix whichever of the two you meant |
 | `animation "A" slot "X" attachment: key at Ns is Ms past the declared duration Ds` | §4.5 — the key is past the end of the animation and nothing will sample it. Move the key onto `duration`, or raise `duration` |
+| `animation "A" slot "X" attachment: attachment "N" is not in slot "X" under any skin (searched: default, alt) — the slot has: plain, trim` | §4.4 — the keyed name is in **no** skin, and the two clauses say where the compiler looked and what it would have taken. Fix the spelling, or give some skin a placeholder called `N`. A name only a NAMED skin fills is not this error and never was one to fix — it compiles, and the slot shows nothing under the skins that lack it. Before [#695](https://github.com/firejune/rigc/issues/695) the message read `attachment "N" is not in slot "X"` and was raised against the **default skin alone**, so it fired on correct rigs: any key into named-skin art, and every key in a rig with no default skin. `the slot has no attachments at all` is the same message where nothing fills the slot |
 | `animation "A" keys unknown bone "X"` | the track's `bone` is not in the rig |
 | `animation "A" bone "X" translatex: key value must be an array of 1 number(s)` | the value shape must match the property (§4.4) |
 | `animation "A" physics constraint "C" mass key at t=… is 0 (massInverse Infinity); must be > 0 — …` | §4.4 — a keyed physics value the runtime cannot use. The message names the bound and the `PhysicsConstraint.js` lines that make it one: `mass` and `strength` are `> 0`, `damping` is inside `(0, 1)`, `mix` is `0` or more, and `inertia`/`wind`/`gravity` are bounded nowhere ([#610](https://github.com/firejune/rigc/issues/610)) |
@@ -4465,6 +4533,35 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `slot "patch": placeholder "patch" is filled by the "default" skin AND by skins "zulu", "mike", and the Spine editor has no way to hold that … Move the default skin's entry for this slot into a named skin — call it "base"` | **R12** — do what it says: move that entry out of `default` into a named skin. The editor has no representation for a placeholder the default skin shares with a named one, in either spelling, and §3.4.2 has both measurements. Renaming the placeholder does not help; the shape is what is refused |
 | `N attachment name collision(s): a placeholder that more than one skin fills is emitted with the name "<skin>/<placeholder>" … slot "patch": skin "base" placeholder "zulu/patch" and skin "zulu" placeholder "patch" would both be named "zulu/patch"` | **R12** — rename the placeholder or the skin. rigc composes an attachment name for every placeholder more than one skin fills (§3.4.2), and this fires when a composed name is one another entry in the same slot already answers to — including a plain name in the default skin, which composed nothing. Both sites are named; either rename ends it |
 
+⚠️ **One refusal in this section is not a `CompileError`, and it is `explain`'s.**
+`explain` prints the `DEFORM` block by **posing** the rig, and a pose resolves every
+attachment against the atlas — so it needs the art `build` needs, reached the same
+two ways (§0.2). A pair whose art it cannot resolve is refused **before a line of
+the report**, at **exit 2**, in rigc's own sentence:
+
+```
+rigc explain: skin "default" slot "lamp" placeholder "shade": attachment "shade"
+wants region "shade", which this build's atlas does not have (it declares no region
+at all). `explain` poses the rig to measure its deform keys and a pose resolves
+every attachment against the atlas, so there is nothing to pose it against. Art
+reaches a compile two ways and this run took neither: `--atlas-in <pack.atlas>`
+resolves the parts against a pack somebody already made, and an "image" per
+attachment resolves them as loose PNGs under `--images <dir>` — a spec that states
+a size and names no image is what `ingest --art none` writes, and `--atlas-in` is
+what reads it. 1 of 1 attachment lookup(s) here resolve to no region.
+```
+
+Both halves of it are measured rather than fixed text: the count is this pair's, and
+where the atlas has a **near miss** the sentence prints that too, in `A08`'s own
+clause and `A08`'s own words. When `--atlas-in` **was** given and the region is still
+absent, the second half names the pack instead and asks you to fix the spec's region
+name or point the flag at the pack that has it. Until
+[#697](https://github.com/firejune/rigc/issues/697) there was no rigc sentence at
+all: the report printed in full and the run then died inside `AtlasAttachmentLoader`
+with `Region not found in atlas: shade (attachment: shade)` and a spine-core stack
+trace, at exit 1 — the runtime's message about rigc's internals standing in for
+rigc's message about your two files.
+
 ### 5.2 Assertions — the gate
 
 The report prints one line per assertion:
@@ -4545,7 +4642,7 @@ Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
 | `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out`. **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) — as it is for `A06`, `A19` and `A27`; see `A07` ([#608](https://github.com/firejune/rigc/issues/608)) |
 | `A18_DETERMINISTIC_EMIT` | both | a second compile of the same inputs differed. That is a compiler bug, not a spec bug — report it |
 | `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part image can never be transparent: no alpha channel (colour type 4 or 6) and no `tRNS` chunk either, so it would paint a solid rectangle over what is behind it. Re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. Only the full-stage base plate may be opaque. Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art ([#266](https://github.com/firejune/rigc/issues/266)) **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) |
-| `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, or a binding at weight 0. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
+| `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not ([#684](https://github.com/firejune/rigc/issues/684)). Fix the rig spec's `controls`/`chain`, or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, a ribbon's entry row, or a contour's outline (which is all of it) is not pinned to its anchor bone at weight 1 |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A23_PHYSICS_CONSTRAINT_EFFECTIVE` | both | a physics constraint that drives no component, is muted by `mix: 0`, has `mass: 0`, has `strength: 0`, or has `damping` outside `(0, 1)` so it never settles — **at rest, and on every physics timeline key** ([#610](https://github.com/firejune/rigc/issues/610)). The timeline arm reads each key through the runtime's own `PhysicsConstraint*Timeline.set`, so a keyed `mass` is judged as the `massInverse` it becomes, and the detail names the animation, the constraint, the key time, the value and the bound. One difference between the two arms, and the runtime is the reason for it: a **key** of `mix: 0` is accepted, because `update` opens with `if (mix === 0) return;` and muting a constraint for a stretch is what a mix timeline is for — the editor's own `sack-pro` example keys it there on 24 of its 36 mix keys. `inertia`, `wind`, `gravity` and the top of `mix` are bounded nowhere, at rest or keyed. **SKIP** when the skeleton declares no physics constraint ([#580](https://github.com/firejune/rigc/issues/580)) — the same sentence `A36` and `A37` have always printed for their own constraint types |
@@ -5937,6 +6034,13 @@ There are two matchers and the `how` column says which one answered:
   confidence: how much better the winning position was than the best rival inside
   the search window. This is what gives a shot like a chain of touching links any
   drift at all — under connected components alone, every frame of it is ambiguous.
+  ⭐ **Only the pixels of it your own composite lets show are correlated**: a
+  template pixel you draw something over cannot match the reference wherever the
+  slot really is, so it adds the same residual at every offset — and, because
+  sliding the template moves those samples onto other pixels, their gradient
+  decides the winner wherever the visible basin is shallow. That is not a
+  hypothetical: it is what made four of the seven examples in this repository
+  report 0.8–2.2 px against frames rendered from themselves (issue #698).
 
 ⚠️ **Both matchers are capped, and a blank is a real answer.** A part can be
 displaced by about its own size and still be that part in the picture; past that,
@@ -5946,6 +6050,23 @@ the 47 px course as its drift. The bar rises with the distance being claimed: a
 peak sitting where you already drew the slot only has to confirm it, a peak
 claiming the part moved most of a radius has to be distinctive to be believed.
 
+⚠️ **And a slot you cover completely has no drift to report at all.** If every
+pixel a slot draws is painted over by something later in your own draw order,
+none of its ink reaches the picture, so there is nothing to correlate — `check`
+says so by name and counts it out, rather than correlating hidden pixels against
+whatever is on top of them:
+
+```
+its drift is not measurable — every one of the 2116 px this 48x54 px slot draws is
+covered by something the candidate draws over it, so none of its own ink reaches the
+picture to be correlated against
+```
+
+That is a fact about the shot and not an error: a part behind another part is
+still where the rig put it, and the answer to *where did it land* is that this
+run cannot say. Read it beside the `slots` column, which counts it as
+unattributed.
+
 The `slots` column is how many of the slots you drew got an answer at all, and the
 summary line carries the same denominator. `N reference component(s) no slot
 reaches` means the reference frame contains something none of your slots overlaps:
@@ -5969,25 +6090,67 @@ bun cli.ts check  --candidate <build> --frames <frames>
      frames     11 on disk, candidate samples 11, 11 compared
      MAE        mean 0.00  worst 0.00 (exact: none of the 11 compared frame(s) differs from the reference)   (0..255 over the union alpha; over the whole frame, mean 0.00)
                 ⤷ over the REFERENCE's own drawn pixels, mean 0.00 — 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.
-     slot drift worst 0.4 px  "arm_b" at f0007
+     slot drift worst 0.5 px  "plate" at f0004
+                ⤷ bounded by 0.71 px — the correlation put this slot where the candidate drew it, so the whole figure is the sub-pixel step, clamped to 0.5 px on each axis
      per-frame all 10 adjacent pair(s) change by as much as the reference's own frames do
 ```
 
 ⚠️ **The MAE floor is zero and the slot-drift floor is not**, and the second half of
 that is the instrument's own arithmetic rather than anything about your rig. Both
 sides are the same pixels, so every frame's MAE is exactly 0 — which is why the line
-says `(exact)` instead of naming a frame. The drift is a **correlation**, and its
-last step fits a parabola through three whole-pixel residuals and takes its vertex,
-clamped to half a pixel on each axis; so an identity run can report up to
-`hypot(0.5, 0.5) = 0.71 px` and no more. ⭐ **It is not zero because the template is
-your slot drawn *alone* and the reference is the composite**: wherever a neighbour
-covers part of the slot, the residual surface around the true minimum is asymmetric
-and the parabola's vertex sits a fraction of a pixel off it. That fraction is the
-floor, it is per slot, and it is bounded — **a drift above 0.71 px on an identity run
-is a defect in `check`, not a property of it.** This example read 3.7 px until issue
-#678: the coarse sweep started at `−radius` and stepped by its stride, so the
-identity offset was on the lattice only when the stride divided the radius, and the
-`±1` refinement around a winner two pixels out could not reach back to it.
+says `(exact)` instead of naming a frame. The drift is a **correlation**: it finds
+the whole-pixel offset that matches best and then fits a parabola through three
+whole-pixel residuals for the fraction, clamped to half a pixel on each axis.
+
+🔑 **So the bound has two halves, and the run states both of them for you.** The
+`⤷ bounded by` line is not a constant off this page: it is `hypot(|dx| + 0.5,
+|dy| + 0.5)` for that match's own whole-pixel winner `(dx, dy)`. A winner at the
+offset you drew — which is the answer on every frame of a correct rig — bounds the
+whole figure at `hypot(0.5, 0.5) = 0.71 px`, and the line says the figure is the
+sub-pixel step and nothing else. A winner one pixel out bounds it at 1.58 px and
+says the correlation moved the part. ⇒ **Read a drift against the line under it,
+never against a number from a page about another rig.** A component match prints
+the other sentence — two centroids have no such bound, only the search radius.
+
+🚨 **The clamp bounds the figure only while the whole-pixel winner is the
+identity, and for a while nothing checked that second half.** Issue #698: four of
+the seven examples in this repository read **0.81, 1.11, 2.13 and 2.21 px** against
+frames rendered from themselves, because the template carried the pixels the
+candidate draws *over itself*. Those match nothing wherever the slot really is, so
+they add a residual at every offset — and sliding the template moves them onto
+other pixels, so their gradient walks the winner off the origin wherever the
+visible basin is shallow. The exhaustive whole-pixel field for `flex`'s backdrop
+had its minimum at `(2, 0)` scoring 7.75 against the identity offset's 8.76.
+Correlating only what shows put all seven back on `(0, 0)`, and `C25`–`C30` of
+the repository's own selftest gate that over every example it ships — so the next
+one is gated by arriving.
+
+🔸 The same page said `3.7 px` before issue #678, for an unrelated reason worth
+keeping: the coarse sweep started at `−radius` and stepped by its stride, so the
+identity offset was on the lattice only when the stride divided the radius, and
+the `±1` refinement around a winner two pixels out could not reach back to it.
+
+**A second example, and the one the repair was measured on.** `gallery/flex` draws
+a banner and a leaf over a full-stage backdrop, so almost every slot of it reaches
+the template matcher:
+
+```bash
+bun cli.ts build  --rig gallery/flex/rig.json --motion gallery/flex/motion.json --out <build>
+bun cli.ts render --candidate <build> --animation wave --fps 12 --out <frames>
+bun cli.ts check  --candidate <build> --frames <frames>
+```
+
+```
+  ── wave — candidate animation "wave", 12 fps ──
+     frames     30 on disk, candidate samples 30, 30 compared
+     MAE        mean 0.00  worst 0.00 (exact: none of the 30 compared frame(s) differs from the reference)   (0..255 over the union alpha; over the whole frame, mean 0.00)
+                ⤷ over the REFERENCE's own drawn pixels, mean 0.00 — 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.
+     slot drift worst 0.2 px  "plate" at f0009
+                ⤷ bounded by 0.71 px — the correlation put this slot where the candidate drew it, so the whole figure is the sub-pixel step, clamped to 0.5 px on each axis
+     per-frame all 29 adjacent pair(s) change by as much as the reference's own frames do
+```
+
+That figure was **2.21 px** on the same command before #698, on the same slot.
 
 ⭐ **And the same frames plus two deliberately wrong builds are what say which column
 answers which question.** Each differs from the build above in exactly one way —
@@ -6029,6 +6192,15 @@ samples, so the column is correctly silent on it. ⇒ Read the pair together: a
 MAE with `per-frame` silent is a pose in the wrong place or at the wrong moment; a
 loud MAE with `per-frame` firing is a **speed**, which is a curve.
 
+🔸 Neither block above reprints its own `⤷ bounded by` line, for the same reason
+both carry the declaration: the spec edits are not in the tree, so those two lines
+would be hand-written rather than taken. What the gate measures on them is stated
+instead — the worst match of each sits at whole-pixel `(0, −31)` and `(0, −32)`,
+which bounds them at **31.50 px** and **32.50 px**. That is the contrast worth
+carrying away: a correct rig's drift is bounded by the clamp because its winner is
+the identity, and these two are bounded by nothing of the kind because a part
+really moved.
+
 **The `chains` block is the same two measures on the unit you actually repair.**
 
 ```

package/docs/INGEST.md

@@ -394,7 +394,10 @@ rigc explain examples/spineboy/export/spineboy-pro.json
 rigc: give either --cut <name> --cuts <cuts.json>, or --rig/--motion/--out
 ```
 
-It takes the same arguments as `build` minus `--profile`, prints the resolved account
+It takes `--rig`, `--motion`, `--out`, and optionally `--manifest`, `--images` and
+`--atlas-in` — `build`'s spec-reading flags, and not the ones that decide what `build`
+*writes* (`--pack`, `--page-size`, `--padding`, `--copy-images`) or the one that gates
+(`--profile`). It prints the resolved account
 of **your** two spec files, and never gates. Which makes it a §2 instrument rather
 than a §1 one — the thing you run to compare what you transcribed against the export
 you transcribed it from, by eye:
@@ -497,7 +500,12 @@ of this section**, with its gutter, its effect on the exit code and what to do.
 
 And two flags for what the skeleton also does not encode: `--art loose` (the default)
 names an `image` per attachment resolved against loose PNGs, `--art none` states
-`width`/`height` for `build --atlas-in`; and under `loose`, `--images <dir>` writes
+`width`/`height` for `build --atlas-in` — and for `explain --atlas-in`, which is the
+same pack read for a report rather than for an artifact: `explain` **poses** the rig
+to print its `DEFORM` block, a pose resolves every attachment against an atlas, and a
+size-only spec carries none of its own, so without the flag that pair is refused by
+name rather than posed ([#697](https://github.com/firejune/rigc/issues/697)); and
+under `loose`, `--images <dir>` writes
 the rig spec's own images directory relative to `--out`, so the rebuild is a plain
 `build --rig … --motion … --out …` rather than one carrying `--images` forever. It is
 refused together with `--art none`, which writes no `image` for a directory to be the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.25.5",
+  "version": "0.25.6",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/src/atlas.ts

@@ -405,10 +405,19 @@ export function parseAtlasText(text: string): ParsedAtlas {
  * field it re-emits, and the ones it did not understand would quietly vanish
  * (`scale:` is the expensive example — [`atlasScales`](render.ts) reports it, and
  * a pack that is coarser than its drawings would stop saying so).
+ *
+ * `rename` is handed the page's INDEX as well as its name, because a name is not
+ * a key: nothing in the format forbids two pages spelling the same path, and a
+ * caller that has already decided one new name per page (`copyAtlasPages` in
+ * [`emit.ts`](emit.ts) assigns the copies' filenames in page order) would then
+ * hand both of them the first decision. The index is the page's identity here;
+ * the name is data.
  */
-export function rewritePageNames(parsed: ParsedAtlas, rename: (name: string) => string): string {
+export function rewritePageNames(parsed: ParsedAtlas, rename: (name: string, index: number) => string): string {
   const out = parsed.lines.slice();
-  for (const page of parsed.pages) out[page.nameLine] = rename(page.name);
+  parsed.pages.forEach((page, index) => {
+    out[page.nameLine] = rename(page.name, index);
+  });
   return out.join('\n');
 }