spine-rigc 0.27.0 → 0.28.0

package/cli.ts

@@ -66,10 +66,24 @@ import {
   type DeformKeyMeasure,
   type DeformSpan,
 } from './src/deformmeasure.ts';
-import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
+import {
+  diffLines,
+  diffSkeletons,
+  reportedFigures,
+  sectionFigures,
+  type DiffAnimationPair,
+  type DiffReport,
+} from './src/diff.ts';
 import { ingest, IngestError, IngestSpecRefused, INGEST_GUTTERS, type IngestFinding, type IngestStage } from './src/ingest.ts';
 import { copyAtlasPages } from './src/emit.ts';
-import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas, parseAtlasText } from './src/atlas.ts';
+import {
+  DEFAULT_PADDING,
+  DEFAULT_PAGE_SIZE,
+  packAtlas,
+  pageFootprint,
+  parseAtlasText,
+  type AtlasRegion,
+} 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';
@@ -218,13 +232,16 @@ const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images',
 /**
  * The flags a command is allowed to spell more than once.
  *
- * Only `vote --candidate` is, because a ballot is *by definition* several
- * candidates. Everywhere else a repeat is a mistake and is refused: `check
+ * `vote --candidate` is, because a ballot is *by definition* several
+ * candidates, and `diff --as` is, because a skeleton has as many shots as it
+ * has and one pairing per flag is the only spelling that keeps each pair a pair
+ * (issue #720). Everywhere else a repeat is a mistake and is refused: `check
  * --candidate a --candidate b` used to take `b` silently, which is a report
  * about a rig the caller did not think they were asking about.
  */
 const REPEATABLE_FLAGS: Record<string, ReadonlySet<string>> = {
   vote: new Set(['candidate']),
+  diff: new Set(['as']),
 };
 
 /**
@@ -1155,6 +1172,45 @@ function dropLine(dropped: DroppedState): string {
   return `  DROP  ${dropped.slot}/${dropped.state}: ${droppedStateReason(dropped)} (state not emitted)`;
 }
 
+/**
+ * The rectangle a region occupies **on its page**, for a line that has already
+ * said where the region is — and the empty string where the page rectangle is
+ * the one `bounds:` already states.
+ *
+ * ## The fact no surface an author reads carried (issue #718)
+ *
+ * The atlas line beside this clause prints the DRAWING's size, because that is
+ * what an attachment's width and height mean. A packer that turned the drawing a
+ * quarter to fit it wrote `bounds:` in the drawing's orientation too. So an
+ * author holding the pack and the build report had neither end of the rectangle
+ * they have to cut out of the page to measure a part against a rendered frame —
+ * and the one place rigc printed it was `A06`'s overlap text, reachable only
+ * under `--profile spine-html`. The knowledge was in the tree the whole time:
+ * `pageFootprint` has derived this rectangle for every reader of it since issue
+ * #579, and nothing an author reads said it.
+ *
+ * ⚠️ **The condition is `pageFootprint`'s own answer, not a second reading of
+ * `degrees`.** Re-spelling that predicate here is the exact duplication #579 was
+ * filed on — four readers derived this rectangle and two derived it wrongly — so
+ * the clause asks the function whether its answer differs from the `bounds:`
+ * line, and prints only then.
+ *
+ * 🔸 A consequence worth stating rather than leaving to be discovered: a region
+ * whose KEPT rectangle is square is silent here, because a quarter turn leaves
+ * its footprint the same two numbers and there is nothing the pack does not
+ * already say. The general rule — `bounds` is the unturned size, the footprint
+ * is its transpose at `rotate: 90` and `rotate: 270`, and which way to turn the
+ * rectangle to recover the drawing — belongs to an author's own reading and is
+ * stated in `docs/AUTHORING.md` §0.2, which holds for every region including
+ * that one.
+ */
+function pageRectangle(region: AtlasRegion): string {
+  const foot = pageFootprint(region);
+  return foot.width === region.width && foot.height === region.height
+    ? ''
+    : `, occupies ${foot.width}x${foot.height}`;
+}
+
 function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
@@ -1208,13 +1264,23 @@ function cmdBuild(flags: Record<string, string>): void {
     // 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.
+    //
+    // `pageRectangle` closes the line's last silence (issue #718), and it is
+    // placed LAST rather than beside the turn it follows from, which is where
+    // the card put it. The two clauses collide nowhere else, and the collision
+    // is real: `scale 0.5 (373x106 texels)` is itself a size, so
+    // `rotate 90, occupies 106x373 scale 0.5 (…)` reads as though the footprint
+    // were the scaled quantity. As a trailing clause of the whole location
+    // phrase it is unambiguous with a `scale:` line and identical to the card's
+    // wording without one, which is every pack that has no `scale:` to state.
     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)`);
+            : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`) +
+          pageRectangle(img.atlas);
     console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${where}`);
   }
   for (const d of result.droppedStates) console.log(dropLine(d));
@@ -1403,7 +1469,69 @@ function cmdValidate(flags: Record<string, string>, positional: string[]): void
   console.log('rigc: green');
 }
 
-function cmdDiff(flags: Record<string, string>, positional: string[]): void {
+/**
+ * `--as <candidate>=<reference>`, one pair per occurrence.
+ *
+ * ⚠️ Spelled with a pair where `check --as <name>` takes one name, and the
+ * difference is in what the two commands have on the other side. `check`
+ * measures against a rendered frame SET, which already carries the reference
+ * animation's name in its own directory, so one name closes the gap. `diff` has
+ * two skeletons and either may have its own vocabulary, so one name says which
+ * shot on which side and leaves the other unanswered. The direction — candidate
+ * first — is the one `bonedist`'s correspondence file already writes its
+ * `animations` map in.
+ *
+ * Every refusal here is a UsageError because every one of them is about the
+ * flag's own value, and each names what it read: a value with no `=`, an empty
+ * side, a name repeated on either side, and a name no animation on that side
+ * answers to. ⛔ The last of those is a refusal rather than a dropped pair for
+ * the reason a miss is refused by name everywhere else in this tool — a typo
+ * that quietly measured less would be a report about a pairing the caller did
+ * not ask for.
+ */
+function readAnimationPairs(values: string[], candidate: unknown, reference: unknown): DiffAnimationPair[] {
+  const animationsOf = (root: unknown): string[] => {
+    const anims = (root as { animations?: unknown } | null)?.animations;
+    return typeof anims === 'object' && anims !== null && !Array.isArray(anims) ? Object.keys(anims) : [];
+  };
+  const have = { candidate: animationsOf(candidate), reference: animationsOf(reference) };
+  const pairs: DiffAnimationPair[] = [];
+  for (const value of values) {
+    const at = value.indexOf('=');
+    if (at < 0) {
+      throw new UsageError(
+        `--as ${JSON.stringify(value)} is not a pair. It takes <candidate>=<reference> — two animation names joined ` +
+          'by `=`, because diff compares two skeletons and either may have its own name for the shot. The candidate ' +
+          `has [${have.candidate.join(', ') || 'none'}] and the reference has [${have.reference.join(', ') || 'none'}].`,
+      );
+    }
+    const pair = { candidate: value.slice(0, at), reference: value.slice(at + 1) };
+    if (pair.candidate === '' || pair.reference === '') {
+      throw new UsageError(
+        `--as ${JSON.stringify(value)} leaves the ${pair.candidate === '' ? 'candidate' : 'reference'} side empty; ` +
+          'it takes <candidate>=<reference>, a name on each side',
+      );
+    }
+    for (const side of ['candidate', 'reference'] as const) {
+      if (!have[side].includes(pair[side])) {
+        throw new UsageError(
+          `--as ${JSON.stringify(value)} names no ${side} animation: the ${side} has ` +
+            `[${have[side].join(', ') || 'none'}] and not ${JSON.stringify(pair[side])}`,
+        );
+      }
+      if (pairs.some((p) => p[side] === pair[side])) {
+        throw new UsageError(
+          `--as pairs the ${side} animation ${JSON.stringify(pair[side])} twice; each animation may be in one pair, ` +
+            'or the block would compare one shot against two',
+        );
+      }
+    }
+    pairs.push(pair);
+  }
+  return pairs;
+}
+
+function cmdDiff(flags: Record<string, string>, lists: Record<string, string[]>, positional: string[]): void {
   const [candidate, reference] = positional;
   if (!candidate || !reference) throw new UsageError('diff takes two paths: <candidate.json> <reference.json>');
   const candidatePath = resolve(candidate);
@@ -1411,7 +1539,10 @@ function cmdDiff(flags: Record<string, string>, positional: string[]): void {
   for (const path of [candidatePath, referencePath]) {
     if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
   }
-  const report = diffSkeletons(readJsonFile(candidatePath), readJsonFile(referencePath));
+  const candidateJson = readJsonFile(candidatePath);
+  const referenceJson = readJsonFile(referencePath);
+  const animationPairs = readAnimationPairs(lists.as ?? [], candidateJson, referenceJson);
+  const report = diffSkeletons(candidateJson, referenceJson, { animationPairs });
   console.log('rigc diff');
   for (const line of diffLines(report, { candidate: candidatePath, reference: referencePath })) console.log(line);
   if (flags.json !== undefined) {
@@ -3266,8 +3397,26 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'diff',
-    usage: ['rigc diff <candidate.json> <reference.json> [--json <out>]'],
-    flags: ['json'],
+    usage: ['rigc diff <candidate.json> <reference.json> [--as <candidate>=<reference>]… [--json <out>]'],
+    flags: ['as', 'json'],
+    overrides: {
+      as: {
+        value: '<candidate>=<reference>',
+        meaning:
+          'pair a candidate animation with a reference one, so the name-agnostic `animations` block can be ' +
+          'measured over shots the two files call different things. Repeatable, one pair each. An INPUT and never ' +
+          'derived: two skeletons cannot say which of their shots are the same shot. Without it the block appears ' +
+          'only when each side has exactly one animation, which pairs by position, and is otherwise absent rather ' +
+          'than guessed',
+      },
+    },
+    notes: [
+      'the `animations` block reads two figures once something has paired the shots, exactly as',
+      '`bones` and `slots` do: name-matched, where `names` lives, and name-agnostic over the pair.',
+      'A candidate that followed a brief withholding the animation name reads `count` 1/1 and 0.000',
+      'on every other name-matched measure — including `duration` and `key_counts` it may have got',
+      'exactly right — so read the pair and not the section mean.',
+    ],
   },
   {
     name: 'check',
@@ -3562,7 +3711,7 @@ try {
   else if (command === 'ingest') cmdIngest(flags, positional);
   else if (command === 'validate') cmdValidate(flags, positional);
   else if (command === 'explain') cmdExplain(flags);
-  else if (command === 'diff') cmdDiff(flags, positional);
+  else if (command === 'diff') cmdDiff(flags, lists, positional);
   else if (command === 'check') cmdCheck(flags);
   else if (command === 'bench') cmdBench(flags, positional);
   else if (command === 'bonedist') cmdBoneDist(flags);

package/docs/AUTHORING.md

@@ -178,7 +178,7 @@ What the flags mean:
 | `--again` | `vote --record` only: record a second vote on a ballot the ledger already has. Without it a repeat is refused by name rather than doubled |
 | `--frame` | `pose` and `chainfit`: one pose frame — the picture to read part placements out of. One frame per call; several key poses are several calls, and correlating them is yours (§11) |
 | `--scale` | the scale window to search, as **frame pixels per part pixel**, `<min>,<max>` (default `0.5,2`). The report states what it searched, and a window that does not contain the truth does not reliably refuse — §11. For `chainfit` it sizes the **internal anchor pass** and is refused beside `--anchor` — §12.4 |
-| `--rotation` | the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright. For `chainfit`, again the internal anchor pass — the chains' own window is `--hinge` |
+| `--rotation` | the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright — a window narrower than the coarse step is divided rather than refused, and `search` states the step that division produced (§11.3). For `chainfit`, again the internal anchor pass — the chains' own window is `--hinge` |
 | `--max-residual` | `pose` and `chainfit`: above this residual a placement is **refused by name** instead of reported flat (default `0.25`). A reporting threshold, not a pass bar — the placement is still in the JSON |
 | `--anchor` | `chainfit` only: a `rigc pose` report for **this** frame, whose confident placements become the anchors the chains hang off. Without it that pass runs internally — §12.2 |
 | `--hinge` | `chainfit` only: the window each child bone's local rotation is searched over, in **Spine** degrees about its setup value, `<min>,<max>` (default `-180,180`) — §12.4 |
@@ -389,6 +389,37 @@ silhouette and an authored mesh's fit figure is the same number. The one thing
 that does not change is what rigc **writes**: its own packer never turns a
 region.
 
+🔑 **That is a claim about rigc's instruments, and you may be holding only the
+pack.** An author who has to cut a part out of the page by hand — to measure it
+against a rendered frame, or to look at it at all — needs what the `rotate:` line
+means for the numbers beside it, and the pack states none of this:
+
+- `bounds: x, y, w, h` gives `w x h` in the **drawing's** orientation, so it is
+  the part's size **unturned**: the same two numbers the same drawing carries at
+  `rotate: 0`;
+- the rectangle on the **page** is therefore `h x w` at `x, y` — the transpose —
+  at `rotate: 90` and at `rotate: 270` alike, while `w x h` is what a region
+  occupies at `rotate: 0` and at `rotate: 180`;
+- cut that rectangle out of the page and turn it **clockwise** to recover the
+  drawing at `rotate: 90`, and **counter-clockwise** at `rotate: 270`; a half
+  turn has no direction to name.
+
+Each direction there is **measured** rather than reasoned about: it comes off
+`MeshAttachment.computeUVs` in the linked runtime, the one routine there that
+says where a region's texels are for all four values, and the selftest derives
+the words in that list from the same routine instead of reading them. ⚠️ Do not
+take the turn from `TextureAtlas`'s own `u2`/`v2` — those transpose at a quarter
+turn one way and not at the other, so one of the two pairs describes a rectangle
+the page does not have ([#579](https://github.com/firejune/rigc/issues/579)).
+
+`build` now prints the page rectangle on the line for a turned region, so the
+report carries the rectangle to cut instead of leaving it to be derived
+([#718](https://github.com/firejune/rigc/issues/718)):
+
+```bash
+#   ..      pendulum   105x139  <- ../export/atlas.png @ 710,16 rotate 90, occupies 139x105
+```
+
 ⚠️ Two limits here are real and neither is about rotation:
 
 - `--atlas-in` cannot recover what a `scale:` quantised away (above), turned or not;
@@ -533,7 +564,7 @@ The other commands:
 ```bash
 bun cli.ts explain  --rig … --motion … --out …   # the compiled rig as a table
 bun cli.ts validate path/to/spine                # re-gate artifacts already on disk
-bun cli.ts diff     candidate.json reference.json
+bun cli.ts diff     candidate.json reference.json [--as <candidate>=<reference>]…
 bun cli.ts check    --candidate path/to/spine --frames path/to/frames [--skin …]
 bun cli.ts bench    3 --candidate path/to/spine [--frames path/to/frames]
 bun cli.ts render   --candidate path/to/spine [--animation …] [--skin …] [--fps 12] [--max 256]
@@ -567,6 +598,19 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   deliberately does not combine them into a score: a rig with the right skeleton
   and the wrong timing and a rig with the right timing and the wrong skeleton call
   for opposite fixes. A measure with nothing to compare says `0/0` and says so.
+
+  ⭐ **If your animation is not called what the reference's is, say so with
+  `--as <candidate>=<reference>`** (repeatable, one pair each) — or let it pair by
+  position, which happens with no flag when each side carries exactly one
+  animation. Without a pairing every animation measure but `count` is keyed on the
+  name, so a rig whose shot is right down to the key counts reads **0.000** across
+  the section. The pairing gets `animations` the same two figures `bones` and
+  `slots` carry, and reading them as a pair — name-agnostic 1.000 beside `names`
+  0.000 — is what says the shot is right and the name is yours. The measures, the
+  refusals and what makes the block absent instead of guessed:
+  [INGEST.md](INGEST.md) §1.3.1, and *The measure inventory* in
+  [BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md),
+  which is repository material rather than part of this package.
 - **`check`** renders your candidate into the reference frames' own pixel grid and
   compares pixels — the only thing here that can see a wrong animation. **§9.**
   🚨 What it certifies is the **default skin** unless you pass `--skin <name>`:
@@ -1081,6 +1125,22 @@ loader's sentence and all the report had. Since
 `A08_REGION_NAMES_MATCH_ATTACHMENTS`, with the skin, the slot, the placeholder
 and the attachment's own name beside the path.
 
+Where each vertex sits on the **art**:
+
+| Field | Meaning |
+| --- | --- |
+| `uvs` | one `u, v` per vertex, in the order the geometry below uses. Both are fractions of the region rather than pixels, and the array's length is what fixes the vertex count — a mesh states no `vertexCount`. **`(0, 0)` is the region's top-left pixel and `(1, 1)` its bottom-right**, so `u` grows toward the right edge and `v` grows *downward* toward the bottom edge: the crop-pixel convention §11.2 states for a manifest, and not Spine's y-up world. What a **turned** region (`rotate: 90`, in a pack somebody else made) does to that is §0.2's subject |
+
+⭐ **Measured, because an assumption about a corner is invisible in a build that
+went green.** On a 64×48 plate whose four quadrants are four flat colours,
+`rigc render` drew a quad given `uvs` running `0 → 0.5` on both axes as 3,120 px
+of the **top-left** quadrant's colour and not one pixel of any other, and the same
+quad given `0.5 → 1` as 3,120 px of the **bottom-right**. Beside it, the runtime's own
+`MeshAttachment.computeUVs`, handed the emitted atlas region, put `(0, 0)` at page
+pixel `(0.00, 0.00)` and `(1, 1)` at `(64.00, 48.00)` — the region's own two
+corners, in the page's y-down pixels. `CUR44` in the selftest holds the sentence
+above against that second measurement.
+
 Geometry comes in one of two fields:
 
 | Field | Meaning |
@@ -1267,6 +1327,105 @@ and uvs. `A13_MESH_BUDGET` counts it as a mesh of its own: the runtime draws it
 one, so a link in a second slot is a second mesh slot against
 `invariants.meshSlots`.
 
+**The three types that carry geometry and no art** — a bounding box, a clipping
+polygon and a path. None of them resolves an atlas region, so none of them has an
+`image`, a `path` key, a `width`/`height` or uvs, and a skin holding only these
+builds an atlas with **no pages** (above). What they do share is one geometry
+shape, and it is the mesh's with one field added:
+
+- 🚨 **`vertexCount` is required and has no parser default.** A mesh takes its
+  count from `uvs.length`; these have no uvs, so the parser reads
+  `map.vertexCount << 1` as the length to expect — and with the field absent that
+  is `undefined << 1` = **0**, which sends `readVertices` down the WEIGHTED branch,
+  decodes the coordinate list as a weight run, and hands back an attachment with no
+  vertices at all. Nothing throws, and none of the three draws a pixel, so nothing
+  downstream notices. rigc refuses it by name: `vertexCount is undefined; a polygon
+  needs at least 3 vertices, stated outright`.
+- **The two encodings are the mesh's own**, traps included: `weights` binds bones
+  by NAME and is the form to use; `vertices` is an unweighted `x, y` run when
+  `vertices.length === vertexCount * 2` and Spine's index-encoded weighted run
+  otherwise, and the second of those needs `"boneIndexing": "raw"` said out loud.
+  `A33_VERTEX_ATTACHMENT_GEOMETRY` (§5.2) gates all three types and accepts either
+  encoding on each — measured by building both on each of the three.
+- 📐 **Which space the numbers are in.** An unweighted `x, y` is in the **slot's
+  bone's** local space; a `weights` binding's `x`/`y` is in **that binding's own
+  bone's** local space, and the slot's bone plays no part in it. Measured through
+  spine-core on a rig where the two are different bones: `(0, 0)`, `(30, 0)`,
+  `(30, 20)` written unweighted on a slot whose bone sits at `(-60, 25)` turned
+  −21° posed at `(-60.0000, 25.0000)`, `(-31.9926, 14.2490)` and
+  `(-24.8252, 32.9206)`, which is that bone's own transform of them; the same three
+  points bound by name to a bone at `(110, 70)` turned 37° and scaled `1.3, 0.8`,
+  in the very same slot, posed at `(110.0000, 70.0000)`, `(141.1468, 93.4708)` and
+  `(131.5177, 106.2490)` — the BOUND bone's transform, to four decimals.
+- **A `deform` timeline reaches all three** (§4.11); none of them is drawn, so a
+  render can show you nothing about any of them.
+
+**Bounding box** ([Spine: bounding boxes](http://esotericsoftware.com/spine-bounding-boxes)) —
+`"type": "boundingbox"`. A polygon the game hit-tests against — a hurt box, a pick
+region, a trigger volume — that moves with the skeleton and draws nothing.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | `"boundingbox"`. **Required**: an omitted `type` is `"region"`, and a region has nowhere to put these keys — measured, the refusal reads `attachment "mask" (region) has 2 keys this compiler does not read: "vertexCount", "vertices"` |
+| `vertexCount` | **required**, 3 or more. No default — the paragraph above is why |
+| `vertices` | the unweighted `x, y` run, in the slot bone's local space; or the index-encoded weighted run, behind `boneIndexing` |
+| `weights` | the by-name form: one entry per vertex, each a list of `{ "bone": …, "x": …, "y": …, "weight": … }`, each pair in that bone's local space. Never beside `vertices` |
+| `boneIndexing` | `"name"` (the default) or `"raw"`, which opts a weighted `vertices` run into Spine's index encoding. `"raw"` beside `weights` is refused: `weights` always binds by name |
+| `color` | `rrggbbaa`. **No default in the file** — omitted, the parser never calls `setFromString` and the attachment keeps the runtime's own colour. It is an editor affordance, the colour the polygon is drawn in there; rigc emits it verbatim when stated and leaves the key out when not |
+
+**Clipping polygon** ([Spine: clipping](http://esotericsoftware.com/spine-clipping)) —
+`"type": "clipping"`. A mask: the polygon clips every slot drawn from the one
+carrying it up to and including `end`, so a window, a portal or a wipe is one
+attachment rather than a second set of art.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | `"clipping"`. **Required** |
+| `vertexCount`, `vertices`, `weights`, `boneIndexing`, `color` | exactly as on a bounding box |
+| `end` | the last slot the clip applies to, **by name**. Absent is the parser's own encoding for *clip everything after this one*, which is why a typo cannot be told from an omission once the file is loaded: `findSlot` returns null on a miss and the parser assigns that null without a word, so the clip runs to the bottom of the draw order and takes every slot below it with it. rigc refuses a name the rig does not declare — `end names slot "X", which this rig does not declare` — and `A33` refuses it again on a skeleton rigc did not write |
+| `convex` | default **false**. True tells the runtime the polygon is convex so it can clip without triangulating it, and a polygon that deforms concave is clipped by its convex hull instead (`ClippingAttachment.convex`). Nothing here checks that the polygon is in fact convex |
+| `inverse` | default **false**. True makes everything **outside** the polygon visible instead of everything inside, and inverse clipping is always treated as convex (`ClippingAttachment.inverse`) |
+
+⚠️ **A clipping attachment is refused by the renderer profile and by nothing
+else.** `A11_NO_CLIPPING_ATTACHMENTS` (§5.2) fires under `--profile spine-html`
+because that renderer skips clipping silently; it is one renderer's policy rather
+than anything about the data, and the default `spine` profile builds one.
+
+**Path** ([Spine: paths](http://esotericsoftware.com/spine-paths)) —
+`"type": "path"`. The composite cubic Bezier a path **constraint** (§3.5.1) slides
+bones along. No runtime draws it, and it deforms with the slot's bone like any
+other vertex attachment.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | `"path"`. **Required** |
+| `vertexCount`, `vertices`, `weights`, `boneIndexing`, `color` | as on a bounding box — except that these vertices are knots **and** their handles, which the count rule below is about |
+| `closed` | default **false**. True joins the last knot back to the first |
+| `constantSpeed` | default **true** — note the direction. Leaving it out asks for the expensive-and-correct traversal, in which the runtime re-measures the path every frame and `lengths` is never read. `false` makes the runtime trust the emitted `lengths` instead: cheaper, exact only while the path holds its setup shape, and the reason a deformed path wants the default |
+| `lengths` | 🚫 **refused by name.** rigc measures the setup length of each curve off the geometry and emits it, the way it measures a region's size off its PNG: `"lengths" is not authored — rigc measures the setup arc length of each curve…`. The field is declared only so the refusal can say that rather than report a misspelt key. What the numbers are — and why *arc length* is the wrong name for them — is §10.6 |
+
+🚨 **`vertexCount` counts knots AND handles, and it has to be a multiple of 3.**
+The parser hands `vertexCount << 1` to `readVertices` and then walks the result in
+groups of six: the first and last points are the outer control handles of the end
+knots and are dropped, leaving a `3K + 1` chain. So an OPEN path of K curves states
+`vertexCount = 3(K + 1)`, minimum **6**, and a CLOSED one states `3K`, minimum
+**3**. A count that is not a multiple of 3 does not throw —
+`Utils.newArray(vertexCount / 3, 0)` accepts a fractional size, the groups of six
+then straddle the knots, and the constraint slides bones along a curve nobody drew
+— so rigc refuses both shapes: `vertexCount is N, which is not a multiple of 3`
+and `vertexCount is N and an open path needs at least 6`.
+
+```json
+"track": { "track": { "type": "path", "vertexCount": 9,
+  "vertices": [-30, 0, 0, 0, 30, 0, 60, 0, 90, 0, 120, 0, 150, 0, 180, 0, 210, 0] } }
+```
+
+Nine points are two curves. The outer handles at `x = -30` and `x = 210` are
+dropped, so the chain runs from `x = 0` to `x = 180` and rigc emits
+`"lengths": [90, 180]` beside it — measured, not stated. That is the path
+§3.5.1's constraint example rides: with `position: 0.25` its `cart` bone poses at
+`worldX = 45.000000`.
+
 The generators are `ring`, `ribbon`, `contour` and `grid` (see
 [`src/mesh.ts`](../src/mesh.ts)); the first two encode a deformation model rather
 than a table of numbers, which is why they are code invoked by data. The last two
@@ -7331,7 +7490,7 @@ Per part:
 | `ambiguous` | at least one alternate is inside the ambiguity margin. **Choose with something this instrument cannot see** — anatomy, the other frame, or `rigc vote` |
 | `rotationFree` | the part is self-similar under rotation, so `rotationDeg` is a placeholder and the value is yours |
 | `rotationSelfSimilarity` | the number `rotationFree` is a threshold on. A part just over the line is worth a look |
-| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part` |
+| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part`. A `no-match` whose best placement stopped **on a wall of the search window** names the wall in its detail — see §11.4 |
 | `coarse` | the grid this part was actually searched on. A handful of cells means the part is small relative to the frame and the first pass had little to go on |
 | `notes` | the same facts in prose, in the order they were found |
 
@@ -7349,6 +7508,16 @@ The report also carries `frame.background` (how the picture's empty space was
 identified — a flat colour, transparency, or `unknown`), `search` (every window
 and threshold that was applied), and `caveats`.
 
+🔒 **`search` states what ran, not what was asked for.** `search.rotation` carries
+`degrees`, the ladder the coarse pass actually walked, and its `stepDeg` is read
+off that ladder rather than off the constant the ladder was capped at. The coarse
+step `15°` is a **ceiling** on the step, not the step: a narrower window is
+divided into whole steps no coarser than it, so
+`--rotation -5,5` prints `rotation -5°–5° in 2 step(s) of 10°` and walks those two
+angles and no others. Nothing reported leaves the window either — the refinement
+and the quarter-turn probes are held inside it, and a window spanning a full turn
+holds nothing because it already contains every angle.
+
 ### 11.4 What it cannot see — read this before using the numbers
 
 - ⚠️ **Residuals degrade under occlusion, and there is no depth solver here.** A
@@ -7364,6 +7533,16 @@ and threshold that was applied), and `caveats`.
   answer is the best placement available *inside* `--scale` / `--rotation` and its
   residual can look reasonable. This is why the window is a reported field: if the
   numbers surprise you, check `search` before you trust them.
+- 🔒 **A refusal that stopped on a wall of the window says which wall.** When a
+  `no-match`'s best placement sits on the floor or the ceiling of `--scale`, or on
+  an edge of a `--rotation` window narrower than a full turn, the detail names it:
+  `best placement at scale 0.500, the floor of --scale 0.5,2 — the truth may lie below the window`.
+  That is the case where the window is the first thing to move rather than the
+  frame or the threshold — eleven parts of one frame came back refused at
+  `scale=0.500` against art rendered at `0.311` per part pixel, and the message
+  said only that the residual was above `--max-residual`. It is printed on a
+  **refusal and nowhere else**: an accepted placement sitting on a wall is a window
+  chosen to bracket the answer, which is the flag working.
 - ⚠️ **A frame whose border has no dominant colour reports `background.unknown`.**
   Every pixel then counts as material, the silhouette signal is gone, and the
   residual is colour agreement alone. The report says so rather than being quietly

package/docs/INGEST.md

@@ -237,7 +237,9 @@ Spine runtime plays it, whatever rigc's own rasteriser or validator thinks.
 `diff` takes two compiled skeletons and reports 49 measures in eight groups, plus two
 blocks that report and gate nothing: the `(reported)` measures beside `attachments`
 and `animations`, and the `skeleton` header block at the top, which measures the stage
-(issue #578). Both sides may be foreign; the interesting pairing during ingest is
+(issue #578). A ninth group of six joins them when something has paired the two sides'
+animations — `--as <candidate>=<reference>`, or one animation each side, which pairs by
+position (§1.3.1). Both sides may be foreign; the interesting pairing during ingest is
 **your transcription against the export it came from**:
 
 ```bash
@@ -326,6 +328,44 @@ attachment types and bone-binding shapes by draw-order position. That is how you
 *"the same rig with a different vocabulary"* from *"a different rig"*, and §4.2 is the
 recipe built on it.
 
+#### 1.3.1 Animations differ by name too — `--as`
+
+`bones` and `slots` are matched name-agnostically by their own shape. Animations have
+none: the candidate's `take01` and the reference's `arcs` are the same shot only
+because somebody says they are. Two things say it —
+
+```bash
+rigc diff work/t6/skeleton.json examples/6-arcs/export/6-arcs-pro.json --as take01=arcs
+```
+
+— and, with no flag, **one animation each side**, which pairs by position because there
+is exactly one reading of which shot is which. `--as` is repeatable, one pair each, and
+the candidate's name goes on the left, as it does in `bonedist`'s correspondence file.
+
+With the pairing in hand the `animations` section reports two figures like the other
+two sections, the second over the paired shots — `duration`, `timeline_kinds`,
+`key_counts`, `curve_kinds`, `draw_order`, `deform` — and the heading says which pairing
+it used:
+
+```
+  animations            mean 0.222  over 9 measures
+      1.000  count                        1/1         how many animations
+      0.000  names                        0/2         the animation names
+      …
+  animations (name-agnostic) mean 1.000  over 6 measures  — the same two skeletons compared with names thrown away, paired by position: take01=arcs, the one animation each side carries
+```
+
+Read that pair exactly as you read `bones`'s: **1.000 beside `names` 0.000** says the
+shot is right and its name is yours. ⛔ `names` never moves into the second block, and
+with two shots on each side and no `--as`, the block is **absent** rather than paired by
+declaration order — a candidate that declares its two shots the other way round would
+then read 0.000 across it and the report would be calling a guess a measurement.
+
+⚠️ An `--as` naming an animation a side does not have is **refused** with what that side
+does have, and so is one that pairs the same animation twice. Neither is dropped
+quietly: a typo that measured less than you asked for is a report about a pairing you
+did not state.
+
 ### 1.4 `check` — the instrument that does see coordinates
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "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/diff.ts

@@ -46,6 +46,34 @@
  *    wrong; name-agnostic low alone is impossible, since a wrong shape cannot
  *    have right names.
  *
+ *    ⭐ `animations` carries the same second comparison, and it arrived last
+ *    because it needs something the other two do not: a PAIRING. A bone is
+ *    paired with a bone by its depth and its child count, which the file
+ *    states; two animations have no such shape to be matched on, so the
+ *    candidate's `take01` and the reference's `arcs` are the same shot only
+ *    because somebody says they are. Until that was said, every animation
+ *    measure was keyed on the name — and a candidate that followed a brief
+ *    withholding it read `count` 1/1 and **0.000 on all eight measures below**,
+ *    on a shot with the same duration, the same timeline families and the same
+ *    key counts (issue #720). That is the *gate that cannot be passed* shape on
+ *    the measuring instrument rather than on the gate.
+ *
+ *    Two things say it, and nothing else does. `--as <candidate>=<reference>`
+ *    pairs them outright; failing that, **one animation each side** pairs by
+ *    position, because there is exactly one reading of which shot is which and
+ *    no name is consulted to reach it. Anything else — two against two, three
+ *    against one — has several readings, so the block is ABSENT rather than
+ *    guessed at, which is what `DiffSection.nameAgnostic` means by *"should say
+ *    so by having none"*. ⚠️ Guessing there is the failure this file is built
+ *    against: pairing two-against-two by position would score a candidate whose
+ *    two shots are declared in the other order 0.000 across the block and call
+ *    it a measurement.
+ *
+ *    🔒 `names` stays in the name-matched block alone, and that is the whole
+ *    point of the split rather than an oversight: the pair is read as *agnostic
+ *    1.000 with `names` 0.000*, which says the shot is right and its name is the
+ *    author's own.
+ *
  * 4. **A measure that cannot gate is not in the mean.** `section.reported`
  *    carries the measures `docs/GATE.md`'s *What never gates* calls
  *    unobservable by construction — *"could any reading of the frames have
@@ -121,6 +149,18 @@ export interface DiffAgnostic {
   /** Unweighted mean of the measures below. NOT a quality score either. */
   ratio: number;
   measures: DiffMeasure[];
+  /**
+   * How the two sides were put against each other, for a block that had to
+   * choose — `animations` alone today. Absent where the correspondence is the
+   * elements themselves and there was nothing to decide.
+   *
+   * ⚠️ It is data rather than a caption. A block whose figures depend on a
+   * pairing, printed without the pairing beside it, is a measurement of
+   * something the reader cannot name — and the two pairings say different
+   * things: `--as` is the caller's claim, position is this file's reading of a
+   * one-against-one roster.
+   */
+  pairedBy?: string;
 }
 
 /**
@@ -279,12 +319,21 @@ function sectionOf(
   measures: DiffMeasure[],
   nameAgnostic?: DiffMeasure[],
   reported?: DiffMeasure[],
+  pairedBy?: string,
 ): DiffSection {
   return {
     name,
     ratio: meanRatio(measures),
     measures,
-    ...(nameAgnostic === undefined ? {} : { nameAgnostic: { ratio: meanRatio(nameAgnostic), measures: nameAgnostic } }),
+    ...(nameAgnostic === undefined
+      ? {}
+      : {
+          nameAgnostic: {
+            ratio: meanRatio(nameAgnostic),
+            measures: nameAgnostic,
+            ...(pairedBy === undefined ? {} : { pairedBy }),
+          },
+        }),
     ...(reported === undefined ? {} : { reported: { measures: reported } }),
   };
 }
@@ -905,11 +954,154 @@ function keyingTotals(f: AnimationFacts): KeyingTotals {
   return { keys: sum(f.keys), timelines: sum(f.kinds), seconds: sum(f.duration) };
 }
 
-function diffAnimations(c: Json, r: Json): DiffSection {
+/** One animation on each side, said to be the same shot. */
+export interface DiffAnimationPair {
+  candidate: string;
+  reference: string;
+}
+
+/**
+ * What a caller may tell `diffSkeletons` that neither file can say itself.
+ *
+ * Only the animation pairing today, and it is an INPUT in the sense
+ * `bonedist`'s correspondence file is one: two skeletons cannot derive which of
+ * their shots are the same shot, so a value worked out here would be a guess
+ * reported as a measurement.
+ */
+export interface DiffOptions {
+  /** `--as <candidate>=<reference>`, in the order the caller stated them. */
+  animationPairs?: readonly DiffAnimationPair[];
+}
+
+/**
+ * The pairing used for `animations.agnostic.*`, or `null` when there is none.
+ *
+ * ⚠️ A stated pair naming an animation a side does not have is DROPPED and said
+ * so in `pairedBy`, rather than silently making the block narrower. `cmdDiff`
+ * refuses one by name before this is reached, so through the CLI the branch is
+ * unreachable; it exists because this module is exported and a caller of the
+ * API can state one.
+ */
+function pairAnimations(
+  a: AnimationFacts,
+  b: AnimationFacts,
+  stated: readonly DiffAnimationPair[],
+): { pairs: DiffAnimationPair[]; pairedBy: string } | null {
+  const spell = (p: DiffAnimationPair): string => `${p.candidate}=${p.reference}`;
+  if (stated.length > 0) {
+    const usable = stated.filter((p) => a.duration.has(p.candidate) && b.duration.has(p.reference));
+    if (usable.length === 0) return null;
+    const dropped = stated.filter((p) => !usable.includes(p));
+    return {
+      pairs: [...usable],
+      pairedBy:
+        `paired by --as: ${usable.map(spell).join(', ')}` +
+        (dropped.length === 0 ? '' : `; ${dropped.map(spell).join(', ')} named an animation a side does not have and was dropped`),
+    };
+  }
+  if (a.names.length === 1 && b.names.length === 1) {
+    const pair = { candidate: a.names[0], reference: b.names[0] };
+    return { pairs: [pair], pairedBy: `paired by position: ${spell(pair)}, the one animation each side carries` };
+  }
+  return null;
+}
+
+/**
+ * `f` restricted to the animations `label` names, with each one's name replaced
+ * by the label — `#0` for the first pair, `#1` for the second.
+ *
+ * That substitution is the whole of what makes the block name-agnostic: the
+ * measures below are the name-matched ones run again over facts whose keys are
+ * positions in the pairing. Everything else about them — the tolerance, the
+ * denominators, the histogram — is unchanged, which is what lets the two blocks
+ * be read against each other.
+ */
+function underLabels(f: AnimationFacts, label: ReadonlyMap<string, string>): AnimationFacts {
+  const keyed = <T>(m: Map<string, T>): Map<string, T> => {
+    const out = new Map<string, T>();
+    for (const [anim, v] of m) {
+      const to = label.get(anim);
+      if (to !== undefined) out.set(to, v);
+    }
+    return out;
+  };
+  // `kinds`, `keys` and `curves` are keyed `<anim>|<rest>`, so only the head is
+  // relabelled and the tail — the timeline's kind, the curve's shape — is what
+  // the histogram then intersects on.
+  const prefixed = (m: Map<string, number>): Map<string, number> => {
+    const out = new Map<string, number>();
+    for (const [k, v] of m) {
+      const bar = k.indexOf('|');
+      const to = label.get(k.slice(0, bar));
+      if (to === undefined) continue;
+      const id = `${to}${k.slice(bar)}`;
+      out.set(id, (out.get(id) ?? 0) + v);
+    }
+    return out;
+  };
+  return {
+    names: [...label.values()],
+    duration: keyed(f.duration),
+    kinds: prefixed(f.kinds),
+    keys: prefixed(f.keys),
+    curves: prefixed(f.curves),
+    events: keyed(f.events),
+    hasDrawOrder: keyed(f.hasDrawOrder),
+    hasDeform: keyed(f.hasDeform),
+  };
+}
+
+/**
+ * The six measures of `animations.agnostic.*`.
+ *
+ * ⛔ `names` is not among them, by construction — a block that threw the names
+ * away cannot then compare them. ⛔ Neither is `count`, which `bones` and
+ * `slots` do carry, and the difference is what the block is OVER: those two
+ * compare whole rosters, so their agnostic half has the same subject as their
+ * name-matched half and restates the count for a reader with one block open.
+ * This one is over the PAIRS. A `count` in it would either restate the roster
+ * figure — a different subject under the same heading — or count the pairs,
+ * which measures the flag rather than the two rigs. The roster figure is
+ * `animations.count`, and it is already name-free.
+ */
+function agnosticAnimationMeasures(a: AnimationFacts, b: AnimationFacts, pairs: readonly DiffAnimationPair[]): DiffMeasure[] {
+  const slot = (i: number): string => `#${i}`;
+  const ca = underLabels(a, new Map(pairs.map((p, i) => [p.candidate, slot(i)])));
+  const rb = underLabels(b, new Map(pairs.map((p, i) => [p.reference, slot(i)])));
+  return [
+    agreement(
+      'animations.agnostic.duration',
+      'each paired animation runs as long (last key time, within one frame)',
+      ca.duration,
+      rb.duration,
+      (x, y) => Math.abs(x - y) <= FRAME,
+    ),
+    histogram('animations.agnostic.timeline_kinds', 'the same timelines exist in the paired animations', ca.kinds, rb.kinds),
+    histogram('animations.agnostic.key_counts', 'those timelines carry as many keys', ca.keys, rb.keys),
+    histogram('animations.agnostic.curve_kinds', 'as many linear / stepped / bezier keys', ca.curves, rb.curves),
+    agreement(
+      'animations.agnostic.draw_order',
+      'a draw-order timeline is present or absent alike',
+      ca.hasDrawOrder,
+      rb.hasDrawOrder,
+      (x, y) => x === y,
+    ),
+    agreement(
+      'animations.agnostic.deform',
+      'a deform timeline is present or absent alike',
+      ca.hasDeform,
+      rb.hasDeform,
+      (x, y) => x === y,
+    ),
+  ];
+}
+
+function diffAnimations(c: Json, r: Json, pairsStated: readonly DiffAnimationPair[]): DiffSection {
   const a = animationFacts(c);
   const b = animationFacts(r);
   const at = keyingTotals(a);
   const bt = keyingTotals(b);
+  const paired = pairAnimations(a, b, pairsStated);
   const perSecond = (t: KeyingTotals): number => (t.seconds === 0 ? 0 : t.keys / t.seconds);
   const perTimeline = (t: KeyingTotals): number => (t.timelines === 0 ? 0 : t.keys / t.timelines);
   return sectionOf('animations', [
@@ -929,7 +1121,14 @@ function diffAnimations(c: Json, r: Json): DiffSection {
     agreement('animations.draw_order', 'a draw-order timeline is present or absent alike', a.hasDrawOrder, b.hasDrawOrder, (x, y) => x === y),
     agreement('animations.deform', 'a deform timeline is present or absent alike', a.hasDeform, b.hasDeform, (x, y) => x === y),
   ],
-  undefined,
+  // ── the same two skeletons' shots, paired rather than named (issue #720) ──
+  //
+  // Absent unless something pairs them — see `pairAnimations` and the header's
+  // point 3. `undefined` and not `[]`: a block with no measures in it prints a
+  // vacuous `mean 1.000 over 0 measures`, which is the false green this whole
+  // file is built to refuse, and `movedAgnosticMeasures` cannot tell it from a
+  // block that agreed about everything.
+  paired === null ? undefined : agnosticAnimationMeasures(a, b, paired.pairs),
   // ── reported (issue #20) ────────────────────────────────────────────────
   //
   // 🔍 What #20 asked and what was actually wrong. The issue proposed making key
@@ -981,7 +1180,8 @@ function diffAnimations(c: Json, r: Json): DiffSection {
         `(${at.timelines} vs ${bt.timelines}), compared as min/max at ${RATE_PLACES} decimal places. Read beside ` +
         '`key_density`: this one alone moving means the same keying spread over a different number of timelines.',
     ),
-  ]);
+  ],
+  paired?.pairedBy);
 }
 
 function eventFacts(root: Json): Map<string, string> {
@@ -1168,11 +1368,19 @@ function orientation(root: Json): Record<string, number> {
   };
 }
 
-export function diffSkeletons(candidate: unknown, reference: unknown): DiffReport {
+export function diffSkeletons(candidate: unknown, reference: unknown, options?: DiffOptions): DiffReport {
   const c = isObj(candidate) ? candidate : {};
   const r = isObj(reference) ? reference : {};
+  const animationPairs = options?.animationPairs ?? [];
   return {
-    sections: [diffBones(c, r), diffSlots(c, r), diffAttachments(c, r), diffConstraints(c, r), diffAnimations(c, r), diffEvents(c, r)],
+    sections: [
+      diffBones(c, r),
+      diffSlots(c, r),
+      diffAttachments(c, r),
+      diffConstraints(c, r),
+      diffAnimations(c, r, animationPairs),
+      diffEvents(c, r),
+    ],
     header: diffHeader(c, r),
     candidate: orientation(c),
     reference: orientation(r),
@@ -1466,8 +1674,18 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
   );
   lines.push(...measureLines(report.header.measures, 'skeleton.'.length));
   lines.push('');
-  // Wide enough for `<longest section> (name-agnostic)`, so that a section's two
-  // headings line their figures up under each other and read as a pair.
+  // Wide enough for `bones (name-agnostic)` and `animations (reported)`, both
+  // exactly 21, so that most of a section's headings line their figures up
+  // under each other and read as a pair.
+  //
+  // ⚠️ Two headings are longer and push their own figure right instead:
+  // `attachments (reported)`, which has done so since that block existed, and
+  // `animations (name-agnostic)` (issue #720). Widening the column is the
+  // obvious repair and it is the wrong one — it moves every heading line of
+  // every report, and those lines are quoted verbatim in `docs/LADDER.md` and
+  // in the landed run records under `bench/runs/`, which are sealed. A
+  // cosmetic alignment is not worth a byte change in every transcript already
+  // written, and the overflow is visible rather than silent.
   const head = (label: string, ratio: number, n: number): string =>
     `  ${label.padEnd(21)} mean ${fmt(ratio)}  over ${n} measures`;
   for (const section of report.sections) {
@@ -1478,7 +1696,9 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
       lines.push('');
       lines.push(
         `${head(`${section.name} (name-agnostic)`, agnostic.ratio, agnostic.measures.length)}` +
-          '  — the same two skeletons compared with names thrown away',
+          '  — the same two skeletons compared with names thrown away' +
+          // The pairing is part of the figure, not decoration: see `DiffAgnostic.pairedBy`.
+          (agnostic.pairedBy === undefined ? '' : `, ${agnostic.pairedBy}`),
       );
       lines.push(...measureLines(agnostic.measures, section.name.length + '.agnostic.'.length));
     }
@@ -1506,6 +1726,12 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
   lines.push('  comparisons, not two halves of one: name-agnostic 1.000 beside a low');
   lines.push('  name-matched figure means the shape is right and the vocabulary differs.');
   lines.push('');
+  lines.push('  `animations` carries the same pair, and only once something has PAIRED the two');
+  lines.push('  sides\' shots: `--as <candidate>=<reference>`, or one animation each side, which');
+  lines.push('  pairs by position. With neither there is no reading of which shot is which, so');
+  lines.push('  the block is absent rather than guessed — and its absence beside `names` 0.000');
+  lines.push('  is the report saying the candidate named its shots itself and nothing said how.');
+  lines.push('');
   lines.push('  `skeleton` is the file\'s own header block and reports two measures for the stage.');
   lines.push('  It has no mean for the reason a `(reported)` block never does, and it never');
   lines.push('  gates for two: no reading of the frames recovers a setup-pose bounding box, and');

package/src/pose.ts

@@ -129,7 +129,16 @@ export const COARSE_STRIDE_FRACTION = 0.25;
 /** How many scale rungs one octave gets in the coarse ladder. */
 export const SCALE_STEPS_PER_OCTAVE = 3;
 
-/** The coarse rotation ladder's step, in degrees. */
+/**
+ * The COARSEST step, in degrees, the rotation ladder is allowed to take.
+ *
+ * ⚠️ A ceiling on the step rather than the step itself, and the distinction is
+ * the whole of issue #719. Read as "the step", a window narrower than it prints
+ * a resolution the search never had: `--rotation -5,5` reported `step 15°` over
+ * a ten-degree window. The ladder therefore divides the window into whole steps
+ * no coarser than this — the same shape `scaleLadder` has always had for
+ * octaves — and the report states the step that division produced.
+ */
 export const COARSE_ROTATION_STEP = 15;
 
 /** Default scale window, as frame pixels per part pixel. */
@@ -271,7 +280,15 @@ export interface PosePart {
 
 export interface PoseSearch {
   scale: { min: number; max: number; steps: number };
-  rotation: { minDeg: number; maxDeg: number; stepDeg: number; steps: number };
+  /**
+   * The rotation window, and the ladder it produced.
+   *
+   * 🔒 `stepDeg` is read off `degrees` rather than off `COARSE_ROTATION_STEP`,
+   * and `degrees` is the array the coarse pass iterated — so the two cannot say
+   * different things about the same run (issue #719). `steps` is how many angles
+   * that is, which is `degrees.length`.
+   */
+  rotation: { minDeg: number; maxDeg: number; stepDeg: number; steps: number; degrees: number[] };
   /**
    * How the exhaustive first pass was sized. The level it runs at is chosen PER
    * PART — see `PosePart.coarse` — because it depends on how big the part is.
@@ -783,8 +800,28 @@ function polish(
   smooth: boolean,
   /** The scale window the report declares. A polish that walked outside it would report a scale nobody searched. */
   bounds: { min: number; max: number },
+  /**
+   * The rotation window the report declares, held for exactly the reason above.
+   *
+   * ⚠️ This argument did not exist until issue #719, and the sentence over
+   * `bounds` was the whole argument for it the entire time: a polish free to
+   * walk outside the window reports an answer nobody searched, and the window is
+   * a field a caller is entitled to read as a promise. `src/chainfit.ts` had
+   * already written that argument out for its own hinge — *"for the same reason
+   * `pose`'s polish clamps its scale"* — while this file, the one it was citing,
+   * clamped one of its two windows. Measured on a rotation window of `-5,5`: the
+   * ladder walked its two endpoints and the report came back with 28.1°, 121.3°
+   * and −122.3°.
+   *
+   * A full turn contains every angle, so it is left unclamped and the rotation
+   * may wrap — which is what the default window is, and why nothing about a
+   * default run moves.
+   */
+  rotationBounds: { min: number; max: number; wraps: boolean },
 ): Candidate {
   const clamp = (v: number): number => Math.min(bounds.max, Math.max(bounds.min, v));
+  const hold = (v: number): number =>
+    rotationBounds.wraps ? v : Math.min(rotationBounds.max, Math.max(rotationBounds.min, v));
   let cur: Candidate = { ...start, residual: residualAt(level, plate, s, start, smooth) };
   let dt = step.translate;
   let dr = step.rotate;
@@ -810,8 +847,8 @@ function polish(
       }
     }
     if (dr > floor.rotate) {
-      push({ cx: cur.cx, cy: cur.cy, rotDeg: cur.rotDeg + dr, scale: cur.scale });
-      push({ cx: cur.cx, cy: cur.cy, rotDeg: cur.rotDeg - dr, scale: cur.scale });
+      push({ cx: cur.cx, cy: cur.cy, rotDeg: hold(cur.rotDeg + dr), scale: cur.scale });
+      push({ cx: cur.cx, cy: cur.cy, rotDeg: hold(cur.rotDeg - dr), scale: cur.scale });
     }
     if (ds > floor.scale) {
       push({ cx: cur.cx, cy: cur.cy, rotDeg: cur.rotDeg, scale: clamp(cur.scale * (1 + ds)) });
@@ -997,22 +1034,76 @@ function scaleLadder(min: number, max: number): number[] {
   return out;
 }
 
-function rotationLadder(minDeg: number, maxDeg: number): number[] {
+/**
+ * The angles the coarse pass actually walks, evenly dividing the window.
+ *
+ * ⭐ `scaleLadder` above is the shape this follows, and it is the reason the
+ * defect was reachable: that one takes a rung count off its window and divides,
+ * so the rung it reports is the rung it walks. This one used to march
+ * `COARSE_ROTATION_STEP` off the floor and then append the ceiling, which left
+ * two ways for the reported step to be a different number from the applied one —
+ * a window narrower than the constant got its two endpoints and a gap of the
+ * window's own width, and any window whose span is not a whole number of steps
+ * got a short final gap. Both printed `step 15°`.
+ *
+ * ⚠️ The count is a CEILING rather than a rounding, which is not tidiness: a
+ * rounding down would make the applied step wider than `COARSE_ROTATION_STEP`
+ * for a window like 20°, so the constant would stop being an upper bound on the
+ * step. Rounding up cannot coarsen the search — measured against the old ladder,
+ * every window it changes gets at least as many angles as before.
+ */
+export function rotationLadder(minDeg: number, maxDeg: number): number[] {
   const span = maxDeg - minDeg;
   if (span <= 0) return [minDeg];
-  // A full turn's two endpoints are the same rotation, so it gets one of them.
-  if (span >= 360 - 1e-9) {
-    const count = Math.round(360 / COARSE_ROTATION_STEP);
-    const out: number[] = [];
-    for (let i = 0; i < count; i++) out.push(minDeg + (i * 360) / count);
-    return out;
-  }
+  const steps = Math.ceil(span / COARSE_ROTATION_STEP - 1e-9);
   const out: number[] = [];
-  for (let deg = minDeg; deg <= maxDeg + 1e-9; deg += COARSE_ROTATION_STEP) out.push(deg);
-  if (out[out.length - 1] < maxDeg - 1e-9) out.push(maxDeg);
+  for (let i = 0; i <= steps; i++) out.push(minDeg + (span * i) / steps);
+  // A full turn's two endpoints are the same rotation, so it gets one of them.
+  if (span >= 360 - 1e-9) out.pop();
   return out;
 }
 
+/** The step a ladder walks, read off the ladder rather than off the constant it was built from. */
+function ladderStep(degrees: number[]): number {
+  return degrees.length > 1 ? degrees[1] - degrees[0] : 0;
+}
+
+/**
+ * The `search` line's rotation clause.
+ *
+ * ⭐ Exported for the same reason `windowEdgeNote` is: `docs/AUTHORING.md`
+ * quotes this line, and a guide that spells a report's own sentence by hand is
+ * a second implementation of it. `CUR47` builds the clause here and looks for it
+ * in the page, so the two go stale together or not at all.
+ */
+export function searchRotationClause(rotation: PoseSearch['rotation']): string {
+  // Rounded for the console alone — `search.rotation` in the JSON carries the
+  // ladder unrounded, because a window that divides into thirds has angles no
+  // decimal place holds.
+  return `rotation ${rotation.minDeg}°–${rotation.maxDeg}° in ${rotation.steps} step(s) of ${roundTo(rotation.stepDeg, 3)}°`;
+}
+
+/**
+ * The sentence a refusal carries when its best placement sits on a WALL of the
+ * search window rather than somewhere inside it.
+ *
+ * ⭐ Exported because the guide quotes it and `CUR48` compares the two: a
+ * message and the document that teaches it are the same interface, and the only
+ * way they cannot drift is for one of them to be built from the other.
+ *
+ * The claim is deliberately weak — *may* lie outside — because that is all that
+ * is known. The search was bounded, the optimum walked to the bound and stopped;
+ * whether the truth is past it or the part simply does not appear in this frame
+ * are two readings this instrument cannot separate. Naming the wall is what lets
+ * an author separate them, by moving the wall.
+ */
+export function windowEdgeNote(axis: 'scale' | 'rotation', edge: 'floor' | 'ceiling', at: string, window: string): string {
+  return (
+    `best placement at ${axis} ${at}, the ${edge} of --${axis} ${window} — ` +
+    `the truth may lie ${edge === 'floor' ? 'below' : 'above'} the window`
+  );
+}
+
 /** The PNGs in a directory, in name order — the parts, and the order the report lists them. */
 export function partFiles(imagesDir: string, exclude: string): string[] {
   const dir = resolve(imagesDir);
@@ -1072,7 +1163,18 @@ export function estimatePose(options: PoseOptions): PoseReport {
     frame: { path: framePath, width: frame.width, height: frame.height, background },
     search: {
       scale: { min: scaleMin, max: scaleMax, steps: scales.length },
-      rotation: { minDeg: rotMin, maxDeg: rotMax, stepDeg: COARSE_ROTATION_STEP, steps: rotations.length },
+      rotation: {
+        minDeg: rotMin,
+        maxDeg: rotMax,
+        // ⚠️ Neither of these is rounded, and every other number in this report
+        // is. Rounding them would make the reported ladder a near-copy of the
+        // applied one, which is the defect this field exists to close — a window
+        // that divides into thirds has angles no decimal place holds. The console
+        // rounds for display; the record is exact.
+        stepDeg: ladderStep(rotations),
+        steps: rotations.length,
+        degrees: [...rotations],
+      },
       coarse: {
         frameLongSide: COARSE_LONG_SIDE,
         partSpan: COARSE_PART_SPAN,
@@ -1097,14 +1199,29 @@ export function estimatePose(options: PoseOptions): PoseReport {
         'only inside the frame canvas. ⚠️ A window that does not contain the true value does NOT reliably ' +
         'refuse: a part shrunk inside the region it came from still explains those pixels, so the answer is the ' +
         'best placement available INSIDE the window and its residual can look reasonable. That is why the window ' +
-        'is a reported field — if the numbers surprise you, check it before you trust them.',
+        'is a reported field — if the numbers surprise you, check it before you trust them. A refused part whose ' +
+        'best placement stopped ON a wall of the window says so in its own `refusal.detail`, which is the case ' +
+        'where the window is the first thing to move.',
     ],
     parts: [],
   };
 
+  // A window spanning a whole turn contains every angle there is, so nothing is
+  // outside it and nothing has to be held inside it.
+  const rotationBounds = { min: rotMin, max: rotMax, wraps: rotMax - rotMin >= 360 - 1e-9 };
   for (const path of paths) {
     report.parts.push(
-      placePart(path, frame, levels, framePyramid, scales, rotations, maxResidual, { min: scaleMin, max: scaleMax }),
+      placePart(
+        path,
+        frame,
+        levels,
+        framePyramid,
+        scales,
+        rotations,
+        maxResidual,
+        { min: scaleMin, max: scaleMax },
+        rotationBounds,
+      ),
     );
   }
   return report;
@@ -1119,6 +1236,7 @@ function placePart(
   rotations: number[],
   maxResidual: number,
   scaleBounds: { min: number; max: number },
+  rotationBounds: { min: number; max: number; wraps: boolean },
 ): PosePart {
   const scaleMin = scaleBounds.min;
   /** The scale the sample sets are sized for — the middle of the window, and NOT the scale under test. */
@@ -1303,7 +1421,7 @@ function placePart(
       }
       seeds.push(start);
     }
-    candidates = seeds.map((seed) => polish(level, plate, s, seed, step, floor, smooth, scaleBounds));
+    candidates = seeds.map((seed) => polish(level, plate, s, seed, step, floor, smooth, scaleBounds, rotationBounds));
     candidates.sort((a, b) => a.residual - b.residual);
     // ⚠️ Eight branches that walked to one optimum are one candidate, not eight —
     // and the radius has to scale with the PART rather than be a pixel count.
@@ -1324,20 +1442,31 @@ function placePart(
   // The one rotation family the translation scan cannot see: a part that is its
   // own mirror after a quarter or a half turn sits in the SAME place at more than
   // one angle, so the field records only whichever won. Probe them explicitly.
+  //
+  // 🚨 Only the turns the window contains, and this is the other half of #719's
+  // measurement. A quarter turn off is a SEED, not a ladder rung — so under
+  // `--rotation -5,5` it entered the answer from outside a window the report was
+  // calling the search, and the candidate who ran the exam read `rot=91.2°`
+  // under `rotation -5°–5°`. A caller who bounds the rotation has said the part
+  // is not a quarter turn over; the honest response is not to look there rather
+  // than to look and report it.
   if (!rotationFree && candidates.length > 0) {
     const primary = candidates[0];
     const s = samplesFor(1, POLISH_SAMPLES);
     for (const turn of [90, 180, 270]) {
+      const turned = primary.rotDeg + turn;
+      if (!rotationBounds.wraps && (turned < rotationBounds.min - 1e-9 || turned > rotationBounds.max + 1e-9)) continue;
       candidates.push(
         polish(
           levels[0],
           plates[0],
           s,
-          { ...primary, rotDeg: primary.rotDeg + turn },
+          { ...primary, rotDeg: turned },
           { translate: 1.5, rotate: 4, scale: 0.04 },
           { translate: 0.05, rotate: 0.1, scale: 0.001 },
           true,
           scaleBounds,
+          rotationBounds,
         ),
       );
     }
@@ -1373,14 +1502,56 @@ function placePart(
     );
   }
   if (best.residual > maxResidual) {
+    // ⭐ The wall the answer stopped against, named in the refusal that reports
+    // it (issue #719). A refusal that states only the residual and the threshold
+    // sends an author to the one remedy that cannot work — every part of a frame
+    // rendered below the scale floor came back refused at the floor, and the
+    // window that could not reach the truth was a line further up the report
+    // nobody was told to read.
+    //
+    // ⚠️ On a refusal and on nothing else. An accepted placement at a wall is an
+    // author who chose the window to bracket the answer, which is the flag
+    // working; saying "the truth may lie outside" over every one of those is how
+    // a warning stops being read. And a window with no interior — `min === max`
+    // — has no wall to be at, so it gets no sentence: being at the only value
+    // there is says nothing about where the truth is.
+    const edges: string[] = [];
+    if (scaleBounds.max > scaleBounds.min) {
+      const window = `${scaleBounds.min},${scaleBounds.max}`;
+      if (best.scale <= scaleBounds.min * (1 + 1e-9)) {
+        edges.push(windowEdgeNote('scale', 'floor', best.scale.toFixed(3), window));
+      } else if (best.scale >= scaleBounds.max * (1 - 1e-9)) {
+        edges.push(windowEdgeNote('scale', 'ceiling', best.scale.toFixed(3), window));
+      }
+    }
+    if (!rotationBounds.wraps && rotationBounds.max > rotationBounds.min) {
+      const window = `${rotationBounds.min},${rotationBounds.max}`;
+      const said = `${best.rotationDeg.toFixed(1)}°`;
+      // Compared through `normaliseDegrees` because the reported angle is
+      // normalised into (-180, 180] and a window need not be: `--rotation
+      // 170,190` has a ceiling the report spells −170°.
+      if (Math.abs(normaliseDegrees(best.rotationDeg - rotationBounds.min)) <= 1e-6) {
+        edges.push(windowEdgeNote('rotation', 'floor', said, window));
+      } else if (Math.abs(normaliseDegrees(best.rotationDeg - rotationBounds.max)) <= 1e-6) {
+        edges.push(windowEdgeNote('rotation', 'ceiling', said, window));
+      }
+    }
     base.refusal = {
       reason: 'no-match',
-      detail: `${name}: the best placement found has residual ${best.residual.toFixed(4)}, above --max-residual ${maxResidual}`,
+      detail:
+        `${name}: the best placement found has residual ${best.residual.toFixed(4)}, above --max-residual ${maxResidual}` +
+        (edges.length === 0 ? '' : `; ${edges.join('; ')}`),
     };
     base.notes.push(
       `${name} matches nowhere in this frame well enough to report. The best placement found is still in ` +
         '`placement` — a refusal names why not to trust it, it does not hide it.',
     );
+    if (edges.length > 0) {
+      base.notes.push(
+        `${name}'s best placement sits on a wall of the search window, so the window is the first thing to move: ` +
+          `${edges.join('; ')}.`,
+      );
+    }
   }
   if (best.unexplained > 0.25 && best.residual <= maxResidual) {
     base.notes.push(
@@ -1419,7 +1590,10 @@ export function poseLines(report: PoseReport): string[] {
     `  ..    ground  ${bgText}`,
     `  ..    parts   ${report.images}  (${report.parts.length} png)`,
     `  ..    search  scale ${report.search.scale.min}–${report.search.scale.max} in ${report.search.scale.steps} step(s) · ` +
-      `rotation ${report.search.rotation.minDeg}°–${report.search.rotation.maxDeg}° step ${report.search.rotation.stepDeg}° · ` +
+      // The step is the ladder's own rather than the constant it was capped at.
+      // Printing the constant here is what issue #719 was: a line that said
+      // `step 15°` over a window ten degrees wide, which no run had ever walked.
+      `${searchRotationClause(report.search.rotation)} · ` +
       `refuse above residual ${report.search.maxResidual}`,
   ];
   const width = Math.max(8, ...report.parts.map((p) => p.part.length));