spine-rigc 0.10.0 → 0.11.0

package/README.md

@@ -373,6 +373,22 @@ A part that matches nowhere is refused by name, two near-equal placements are re
 as both, and nothing it prints is a score. Fields, the coordinate contract and the
 limits: [AUTHORING.md §11](docs/AUTHORING.md).
 
+## The gallery — four complete rigs over art that ships with them
+
+Each directory in [`gallery/`](https://github.com/firejune/rigc/tree/main/gallery) is
+one rig spec, one motion spec and the PNGs they name, small enough to read in one
+sitting. Each stars a single feature, so *how do I do X* has a working answer rather
+than a field table, and each README carries the frame rate it was authored at, what
+was verified, and what writing it cost. Repository material: a clone and
+`bun install` runs them.
+
+| Example | Stars | What it is |
+| --- | --- | --- |
+| [`gallery/walk`](https://github.com/firejune/rigc/tree/main/gallery/walk) | `ik` constraints + **`ik` timelines** | Two two-bone leg chains solved to foot targets — the planted leg nailed down, the swinging one let go at the top of its lift |
+| [`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash) | **`deform` timelines** | A ball squashed about its contact point and stretched along its travel, from two affine transforms written out in the README |
+| [`gallery/flex`](https://github.com/firejune/rigc/tree/main/gallery/flex) | **`contour` meshes** | A swallow-tailed banner and a serrated leaf: four meshes traced off their own alpha, waved by bone timelines and rippled by a `deform` |
+| [`gallery/ride`](https://github.com/firejune/rigc/tree/main/gallery/ride) | `path` attachments + **path constraints** | A trolley coasting down a drawn rail and rolling back, driven by a `position` timeline, with `groups` + `stagger` keying the wheels and the ears |
+
 ## Commands
 
 Every command takes its paths explicitly. `rigc <command> --help` prints its flags, and

package/cli.ts

@@ -382,10 +382,41 @@ const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> =
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
-/** What a contour mesh measured about its own fit, or nothing for the others. */
+/**
+ * What a mesh measured about its own fit against the art it names, or nothing
+ * for a mesh with no art to measure against.
+ *
+ * Printed for authored geometry as well as for a `contour` (issue #277): the
+ * figure is a measurement between the emitted triangles and the PNG, so it means
+ * the same thing whoever drew the vertices, and the silence was the defect —
+ * an octagon rim placed on a round part's silhouette clips its own ink outline
+ * at 94.31% and used to print nothing at all.
+ *
+ * The hole is appended only when there is one, so the common line is unchanged.
+ * It is the one figure in the report that a hole moves: `coverage` and
+ * `overshoot` are both measured against the FILLED silhouette, so spanning an
+ * interior hole is neither missing coverage nor reaching past anything, and an
+ * unintentional hole — a gap in the art, a stroke that failed to join — bought
+ * fill over transparent pixels with nothing anywhere saying so (issue #275).
+ */
 function meshFit(m: CompileResult['meshes'][number]): string {
   if (m.coverage === undefined) return '';
-  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it`;
+  const hole = m.holePixels ? `, enclosing ${m.holePixels}px of hole` : '';
+  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it${hole}`;
+}
+
+/**
+ * The triangle budget a `MESH` line is read against: the rig's, or nothing.
+ *
+ * 📐 It used to be the literal `80`, which was nobody's budget — the rig quoted
+ * in issue #275 declared 64, `A13_MESH_BUDGET` measured against that 64
+ * correctly, and the line an author actually reads printed 80. Under the default
+ * `--profile spine` `A13` is `PROF`, so the printed number is the only budget
+ * figure in the output and it has to be the declared one. A rig that declares
+ * none says so in the same words `A13` SKIPs in, rather than being given a wall.
+ */
+function meshBudget(rig: CompileResult['rig']): string {
+  return rig.meshTriangleBudget === null ? '(no budget declared)' : `(budget ${rig.meshTriangleBudget})`;
 }
 
 /**
@@ -471,7 +502,7 @@ function cmdBuild(flags: Record<string, string>): void {
   for (const m of result.meshes) {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-        `(budget 80)  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
+        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
     );
   }
   for (const ph of result.physics) {
@@ -1763,7 +1794,8 @@ function cmdExplain(flags: Record<string, string>): void {
     for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);
     for (const m of result.meshes) {
       console.log(
-        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
+        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
+          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
       );
     }
   }

package/docs/AUTHORING.md

@@ -669,12 +669,44 @@ 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`.
 
+⭐ **Coverage is the exception, and it is reported for an authored mesh too.** Those
+rules are about a mesh's **structure** — where its rim is, how its rows pair —
+which rigc cannot know about geometry it did not build. Coverage is a measurement
+between two things it has in front of it: the emitted triangles, and the PNG the
+attachment names with `image`. So any mesh that names one gets the figure on its
+`MESH` line, authored or generated:
+
+```
+  MESH  ball         authored 9 vertices / 8 triangles  (budget 8)  bones=[ball]  attachments=[ball]  covers 94.31% of the art, reaching 2.50px past it
+```
+
+**A number, not a bar.** A `contour` under 99.5% is *refused* because rigc
+generated that geometry as a claim about the art; an authored mesh that sits inside
+its art is a legitimate thing to draw — a soft feather, a trimmed hull, a mesh
+meant to bend a core while its edges stretch — so the figure informs and the
+decision stays with the author. A mesh with no `image` reports nothing, because
+there is nothing to measure it against. The silence was worth closing: the line
+above is a round part meshed as a centre vertex plus 8 rim vertices placed on the
+silhouette, and an octagon's sides pass `R · cos(π/8)` from its centre, so 5.7% of
+the drawing — its whole ink outline, between the spokes — was not going to be
+drawn, and every assertion passed (issue #277).
+
 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.
 
+🚨 **A rig that invokes a generator must declare `invariants.meshSlots` (§3.7).**
+Geometry rigc built is geometry rigc will not ship **unmeasured**: a generated
+mesh counts against that budget, a rig that declares none has a budget of
+**zero**, and the build is refused before the gate —
+`1 mesh slot(s) emitted but the rig "hello" allows 0`. Declare `meshTriangles`
+beside it: without it `A13_MESH_BUDGET` has nothing to measure against and SKIPs,
+and the `MESH` report line has no budget to print. Authored geometry is exempt in
+the other direction and for the same reason — rigc did not draw it, so leaving it
+unmeasured is the author's call (issue #274).
+
 ⭐ **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
@@ -690,18 +722,31 @@ 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.
+`image`, so there is no number here that can disagree with the pixels. The rig
+header still budgets for it, which is the `invariants` block below and not a
+detail of the attachment.
 
 ```json
-"cape": {
-  "cape": {
-    "type": "mesh",
-    "image": "cape.png",
-    "generator": { "kind": "contour", "tolerance": 1.5, "margin": 2, "maxVertices": 48 }
+"invariants": { "meshSlots": 1, "meshTriangles": 64 },
+"skins": {
+  "default": {
+    "cape": {
+      "cape": {
+        "type": "mesh",
+        "image": "cape.png",
+        "generator": { "kind": "contour", "tolerance": 1.5, "margin": 2, "maxVertices": 48 }
+      }
+    }
   }
 }
 ```
 
+⭐ **Both keys are the fragment.** Drop the two of them into §1.1's minimal rig in
+place of its `skins`, rename its `box` bone and slot to `cape`, put a
+transparent-margined `cape.png` in `images/`, and it compiles — `invariants`
+included, because without it the generator is refused (issue #274). The
+`meshTriangles` figure is invented; pick the one your renderer can afford.
+
 | Field | Meaning |
 | --- | --- |
 | `tolerance` | **required.** Douglas-Peucker tolerance, in part pixels. Bigger spends fewer vertices and cuts more corners |
@@ -722,7 +767,18 @@ the raw outline encloses every art pixel *whole*), simplify it, push it out by
 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
+  MESH  cape         contour  15 vertices / 13 triangles  (budget 64)  bones=[cape]  attachments=[cape]  covers 100.00% of the art, reaching 3.16px past it
+```
+
+The budget in that line is the rig's `invariants.meshTriangles` — `(no budget
+declared)` when it declares none, which is the same distinction `A13` SKIPs on. It
+used to be the literal `80` whatever the rig said, so the line an author reads and
+the assertion that measures could print two different numbers (issue #275). A part
+whose outline encloses a hole says so too, because nothing else in the output
+moves when one appears:
+
+```
+  MESH  flag_b       contour  48 vertices / 46 triangles  (budget 96)  bones=[flag_b]  attachments=[flag_b]  covers 100.00% of the art, reaching 2.00px past it, enclosing 848px of hole
 ```
 
 🚨 **It is geometry, not a deformation model.** Every vertex is pinned to the slot
@@ -740,7 +796,7 @@ mesh rather than a rim prefix, and `A28_RIBBON_ROWS_SHARE_WEIGHTS` **SKIPs** wit
 | --- | --- |
 | 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 **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. `build` and `explain` print the hole in pixels, because `coverage` and `overshoot` are both measured against the FILLED silhouette and neither of them moves when a part gains one |
 | 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 |
@@ -757,6 +813,9 @@ 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.
 
+🖼️ **Worked example: [`gallery/flex`](https://github.com/firejune/rigc/tree/main/gallery/flex)** — four contours over real art, with
+the `tolerance`/`margin` sweep that picked their settings and what each one measured.
+
 **Bounding box** ([Spine: bounding boxes](http://esotericsoftware.com/spine-bounding-boxes))
 and **clipping** ([Spine: clipping](http://esotericsoftware.com/spine-clipping))
 attachments — a polygon, and nothing else.
@@ -982,6 +1041,9 @@ 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.
 
+🖼️ **Worked example: [`gallery/ride`](https://github.com/firejune/rigc/tree/main/gallery/ride)** — a trolley on a drawn rail, moved
+by a `position` timeline, with `groups` + `stagger` keying the wheels.
+
 #### 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 —
@@ -1069,9 +1131,9 @@ is not an array. Every field is optional and each is the payload a firing
 
 ### 3.7 `invariants` — what the artifact cannot say about itself
 
-Optional, and only meaningful for rigc's own formations: `meshSlots` and
-`meshTriangles` (the two halves of the mesh budget `A13` measures against),
-`axisBone`, `massBone`, `detached`. Nothing in skeleton JSON records that a
+Optional with one exception, and only meaningful for rigc's own formations:
+`meshSlots` and `meshTriangles` (the two halves of the mesh budget `A13` measures
+against), `axisBone`, `massBone`, `detached`. Nothing in skeleton JSON records that a
 bone carries a cut's axis or that a parentage is forbidden, so the rig spec says it
 and the validator's archetype assertions read it. **An assertion whose field is
 absent reports SKIP, never a pass.** If you are reproducing a foreign skeleton,
@@ -1079,6 +1141,15 @@ leave this out entirely and run `--profile spine` — and expect `PROF` rather t
 that SKIP, because the profile excludes an archetype assertion before its body
 could notice the missing field (§5.2).
 
+🚨 **The exception: `meshSlots` is required by a rig that invokes a mesh
+generator** (`ring`, `ribbon`, `contour` — §3.4), and it is a **compile-time**
+refusal rather than an assertion. Undeclared means a budget of zero, so the build
+stops before the gate with `N mesh slot(s) emitted but the rig "X" allows 0`.
+Geometry rigc built is geometry rigc will not ship unmeasured; geometry the author
+drew is exempt, because rigc did not draw it. So `A13`'s **SKIP** means *this rig
+is unmeasured*, not *this budget is inert* — those are two code paths with one
+name, and reading the SKIP as the whole story is what issue #274 was.
+
 ---
 
 ## 4. The motion spec, field by field
@@ -1369,13 +1440,25 @@ here was measured off a real rig. Copy the shape, not the values.
 | --- | --- | --- |
 | `mix` | 0..1, how much of the solved rotation is applied | `1` |
 | `softness` | distance from full reach at which the bones stop straightening | `0` |
-| `bendPositive` | two-bone bend direction | `true` |
-| `compress` | one-bone IK scales the bone down to reach a close target | `false` |
-| `stretch` | scales the bone up to reach a far target | `false` |
+| `bendPositive` | two-bone bend direction | **the rig's** (`true` if the rig says nothing) |
+| `compress` | one-bone IK scales the bone down to reach a close target | **the rig's** (`false` if the rig says nothing) |
+| `stretch` | scales the bone up to reach a far target | **the rig's** (`false` if the rig says nothing) |
 
 - **`mix` and `softness` are the two curve channels, in that order.** A raw
   `curve` is therefore 8 numbers, and the three booleans are stepped by nature —
   nothing interpolates a bend direction.
+- 🚨 **The three booleans are the one place a key's absent value is the RIG's and
+  not the format's.** The parser reads them twice with the same defaults — once on
+  the constraint (`SkeletonJson:155`) and once on **every timeline key**
+  (`:912`) — so a key that omits `bendPositive` does not inherit the constraint's
+  value, it asserts `true`. A rig declaring `bendPositive: false` under a timeline
+  that keys only `mix` therefore bent the *other* way for the whole animation,
+  with the field still in the file and inert: four builds differing only in those
+  values posed one pose, and the gate was green throughout (issue #273). rigc now
+  stamps the rig's value onto every emitted key, so the declaration reaches the
+  runtime. **Stating a flag on every key still overrides the rig** — the format
+  keys them per key on purpose, a bend that flips partway through is a real thing
+  to write, and it is what the editor's own export does.
 - `mix` outside `0..1` is a compile error: `IkConstraintPose.mix` is documented as
   a percentage. A **transform** mix is documented *unbounded*, which is why §4.10
   has no such rule — the asymmetry is the runtime's, not ours.
@@ -1404,6 +1487,10 @@ consumer's process, which is late. `A34_CONSTRAINT_TIMELINE_TARGETS` checks the
 same two from the other side, plus one thing the compiler cannot produce and a
 hand-edited file can: an **empty key array**, which the parser skips in silence.
 
+🖼️ **Worked example: [`gallery/walk`](https://github.com/firejune/rigc/tree/main/gallery/walk)** — two mirrored two-bone leg chains
+whose `mix`, `softness` and `bendPositive` are keyed through a stance and a swing,
+with the README's table of what each key is for.
+
 ### 4.10 `transform` — turning a muted transform constraint on
 
 Same shape as §4.9 and the same absent-means-default rule; six mixes instead of
@@ -1569,6 +1656,9 @@ where the remedy is a line you own. `A35` does **not** refuse it: it is pointed
 other people's files, and a rule stricter than the runtime tells its reader to go
 and break correct data.
 
+🖼️ **Worked example: [`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash)** — a 9-vertex ball squashed about
+its contact point, with the two affine transforms its keys were derived from.
+
 ---
 
 ### 4.12 `path` and `slider` timelines — tracks, not their own groups
@@ -1643,6 +1733,7 @@ the frequent ones, verbatim:
 | `key times must strictly increase (at t=…)` | including after `lag` and `stagger` |
 | `animation "A" has two tracks on X.property; merge them into one track` | one timeline per target property |
 | `no stage size: give the rig spec a \`skeleton.width\`/\`skeleton.height\`` | §3.1 |
+| `N mesh slot(s) emitted but the rig "X" allows 0 — a mesh rigc GENERATED counts against \`invariants.meshSlots\`…` | §3.4 / §3.7 — a rig that invokes a mesh generator declares the budget; undeclared is zero. Add `"invariants": { "meshSlots": N, "meshTriangles": M }` |
 | `drawOrder at t=…: slot "X" is not one this rig emits` / `is offset twice in one key` / `puts it at N, outside the … emitted slots` | §4.7 |
 | `events at t=…: event "X" is not declared in the rig spec's "events" block` | declare it in the rig spec (§3.6), or fix the name |
 | `events: key times must not go backwards` | put the firings in time order (§4.8) |
@@ -1711,7 +1802,7 @@ The report prints one line per assertion:
 | `A10_NO_NAN_AFTER_STEPPING` | both | stepping the animation produced a `NaN` pose. Look for a degenerate curve or a zero scale |
 | `A11_NO_CLIPPING_ATTACHMENTS` | renderer | a clipping attachment; the target renderer skips them silently |
 | `A12_NO_DARK_COLOR` | renderer | a slot `dark` colour or an `rgba2`/`rgb2` timeline; parsed, then ignored |
-| `A13_MESH_BUDGET` | renderer | more mesh slots than the rig's `invariants.meshSlots`, or a mesh over its `invariants.meshTriangles`. Thin the mesh, or raise the budget in the rig spec. **SKIP** when the rig declares neither |
+| `A13_MESH_BUDGET` | renderer | more mesh slots than the rig's `invariants.meshSlots`, or a mesh over its `invariants.meshTriangles`. Thin the mesh, or raise the budget in the rig spec. **SKIP** when the rig declares neither — which means *unmeasured*, not that the budget is inert: the same `meshSlots` is a **compile-time** refusal for rigc's own generators, before the gate (§3.7, issue #274) |
 | `A14_NO_FULL_FRAME_MESH` | renderer | a mesh spans the whole stage — a full-frame canvas that can never dirty-skip |
 | `A15_IDLE_NO_MESH_BONE_KEYS` | renderer | the `idle` animation keys a bone that drives a mesh, directly or as a control bone |
 | `A16_SKELETON_VERSION_4_3` | both | the `skeleton.spine` label is not on the 4.3 line (`4.3`, `4.3.N`, `4.3.N-suffix`) |

package/docs/MOTION.md

@@ -600,6 +600,13 @@ Nothing here is an answer to anything.
 What *is* real: every command line below was run, and every figure printed in an
 output block is what the command actually printed.
 
+🖼️ **For the same recipe on art that ships, the four
+[`gallery/`](https://github.com/firejune/rigc/tree/main/gallery) examples are worked
+in-betweening material** — `walk` is §3.5's arcs and §3.7's phase offsets on two leg
+chains, `ride` puts the same offsets in `groups` + `stagger`, and `squash` is §3.9's
+pivot written as a `deform` about a contact point. Each README says what every key is
+*for* rather than only what it is, and what looking at the render changed.
+
 ### The request
 
 > *"Here are the parts and two pictures of the signal arm — hanging down in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.10.0",
+  "version": "0.11.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/compile.ts

@@ -47,8 +47,10 @@ import {
   buildRibbonMesh,
   buildRingMesh,
   encodeWeightedVertices,
+  measureAuthoredMeshFit,
   MeshError,
   type MeshBoneRef,
+  type MeshFitReport,
 } from './mesh.ts';
 import { Plate, readPlate } from '../tools/plate.ts';
 import {
@@ -1192,16 +1194,33 @@ export function compile(opts: CompileOptions): CompileResult {
       tableFor(skinName)[rigSlot.name] = perSlot;
     }
   }
-  // 📐 The implicit budget of 0 is a statement about rigc's own GENERATORS: a rig
-  // that declares no `invariants.meshSlots` has not asked rigc to build any mesh,
-  // so building one is a mistake. It is not a statement about geometry somebody
+  // 📐 The implicit budget of 0 is a statement about rigc's own GENERATORS:
+  // geometry rigc built is geometry rigc will not ship unmeasured, and
+  // `A13_MESH_BUDGET` has nothing to measure a generated mesh against until the
+  // rig states a budget out loud. It is not a statement about geometry somebody
   // else drew — `RigInvariants.meshTriangles` says the same thing in words:
   // a number baked in here would be one project's frame time masquerading as a
   // property of the format. So authored meshes count against a budget the rig
-  // states out loud, and against nothing when it states none.
+  // states out loud, and against nothing when it states none: rigc did not draw
+  // them, so leaving them unmeasured is the author's call (issue #44's rule).
+  // #277's coverage report splits the same way and lands on the other side of it:
+  // both kinds are MEASURED, and only rigc's own output gets a wall.
+  //
+  // ⚠️ The message has to name the field, because the three doc places a reader
+  // checks all read as "you do not need this" and one of them is §3.4's own
+  // worked example (issue #274).
   const budgeted = rig.invariants?.meshSlots === undefined ? meshes.filter((m) => m.kind !== 'authored') : meshes;
   if (budgeted.length > meshBudget) {
-    throw new CompileError(`${budgeted.length} mesh slot(s) emitted but the rig "${rig.name}" allows ${meshBudget}`);
+    throw new CompileError(
+      `${budgeted.length} mesh slot(s) emitted but the rig "${rig.name}" allows ${meshBudget}` +
+        (rig.invariants?.meshSlots === undefined
+          ? ' — a mesh rigc GENERATED counts against `invariants.meshSlots`, and this rig declares none, which is a ' +
+            'budget of 0. Add `"invariants": { "meshSlots": ' +
+            `${budgeted.length}, "meshTriangles": <triangles one mesh may carry> }\` to the rig spec: geometry rigc ` +
+            'built is geometry it will not ship unmeasured, and `A13_MESH_BUDGET` has nothing to measure against ' +
+            'until that budget is stated. (Authored geometry is exempt — rigc did not draw it.)'
+          : ' — raise `invariants.meshSlots` in the rig spec if that budget is the thing being changed'),
+    );
   }
 
   // -- 4b. constraints -------------------------------------------------------
@@ -1217,6 +1236,22 @@ export function compile(opts: CompileOptions): CompileResult {
   // constraint of the same name and the parser then throws. Keeping the type
   // beside the name is what lets the refusal say which of the two it is.
   const constraintTypes = new Map<string, string>();
+  /**
+   * ik constraint -> the booleans it declares that the timeline format would
+   * otherwise take away from it. Issue #273.
+   *
+   * 🚨 `SkeletonJson` reads `bendPositive`, `compress` and `stretch` in TWO
+   * places with the same defaults: once on the constraint (`:155`) and once on
+   * **every timeline key** (`:912`). A key that omits one does not inherit the
+   * constraint's value — it asserts the parser's default. So a rig that declares
+   * `bendPositive: false` and an `ik` timeline that keys only `mix` produce a
+   * constraint that bends the other way for the whole animation, with the field
+   * still in the file and inert: four builds differing only in these flags posed
+   * one pose. What goes in this map is only the values that DIFFER from the
+   * per-key default, because a rig that says nothing and a key that says nothing
+   * already agree and there is nothing to carry.
+   */
+  const ikRigFlags = new Map<string, Record<string, boolean>>();
   // Which slots can actually show a path, for the path constraint's own check.
   // Read off the emitted skin tables rather than the spec, so it answers the
   // question the runtime asks: is there an attachment of that type on that slot?
@@ -1243,6 +1278,14 @@ export function compile(opts: CompileOptions): CompileResult {
     constraints.push(buildRigConstraint(spec, constraintCtx));
     constraintNames.add(spec.name);
     constraintTypes.set(spec.name, spec.type);
+    if (spec.type === 'ik') {
+      const carried: Record<string, boolean> = {};
+      for (const flag of CONSTRAINT_TIMELINES.ik.flags) {
+        const declared = spec[flag.field];
+        if (typeof declared === 'boolean' && declared !== flag.dflt) carried[flag.field] = declared;
+      }
+      if (Object.keys(carried).length) ikRigFlags.set(spec.name, carried);
+    }
   }
   withMotionSource(() => {
     for (const [name, spec] of Object.entries(motion.physics ?? {})) {
@@ -1414,7 +1457,14 @@ export function compile(opts: CompileOptions): CompileResult {
                 'the group holds one timeline per constraint, so merge them into one',
             );
           }
-          const keys = compileConstraintTrack(group, track, motion, animName, anim.duration);
+          const keys = compileConstraintTrack(
+            group,
+            track,
+            motion,
+            animName,
+            anim.duration,
+            ikRigFlags.get(name) ?? {},
+          );
           for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
           constraintTimelines[group][name] = keys;
         }
@@ -2153,6 +2203,44 @@ function encodeNamedWeights(weights: RigMeshBinding[][], where: string, ctx: Att
   return out;
 }
 
+/**
+ * Measure an authored mesh against the art it names, or report nothing.
+ *
+ * 🚨 A measurement, never a refusal — and that asymmetry with `contour` is the
+ * whole decision (issue #277). A contour mesh is refused under 99.5% because rigc
+ * GENERATED that geometry as a claim about the art: below the bar, rigc's own
+ * arithmetic clipped the drawing. Authored geometry is the author's intent, and a
+ * mesh that sits inside its art is a legitimate thing to draw — a soft feather, a
+ * deliberately trimmed hull, a mesh meant to bend a core while its edges stretch.
+ * Refusing those would be #44's mistake in a new place. So the figure is printed
+ * and the decision stays with the author.
+ *
+ * Nothing is reported in the two cases where there is nothing to compare:
+ * an attachment with no `image` (there is no PNG the mesh is a claim about), and
+ * a part with no art at all (0 of 0 pixels is not a percentage). Neither is an
+ * error here — a mesh with no image is ordinary data, and an all-transparent part
+ * is somebody else's assertion to make.
+ */
+function measureAuthoredFit(att: RigMeshAttachment, ctx: AttachmentContext): MeshFitReport | null {
+  if (att.image === undefined || att.uvs === undefined || att.triangles === undefined) return null;
+  const region = basename(att.image, '.png');
+  const img = ctx.images.find((im) => im.region === region);
+  if (!img) return null;
+  const plate = partPlate(img);
+  const alpha = new Uint8Array(plate.width * plate.height);
+  for (let i = 0; i < alpha.length; i++) alpha[i] = plate.data[i * 4 + 3];
+  // uvs are the part window in 0..1 — the same normalisation `buildContourMesh`
+  // emits — so the pixel grid they land on is the PLATE's, which is the grid the
+  // alpha was read off. On an imported page that declares a `scale:` the
+  // drawing's size and the plate's differ, and it is the plate that has pixels.
+  const points = [] as Array<[number, number]>;
+  for (let i = 0; i + 1 < att.uvs.length; i += 2) {
+    points.push([att.uvs[i] * plate.width, att.uvs[i + 1] * plate.height]);
+  }
+  const fit = measureAuthoredMeshFit({ width: plate.width, height: plate.height, alpha }, 1, points, att.triangles);
+  return fit.artPixels === 0 ? null : fit;
+}
+
 function buildRigMesh(
   att: RigMeshAttachment,
   placeholder: string,
@@ -2230,6 +2318,7 @@ function buildRigMesh(
   // read this and skip rather than measuring a ring that was never a ring.
   ctx.meshBones.add(ctx.anchorBone);
   for (const name of boundBones) ctx.meshBones.add(name);
+  const fit = measureAuthoredFit(att, ctx);
   ctx.meshes.push({
     slot: ctx.slotName,
     kind: 'authored',
@@ -2237,6 +2326,8 @@ function buildRigMesh(
     vertices: uvCount / 2,
     triangles: att.triangles.length / 3,
     bones: boundBones.length ? boundBones : [ctx.anchorBone],
+    coverage: fit === null ? undefined : r6(fit.coverage),
+    overshoot: fit?.overshoot,
   });
   return out;
 }
@@ -2417,6 +2508,7 @@ function buildContourAttachment(
     bones: [ctx.anchorBone],
     coverage: geometry.contour?.coverage,
     overshoot: geometry.contour?.overshoot,
+    holePixels: geometry.contour?.holePixels,
   });
   const out: SpineMeshAttachment = {
     type: 'mesh',
@@ -3233,6 +3325,23 @@ function compileEvents(
  * That is reading the format, not inventing a value: it is exactly what the
  * runtime will interpolate, and a bezier built against anything else would
  * describe a curve the player does not play.
+ *
+ * 🚨 `rigFlags` is the same reading applied one level up, for the three ik
+ * booleans (issue #273). The parser reads them per KEY as well as on the
+ * constraint, with the same defaults in both places, so an ik timeline whose keys
+ * omit `bendPositive` does not inherit the rig's — it asserts `true`, and a rig
+ * that declared `false` bends the other way for the whole animation with the
+ * field still sitting in the file. Every key therefore carries the EFFECTIVE
+ * direction: the motion's where the motion states one, and the rig's where it
+ * does not.
+ *
+ * **A motion key may still override.** The format keys these per key on purpose
+ * — they are stepped by nature, and a bend that flips partway through an
+ * animation is a real thing to write — so a track that states a flag on every key
+ * is honoured as written, whatever the rig says. That is also what the editor's
+ * own export does: spineboy-pro declares `bendPositive: false` on both leg chains
+ * and restates it on every key of all six ik timelines that touch them. What
+ * changes here is only the silent case.
  */
 function compileConstraintTrack(
   group: 'ik' | 'transform',
@@ -3240,6 +3349,8 @@ function compileConstraintTrack(
   motion: MotionSpec,
   animName: string,
   duration: number,
+  /** Non-default ik booleans the rig declared, by field. Empty for `transform`. */
+  rigFlags: Record<string, boolean>,
 ): SpineTimelineKey[] {
   const shape = CONSTRAINT_TIMELINES[group];
   const article = group === 'ik' ? 'an' : 'a';
@@ -3316,7 +3427,15 @@ function compileConstraintTrack(
     }
     for (const flag of shape.flags) {
       const v = read(key, flag.field);
-      if (v === undefined) continue;
+      if (v === undefined) {
+        // The rig's value, stamped on this key because nothing else will carry
+        // it there. Absent from `rigFlags` means the rig's value IS the per-key
+        // default, so omitting the field says the same thing and the emitted
+        // bytes do not move.
+        const carried = rigFlags[flag.field];
+        if (carried !== undefined) entry[flag.field] = carried;
+        continue;
+      }
       if (typeof v !== 'boolean') {
         throw new CompileError(`${where} (t=${key.t}): ${flag.field} is ${JSON.stringify(v)}, not true or false`);
       }

package/src/mesh.ts

@@ -981,8 +981,19 @@ export function traceAlphaOutline(
     dir = next;
   }
 
-  // Holes: background pixels the island encloses. Flooded from outside the part,
-  // so "enclosed" is decided by reachability rather than by a winding rule.
+  const { filled, holePixels } = fillEnclosed(inside, w, h);
+  return { outline, artPixels, islandPixels: sizes[biggest - 1], islands: sizes.length, holePixels, filled };
+}
+
+/**
+ * A set of pixels plus every background pixel it encloses.
+ *
+ * Flooded from outside the part, so "enclosed" is decided by REACHABILITY rather
+ * than by a winding rule — which is what makes it answer the same question for a
+ * mask of one island and a mask of several, and is why the authored-mesh
+ * measurement can pass it all the art where the trace passes it one island.
+ */
+function fillEnclosed(inside: Uint8Array, w: number, h: number): { filled: Uint8Array; holePixels: number } {
   const outsideReach = new Uint8Array(w * h);
   const queue: number[] = [];
   const seed = (x: number, y: number): void => {
@@ -1018,8 +1029,37 @@ export function traceAlphaOutline(
       holePixels++;
     }
   }
+  return { filled, holePixels };
+}
 
-  return { outline, artPixels, islandPixels: sizes[biggest - 1], islands: sizes.length, holePixels, filled };
+/**
+ * Which pixels of a `w`x`h` grid a triangle set draws over.
+ *
+ * A pixel counts as covered when its CENTRE is in or on a triangle, which is the
+ * same convention `src/render.ts` rasterises by. A degenerate triangle — zero
+ * doubled area — is skipped rather than given an orientation it does not have.
+ */
+function rasteriseTriangles(points: Array<[number, number]>, triangles: number[], w: number, h: number): Uint8Array {
+  const covered = new Uint8Array(w * h);
+  for (let t = 0; t + 2 < triangles.length; t += 3) {
+    const a = points[triangles[t]];
+    const b = points[triangles[t + 1]];
+    const c = points[triangles[t + 2]];
+    const twice = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+    if (Math.abs(twice) < 1e-12) continue;
+    const orient = twice > 0 ? 1 : -1;
+    const minX = Math.max(0, Math.floor(Math.min(a[0], b[0], c[0]) - 1));
+    const maxX = Math.min(w - 1, Math.ceil(Math.max(a[0], b[0], c[0]) + 1));
+    const minY = Math.max(0, Math.floor(Math.min(a[1], b[1], c[1]) - 1));
+    const maxY = Math.min(h - 1, Math.ceil(Math.max(a[1], b[1], c[1]) + 1));
+    for (let y = minY; y <= maxY; y++) {
+      for (let x = minX; x <= maxX; x++) {
+        if (covered[y * w + x]) continue;
+        if (pointInTriangle([x + 0.5, y + 0.5], a, b, c, orient)) covered[y * w + x] = 1;
+      }
+    }
+  }
+  return covered;
 }
 
 /**
@@ -1049,25 +1089,7 @@ export function measureContourFit(
 ): { coverage: number; overshoot: number; artPixels: number; coveredArt: number } {
   const { width: w, height: h } = mask;
   const art = artOf(mask, threshold);
-  const covered = new Uint8Array(w * h);
-  for (let t = 0; t + 2 < triangles.length; t += 3) {
-    const a = points[triangles[t]];
-    const b = points[triangles[t + 1]];
-    const c = points[triangles[t + 2]];
-    const twice = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
-    if (Math.abs(twice) < 1e-12) continue;
-    const orient = twice > 0 ? 1 : -1;
-    const minX = Math.max(0, Math.floor(Math.min(a[0], b[0], c[0]) - 1));
-    const maxX = Math.min(w - 1, Math.ceil(Math.max(a[0], b[0], c[0]) + 1));
-    const minY = Math.max(0, Math.floor(Math.min(a[1], b[1], c[1]) - 1));
-    const maxY = Math.min(h - 1, Math.ceil(Math.max(a[1], b[1], c[1]) + 1));
-    for (let y = minY; y <= maxY; y++) {
-      for (let x = minX; x <= maxX; x++) {
-        if (covered[y * w + x]) continue;
-        if (pointInTriangle([x + 0.5, y + 0.5], a, b, c, orient)) covered[y * w + x] = 1;
-      }
-    }
-  }
+  const covered = rasteriseTriangles(points, triangles, w, h);
   let artPixels = 0;
   let coveredArt = 0;
   for (let i = 0; i < art.length; i++) {
@@ -1104,6 +1126,145 @@ export function measureContourFit(
   };
 }
 
+/** What a mesh's triangles measure against the art the attachment names. */
+export interface MeshFitReport {
+  /** Pixels at or above the threshold. */
+  artPixels: number;
+  /** How many of them a triangle covers. */
+  coveredArt: number;
+  /** `coveredArt / artPixels`, 0..1. */
+  coverage: number;
+  /** Furthest a covered pixel sits outside the filled silhouette, in pixels. */
+  overshoot: number;
+}
+
+/**
+ * The same measurement for geometry rigc did NOT build — issue #277.
+ *
+ * ## Why an authored mesh can be measured at all
+ *
+ * Issue #44's lesson was that rigc must not apply a GENERATOR's topology rules to
+ * authored geometry: where a rim is, how rows pair, which edge is pinned. It did
+ * not build the mesh, so it cannot know any of that. Coverage is not topology.
+ * It is a number between two things the compiler has in front of it — the emitted
+ * triangles, and the PNG the attachment names with `image` — and it assumes
+ * nothing whatever about how the vertices are arranged. The defect it catches is
+ * the renderer's, not the author's: texture outside the triangles is not drawn,
+ * so art outside the mesh disappears on every runtime. A 9-vertex fan whose 8 rim
+ * vertices sit exactly on a round part's silhouette loses its whole ink outline
+ * between the spokes — an octagon's sides pass `R·cos(π/8)` from its centre — and
+ * measured 94.31%, five points under the bar the same art would have been refused
+ * at as a `contour`, with nothing in the report saying so.
+ *
+ * ## Two differences from `measureContourFit`, both deliberate
+ *
+ * **The filled silhouette is ALL the art plus what it encloses**, not the largest
+ * island plus what that encloses. A contour is one traced loop and can only ever
+ * enclose one island; an authored mesh over a part drawn as several islands is
+ * ordinary, correct data.
+ *
+ * **The overshoot search has no radius.** `measureContourFit` bounds it because a
+ * contour past its bound is refused and needs no exact figure. An authored mesh
+ * is never refused, so every figure needs a number — hence the exact distance
+ * transform below rather than a neighbourhood search that would have to stop
+ * somewhere.
+ */
+export function measureAuthoredMeshFit(
+  mask: AlphaMask,
+  threshold: number,
+  points: Array<[number, number]>,
+  triangles: number[],
+): MeshFitReport {
+  const { width: w, height: h } = mask;
+  const art = artOf(mask, threshold);
+  const { filled } = fillEnclosed(art, w, h);
+  const covered = rasteriseTriangles(points, triangles, w, h);
+  let artPixels = 0;
+  let coveredArt = 0;
+  for (let i = 0; i < art.length; i++) {
+    if (!art[i]) continue;
+    artPixels++;
+    if (covered[i]) coveredArt++;
+  }
+  const squared = squaredDistanceToSet(filled, w, h);
+  let worst = 0;
+  for (let i = 0; i < covered.length; i++) {
+    if (!covered[i] || filled[i]) continue;
+    if (squared[i] > worst) worst = squared[i];
+  }
+  return {
+    artPixels,
+    coveredArt,
+    coverage: artPixels === 0 ? 0 : coveredArt / artPixels,
+    overshoot: r6(Math.sqrt(worst)),
+  };
+}
+
+/**
+ * Exact squared Euclidean distance from every pixel to the nearest set pixel of
+ * `inside`, by the two-pass lower-envelope transform (Felzenszwalb-Huttenlocher).
+ *
+ * Two one-dimensional passes — down each column, then along each row of the
+ * result — because the squared Euclidean distance separates across axes:
+ * `min_p (x-px)² + (y-py)²` is the lower envelope of one parabola per candidate,
+ * and a pass builds that envelope in one sweep. Exact, and linear in the number
+ * of pixels, which is the reason it is here at all: the bounded neighbourhood
+ * search `measureContourFit` uses costs `radius²` per pixel and has to be told
+ * where to stop, and the authored path has nowhere to stop.
+ *
+ * `INF` is one past the furthest two pixels of this grid can be, so a column with
+ * no set pixel survives the first pass as "nothing in this column" rather than as
+ * a distance. A grid with no set pixel at all comes back all `INF`; the one caller
+ * never asks (a mask with no art has no covered-outside pixel to ask about).
+ */
+function squaredDistanceToSet(inside: Uint8Array, w: number, h: number): Float64Array {
+  const INF = w * w + h * h + 1;
+  const dist = new Float64Array(w * h);
+  for (let i = 0; i < dist.length; i++) dist[i] = inside[i] ? 0 : INF;
+
+  const span = Math.max(w, h);
+  const f = new Float64Array(span);
+  const out = new Float64Array(span);
+  /** The parabolas still on the envelope, as the sample index each rises from. */
+  const v = new Int32Array(span);
+  /** Where consecutive envelope parabolas cross. One longer than `v` by nature. */
+  const z = new Float64Array(span + 1);
+  const envelope = (n: number): void => {
+    let k = 0;
+    v[0] = 0;
+    z[0] = -Infinity;
+    z[1] = Infinity;
+    for (let q = 1; q < n; q++) {
+      let s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+      while (s <= z[k]) {
+        k--;
+        s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+      }
+      k++;
+      v[k] = q;
+      z[k] = s;
+      z[k + 1] = Infinity;
+    }
+    k = 0;
+    for (let q = 0; q < n; q++) {
+      while (z[k + 1] < q) k++;
+      out[q] = (q - v[k]) * (q - v[k]) + f[v[k]];
+    }
+  };
+
+  for (let x = 0; x < w; x++) {
+    for (let y = 0; y < h; y++) f[y] = dist[y * w + x];
+    envelope(h);
+    for (let y = 0; y < h; y++) dist[y * w + x] = out[y];
+  }
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) f[x] = dist[y * w + x];
+    envelope(w);
+    for (let x = 0; x < w; x++) dist[y * w + x] = out[x];
+  }
+  return dist;
+}
+
 /**
  * Build a mesh cut to the part's own alpha silhouette.
  *

package/src/render.ts

@@ -330,7 +330,7 @@ export function boneSnapshots(skeleton: Skeleton): BoneSnapshot[] {
 
 export interface Quad extends PieceCommon {
   kind: 'region';
-  /** World-space corners, in spine-core's region order: br, bl, ul, ur. */
+  /** World-space corners, in spine-core's region order: bl, ul, ur, br (verified against computeWorldVertices — the 2026-09-03 run reconstructed this from measurement after the old comment cost it days). */
   world: number[];
   /** Page UVs for the same four corners. */
   uvs: ArrayLike<number>;

package/src/types.ts

@@ -937,13 +937,24 @@ export interface CompileResult {
     triangles: number;
     bones: string[];
     /**
-     * Share of the part's own art the triangles cover, 0..1. Only a `contour`
-     * mesh has one — it is the only generator whose shape is a claim ABOUT the
-     * art, so it is the only one with something to measure against it.
+     * Share of the part's own art the triangles cover, 0..1.
+     *
+     * Measured for every mesh that names an `image`, generated or authored: it is
+     * a number between two things the compiler has in front of it — the emitted
+     * triangles and the PNG — and it assumes nothing about how the vertices are
+     * arranged (issue #277). Absent on a mesh with no `image`, which has nothing
+     * to be measured against, and on a `ring` or `ribbon`, whose window size
+     * comes from the spec rather than from art.
      */
     coverage?: number;
     /** How far past the silhouette that mesh reaches, in part pixels. */
     overshoot?: number;
+    /**
+     * Transparent pixels the traced outline encloses — inside the mesh, drawing
+     * nothing. Only a `contour` has one: it is a property of the trace, and an
+     * authored mesh was not traced.
+     */
+    holePixels?: number;
   }>;
   /** Structural expectations handed to the validator. */
   rig: RigInfo;