spine-rigc 1.2.3 → 1.3.0

package/README.md

@@ -530,7 +530,7 @@ commands take it and what its default is.
 | Command | Does |
 | --- | --- |
 | `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained, with `skeleton.images` pointing at it so the editor's import finds the parts |
-| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
+| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size`, `--padding` and `--page-edges` tune it |
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |

package/cli.ts

@@ -101,8 +101,12 @@ import { NotAPngError } from './src/png.ts';
 import { copyAtlasPages } from './src/emit.ts';
 import {
   DEFAULT_PADDING,
+  DEFAULT_PAGE_EDGES,
   DEFAULT_PAGE_SIZE,
+  FREE_EDGE_STEP,
+  PAGE_EDGES,
   packAtlas,
+  type PageEdges,
   pageFootprint,
   parseAtlasText,
   type AtlasRegion,
@@ -612,9 +616,37 @@ const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> =
   ribbon: 'ribbon    entry row pinned, rows share their weights so the strip lengthens without widening',
   contour: 'contour   the art\'s own silhouette, every vertex pinned to the slot bone (geometry, not a deformation)',
   grid: 'grid      a lattice over the part window at stated column and row positions, every vertex pinned to the slot bone',
+  segments: 'segments  a lattice over the part\'s alpha, every vertex weighted by distance to the bone segments it names',
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
+/**
+ * The line under a `segments` mesh: how its bones share the vertices.
+ *
+ * ⭐ The weights are this generator's whole output, and the per-vertex numbers
+ * are nowhere a reader can see them — so the three figures that say whether the
+ * falloff did what was meant are printed where the mesh is: the most bones any
+ * vertex binds (against `maxBones`), the mean, and how many vertices a single
+ * bone owns outright. A named bone no vertex binds is said by name, because it
+ * is in no weight and so in no other figure either.
+ */
+function meshInfluenceNote(m: CompileResult['meshes'][number]): string {
+  const inf = m.influence;
+  if (inf === undefined) return '';
+  const unbound = m.bones.filter((b) => !inf.bound.includes(b));
+  const single = m.vertices === 0 ? 0 : (inf.singleBone / m.vertices) * 100;
+  const joined = inf.keptCells - inf.artCells;
+  return (
+    `\n        influence  max ${inf.maxBones} bone(s) per vertex, mean ${inf.meanBones.toFixed(2)}, ` +
+    `${inf.singleBone} of ${m.vertices} vertices (${single.toFixed(2)}%) on a single bone` +
+    (unbound.length ? `; named and bound by no vertex: ${unbound.join(', ')}` : '') +
+    `\n        lattice    cell ${inf.cell}px, ${inf.cols}x${inf.rows} cells, ${inf.artCells} with art, ${inf.keptCells} kept` +
+    (inf.islands > 1 || joined > 0
+      ? ` (${inf.islands} island(s) joined into one outline, ${joined} cell(s) added that hold no art)`
+      : '')
+  );
+}
+
 /**
  * Why a figure taken off a part's texels is withheld on a page whose file is
  * not the size its atlas declares — the tail of every line that withholds one
@@ -1260,6 +1292,21 @@ function readIntFlag(flags: Record<string, string>, name: string, fallback: numb
   return Number(raw);
 }
 
+/**
+ * Read `--page-edges`, or its default — `pot`.
+ *
+ * An unknown value is a usage error for `readProfile`'s reason: a typo that fell
+ * back to `pot` would hand the caller who asked for the smaller page the bigger
+ * one, green, and say nothing.
+ */
+function readPageEdges(flags: Record<string, string>): PageEdges {
+  const raw = flags['page-edges'];
+  if (raw === undefined) return DEFAULT_PAGE_EDGES;
+  const found = PAGE_EDGES.find((e) => e === raw);
+  if (!found) throw new UsageError(`--page-edges ${JSON.stringify(raw)}; known values: ${PAGE_EDGES.join(', ')}`);
+  return found;
+}
+
 /**
  * One `DROP` line, written once because two outcomes print it.
  *
@@ -1343,7 +1390,7 @@ function cmdBuild(flags: Record<string, string>): void {
   // now a build like any other — and it is the only one that puts the renderer's
   // own rulebook over shared-page sampling.
   if (!packing) {
-    for (const name of ['page-size', 'padding'] as const) {
+    for (const name of ['page-size', 'padding', 'page-edges'] as const) {
       if (flags[name] !== undefined) throw new UsageError(`--${name} only means something with --pack`);
     }
   }
@@ -1394,7 +1441,8 @@ function cmdBuild(flags: Record<string, string>): void {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
         `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}` +
-        meshDepthNote(m),
+        meshDepthNote(m) +
+        meshInfluenceNote(m),
     );
   }
   for (const ph of result.physics) {
@@ -1445,6 +1493,7 @@ function cmdBuild(flags: Record<string, string>): void {
     const packOpts = {
       pageSize: readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE),
       padding: readIntFlag(flags, 'padding', DEFAULT_PADDING),
+      pageEdges: readPageEdges(flags),
       pageStem: 'skeleton',
     };
     const inputs = result.images.map((img) => ({
@@ -1460,7 +1509,8 @@ function cmdBuild(flags: Record<string, string>): void {
       console.log(
         `  ..    pack: ${page.name} ${page.width}x${page.height}, ` +
           `${packed.placements.filter((p) => packed.pages[p.page].name === page.name).length} region(s), ` +
-          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}`,
+          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}` +
+          (packOpts.pageEdges === 'free' ? ', page edges free' : ''),
       );
     }
     for (const place of packed.placements) {
@@ -3327,7 +3377,8 @@ function cmdExplain(flags: Record<string, string>): void {
       console.log(
         `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
           `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}` +
-          meshDepthNote(m),
+          meshDepthNote(m) +
+          meshInfluenceNote(m),
       );
     }
   }
@@ -3737,6 +3788,10 @@ const FLAG_MEANINGS: Record<string, string> = {
     'one written is the smallest that holds the pack, spilling to more pages only when the set will not fit',
   padding: `gutter each region reserves on every side, --pack only (default ${DEFAULT_PADDING}); it is filled by ` +
     "extending the region's own edge pixels outwards, which is what stops a neighbour bleeding in",
+  'page-edges': `what a page's edges may be, --pack only (default ${DEFAULT_PAGE_EDGES}): pot is a power of two on ` +
+    `both; free tries every width on a ${FREE_EDGE_STEP}px step, takes the height the placement needs and keeps ` +
+    'the least area — a smaller page, at the cost of region attachments sampling within 1 LSB of the loose ' +
+    'build rather than exactly',
   'atlas-in':
     'resolve every part against the regions of this pre-packed .atlas instead of against loose PNGs — region ' +
     'geometry (bounds/offsets/rotate) is read from the file and the atlas is re-emitted into --out, re-anchored',
@@ -3855,6 +3910,7 @@ const FLAG_VALUES: Record<string, string> = {
   'atlas-in': '<file.atlas>',
   'page-size': '<px>',
   padding: '<px>',
+  'page-edges': 'pot|free',
   'texture-from': '<path>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
@@ -3941,7 +3997,7 @@ const COMMANDS: CommandDoc[] = [
     name: 'build',
     usage: [
       'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]',
-      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}]   (parts onto shared pages, written into --out)`,
+      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free]   (parts onto shared pages, written into --out)`,
       'rigc build … --atlas-in <skeleton.atlas>                    (resolve the parts against a pack somebody already made)',
       'rigc build --cut <name> --cuts <cuts.json>',
     ],
@@ -3955,6 +4011,7 @@ const COMMANDS: CommandDoc[] = [
       'pack',
       'page-size',
       'padding',
+      'page-edges',
       'atlas-in',
       'cut',
       'cuts',
@@ -3973,7 +4030,7 @@ const COMMANDS: CommandDoc[] = [
       'this line said "the same arguments as build, minus --profile" and was false in both',
       'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
       'command read what `ingest --art none` writes was reachable and undocumented, while',
-      '--pack, --page-size, --padding and --copy-images are build\'s and do nothing here —',
+      '--pack, --page-size, --padding, --page-edges and --copy-images are build\'s and do nothing here —',
       'they decide what is WRITTEN, and this command writes nothing. What it takes is listed',
       'above, and that is now the whole of it.',
     ],

package/docs/AUTHORING.md

@@ -200,6 +200,7 @@ What the flags mean:
 | `--pack` | `build` only: arrange every part onto **shared** atlas page(s), written into `--out` as real PNGs, instead of one page per part. Lossless — nothing is resampled, trimmed or rotated. The default is one page per part — **§0.1** |
 | `--page-size` | `build --pack` only: the largest page edge (default `2048`). A ceiling, not the size: page edges are powers of two and the one written is the smallest that holds the pack — **§0.1** |
 | `--padding` | `build --pack` only: the gutter each region reserves on every side (default `2`), filled by extending the region's own edge pixels outwards. `0` is not a legal-but-tight choice, it is bleed — **§0.1** |
+| `--page-edges` | `build --pack` only: `pot` (default) or `free`. `pot` keeps both page edges powers of two; `free` sizes the page to the parts — a smaller page, at the cost of region attachments sampling within one least significant bit of the loose build instead of exactly. Any other value is refused by name — **§0.1** |
 | `--atlas-in` | `build` and `explain`: resolve every part against the **regions of a pre-packed `.atlas`** instead of against loose PNGs. Region geometry is read from the file and sizes are descaled by the page's `scale:`; `build` re-emits the atlas into `--out`, re-anchored, and `explain` writes nothing and poses through it — **§0.2**. On `explain` it is the flag that makes a **size-only** spec readable at all (`ingest --art none`), because posing resolves every attachment against an atlas; without it that pair is refused by name rather than thrown through (§5.1) |
 | `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order. For `chainfit` it is only where each attachment's image name **resolves**: the candidate decides what the parts are, so extra PNGs are unused and a missing name is refused by name (§12.3) |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
@@ -313,7 +314,10 @@ a gap:
   `RegionAttachment.computeUVs` assigns a different corner order at 90, so a
   rotated pack is one rigc's own `--atlas` substitution cannot read.
   Rotation buys page area; a page that runs out of room spills to a second page
-  instead.
+  instead. Measured on two painting rigs (issue #860), a pack that turned 12
+  regions `rotate: 90` lifted every region back byte for byte and drew its
+  region attachments with 0 differing pixels — and made neither page smaller,
+  because both were already on the smallest power-of-two page their area allows.
 - **no re-ordering of anything the skeleton says.** `skeleton.json` from a packed
   build is **byte-identical** to the unpacked one, because sizes are still
   measured from the loose PNGs and packing is an output arrangement.
@@ -348,6 +352,38 @@ it usually does not appear at all: eleven of the thirteen rigs in this repositor
 render **byte-identically** packed and unpacked across 1,101 frames, and the two
 that do not are the two with meshes, at 1 and 146 samples of 6 and 60 million.
 
+**`--page-edges free`: a page sized to the parts.** The default, `pot`, tries
+every power-of-two pair up to `--page-size` in order of area and writes the first
+the pack fits — it never doubles past a smaller page that would do. So when the
+parts' own area already exceeds the next power-of-two page down, no `pot` packer
+can do better, and `free` is the lever left. Under `free` the candidate widths
+are the multiples of 32 from the widest padded part up to `--page-size`; at each
+width the parts are placed by the same MaxRects pass on a page `--page-size`
+tall, and the height is the bottom edge of the lowest part. The page with the
+least area wins, then the squarer one (smaller |width − height|), then the
+narrower one — every candidate has a different width, so the order is total and
+two builds of the same parts write the same bytes. Spilling, the packing order
+and `--page-size` as the ceiling are the same as under `pot`.
+
+The default stays `pot` because every runtime accepts a power-of-two page and
+the editor's own packer writes one by default: 9 of the 10 atlases in the
+fetched `examples/` corpus are power-of-two on both edges. What `free` costs is
+the exactness above. `x / pageWidth` is no longer exact, so a **region**
+attachment's samples join a mesh's at one least significant bit against the
+loose build instead of 0. No region's bytes change: every one lifts back byte for
+byte, as under `pot`. Observed on two painting rigs of 22 and 20 parts:
+
+| Rig | `pot` page | `free` page | Area | Covered | Opaque (alpha > 0) | Render vs loose, region attachments only | Render vs loose, whole rig |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 22 parts | 1024x2048 = 2,097,152 | 1888x697 = 1,315,936 | −37.3 % | 56.3 % → 89.7 % | 36.8 % → 58.7 % | 0 → 2,323 px, worst 1 | 3,854 → 5,216 px, worst 1 |
+| 20 parts | 512x2048 = 1,048,576 | 480x1166 = 559,680 | −46.6 % | 49.7 % → 93.2 % | 28.7 % → 53.8 % | 0 → 527 px, worst 1 | 1,260 → 1,669 px, worst 1 |
+
+The pixel counts are over 49 frames at `render --max 1024`. **Covered** is the
+regions' own rectangles over the page, which the pack line prints; **opaque** is
+the page's texels with any alpha. The gap between the two is transparency
+inside the parts, which no packer that copies bytes can remove. The pack line
+ends `, page edges free` when the flag is set.
+
 ### 0.2 Building against a pack somebody else made — `--atlas-in`
 
 The other direction. `--atlas-in <file.atlas>` resolves every part against the
@@ -814,8 +850,9 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   `build --atlas-in` gates green is readable here through the same flag, and
   without it the pair is refused by name at exit 2 rather than posed
   (§5.1). ⚠️ `--profile`,
-  `--pack`, `--page-size`, `--padding` and `--copy-images` are `build`'s and are
-  not here: four of them decide what is *written*, and this command writes nothing.
+  `--pack`, `--page-size`, `--padding`, `--page-edges` and `--copy-images` are
+  `build`'s and are not here: five of them decide what is *written*, and this
+  command writes nothing.
 
   📐 **What it will not measure: the texels of a page that is not its declared
   size.** Under
@@ -1703,13 +1740,15 @@ is the wrap-around curve from `x = 180` back to `x = 0`, which nothing reads. Th
 §3.5.1's constraint example rides: with `position: 0.25` its `cart` bone poses at
 `worldX = 45.000000`.
 
-The generators are `ring`, `ribbon`, `contour` and `grid` (see
+The generators are `ring`, `ribbon`, `contour`, `grid` and `segments` (see
 [`src/mesh.ts`](../src/mesh.ts)); the first two encode a deformation model rather
-than a table of numbers, which is why they are code invoked by data. The last two
-are geometry: they pin every vertex to the slot bone and exist to give a
-`deform` timeline (§4.12) somewhere to push. A generator
-is for a skeleton with **no** manifest; a cut that has one invokes the same
-builders through the manifest's `mesh` block.
+than a table of numbers, which is why they are code invoked by data. `contour`
+and `grid` are geometry: they pin every vertex to the slot bone and exist to give
+a `deform` timeline (§4.12) somewhere to push. `segments` is both at once — a
+lattice traced off the art, weighted by distance to the bones you name. A
+generator is for a skeleton with **no** manifest; a cut that has one invokes the
+same builders through the manifest's `mesh` block — except `segments`, which has
+no manifest spelling and is reached from a rig spec only.
 
 🚨 **A rig that invokes a generator must declare `invariants.meshSlots` (§3.7).**
 Geometry rigc built is geometry rigc will not ship **unmeasured**: a generated
@@ -2256,6 +2295,130 @@ influence through that bone's own inverse, so the **angle** a raised surface tur
 through and the **impact** a soft one answers sit on one slot. ⚠️ Read §4.11.1 before you add a mask to a part that already turns:
 past one bone the model's own coordinates are **world** ones, so `radius` and
 `about` change units.
+#### `segments` — a lattice over the art, weighted by distance to the bones you name
+
+**When you need one:** an arbitrary layer that a chosen set of bones should
+pull — a robe over a chest, a hip and two legs; a head of hair over a skull and
+three locks; a sleeve under an arm chain. None of the other generators fits
+that: a `ribbon` needs a strip, a `ring` an aperture, and `contour`/`grid` pin
+everything to one bone. Without this, every pipeline weights such a layer
+itself and transcribes the result into authored `weights`.
+
+⭐ **Its inputs are the one decision, and everything else is derived.** What
+you decide is **which segments may pull the part**. The lattice is read off
+the attachment's own `image`, each segment off the skeleton's setup pose, and
+every weight off the distance between a vertex and those segments — so the
+only thing in this block that is a judgement is `bones`, and the numbers
+beside it say how a distance becomes a share.
+
+```json
+"invariants": { "meshSlots": 1, "meshTriangles": 200 },
+"skins": {
+  "default": {
+    "robe": {
+      "robe": {
+        "type": "mesh",
+        "image": "robe.png",
+        "generator": {
+          "kind": "segments",
+          "cell": 24,
+          "bones": ["chest", ["skirt_0", "skirt_1", "skirt_2"],
+                    { "bone": "hip", "from": [20, 180], "to": [220, 180] }],
+          "falloff": { "power": 2, "radius": 10, "maxBones": 4, "minWeight": 0.03 },
+          "anchor": [120, 96]
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `cell` | **required.** The lattice's square, in the part's pixels — a whole number of at least 1. No default: it is a length on this art, and how fine a mesh the part needs is not something rigc can read off it |
+| `bones` | **required, at least one entry.** Which segments may pull the part. An entry is one of three forms, below |
+| `falloff` | **required**, because `radius` is: `{ "power"?, "radius", "maxBones"?, "minWeight"? }` |
+| `radius` | **required.** Added to every distance before the power is taken, in the part's pixels, so a vertex ON a segment has a finite pull and the blend between two segments is about this wide. Positive |
+| `power` | the exponent a pull falls off by: `w = 1 / (d + radius)^power`. Positive. Default `2` |
+| `maxBones` | at most this many bones pull one vertex — the strongest ones. A whole number of at least 1. Default `4` |
+| `minWeight` | a share under this is dropped, and the kept shares normalised again. In `0.000001`..`1`, 1 excluded. Default `0.03` |
+| `alpha` | the alpha at or above which a pixel counts as art, `1`..`255`. Default `1` — `contour`'s own |
+| `anchor` | where the **slot bone** sits in the part's pixels, `[x, y]`, y down. Default the window's centre — the placement every generator on this route uses (the ⭐ above). State it when the art is not drawn centred on its bone: unlike a pinned generator, this one's weights depend on where the art is relative to the bones |
+
+**The three forms of a `bones` entry**, each resolved by name against the rig:
+
+| Entry | Its segment(s) |
+| --- | --- |
+| `"chest"` — a bone | from the bone's origin to its **`length` tip**, along its setup rotation. A bone with no `length` has an origin and no segment, and is refused |
+| `["skirt_0", "skirt_1", "skirt_2"]` — a chain, root first | one per link: each link from its origin to the **next link's** origin, the last from its origin to its `length` tip. Each link must be a descendant of the one before it — the list is the chain's order, which is `ribbon`'s `chain` convention |
+| `{ "bone": "hip", "from": [x, y], "to": [x, y] }` — a span | exactly that segment, in the part's pixels, y down, pulling for `bone`. For a line no bone's own span describes — a hip pulling across a waist, or two meshes over one bone that each want it along a different line. `from` equal to `to` is a point |
+
+A bone named by two entries keeps the **stronger** of its pulls, and ties
+between bones keep the order they are first named in.
+
+**What it does, in order:** a lattice of `cell`-pixel squares over the part,
+the last column and row clipped to the image; a cell is kept when any pixel in
+it reaches `alpha`, so the triangles cover **every** art pixel. Then the kept
+cells are made **one closed outline**: holes filled, every other island joined
+to the largest by a straight run of cells, every diagonal pinch filled,
+repeated until a pass changes nothing. That is the case the *"the triangles'
+outline is not one closed loop"* refusal (above) would otherwise fire on — a
+layer the alpha splits in two is still one attachment — and the cells the join
+adds hold no art and draw nothing. Two triangles per cell, the diagonal
+alternating so the lattice has no preferred shear, the outline walked first
+(`hull` is the outline's vertex count), and the uvs are the lattice points over
+the image size. Then, per vertex, `1 / (d + radius)^power` to the nearest point
+of each segment, the strongest `maxBones` kept and normalised, any share under
+`minWeight` dropped, the rest normalised again — so every vertex closes at 1 by
+construction. The emitted mesh is a weighted one, bound by name.
+
+`build` and `explain` print what it measured, under the mesh's line. This is
+the selftest's own `segments_probe` (`fixtures/public.ts` in the repository) —
+one 96x64 plate of two islands under two two-link chains, `cell: 8`,
+`radius: 4`, `maxBones: 3` — as `build` prints it:
+
+```
+  MESH  cloth        segments 72 vertices / 100 triangles  (budget 200)  bones=[left_0, left_1, right_0, right_1]  attachments=[cloth]  covers 100.00% of the art, reaching 8.00px past it
+        influence  max 3 bone(s) per vertex, mean 2.61, 4 of 72 vertices (5.56%) on a single bone
+        lattice    cell 8px, 12x8 cells, 48 with art, 50 kept (2 island(s) joined into one outline, 2 cell(s) added that hold no art)
+```
+
+The `influence` line is the falloff's report: the most bones any vertex binds
+(read it against `maxBones`), the mean, and how many vertices one bone owns
+outright. A named bone that **no** vertex binds is listed there by name — it is
+in no weight, so no other figure moves — and under `--profile spine-html`
+`A20_MESH_WEIGHTS_COHERENT` refuses it as a declared bone nothing binds. The
+`lattice` line says how many cells had art and how many were kept, and when
+islands were joined, how many and how many cells the join added. The coverage
+figure is §3.4's authored-mesh one: 100% by construction, and the reach past
+the art is the lattice's own — up to a cell past the silhouette, and a join run
+across a gap (the 8.00px above is the two join cells).
+
+🔸 **What the gate does with it.** `A20`'s coherence rules and both of its
+generator-policy branches apply in full. `A21_MESH_RIM_PINNED` **SKIPs** on a
+segments mesh, by name: its outline is weighted by distance like every other
+vertex, because a layer pulled by named bones is *supposed* to move at its
+edge, so "the rim is pinned to the slot bone" is not a claim it makes.
+`A28_RIBBON_ROWS_SHARE_WEIGHTS` skips it too — a lattice has cells, not cross
+rows.
+
+**Stated limits, each a named refusal rather than a mesh that loads wrong:**
+
+| The input | What you get |
+| --- | --- |
+| a bone the rig does not declare | `"bones"[0][1] names mesh bone "nobody", which is not in the rig's bone list` |
+| an empty `bones` | `the "segments" generator names no bones. "bones" is the one decision this generator takes …` |
+| a part whose alpha keeps no cell | `no pixel of the 96x64 part reaches alpha 1, so a lattice at cell 8 keeps no cell — there is no art to cover` |
+| `minWeight` at or above 1, or under `0.000001` | `"falloff.minWeight" is 1; … at 1 or above every share is dropped, and under 0.000001, one step of the 6-decimal grid weights are written on, a kept binding could be written as 0` |
+| `maxBones` under 1 | `"falloff.maxBones" is 0; it is how many bones may pull one vertex, a whole number of at least 1` |
+| a vertex every one of whose kept shares is under `minWeight` | `vertex 0, at (0, 0) in the part's pixels, keeps no bone — the 4 strongest pull(s) share it as … and every one is under "minWeight" 0.3` — **refused, not handed the largest.** A bone the falloff dropped is a weight nobody decided; the message names the fix, a `minWeight` at or under `1 / maxBones`, which the strongest share can never fall below |
+| a bone with no `length` named alone, or as the last link of a chain | `names bone "body", which has no "length", so it has an origin and no segment` — give it a `length`, put it inside a chain, or state a span |
+| a chain whose next link is not beneath it | `chains "right_0" to "left_1", and "left_1" is not under "right_0" in the bone tree` |
+| a chain link at its next link's origin | `… the two bones share their setup origin (…), so the link has no length and no direction to weight along` |
+| an empty chain, a span with a malformed end, an entry of none of the three forms | `is an empty chain`; `both ends are [x, y] in the part's pixels`; `an entry is a bone name, a chain as a list of bone names, or { "bone", "from", "to" }` |
+| no `falloff`, a `radius` or `power` at or below 0, a malformed `anchor`, a `cell` under 1, no `image` | each named by its field — `radius` has no default because it is a length on this art |
+| a part on a packed page that declares a `scale:` | refused: `cell` and `radius` are the part's pixels and this generator does not convert them to a page's texels. Build from the loose part, or a pack at scale 1 |
+
 #### 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
@@ -2591,7 +2754,7 @@ that lists it — see §3.4.1, and note that the flag alone does nothing.
 that is deliberate. Every key on a constraint object is a Spine field the emitter
 writes; a statement to the gate about who turns the dial is what the artifact cannot
 say about itself, so it lives in `invariants.consumerDrivenMix` (§3.7), beside
-`deformMayFold` — the one other exemption from a named rule, which names its subject
+`deformMayFold` — another exemption from a named rule, which names its subject
 the same way.
 
 #### 3.5.1 `path` — bones that travel along a curve
@@ -3105,7 +3268,7 @@ is not an array. Every field is optional and each is the payload a firing
 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`, `deformMayFold`, `editorRoundTrip`,
-`consumerDrivenMix`.
+`consumerDrivenMix`, `idleDrivesMeshes`.
 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
@@ -3141,8 +3304,8 @@ loads and still animates and merely lies — something released into the world t
 must not ride the part that released it. [RIGGING.md](RIGGING.md) §10.3 has a
 worked one.
 
-🚨 **`deformMayFold` is one of the two fields here that turn a check OFF**
-(`consumerDrivenMix`, below, is the other), so it is held to a shape that is
+🚨 **`deformMayFold` is one of the three fields here that turn a check OFF**
+(`consumerDrivenMix` and `idleDrivesMeshes`, below, are the others), so it is held to a shape that is
 refused rather than skipped. It is
 `[{ "slot": …, "why": … }]`, it exempts that slot from
 `A39_DEFORM_KEEPS_TRIANGLE_WINDING`, and three shapes are compile errors: a slot
@@ -3216,6 +3379,37 @@ spelling of `gallery/look`'s rule that a face angle is a value rather than a tim
 - What it buys is a **SKIP by name, never a pass** (§4.12 has the line). The
   declaration is a statement to the gate and changes no emitted byte.
 
+🎨 **`idleDrivesMeshes` says this rig's `idle` deforms meshes on purpose.** It is
+`{ "why": … }`, and it switches off `A15_IDLE_NO_MESH_BONE_KEYS` (§5.2). That rule
+assumes meshes are **mostly static**: the `spine-html` renderer skips redrawing a
+mesh nothing moved, so an `idle` keying a mesh's bone spends that skip on every
+frame. A **painting rig** is the genre where that is false by design — one
+illustration split into layers, most of them weighted meshes over bone chains, and
+an `idle` whose job is to move them (hair, sleeves, breathing). Without the field,
+the only way through is a parent bone above every keyed bone with the keys moved
+onto it: on the first such rig that was 42 extra bones for an identical pose.
+
+- Four shapes are compile errors, each naming `invariants.idleDrivesMeshes`: a
+  missing `why`, a blank one, one that is not a string, and anything that is not
+  an object (a bare `true` included, since it is a switch with no reason). A key
+  other than `why` is refused like any unknown key.
+- What it buys is a **SKIP, never a pass**, and the SKIP states the cost —
+  the keyed bones (all of them up to eight, then the first eight and `+k`), the
+  mesh attachments they drive and the vertices those hold, counted from each mesh's
+  loaded `worldVerticesLength`: `declared by the rig ("<why>"): idle keys N bone(s)
+  that drive M mesh attachment(s) totalling V vertices — "a", "b" — and each of
+  those meshes is recomputed on every frame it is shown`. "Drive" is A15's own reading: the mesh's slot bone, or a bone its weights name.
+  A mesh under a keyed bone's *descendant* also moves and is not counted, so the
+  figures are a floor.
+- ⛔ **A declaration nothing exercises is refused at the gate**, not skipped: an
+  `idle` that keys no mesh-driving bone, carries no bone timeline, or does not
+  exist fails A15 with `the rig "X" declares invariants.idleDrivesMeshes ("…"),
+  but "idle" keys no bone that drives a mesh, so the declaration switches off
+  nothing — remove it`. That is the `consumerDrivenMix` standard: an opt-out that
+  exempts nothing reads exactly like one that worked.
+- ⚠️ A15 is a renderer rule, so under `--profile spine` it reports `PROF` and the
+  declaration is not read at all, stale or not.
+
 ---
 
 ## 4. The motion spec, field by field
@@ -5487,20 +5681,20 @@ Fix A00 and run it again.
 | `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 — 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) **SKIP** also when the rig budgets **only** triangles and the skeleton carries no mesh. A declared slot budget still PASSes there, because zero mesh slots is a count measured against a ceiling |
 | `A14_NO_FULL_FRAME_MESH` | renderer | a mesh spans the whole stage — a full-frame canvas that can never dirty-skip. **SKIP** when the skeleton declares no stage (§3.1): there is no full frame to span, and *unmeasured* must not print the same green as *measured and clear* |
-| `A15_IDLE_NO_MESH_BONE_KEYS` | renderer | the `idle` animation keys a bone that drives a mesh, directly or as a control bone. **SKIP** when there is no `idle` animation, or when the one there is carries no bone timeline — a rule whose subject does not exist is unmeasured and not satisfied |
+| `A15_IDLE_NO_MESH_BONE_KEYS` | renderer | the `idle` animation keys a bone that drives a mesh, directly or as a control bone. The rule assumes meshes are mostly static — the renderer skips redrawing a mesh nothing moved — so it has three states. **FAIL per bone** when the rig declares nothing: `idle keys bone "X", which drives a mesh — meshes never idle-skip`, and the **first** of those lines, once per run, names the case: `K bone(s) keyed by idle drive meshes; if this idle is meant to deform them (a painting rig), declare invariants.idleDrivesMeshes: { "why": … } in the rig spec — or, where the motion belongs to a pivot above the mesh, key that pivot one link up (FACE.md §3)`. It rides the first finding, so the count of FAIL lines is still the count of bones. **SKIP with the cost** when the rig declares `invariants.idleDrivesMeshes` (§3.7): `declared by the rig ("<why>"): idle keys N bone(s) that drive M mesh attachment(s) totalling V vertices — "a", "b" — and each of those meshes is recomputed on every frame it is shown`. **FAIL on a stale declaration** — declared, and the `idle` keys no mesh-driving bone, carries no bone timeline or does not exist: `the rig "X" declares invariants.idleDrivesMeshes ("…"), but "idle" keys no bone that drives a mesh, so the declaration switches off nothing — remove it`. Otherwise **SKIP** when there is no `idle` animation, or when the one there is carries no bone timeline — a rule whose subject does not exist is unmeasured and not satisfied |
 | `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`) |
 | `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out`. **SKIP** when the atlas declares no page — as it is for `A06`, `A19` and `A27`; see `A07` |
 | `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 cannot draw a transparent pixel, so it would paint a solid rectangle over what is behind it. **The texels decide, on both routes**; the file header is only the fast negative. A file with no alpha channel (colour type 4 or 6) and no `tRNS` chunk has nowhere to keep a clear texel and is refused without being opened, by a sentence that names its colour type — so re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. A file whose header says it **could** be transparent is opened and read until its first texel below full alpha; one clear texel passes, and none is refused in the words the packed route uses for a region, naming the file and what it can hold — `is opaque in every one of its 200x80 texels` … `its file can hold transparency — colour type 6 (truecolour + alpha) carries an alpha channel — and no texel uses it`. Saving as RGBA is not the repair: the runtime draws the texels, not the declaration. On a loose page the file is the part, so the whole decoded image is the rectangle and no atlas coordinate is read. Only the base plate may be opaque, and which image that is is decided once for both routes: the plate the build names — on a cut manifest, the part whose window is the crop — and, only when it names none, an image at least the stage's size. The rig's statement comes first because the two can disagree: a stage stated small enough for an overlay to cover would otherwise exempt that overlay. A rig spec cannot name a base plate, so a stageless rig-spec build, and `validate <dir>` on a stageless skeleton, has nothing to decide it; an opaque part there is refused with *"nothing here decides which image that is: this skeleton declares no stage size to measure one against"* and the two ways to decide it — a `skeleton` stage the plate covers, or a cut manifest (for `validate`, the specs it was built from: `--rig`, `--motion` and the `--manifest`). Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art. ⚠️ **That scan states its verdict over the texels it READ, and never over texels that are not on the page**: a rectangle partly on its page is judged over the part that is on it, and the message carries both counts — `opaque in every one of the 77 texels of its 12x8 rectangle at -1,-1 … the other 19 of the 96 it declares are not on the page and are not measured here`. A rectangle with **no** texel on the page is reported **not measured** by name — the region, its rectangle, the page image's size, and the pointer to `A06`, which is the rule that judges a region's rectangle — and no verdict about opacity is printed at all. ⚠️ **A page whose IMAGE is not the size the atlas declares for it is the same non-measurement for every region on it**, and the clause above does not cover that case: a page rescaled after packing leaves most rectangles partly on it, at coordinates that address a different part of the picture, so a scan would come back with a confident verdict over texels nobody had located — on a two-region pack at a uniform 0.5 an opaque part's failure **disappears**, the scan finding a transparent texel 32 texels away from it. The row names the page's two sizes and points at `A06`, which judges the page grid and prints the header that repairs it (§0.2). It stays a failure rather than becoming a SKIP because a SKIP is per ASSERTION: it would delete the verdicts on every other part of the same page, and an assertion cannot be skipped and failed at once without the report counting it twice. ⚠️ **A page file that cannot be read as PNG at all is the same non-measurement for every part on it**: one row per page naming its parts and pointing at `A06`, which names what the file is. **SKIP** when the atlas declares no page |
-| `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not. Fix the rig spec's `controls`/`chain`, or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment |
-| `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 |
+| `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not. Fix the rig spec's `controls`/`chain`, a `segments` generator's `bones` (its `influence` line names a bone no vertex binds), or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment |
+| `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. **SKIPs** by name on authored or linked geometry and on a `segments` mesh, whose outline is weighted by distance like the rest of it — none of them claims a pinned rim |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count. **SKIP** when the skeleton carries no mesh attachment |
 | `A23_PHYSICS_CONSTRAINT_EFFECTIVE` | both | a physics constraint that drives no component, rests at `mix: 0` with **no timeline in any animation keying that `mix` above 0**, has `mass: 0`, has `strength` at or below 0 — `0` says `nothing pulls it back`, below 0 says the offset `is pushed away and grows with every step`, both read off the row's `outside` arms, which the key's refusal quotes too — or has `damping` outside `[0, 1]`, which says `` physics "C" has damping 1.5; must be inside [0, 1] — the per-step decay is `damping ** (60 * step)`, and the runtime runs this value finitely, so refusing it is rigc's call rather than the runtime's: above 1 every velocity grows on every step and the offset diverges ``, the bound read off the row the key's refusal reads; `1` and `0` are inside, since both are finite at every rate — **at rest, and on every physics timeline key**. The timeline arm reads each key through the runtime's own `PhysicsConstraint*Timeline.set`, so a keyed `mass` is judged as the `massInverse` it becomes, and the detail names the animation, the constraint, the key time, the value and the bound. Two differences between the two arms, and the runtime is the reason for both: a **key** of `mix: 0` is accepted, because `update` opens with `if (mix === 0) return;` and muting a constraint for a stretch is what a mix timeline is for — the editor's own `sack-pro` example keys it there on 24 of its 36 mix keys — and a **key** of `strength: 0` is accepted, because it releases the constraint for the span with `damping` and `inertia` still applied and the next key pulls the offset back, measured through spine-core at no NaN, a coast to a limit and a return in 54 steps. As a **setup** value `strength: 0` is still refused by the arm above, and `mix: 0` is refused only when nothing keys it above 0. The `mix` branch above is why `mix` is the one setup value a key can answer for: at rest the constraint is **inert** rather than broken, so a rig that rests muted and is keyed above 0 is refused by nothing, while a rig resting at `mass: 0` is `massInverse` Infinity before anything plays and no key reaches back into that. The detail of the refusal says both halves and how many animations were searched: `` physics "C" has mix 0 and none of the 3 animations keys its mix above 0; the runtime runs this value finitely, so refusing it is rigc's call rather than the runtime's: at 0 `update` returns before it does anything (`PhysicsConstraint.js:109-111`), so the constraint is muted — rest it above 0, or key its mix above 0 in an animation ``. ⚠️ Every reason A23 prints for a setup value is that value's row `basis` arm (§4.4's table) — an arithmetic arm names its expression (`physics "C" has massInverse Infinity; mass must be > 0 — at 0 …`), a behavioural one says it is rigc's call and what the value does. A setup `mix` **below** 0 is told the jiggle is applied inverted, not that it is muted: such a constraint is measured moving its bone by exactly the opposite of a positive mix. The search counts the unnamed global timeline for every constraint whose own `mixGlobal` is set, reads each key through the runtime's accessor, counts every sample of a Bezier between two keys as a value the timeline poses — so two keys of 0 joined by a curve lifted above 0 are a rescue, measured to move the bone — and takes an animation a slider applies like any other. It is the one reading `A36` and `A37` use as well. `inertia`, `wind`, `gravity` and the top of `mix` are bounded nowhere, at rest or keyed. `ingest` does not carry a constraint that drives no component into the spec it writes: it omits it with its timelines and reports `PHYSICS_DRIVES_NOTHING` ([INGEST §2.0](INGEST.md)), so this sentence is met on a file, never on a decompiled rebuild. **SKIP** when the skeleton declares no physics constraint — the same sentence `A36` and `A37` print for their own constraint types |
 | `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. **SKIP** when the rig declares no axis bone, and also when no animation keys that bone or anything under it |
 | `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 the rig's slot table — a slot is out of order, is not in the table at all, or is in the table and missing from the skeleton (§3.3). **SKIP** when the rig declares no canonical slot order. ⚠️ A skeleton with **no** slot beside a rig that declares some is **not** a skip, and it is the one rule in this family where an empty loop is not a vacuous pass: the completeness clause reads it as every declared slot lost and names them |
 | `A27_REGION_NAME_MATCHES_PAGE_FILENAME` | renderer | a single-region page whose region name is not the PNG's basename. **SKIP** when the atlas declares no region |
-| `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 |
+| `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, a contour mesh and a `segments` lattice — none 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 |
@@ -8307,8 +8501,9 @@ Per part:
 | `ambiguous` | at least one alternate is inside the ambiguity margin. **Choose with something this instrument cannot see** — anatomy, the other frame, or `rigc vote` |
 | `rotationFree` | the part is self-similar under rotation, so `rotationDeg` is a placeholder and the value is yours |
 | `rotationSelfSimilarity` | the number `rotationFree` is a threshold on. A part just over the line is worth a look |
-| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part`. A `no-match` whose best placement stopped **on a wall of the search window** names the wall in its detail — see §11.4 |
+| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part`. A `no-match` whose best placement stopped **on a wall of the search window** names the wall in its detail — see §11.4 — and every `no-match` with a placement ends with `legibility.reading` — see §11.5 |
 | `coarse` | the grid this part was actually searched on. A handful of cells means the part is small relative to the frame and the first pass had little to go on |
+| `legibility` | what the part gave the search to work with, and how its answers stood against each other — `null` only when nothing was searched. `width`, `height`: the material box, part px · `span`: its longest side at the best placement's scale, **frame** px · `opaqueShare`: alpha weight over the box's area · `texture`: the part's **texture figure** (§11.5) · `candidates`: distinct placements measured at full resolution · `best`, `next`, `spread`: the best residual, the second distinct one, and `next − best` (`null` with no second) · `floor`: `below` or `above` the measured floor (§11.5), on every part · `reading`: on a refused or ambiguous part, the sentence saying which of the two readings those figures support; `null` on a placed one |
 | `notes` | the same facts in prose, in the order they were found |
 
 Per placement:
@@ -8383,6 +8578,102 @@ holds nothing because it already contains every angle.
   with B — which placement of a repeated part belongs to which limb, across two
   frames — is the authoring job, not this tool's.
 
+### 11.5 Too small or too plain — the measured floor
+
+A refusal or an ambiguity has two readings the residual cannot separate: **the
+part is wrong**, or **the part is too small or too plain for `pose`** to pin
+down. A correct cut of a plain sleeve and a foreign part can end in the same
+verdict. So every searched part carries `legibility`, and a refused or
+ambiguous one ends with a sentence saying which reading its figures support:
+
+- **below the floor** — a 40x28 part of one flat colour, cut from a plain block it fits anywhere inside:
+
+  > part is 40x28 px (span 40 frame px, opaque 1) with texture 0, detail 0; 11 candidate(s), best 0.0000, next 0.0000, spread 0.0000 — below the measured floor (AUTHORING §11.5: detail 0.5, measured from 24 px up): pose placed 7% of the measured parts this plain, so this part is too plain for pose to tell its placements apart; that says nothing about whether the cut is right
+
+- **above the floor** — a 200x150 black-and-white checker the frame does not hold:
+
+  > loud.png: the best placement found has residual 0.5000, above --max-residual 0.25; part is 200x150 px (span 200 frame px, opaque 1) with texture 0.2473, detail 49.455; 2 candidate(s), best 0.5000, next 0.5000, spread 0.0000 — above the measured floor (AUTHORING §11.5: detail 0.5, measured from 24 px up), so size and texture do not explain this; the cut (or the search window) is the suspect
+
+Read the figures, not only the verdict. *Below* says plainness alone explains the
+failure: the cut may be right, and `pose` cannot tell. *Above* says it does not,
+so look at the cut, the `--scale`/`--rotation` window, or — for an ambiguity — at
+whether the frame really holds the part twice. ⚠️ Above the floor is **not** a
+promise that `pose` will place the part (see the rates below).
+
+**The texture figure.** `legibility.texture` is the mean colour step between
+neighbouring material pixels, `0..1`, in the residual's own units: each pair of a
+pixel and its right or lower neighbour, both with material, contributes its mean
+absolute channel difference over 255, weighted by the smaller alpha. A part of
+one flat colour reads exactly `0`. It is chosen over a colour variance because it
+is, to first order, **what a one-pixel shift costs**: a part whose residual
+cannot rise when it moves cannot be told from itself moved. The silhouette is not
+counted — the material term already reads it, and only where the frame is ground.
+
+**The floor**, measured with `bun tools/pose_floor.ts`:
+
+Found within 2 px of the truth, out of 15 trials per cell (free search, default windows):
+
+| texture level (mean) | 24 px | 32 px | 48 px | 64 px | 96 px | 128 px | 192 px |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `native` (detail 3.49) | 10/15 (5 amb) | 8/15 (6 amb, 1 wrong) | 11/15 (4 amb) | 9/15 (4 amb, 2 wrong) | 10/15 (4 amb, 1 wrong) | 10/15 (3 amb, 2 wrong) | 12/15 (3 amb) |
+| `blur1` (detail 1.58) | 9/15 (6 amb) | 9/15 (6 amb) | 10/15 (4 amb, 1 wrong) | 8/15 (5 amb, 2 wrong) | 11/15 (2 amb, 2 wrong) | 9/15 (2 amb, 4 wrong) | 9/15 (5 amb, 1 wrong) |
+| `blur2` (detail 0.59) | 6/15 (9 amb) | 9/15 (4 amb, 2 wrong) | 8/15 (4 amb, 3 wrong) | 7/15 (4 amb, 4 wrong) | 8/15 (2 amb, 5 wrong) | 6/15 (4 amb, 5 wrong) | 6/15 (4 amb, 5 wrong) |
+| `flat` (detail 0.00) | 0/15 (14 amb, 1 wrong) | 0/15 (14 amb, 1 wrong) | 0/15 (12 amb, 3 wrong) | 0/15 (11 amb, 4 wrong) | 0/15 (12 amb, 3 wrong) | 0/15 (12 amb, 3 wrong) | 0/15 (12 amb, 3 wrong) |
+
+The same trials, grouped by `detail`:
+
+| detail | found | ambiguous | wrong | refused |
+| --- | --- | --- | --- | --- |
+| under 0.25 | 8/119 | 87 | 24 | 0 |
+| 0.25–0.5 | 0/3 | 3 | 0 | 0 |
+| 0.5–0.75 | 46/81 | 15 | 20 | 0 |
+| 0.75–1 | 14/34 | 18 | 2 | 0 |
+| 1–1.5 | 19/25 | 3 | 3 | 0 |
+| 1.5–2 | 29/48 | 16 | 3 | 0 |
+| 2–3 | 27/44 | 14 | 3 | 0 |
+| 3–4 | 25/34 | 7 | 2 | 0 |
+| 4 and over | 17/32 | 14 | 1 | 0 |
+
+**Method.** The truth set is `examples/spineboy`: its setup pose and one frame of
+`walk` (a third of the way in). For every trial the figure is rendered twice with one
+viewport — whole on the renderer's ground (the pose frame), and one slot alone on
+transparency (the part, cropped to its own alpha) — so the truth is the crop's own
+offset at rotation 0 and scale 1, fitted by nothing. Slots with at least 75% of their
+material visible take part: 8 in the setup pose and 7 in the walk frame, which makes 15
+trials per cell. The size is set by the viewport, so the part's longest side is the
+column's size in frame pixels. The texture is set on the atlas region the slot samples,
+so the part and the frame carry the same plainer art: `native`; `blur1`/`blur2`, a box
+blur of 3% and 10% of the region's longest side; `flat`, one alpha-weighted mean colour.
+A trial is *found* when it is neither refused nor ambiguous and its centre is within
+2 px of the truth.
+
+**The figure the floor is stated in** is `legibility.detail` = `texture` × the material
+box's longest side in part pixels: the colour change a walk along the part
+accumulates. The per-pixel `texture` alone does not predict the outcome — an upscaled
+part has a low per-pixel gradient and still places — and size alone has no
+measurable effect across 24–192 px at any level.
+
+**The edge**, derived by `deriveFloor` as the largest rung of a fixed ladder under
+which at most a tenth of the trials were found: **`detail` 0.5**. Under it, **6.6%**
+of the trials were found (8/122); at or over it, **59.4%** (177/298). A part is below
+the floor when its `detail` is under 0.5, or when its own longest side is under 24 px,
+the smallest size measured (there, nothing measured says `pose` can place it).
+
+⚠️ **What this is and is not.** No cell of the grid placed 90% of its trials (the best
+placed 12/15), so there is no size and texture above which `pose` is reliable, and
+none is claimed. The failures above the edge are the same few parts at every size
+(the gun placed 10 of 42, the goggles 11 of 42), and they are search failures rather
+than plainness: on one of them the true placement scored a lower residual than the two
+wrong answers the search reported. All this was measured on **ideal cuts**, the frame's
+own pixels, where a residual at the truth is near zero. A generated cut also disagrees
+with its picture, which can only make it harder to place. So the edge is where `pose`
+fails even on ideal cuts, and never a guarantee above it.
+
+Re-run it with `bun tools/pose_floor.ts --textures <level> --json <out>` (one level per
+process parallelises it), then `bun tools/pose_floor.ts --from <a.json>,<b.json>,…` to
+print the table and derive the edge. `PO22` in `bun run selftest` re-measures three of
+its cells.
+
 ## 12. Reading the half of that picture `pose` refuses — `rigc chainfit`
 
 ```bash