spine-rigc 0.8.0 → 0.9.0

package/docs/AUTHORING.md

@@ -450,6 +450,10 @@ skin's slot key can cost you a slot quietly, so check `explain`'s slot table.
 uses a named skin — all twelve official example skeletons have exactly one skin,
 called `default`.)
 
+A skin can also say which bones and constraints it **switches on**, and that needs
+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.
+
 **Region attachment** ([Spine: region attachments](http://esotericsoftware.com/spine-regions)),
 the default `type`:
 
@@ -515,10 +519,93 @@ is weighted; a generated mesh binds only bones that move it) do not apply to one
 #44; before it was fixed, `A21` reported 40 failures on a correct 40-vertex editor
 mesh because an absent `meshKinds` entry read as `ring`.
 
-The two generators are `ring` and `ribbon` (see [`src/mesh.ts`](../src/mesh.ts));
-they encode a deformation model rather than a table of numbers, which is why they
-are code invoked by data. A generator is for a skeleton with **no** manifest; a cut
-that has one invokes the same builders through the manifest's `mesh` block.
+The generators are `ring`, `ribbon` and `contour` (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. A generator
+is for a skeleton with **no** manifest; a cut that has one invokes the same
+builders through the manifest's `mesh` block.
+
+⭐ **The no-manifest path centres the part window on its own slot bone.** There is
+no crop to flip against, so `size` (or, for a contour, the PNG's own size) is
+placed with its centre on the bone the slot names — which is also exactly where a
+plain region attachment with no `x`/`y` would have drawn it. Measured on a ring, a
+ribbon and a moved bone by `CT05` in the selftest (issue #1).
+
+#### `contour` — the mesh is the art's own silhouette
+
+**When you need one:** the part's outline is the interesting thing and a
+rectangle of region is the wrong shape — a leaf, a cape, a splash, anything whose
+quad is mostly transparent pixels the renderer still blends. Or you want real
+vertices to push with a `deform` timeline (§4.11) at the places the silhouette
+actually is, instead of at four corners.
+
+It takes **no geometry and no size**: the shape is traced off the attachment's own
+`image`, so there is no number here that can disagree with the pixels.
+
+```json
+"cape": {
+  "cape": {
+    "type": "mesh",
+    "image": "cape.png",
+    "generator": { "kind": "contour", "tolerance": 1.5, "margin": 2, "maxVertices": 48 }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `tolerance` | **required.** Douglas-Peucker tolerance, in part pixels. Bigger spends fewer vertices and cuts more corners |
+| `margin` | how far the outline is pushed out past the traced silhouette, in pixels. Default `1` |
+| `maxVertices` | refuse rather than emit more outline vertices than this. Default `64` |
+| `alpha` | the alpha at or above which a pixel counts as art, `1`..`255`. Default `1` — any pixel that is not fully transparent |
+
+The numbers above are invented, and the pair that matters is `tolerance` and
+`margin`: simplification may bite **`tolerance` pixels into the art**, and the
+margin is what pays that back, so **`margin >= tolerance`** is the setting that
+survives the coverage check below. `alpha` is the lever for art with a long soft
+feather — raise it and the outline hugs the solid core instead of the last
+almost-invisible pixel.
+
+**What it does, in order:** trace the alpha mask on the pixel-corner lattice (so
+the raw outline encloses every art pixel *whole*), simplify it, push it out by
+`margin`, clamp it to the part window, ear-clip it, and then **measure the result
+against the mask it came from**. `build` and `explain` print what it measured:
+
+```
+  MESH  cape         contour  15 vertices / 13 triangles  (budget 80)  bones=[cape]  attachments=[cape]  covers 100.00% of the art, reaching 3.16px past it
+```
+
+🚨 **It is geometry, not a deformation model.** Every vertex is pinned to the slot
+bone at weight 1, so a contour mesh at rest draws what the region drew and **no
+bone can bend it**. What you gain over a region is a real outline, real triangles
+and a `hull` other tools can read; what you do not gain is bone-driven motion —
+that is what `ring` is for, or authored `weights` (§3.4) if you have an editor's
+auto-weighting to transcribe. `A21_MESH_RIM_PINNED` therefore reads over the whole
+mesh rather than a rim prefix, and `A28_RIBBON_ROWS_SHARE_WEIGHTS` **SKIPs** with
+"a contour is one silhouette loop" as the reason.
+
+**Stated limits, each a named refusal rather than a mesh that loads wrong:**
+
+| The art | What you get |
+| --- | --- |
+| every pixel opaque | `every pixel of the 96x64 part reaches alpha 1, so its silhouette IS the part window and a contour mesh of it is a region attachment with extra vertices` |
+| two or more islands | `the art is 2 separate islands and one outline can only enclose the largest (529 of 989 px, 53.49%)` — one outline encloses one region; give each island its own slot |
+| a **hole** (a donut) | **accepted, and the hole is inside the mesh.** Ear clipping has no bridging step, so the outline is the art's *outer* boundary; those pixels draw nothing (their alpha is still 0) and the extra triangles are the whole cost. `explain` reports the coverage either way |
+| a **diagonal pinch** — two parts of the art meeting at one pixel corner | `the alpha silhouette pinches to a single point at pixel corner (2,2) … one outline cannot pass through one point twice` |
+| a neck narrower than `margin` | `the outline crosses itself: edge 0 meets edge 3 after a margin of 3px was pushed out of a silhouette narrower than that` |
+| more outline than `maxVertices` | `the silhouette simplified to 15 vertices at tolerance 1.5, past the 4 this mesh allows` — refused, never silently decimated |
+| a `margin` too small for the `tolerance` | `the mesh covers 91.81% of the art (2936 of 3198 px), under the 99.5% a contour mesh guarantees` |
+
+That last one is the guarantee: **the emitted triangles cover at least 99.5% of
+the art**, measured by rasterising them back over the mask, and a build that would
+clip the art is refused rather than shipped. It is not 100% because a
+simplification that could never cut a corner would not be one — the figure a
+given part actually measures is in the `build`/`explain` line above, and the
+selftest's fixture measures 100.000%.
+
+Self-intersection is refused; **holes are not cut out**; and nothing here does
+interior/Steiner points, so a contour mesh bends only where its outline has
+vertices.
 
 **Bounding box** ([Spine: bounding boxes](http://esotericsoftware.com/spine-bounding-boxes))
 and **clipping** ([Spine: clipping](http://esotericsoftware.com/spine-clipping))
@@ -573,16 +660,122 @@ everything after this one", and is left alone.
 was supposed to hide something would not. It is valid Spine and the default
 `--profile spine` accepts it; the refusal is policy, not validity.
 
+**Path attachment** ([Spine: paths](http://esotericsoftware.com/spine-paths)) — a
+composite cubic Bezier, and the only attachment whose purpose is to be *followed*.
+
+**When you need one:** a path constraint has nowhere to aim without it (§3.5). The
+curve is not drawn — no runtime renders a path — and it deforms with its slot's
+bone like any other vertex attachment, so an animated path is a moving track.
+
+```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] } }
+```
+
+That is nine invented points forming a straight line: knots at x = 0, 90 and 180
+with their handles evenly spaced between them, which is the simplest path there is
+and the one worth reading twice.
+
+| Field | Meaning |
+| --- | --- |
+| `vertexCount` | **required**, and a multiple of 3 — see below |
+| `vertices` / `weights` | the same two encodings a mesh's geometry uses, with the same by-name default |
+| `closed` | default false. When true the last knot joins the first |
+| `constantSpeed` | default **true**: the runtime re-measures the curve every frame so travel along it is even. `false` makes it trust the emitted `lengths` instead — cheaper, and exact only while the path holds its setup shape |
+| `color` | `rrggbbaa`; the colour the editor draws the curve in |
+
+🚨 **`vertexCount` counts knots AND handles, and the arithmetic is not the one you
+would guess.** The vertices are walked in groups of three, and an **open** path
+drops the first and last point — those two are the outer control handles of the end
+knots, and no curve uses them. So:
+
+- an open path of K curves has `vertexCount = 3(K + 1)`, minimum **6** (one curve);
+- a closed one has `vertexCount = 3K`, minimum **3**, because the chain wraps.
+
+A count that is not a multiple of 3 does not throw anywhere:
+`Utils.newArray(vertexCount / 3, 0)` takes a fractional size happily, the groups of
+six then straddle the knots, and bones slide along a curve nobody drew. rigc refuses
+it, and `A33_VERTEX_ATTACHMENT_GEOMETRY` refuses it again on the artifact.
+
+⚠️ **`lengths` is not yours to write.** The emitted file carries one — the
+cumulative arc length at the end of each curve, in world units, in the setup pose —
+and rigc **measures** it off the geometry above, exactly as it measures a region's
+`width`/`height` off its PNG (R5). Writing one is a `CompileError`: it is a second
+copy of a number the vertices already determine, a copy that disagrees is only
+visible under `constantSpeed: false`, and there it silently rescales the whole
+traversal. `explain` prints the measurement, so `position: 0.25` on a curve that
+reports `180 long` is a bone at 45 units along it.
+
+#### 3.4.1 A skin that switches bones and constraints on
+
+**When you need one:** a skin that is more than a change of art — a variant with an
+extra bone (a pauldron, a tail, a hat with its own physics), or one where a
+constraint should only run while that skin is applied.
+
+A skin entry has two spellings. The short one is `slotName → placeholder →
+attachment`, above. The long one puts that table under `attachments` and adds the
+lists:
+
+```json
+"skins": {
+  "default": {
+    "attachments": {
+      "torso": { "torso": { "image": "torso.png" } }
+    }
+  },
+  "armoured": {
+    "attachments": {
+      "torso": { "torso_armoured": { "image": "torso_armoured.png" } }
+    },
+    "bones": ["pauldron"],
+    "ik": ["pauldron-ik"]
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `attachments` | the short form's whole table, moved one level down |
+| `bones` | bone names this skin activates |
+| `ik`, `transform`, `path`, `physics`, `slider` | constraint names this skin activates, **still split per type** even though the top-level `constraints` array is unified |
+
+⭐ **The list is half a switch, and the other half is `skin: true` on the member.**
+A bone's `skin: true` and a constraint's `skin: true` set `skinRequired`, and
+`Skeleton.updateCache` starts every `skinRequired` object **inactive**, turning it
+on only for the skin that names it (a listed bone activates its whole ancestor
+chain with it). So the two fields only mean anything together, and either one alone
+is dead data in silence:
+
+- listed **without** `skin: true` — the bone poses under every skin, the constraint
+  runs under every skin, and the list changes nothing at all;
+- `skin: true` **listed nowhere** — the bone never poses and the constraint never
+  runs, under any skin there is.
+
+rigc refuses both halves by name, and `A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED` checks
+the artifact for them. A bone or constraint belongs to **one** skin; two skins
+naming the same one is also refused.
+
+⚠️ **The two spellings are told apart by these seven keys** — `attachments`,
+`bones`, `ik`, `transform`, `path`, `physics`, `slider` — so a skin that uses any of
+them is the long form and every one of its keys must be one of them. A slot left
+beside them is refused rather than ignored (an ignored slot is an attachment that
+vanishes), and a rig with a *slot* of one of those names is refused too, because
+there the two forms are genuinely ambiguous. Rename the slot.
+
 ### 3.5 `constraints` — 4.3's single typed array
 
 Spine 4.3 folds every constraint into one `constraints` array with a `type`
 discriminator. The 4.1/4.2 shape (top-level `ik`/`transform`/`path`/`physics`
 arrays) still loads clean and **the constraints simply vanish** — that is `A01`.
 
-rigc emits `ik` ([IK constraints](http://esotericsoftware.com/spine-ik-constraints)),
-`transform` ([transform constraints](http://esotericsoftware.com/spine-transform-constraints))
-and `physics` ([physics constraints](http://esotericsoftware.com/spine-physics-constraints)).
-Field lists are in [`src/rig.ts`](../src/rig.ts); three traps worth carrying here:
+rigc emits all five: `ik`
+([IK constraints](http://esotericsoftware.com/spine-ik-constraints)), `transform`
+([transform constraints](http://esotericsoftware.com/spine-transform-constraints)),
+`path` ([path constraints](http://esotericsoftware.com/spine-path-constraints)),
+`physics` ([physics constraints](http://esotericsoftware.com/spine-physics-constraints))
+and `slider`. Field lists are in [`src/rig.ts`](../src/rig.ts); three traps worth
+carrying here:
 
 - A transform constraint's `properties` names come from a fixed six — `rotate`,
   `x`, `y`, `scaleX`, `scaleY`, `shearY`. rigc refuses anything else by name; in
@@ -593,6 +786,106 @@ Field lists are in [`src/rig.ts`](../src/rig.ts); three traps worth carrying her
   them parses cleanly and does nothing at all. rigc refuses it up front, and `A23`
   catches it from the other side.
 
+Every constraint may also carry `skin: true`, which makes it run only under the skin
+that lists it — see §3.4.1, and note that the flag alone does nothing.
+
+#### 3.5.1 `path` — bones that travel along a curve
+
+**When you need one:** anything that moves *along* something rather than around a
+joint — a cart on a track, a fish in a current, a chain of links wrapping a pulley.
+One `position` key moves the whole train, and the shape of the motion lives in the
+curve instead of in the keys.
+
+```json
+{ "name": "ride", "type": "path", "bones": ["cart"], "slot": "track",
+  "positionMode": "percent", "spacingMode": "percent", "rotateMode": "tangent",
+  "position": 0.25 }
+```
+
+| Field | Meaning |
+| --- | --- |
+| `bones` | at least one, in the order they ride the path |
+| `slot` | **required.** The slot whose path attachment they follow (§3.4) |
+| `positionMode` | default `"Percent"`: `position` is a fraction of the arc length. `"Fixed"` makes it world units |
+| `spacingMode` | default `"Length"` — `Length`, `Fixed`, `Percent` or `Proportional` |
+| `rotateMode` | default `"Tangent"`: each bone turns to the curve's tangent where it sits. `"Chain"`, `"ChainScale"` |
+| `rotation` | default 0. Degrees added after the path's own rotation |
+| `position` | default 0. Where the first bone sits |
+| `spacing` | default 0. The gap between bones, in the unit `spacingMode` chose |
+| `mixRotate`, `mixX` | default 1. `mixY` defaults to the same entry's `mixX` |
+
+With the nine-point path of §3.4 — 180 units long — that constraint puts `cart` at
+exactly `x = 45`, and a `position` timeline walking 0 → 0.5 walks it 0 → 90.
+
+🚨 **The slot has to be able to show a path.** `PathConstraint.update` opens with
+`if (!(attachment instanceof PathAttachment)) return`, so a constraint aimed at a
+slot that never shows one loads perfectly, reports every mix it was given, and moves
+nothing at all — there is no error anywhere in that. rigc refuses a slot with no
+path attachment in any skin, and `A36_PATH_CONSTRAINT_EFFECTIVE` refuses it again on
+the artifact.
+
+⚠️ **The three mode names are checked, and only the first letter's case is free.**
+The parser resolves them with `type[name[0].toUpperCase() + name.slice(1)]`, so
+`"percent"` and `"Percent"` both work and `"PERCENT"` resolves to **`undefined`** —
+which is then assigned without a word, and the constraint runs some *other* mode. An
+unresolved `spacingMode` fails the `=== Length` test and spaces bones as though
+`Fixed` had been asked for; an unresolved `rotateMode` is neither `Tangent` nor
+`ChainScale`, so bones follow the curve and never turn along it.
+
+#### 3.5.2 `slider` — a value that drives an animation
+
+**When you need one:** a pose that has to be driven by a value instead of by time —
+a dial that opens a door, a blend shape on a face, a suspension that compresses as
+the wheel rises. A slider is the only constraint that applies an **animation**: the
+animation is under its control while it is on, and `mix` is how much of it lands.
+
+It comes in two shapes, and `bone` is the switch.
+
+**Property-driven** — a bone's transform property maps to a time:
+
+```json
+{ "name": "knob", "type": "slider", "animation": "gate-swing",
+  "bone": "dial", "property": "rotate", "from": 0, "to": 0, "scale": 0.011111 }
+```
+
+`time = to + (value - from) * scale`, so at `scale: 0.011111` (≈ 1/90) a dial turned
+90° applies `gate-swing` at one second — which is the whole mechanism: turn the
+dial, the gate swings.
+
+**Time-driven** — no bone, and the time is the slider's own pose value, keyed by an
+`animations.<a>.slider.<name>.time` timeline (§4.12):
+
+```json
+{ "name": "reveal", "type": "slider", "animation": "curtain", "time": 0 }
+```
+
+| Field | Meaning |
+| --- | --- |
+| `animation` | **required.** An animation the **motion spec** declares |
+| `mix` | default 1. The slider's authority over what its animation keys |
+| `additive` | default false. Add to the current pose instead of overwriting it |
+| `loop` | default false. Repeat past the duration instead of holding the last frame |
+| `bone` | the driving bone. Its presence switches the model |
+| `property` | required with a bone: one of `rotate`, `x`, `y`, `scaleX`, `scaleY`, `shearY` |
+| `from`, `to`, `scale` | the mapping above. Defaults 0, 0, 1 |
+| `max` | default 0. Nonessential: the top of the editor's slider range |
+| `local` | default false. Read the bone's local transform instead of its world one |
+| `time` | the bone-less form's setup time |
+
+⭐ **`animation` is the one field in a rig spec that points at the motion spec.** It
+is the mirror of `events`, where the rig declares a name the motion spec fires. The
+parser resolves it in a **second pass** over the constraints array, after the
+animations are read, and a miss throws `Slider animation not found`; rigc refuses it
+where the message can name both files.
+
+⚠️ **The fields of the model you did not choose are refused, not ignored.** The
+parser reads `time` only in the bone-less branch and `property`/`from`/`to`/`scale`/
+`max`/`local` only in the other, so the losing half would be data no runtime ever
+looks at. Two more shapes `A37_SLIDER_CONSTRAINT_EFFECTIVE` catches from the
+artifact side: an animation with no timelines (the slider runs and the skeleton
+never changes), and `loop: true` on a zero-length animation — looping computes
+`duration + (time % duration)`, so the animation is applied at **NaN**.
+
 ### 3.6 `events` — names the animation can fire
 
 **When you need one:** something outside the skeleton has to happen on a
@@ -678,8 +971,14 @@ member order.
 
 ### 4.4 `tracks` — one target, one property
 
-A track names **exactly one** of `bone`, `slot`, `group`, `physics`. Two tracks on
-the same `target.property` is a compile error: merge them.
+A track names **exactly one** of `bone`, `slot`, `group`, `physics`, `path`,
+`slider`. Two tracks on the same `target.property` is a compile error: merge them.
+
+⭐ **The target field picks the family, not the property.** All three constraint
+families have a timeline called `mix`, so `{ "physics": "hair", "property": "mix" }`
+and `{ "path": "ride", "property": "mix" }` are different timelines with the same
+property name — which is why the constraint's name goes in a field named after its
+type rather than in a shared `constraint` key.
 
 Three families are **not** tracks and sit beside `tracks` instead — `ik` (§4.9),
 `transform` (§4.10) and `deform` (§4.11). The reason is the key rather than the
@@ -696,6 +995,10 @@ a deform). Folding them in would make `v` mean four different things depending o
 | `slot` | `attachment` | the attachment name, or `null` for "show nothing" |
 | `physics` | `mix` | `[mix]`, 0..1 — the constraint's authority |
 | `physics` | `reset` | `null` — the key *is* the event |
+| `path` | `position`, `spacing` | `[value]` — see §4.12 |
+| `path` | `mix` | `[mixRotate, mixX, mixY]` — one timeline, three channels |
+| `slider` | `time` | `[seconds]` — where in its animation the slider sits |
+| `slider` | `mix` | `[mix]` — the slider's authority |
 
 Translate values are **relative to the bone's setup position**; scale values are
 multipliers where `1` is setup; rotation is in degrees.
@@ -1108,6 +1411,50 @@ an encoding.
 
 ---
 
+### 4.12 `path` and `slider` timelines — tracks, not their own groups
+
+Unlike `ik` and `transform`, these two are ordinary `tracks` entries: the format
+writes them as `animations.<a>.path.<constraint>.<timeline>` — a constraint name,
+then a timeline name under it — which is the same shape as `physics`, and a key that
+carries one `v` fits it.
+
+```json
+"tracks": [
+  { "path": "ride", "property": "position", "keys": [
+      { "t": 0, "v": [0], "ease": "smooth" }, { "t": 2, "v": [1] } ] },
+  { "path": "ride", "property": "mix", "keys": [
+      { "t": 0, "v": [0, 0, 0] }, { "t": 0.4, "v": [1, 1, 1] } ] },
+  { "slider": "knob", "property": "mix", "keys": [
+      { "t": 0, "v": [0] }, { "t": 0.5, "v": [1] } ] }
+]
+```
+
+Those numbers are invented, and the first track is the one to read: `position` 0 → 1
+under `positionMode: "percent"` walks the constrained bones from one end of the
+curve to the other over two seconds. On the 180-long path of §3.4 the bone passes
+through exactly `x = 90` at the halfway point of a linear key pair, which is how you
+tell a working traversal from a plausible one.
+
+| Group | `property` | Channels | Note |
+| --- | --- | --- | --- |
+| `path` | `position` | 1 | a fraction of the arc length, or world units under `positionMode: "fixed"` |
+| `path` | `spacing` | 1 | in the unit `spacingMode` chose |
+| `path` | `mix` | **3** | `[mixRotate, mixX, mixY]` in one key, so a raw `curve` is 12 numbers |
+| `slider` | `time` | 1 | the bone-less slider's own time. A slider WITH a bone takes its time from the bone and this timeline is not what drives it |
+| `slider` | `mix` | 1 | mix 0 makes `update()` return, so this is the on/off switch |
+
+⚠️ **A `path.mix` key states all three mixes.** In the file `mixY` defaults to the
+same key's `mixX`, and every field has a per-key default rather than carrying the
+previous key's value forward — the same trap as §4.9's. rigc writes all three out,
+so `v` is three numbers and not one.
+
+⚠️ **A muted constraint with no timeline is a finding, not an idiom.** Turning a
+constraint on from an animation is the idiom (§4.10), so `A36`/`A37` only object to
+all-zero mixes when **no** animation keys that constraint's `mix`. If you mute one
+at setup, key it somewhere.
+
+---
+
 ## 5. Reading a failure
 
 Failures arrive in two layers, and they read differently.
@@ -1152,6 +1499,19 @@ the frequent ones, verbatim:
 | `deform … (t=…): offset 3 is odd` | §4.11 — the deform array is `x, y` pairs, so a run starts on an even index |
 | `deform …: "fromVertex" counts VERTICES, and this attachment is weighted … vertex 2 has 2 of them` | §4.11 — key the control bone, or write bind-space pairs and start with `offset` |
 | `deform …: slot "X" in skin "default" has no attachment "Y" (it has: …)` | §4.11 — fix the placeholder name |
+| `vertexCount is N, which is not a multiple of 3` | §3.4 — a path's vertices are knots and handles read in groups of three: `3(K + 1)` open, `3K` closed |
+| `vertexCount is N and an open path needs at least 6` | §3.4 — an open path drops its first and last point, so it needs six for one curve |
+| `"lengths" is not authored — rigc measures the setup arc length of each curve` | §3.4 — delete the array; it is a measurement of the vertices above it |
+| `rig constraint "X": slot "Y" has no path attachment in any skin` | §3.5.1 — give that slot a `"type": "path"` attachment, or aim the constraint at the slot that has one |
+| `rig constraint "X": rotateMode is "CHAINSCALE"; known: Tangent, Chain, ChainScale` | §3.5.1 — only the first letter's case is free; anything else resolves to `undefined` in the parser |
+| `rig constraint "X": applies animation "Y", which the motion spec does not declare (it declares: …)` | §3.5.2 — fix the slider's `animation`, or add it to the motion spec |
+| `rig constraint "X": declares both a "bone" and "time"` | §3.5.2 — `bone` picks the model and `time` belongs to the other one |
+| `rig constraint "X": declares "property" but no "bone"` | §3.5.2 — name the driving bone, or key `slider.<name>.time` instead |
+| `skin "S" activates bone "B", but that bone does not declare \`"skin": true\`` | §3.4.1 — the list and the flag are one switch; add the flag or drop the list |
+| `bone "B" declares \`"skin": true\` but no skin activates it` | §3.4.1 — the other half: list it in the skin it belongs to, or drop the flag |
+| `skin "S": uses the long form … and also has a key "X"` | §3.4.1 — move the slot inside `attachments` |
+| `animation "A" keys "X" as a path constraint, but the rig declares it as a "slider"` | §4.12 — a timeline group resolves by name AND type; use the field named after the constraint's own type |
+| `animation "A": "position" is a path constraint timeline, and this track names no constraint` | §4.12 — put the name in `"path"` |
 
 ### 5.2 Assertions — the gate
 
@@ -1199,21 +1559,24 @@ The report prints one line per assertion:
 | `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 |
 | `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 |
-| `A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, or a ribbon's entry row, is not pinned to its anchor bone at weight 1 |
+| `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 |
 | `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 |
 | `A24_AXIS_SPACE_STROKE` | archetype | a bone under the rig's `axisBone` was keyed with a screen-space Y component, or the axis bone itself was keyed |
 | `A25_DETACHED_BONE_PARENTAGE` | archetype | a bone the rig declares `detached` is a descendant of the bone it must never hang under |
 | `A26_SLOT_DRAW_ORDER` | archetype | the emitted slots are not a subsequence of the rig's slot table — a slot is out of order, or is not in the table at all |
 | `A27_REGION_NAME_MATCHES_PAGE_FILENAME` | renderer | a single-region page whose region name is not the PNG's basename |
-| `A28_RIBBON_ROWS_SHARE_WEIGHTS` | archetype | the two vertices of a ribbon row carry different weights, so the strip would change width |
+| `A28_RIBBON_ROWS_SHARE_WEIGHTS` | archetype | the two vertices of a ribbon row carry different weights, so the strip would change width. **SKIPs** on authored geometry and on a contour mesh — neither has rows rigc paired |
 | `A29_STROKE_WITHIN_CONTACT_DEPTH` | archetype | the animation drives deeper than the manifest's measured contact depth |
 | `A30_STROKE_WITHIN_CAP_CONTAINMENT` | archetype | the animation drives past the measured containment ceiling, or scales a bone in the axis subtree |
 | `A31_DRAW_ORDER_OFFSETS_RESOLVE` | both | a draw-order key names a slot the skeleton does not have, offsets one slot twice, puts a slot outside the slots array, or lists its offsets out of slot order (§4.7). The only assertion that runs **before** `A00` — the last of those shapes makes the loader spin rather than return, so the round trip is refused instead of attempted |
 | `A32_EVENT_KEYS_RESOLVE` | both | an event key fires a name the skeleton's `events` block does not declare, sits earlier in time than the key before it, or sets `volume`/`balance` on an event with no `audio` (§4.8). **SKIP** when no animation carries an event timeline |
-| `A33_VERTEX_ATTACHMENT_GEOMETRY` | both | a bounding box or clipping polygon whose `vertexCount` is missing or disagrees with its vertex array, a weighted run that decodes to the wrong number of vertices or an out-of-range bone index, or a clipping `end` naming a slot the skeleton does not have (§3.4). **SKIP** when the skeleton carries neither type |
-| `A34_CONSTRAINT_TIMELINE_TARGETS` | both | an `ik` or `transform` timeline names a constraint the skeleton does not declare, names one of the other type, or carries no keys at all (§4.9, §4.10). The last is silent: the parser reads key 0, finds nothing, and skips the timeline. **SKIP** when no animation carries one |
+| `A33_VERTEX_ATTACHMENT_GEOMETRY` | both | a bounding box, clipping polygon or path whose `vertexCount` is missing or disagrees with its vertex array, a weighted run that decodes to the wrong number of vertices or an out-of-range bone index, a clipping `end` naming a slot the skeleton does not have, a path whose vertex count is not a multiple of 3, or a path `lengths` array that does not strictly increase (§3.4). **SKIP** when the skeleton carries none of the three |
+| `A34_CONSTRAINT_TIMELINE_TARGETS` | both | an `ik`, `transform`, `path` or `slider` timeline names a constraint the skeleton does not declare, names one of another type, or carries no keys at all (§4.9, §4.10, §4.12). The last is silent: the parser reads key 0, finds nothing, and skips the timeline. **SKIP** when no animation carries one |
 | `A35_DEFORM_KEYS_FIT_THE_ATTACHMENT` | both | a deform key's run runs past the end of the attachment's deform array, starts on an odd index, holds an odd count of numbers or a non-finite one, or names a skin/slot/attachment triple that does not resolve (§4.11). The overrun is the quiet one — the parser copies into a `Float32Array` and drops the tail. **SKIP** when no animation carries a deform timeline |
+| `A36_PATH_CONSTRAINT_EFFECTIVE` | both | a path constraint whose slot has no path attachment in any skin, one that constrains no bone, or one whose three mixes are all 0 at setup with no animation keying its `mix` (§3.5.1). The first is the quiet one: `update()` returns on its first line and the constraint reports mixes it never applies. **SKIP** when the skeleton declares no path constraint |
+| `A37_SLIDER_CONSTRAINT_EFFECTIVE` | both | a slider whose animation carries no timeline, one that loops a zero-length animation (the applied time is NaN), one driving off a bone at `scale: 0`, or one muted at setup with no animation keying its `mix` (§3.5.2). **SKIP** when the skeleton declares no slider |
+| `A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED` | both | a bone or constraint a skin activates that is not `skinRequired` (the list changes nothing), or one that is `skinRequired` and no skin activates (it is never active). Two keys in two places, and only together do they mean "this belongs to that skin" (§3.4.1). **SKIP** when no skin activates anything and nothing is `skinRequired` |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.
@@ -1228,15 +1591,16 @@ worse: an unknown attachment `type` returns `null` and the attachment disappears
 and a constraint entry with an unrecognised `type` matches no case and vanishes.
 
 Each is deferred for a stated reason, and the reason is the same one in every row:
-**not one of these types appears anywhere in the benchmark corpus** (SPEC_COVERAGE
-parts 3-1 and 4-2), so none of them is on the ladder's critical path. The message
+**neither of these types appears anywhere in the benchmark corpus** (SPEC_COVERAGE
+parts 3-1 and 4-2), so neither is on the ladder's critical path. The message
 says so, because a deferral without its reason is a wall rather than a work item.
 
 | You wrote | You get |
 | --- | --- |
-| attachment `type` of `point`, `path`, `linkedmesh` | `attachment type "X" is in the Spine 4.3 format and rigc does not emit it yet. Implemented: region, mesh, boundingbox, clipping. point, path and linkedmesh are deliberately deferred: not one of them appears anywhere in the benchmark corpus …` |
-| constraint `type` of `path` or `slider` | `constraint type "X" … Implemented: ik, transform, physics.` |
-| mesh `generator.kind` of `contour` | `the "contour" generator would triangulate a part's own alpha mask, and src/mesh.ts has no triangulator` |
+| attachment `type` of `point` or `linkedmesh` | `attachment type "X" is in the Spine 4.3 format and rigc does not emit it yet. Implemented: region, mesh, boundingbox, clipping, path. point and linkedmesh are deliberately deferred: neither appears anywhere in the benchmark corpus …` |
+| constraint `type` of anything else | `constraint type "X" is not one Spine 4.3 knows. The five are: ik, transform, path, physics, slider.` — all five are emitted, so this is a typo, and a typo is what the parser drops in silence |
+| a path attachment's `lengths` | `"lengths" is not authored — rigc measures the setup arc length of each curve off the geometry` (§3.4). Not a deferral: a second copy of a number the vertices already fix |
+| a `deform` timeline on a path attachment | `a path attachment does have a vertex array, and rigc does not key it yet` — the format allows it and an animated track is a real idiom, but a deformed path invalidates the `lengths` a `constantSpeed: false` traversal reads. Move the curve by posing the bones its vertices are bound to |
 
 Two more limits that are not errors but will shape what you can attempt:
 
@@ -1244,13 +1608,12 @@ Two more limits that are not errors but will shape what you can attempt:
   region covers its whole page, `pma: false`. To reproduce a skeleton whose art
   ships as a packed atlas you either supply loose PNGs and let rigc build its own
   atlas, or hand the packed atlas to `validate`/`bench` alongside the candidate.
-- **`sequence` timelines, `drawOrderFolder` and `slider` / `path` constraint
-  timelines** are walked by the validator (so `A05` checks their curves and `diff`
-  counts their keys) and cannot be *written*: there is no motion-spec property for
-  any of them. The two constraint groups are blocked one level down — rigc emits no
-  `path` or `slider` constraint to key. Everything a motion spec **can** key is
-  §4.4's track table plus the five families that sit beside `tracks`: `drawOrder`
-  (§4.7), `events` (§4.8), `ik` (§4.9), `transform` (§4.10) and `deform` (§4.11).
+- **`sequence` timelines and `drawOrderFolder`** are walked by the validator (so
+  `A05` checks their curves and `diff` counts their keys) and cannot be *written*:
+  there is no motion-spec property for either. Everything a motion spec **can** key
+  is §4.4's track table — which now includes the `path` and `slider` groups (§4.12)
+  — plus the five families that sit beside `tracks`: `drawOrder` (§4.7), `events`
+  (§4.8), `ik` (§4.9), `transform` (§4.10) and `deform` (§4.11).
 
 ---
 
@@ -1742,7 +2105,10 @@ which checks every animation of that shot, framed per set — see the scope note
 below) or **one animation directory** inside it. Everything else is optional:
 `--atlas` when the candidate's atlas is not beside its skeleton, `--as <name>` when
 your animation is called something the frame directory is not, `--framing shared`
-to fit one framing across every set instead of one each, `--all-frames` to list
+to fit one framing across every set instead of one each,
+`--texture-from <atlas>` to attribute how much of the MAE is texture resampling
+rather than the rig (**§9.2**'s atlas floor — and note that it is *not* `--atlas`,
+which re-seats your geometry on that atlas's packing), `--all-frames` to list
 every frame instead of the worst by MAE, `--json <out>` for the whole per-frame,
 per-slot report.
 
@@ -2096,11 +2462,14 @@ of them.
              ⤷ fit x0.999256  offset +0.05, -0.02 px   rms 0.42 px over 344 edge(s)   union residual -0.27 x +0.17 px   aspect -0.30%  (derived, 4 pass(es), settled)
              ⭐ MAE-refined by -1, +1 px: 54.31 → 48.47 over the reference's own pixels (10.7% of the figure). …
   in units   candidate 1995.3 x 809.7   reference 1995.3 x 809.9   x0.9999
+  declared   frames.json's own box: REFUSED, coordinates — a fit there asks for … px, past the … px the
+             extent-spread tolerance reaches — a different origin or a different unit, over 86 frame(s).
 
   ── heavy — candidate animation "heavy", 12 fps ──
      frames     65 on disk, candidate samples 65, 65 compared
      MAE        mean 23.10  worst 43.36 at f0029   (0..255 over the union alpha; …)
                 ⤷ over the REFERENCE's own drawn pixels, mean 23.90 — the union figure compares two builds …
+                (a ⭐ texture floor line joins these two when --texture-from is given — see below)
      slot drift worst 2.1 px  "pendulum" at f0029
      per-frame 1 of 64 adjacent pair(s) change by a different amount than the reference does; worst
                f0018, yours moved 0 px where the reference moved 374
@@ -2134,6 +2503,11 @@ pass count, then one of
   The fit beside it is what a fit would still ask for, and on a shot whose
   silhouette differs anywhere that is not zero; it is the fit's floor, not your
   keys.
+- `extent-spread` — the frames' own box was kept even though your pixels did *not*
+  land in it to within a pixel, because the correction a fit asks for is small
+  relative to the shot and the fit admits it cannot explain it (see the `declared`
+  line and the ⚖️ below). What is left over is a **silhouette** difference at the
+  extremes and is a finding about your own outline, not about the box.
 - `cycling` — the correction fell into a repeating orbit instead of converging.
   **More passes cannot help**: the fit has no fixed point here. Read the `⚠️` line
   under it, which says whether the two content boxes agree anyway (the fit's own
@@ -2176,6 +2550,11 @@ The lines, in order:
 - `in units` — the same two boxes in world units. The framing absorbs a pure scale
   on purpose, so this is the only place one shows; it compares only if you measured
   the shot in the frames' own units.
+- `declared` — whether `frames.json`'s own box was taken for this set and on which
+  clause, with the correction a fit there asks for and what that fit could not
+  explain. It is printed whether the box was taken or refused, because *"refused,
+  and by this much, on this ground"* is the part an author has to act on. The ⚖️
+  passage below is what the three answers mean.
 
 ⚠️ **The framing is fitted to extent, and extent is not the same as alignment.**
 When your silhouette genuinely differs somewhere — a limb that overreaches, a part
@@ -2234,55 +2613,76 @@ much ink as the reference does gets `⚠️ overdraw` beside those two numbers,
 both pixel counts, because at that point the first figure is cheap for a reason
 that has nothing to do with your keys.
 
-🚨 **Part of your MAE is the texture, not the animation, and nothing in the report
-says so.** The reference frames are rendered through the example's **own packed
-atlas**, and a packed atlas may carry a `scale:` line — the ladder has one at
-`scale: 0.5`, whose 745x212 part is packed at 373x106. rigc has no packer (**§6**), so
-a candidate built from the loose PNGs samples a texture at twice that resolution and
-resamples every edge differently. The pixels are the same shape in the same place; they
-are filtered from a different source, and the difference lands on the outline of every
-part in every frame. It is a constant, it is invisible to `content`, `rms` and the
-`±2 px` refinement — a resampling difference is not an offset — and **no key you write
-can move it**.
-
-⇒ **When the MAE is flat across the whole set and the drift is already at the floor,
-check the atlas before you look for keys.** The example's `.atlas` is an allowed input
-in its own right (`bench/runs/README.md`, *What a run may read*, item 4), and one line
-of it answers the question. To size the floor, re-run `check` once with
-`--atlas <the example's own .atlas>`: same skeleton, same keys, the reference's own
-texture. Measured on rung 3, MAE **6.13 / 6.01** with the candidate's own
-full-resolution atlas against **2.25 / 2.30** with the supplied one — **two thirds of
-the figure was the texture**, and the run that did not know it would have spent its
-whole budget hunting a rig that was already right.
-
-⚠️ Two things about that diagnostic. It is a **diagnostic and not a better number**:
-the artifact `bench` validates ships its own atlas, so the first figure is the one
-that belongs in a run's record and the second is the explanation of where it went.
-And the coarser texture **loses** resolution the finer one has — on the same rung a
-pair the reference moves *one pixel* across stopped being visible at half scale, so
-the diagnostic run reported a frame-change disagreement the graded run does not have.
-Read it for the floor, never as the verdict.
-
-🚨 **And a third, which decides whether the recipe measures anything at all: `--atlas`
-substitutes region *geometry* as well as texture.** The diagnostic's logic is *"same
-skeleton, same keys, the reference's own texture"* — but an atlas entry is not only a
-page and a rectangle. It also carries how the region was packed: **`rotate`**, and the
-trim offsets that say where the opaque part sits inside the original image. Swap the
-atlas and your attachments are re-seated on those, so the quads change too.
-
-⇒ **The recipe measures a floor only when the substitution is *"same quads, coarser
-texture"*.** Where the supplied atlas packs its regions **rotated or trimmed** and your
-attachments were measured off the loose PNGs, it is not — and the tell is unmistakable:
-**the number goes the wrong way.** A texture floor can only *explain* error, so a
-diagnostic that sends the MAE **up** on every set has substituted geometry, not just
-pixels, and the run's own atlas was the more faithful of the two.
-
-⚠️ **Then the honest verdict is *inconclusive*, not *no floor*.** Both readings stay
-open — there may be a texture floor this diagnostic cannot isolate — so record the
-figures, say the substitution changed the quads, and do **not** convert a failed
-diagnostic into a claim about the shot. ⇒ Check the atlas's own entries for `rotate` and
-for trim before you run it; that is one look at a text file, and it tells you in advance
-whether the number you are about to take will mean anything.
+🚨 **Part of your MAE is the texture, not the animation.** The reference frames are
+rendered through the example's **own packed atlas**, and a packed atlas may carry a
+`scale:` line — the ladder has one at `scale: 0.5`, whose 745x212 part is packed at
+373x106. rigc has no packer (**§6**), so a candidate built from the loose PNGs samples
+a texture at twice that resolution and resamples every edge differently. The pixels are
+the same shape in the same place; they are filtered from a different source, and the
+difference lands on the outline of every part in every frame. It is a constant, it is
+invisible to `content`, `rms` and the `±2 px` refinement — a resampling difference is
+not an offset — and **no key you write can move it**.
+
+⇒ **`check` attributes it when you tell it where the frames' own atlas is.** Pass
+`--texture-from <the example's own .atlas>` (its `.atlas` is an allowed input in its
+own right — `bench/runs/README.md`, *What a run may read*, item 4) and two figures
+appear under the MAE:
+
+```
+     MAE        mean 6.13  worst 7.51 at f0021   (0..255 over the union alpha; …)
+                ⤷ over the REFERENCE's own drawn pixels, mean 6.13 — …
+                ⭐ texture floor 5.84  above it 1.68   (over the reference's own pixels, 5.83 and 1.67)
+                   ⤷ … the texture accounts for 4.45 of this set's MAE (72.6% of the figure above) and
+                     cannot account for more than 5.84 — |MAE − above| ≤ floor …
+```
+
+- `texture floor` is your **own geometry through their texels** measured against your
+  own render: same pose, same quads, same rasteriser, so there is no rig content in it
+  at all.
+- `above it` is the MAE with that difference taken out.
+- ⭐ **They bound rather than subtract.** Absolute errors do not add, so
+  `MAE = floor + above` is false; what is true, per pixel and therefore of the means,
+  is `|MAE − above| ≤ floor`. So `MAE − above` is what the texture explained on these
+  frames and `floor` is the most it could ever explain. **A floor near zero is a proof
+  that the texture is not your problem** — which is a finding worth having before a
+  day of key-hunting, and one the old recipe could not give.
+
+Measured on rung 3: **6.13 / 6.01** with the candidate's own full-resolution atlas,
+of which **4.45 and 4.10 is texture** — about **70 %** — leaving **1.68 / 1.91** that
+is the rig. A run that did not know that would have spent its whole budget hunting a
+rig that was already right.
+
+⚠️ Two things about it. It is a **diagnostic and not a better number**: the artifact
+`bench` validates ships its own atlas, so the MAE is the figure that belongs in a run's
+record and the floor is the account of where part of it went. And the coarser texture
+**loses** resolution the finer one has — on rung 3 a pair the reference moves *one
+pixel* across stopped being visible at half scale, so a substituted run can report a
+frame-change disagreement the graded run does not have. Read it for the floor, never as
+the verdict.
+
+🚨 **Do not run this with `--atlas`, which is what the recipe used to say and which
+substitutes region *geometry* along with the texture.** `--atlas` names **your own**
+atlas for the case where it is not beside your skeleton; point it at a foreign one and
+the skeleton is re-loaded against that atlas. An atlas entry is not only a page and a
+rectangle — it carries **`rotate:`** and the trim offsets that say where the opaque part
+sits inside the original image, and a region attachment's quad is derived from those, so
+your attachments are re-seated and the quads change. Worse, `spine-core` implements a
+region's rotated corner assignment for `rotate: 90` and for nothing else, so a
+270-packed region is sampled from the wrong part of the page outright.
+
+⇒ **The tell was unmistakable and it is the reason this is now a flag of its own: the
+number went the wrong way.** A texture floor can only *explain* error, so a diagnostic
+that sends the MAE **up** on every set has substituted geometry rather than pixels.
+Rung 7 is that case — its pack is `rotate: 270` — and under `--atlas` it read
+24.93 → 28.84 and 19.17 → 27.75, which had to be recorded as **inconclusive**. Under
+`--texture-from` the same rung measures a floor of **1.7 MAE** on every set, about 2 %
+of each figure: there *is* a floor, it is small, and the rig is the story after all.
+
+⇒ **You no longer have to inspect the atlas for `rotate` or trim before running it.**
+`--texture-from` keeps every world vertex where your own atlas put it and remaps only
+the texture coordinates, through the drawing's own coordinate space, so a rotated or
+trimmed pack lands the same artwork in the same place. If a region of yours is missing
+from the substituting atlas the report names it and says the floor is a mixture.
 
 🚨 **The precondition the advice above does not state: a floor measured with another
 part misplaced is not a floor.** Measuring at the rest pose is right — it is the one
@@ -2316,27 +2716,54 @@ the floor is an upper bound on the error rather than a floor under it. ⚠️ Th
 same failure as capturing a guard's expected value from a screen that is already
 broken: the baseline records the defect, and then the *repair* is what looks wrong.
 
-⚖️ **`frames.json`'s own box can be refused for a reason that is not a coordinate
-error, and there is an honest answer.** The test is on **extent**: a candidate authored
-in the frames' own world units — one whose setup box lands on the reference's to the
-pixel — still fails it if its union content box differs by a few pixels at the
-extremes, because one part reaching somewhere nothing in the frames reaches is enough.
-`check` then fits its own box, and on a multi-shot root the fitted framing costs every
-set some MAE against the declared one — the same order as the shared-versus-per-set gap
-the `--framing` flag's own help quotes, and easily more than a round of fitting buys.
-That cost is real and it is **not** a sign you got the coordinates wrong.
-
-⇒ **Report both, label which is which, and say what separates them.** Run `check`
-unaided — that is the figure the artifact produces on its own and the one that belongs
-in a run's record — then run it once more with `--viewport` on the declared box and keep
-that output as a **named diagnostic file** beside the first. The gap between them is the
-framing; what is left is the keys, which is the only reason to want the second number.
-🚫 **The pinned run is never the record.** `--viewport` is a claim about your own
-coordinates and `check` says so above every figure it prints under one: *nothing checks
-it*. And do not chase the refusal by shrinking a part to fit the box — that trades a
-framing cost for a wrong silhouette, which is worse in every column that matters.
-Instead read the `content` line's own advice: it names how much wider and shorter you
-cover, and **which part reaches too far is a drift question**, not a framing one.
+⚖️ **`frames.json`'s own box, and the `declared` line that says whether you got it.**
+Every set now prints one, taken or refused, with the numbers that decided:
+
+```
+     declared   frames.json's own box: TAKEN, coincident — a fit there asks for 0.08 px, under
+                the 1 px that separates a candidate in the frames' coordinates from one in its
+                own, over 65 frame(s).
+```
+
+Two clauses take the box. **`coincident`** is the plain one: rendering into that box
+put your pixels on the reference's, so you are authored in the frames' own
+coordinates — measured, not assumed. **`extent-spread`** is the tolerance for the case
+below, and when it engages the report names it and gives both of its numbers. A
+**`coordinates`** refusal means one scale and one offset account for the whole
+correction, which is what a different origin or a different unit looks like, and
+`check` frames you by a fit instead — where it is blind to your units by design.
+
+⚠️ **The test is on extent, and extent is not the same claim as coordinates.** A
+candidate authored in the frames' own world units — one whose setup box lands on the
+reference's to the pixel — used to fail it whenever its union content box differed by
+a few per cent at the extremes, because `fitFraming` registers extent and a box 6 %
+narrower reads as 6 % of scale, which is arithmetically what a units error reads as.
+Rung 7 was refused on **all twelve** of its sets that way, and the fitted framing it
+fell back to cost every one of them 0.28–2.01 MAE against the declared box. That cost
+was real and it was **not** a sign the coordinates were wrong.
+
+⇒ **`check` now separates the two by asking whether one similarity can explain the
+disagreement at all.** A difference of units or of origin *is* a similarity, so the fit
+absorbs it exactly and leaves a residual near zero — a rig at 2 % different units leaves
+0.27 px rms. A silhouette differing at the extremes is not a similarity, so the residual
+stays the size of the disagreement — rung 7 leaves 3.32–16.85 px. So the box is taken
+when the correction reaches no further than **5 % of the reference's own content box**
+*and* the fit leaves **more than a pixel rms** it cannot explain. Both halves matter:
+the residual test on its own also takes a rig 300 units away, whose content box is
+truncated by the box it is being probed in and whose fit is therefore meaningless.
+
+⇒ **When the box is still refused, report both figures and label which is which.** Run
+`check` unaided — that is the figure the artifact produces on its own and the one that
+belongs in a run's record — then run it once more with `--viewport` on the declared box
+and keep that output as a **named diagnostic file** beside the first. The gap between
+them is the framing; what is left is the keys, which is the only reason to want the
+second number. 🚫 **The pinned run is never the record.** `--viewport` is a claim about
+your own coordinates and `check` says so above every figure it prints under one:
+*nothing checks it*. And do not chase a refusal by shrinking a part to fit the box —
+that trades a framing cost for a wrong silhouette, which is worse in every column that
+matters. Read the `content` line's own advice instead: it names how much wider and
+shorter you cover, and **which part reaches too far is a drift question**, not a
+framing one.
 
 **`Δpx` and `ref Δ`** are the two columns that do **not** compare you against the
 reference. They compare each side against **itself one frame earlier**: how many