spine-rigc 0.20.0 → 0.20.2

package/README.md

@@ -443,7 +443,7 @@ limits: [AUTHORING.md §11](docs/AUTHORING.md). The parts it refuses because
 something is drawn over them are `rigc chainfit`'s, once a candidate exists —
 [§12](docs/AUTHORING.md).
 
-## The gallery — six complete rigs over art that ships with them
+## The gallery — seven 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
@@ -460,6 +460,7 @@ was verified, and what writing it cost. Repository material: a clone and
 | [`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 |
 | [`gallery/portrait`](https://github.com/firejune/rigc/tree/main/gallery/portrait) | **deform `transform`** + `derive` group tracks | A 2.5D head turn: two meshes and six feature bones all keyed from one stated expression, `dx = x(cos t − 1) − z·sin t`, with the depths in the spec rather than a README |
 | [`gallery/nod`](https://github.com/firejune/rigc/tree/main/gallery/nod) | the **`pitch`** and **`wave`** transform kinds | A head bowing and two lop ears rippling, on three meshes each laid out for the closed form that moves it — a fold angle solved for before authoring, and a shear whose winding no amplitude can reverse |
+| [`gallery/look`](https://github.com/firejune/rigc/tree/main/gallery/look) | **`slider` constraints** | A head that turns because a **value** says so: two dials drive two sliders, and the rendered animation moves the needles rather than the face — with a depth map under the face mesh, a soft mask on the cowlick, and a slider range derived from the turn ceiling `build` reports rather than picked by eye |
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/rigc-scene.gif" alt="A portrait rig breathing, glancing aside, then turning its head in 2.5D — hair and features sliding at different depths" width="600" />

package/docs/AUTHORING.md

@@ -773,8 +773,13 @@ 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:
 
+```bash
+bun cli.ts build --rig gallery/squash/rig.json \
+                 --motion gallery/squash/motion.json --out /tmp/squash
+```
+
 ```
-  MESH  ball         authored 9 vertices / 8 triangles  (budget 8)  bones=[ball]  attachments=[ball]  covers 94.31% of the art, reaching 2.50px past it
+  MESH  ball         authored 9 vertices / 8 triangles  (budget 8)  bones=[ball]  attachments=[ball]  covers 100.00% of the art, reaching 15.00px past it
 ```
 
 **A number, not a bar.** A `contour` under 99.5% is *refused* because rigc
@@ -782,11 +787,17 @@ generated that geometry as a claim about the art; an authored mesh that sits ins
 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).
+there is nothing to measure it against.
+
+**The silence was worth closing, and that example is where it was found.** The
+ball is a centre vertex plus 8 rim vertices, and the first version placed them
+*on* the silhouette — but an octagon's sides pass `R · cos(π/8)` from its centre,
+so its whole ink outline between the spokes was not going to be drawn, and every
+assertion passed (issue #277). That is why the command above prints 100.00%
+rather than the figure it was filed over:
+[`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash)'s
+README carries the inradius arithmetic, both coverage readings, and the rim move
+that settled it.
 
 The generators are `ring`, `ribbon`, `contour` and `grid` (see
 [`src/mesh.ts`](../src/mesh.ts)); the first two encode a deformation model rather
@@ -1032,10 +1043,14 @@ triangle does not, and nothing on the first line says so.
 | `which is 0.049 of the range this mesh sampled` — the **same step, over the range this mesh sampled** | how much of everything the sheet said across the whole part it said across that one triangle. A form's slope is bounded, so this **halves every time you double the lattice** while the angle settles. Near 1 it is a **cliff**: a step with no slope in it, whose angle halves with the lattice instead and describes nothing at any density. Measured: `gallery/look` reads 0.112 and 0.468, a synthetic raised cosine 0.394 falling to 0.027 under refinement, the same cosine with one planted cliff a flat 0.50, and estimated depth sheets over cut-out art **0.92–0.99** |
 | `+none` | on the ceiling line, nothing folds on that side at all, at any angle. On the percentile line it is the same statement — there is no population, because there is nothing to take a percentile of |
 
-A real one rather than the illustration above — `bun cli.ts build --rig
-gallery/look/rig.json --motion gallery/look/motion.json --images
-gallery/look/parts --out <dir>`, whose two meshes happen to print two of the
-three spellings:
+A real one rather than the illustration above — `gallery/look`, whose two meshes
+happen to print two of the three spellings:
+
+```bash
+bun cli.ts build --rig gallery/look/rig.json \
+                 --motion gallery/look/motion.json \
+                 --images gallery/look/parts --out /tmp/look
+```
 
 ```
   MESH  head         grid     189 vertices / 320 triangles  (budget 320)  bones=[head]  attachments=[head]
@@ -1653,6 +1668,13 @@ rather than 1 s. With `loop: false` that is the last frame and harmless, with
 one — pick `to`/`scale` so the endpoint lands **inside** the duration rather than
 exactly on it.
 
+🖼️ **Worked example: [`gallery/look`](https://github.com/firejune/rigc/tree/main/gallery/look)** — a face
+whose yaw and pitch are two sliders sharing one bone, both `local: true` and both
+`additive: true`, with each range derived from the turn ceiling `build` reports
+for that mesh (§3.4) rather than chosen. [`docs/FACE.md`](FACE.md) §8's *The turn
+as a value rather than a time* states that derivation as a rule, and its §7 is
+what a slider does to a face's channel allocation.
+
 ### 3.6 `events` — names the animation can fire
 
 **When you need one:** something outside the skeleton has to happen on a
@@ -2082,6 +2104,7 @@ is not the arrangement the format has. Spine keys one bone per timeline, so the
 six numbers of a head turn are eighty lines apart in the artifact and nobody can
 see a wrong sign in them.
 
+**No run reproduces this:** the legend and one group's record lifted out of one `explain` run, which prints the two `bone "faceshift"` records between them
 ```
 group members  (the per-member values of one track, side by side — issue #295)
   ..    a row per member and a block per key, because a wrong sign is visible in a column of six and
@@ -2661,10 +2684,15 @@ makes against them.
 
 **It is auditable.** `explain` prints the model, the scalars the closed form
 derived from it, and every offset it produced — the emitted ones, not a second
-evaluation:
+evaluation. This is the `t=0.62` key of the spec above, whole:
 
+```bash
+bun cli.ts explain --rig gallery/portrait/rig.json \
+                   --motion gallery/portrait/motion.json --out /tmp/explain
 ```
-      t=0.62    deform[0..50]  25 pair(s)                      bezier[4]
+
+```
+      t=0.62    deform[0..50]  25 pair(s)                      stepped
                transform yaw  radius=170 degrees=12
                dx = (x−about)·(cos t − 1) − z·sin t,   z = √(radius² − (x−about)²)
                  t = 0.20944 rad
@@ -2673,9 +2701,19 @@ evaluation:
                  centre shift = −radius·sin t = -35.344987
                25 vertices, largest offset 35.344987px at vertex 2
                  v  0 (-7.17493, 0)  v  1 (-22.413595, 0)  v  2 (-35.344987, 0)  v  3 (-27.658171, 0)
-                 …five more lines
+                 v  4 (-14.255108, 0)  v  5 (-14.255108, 0)  v  6 (-14.255108, 0)  v  7 (-14.255108, 0)
+                 v  8 (-14.255108, 0)  v  9 (-27.658171, 0)  v 10 (-35.344987, 0)  v 11 (-22.413595, 0)
+                 v 12 (-7.17493, 0)  v 13 (-7.17493, 0)  v 14 (-7.17493, 0)  v 15 (-7.17493, 0)
+                 v 16 (-22.413595, 0)  v 17 (-35.344987, 0)  v 18 (-27.658171, 0)  v 19 (-22.413595, 0)
+                 v 20 (-35.344987, 0)  v 21 (-27.658171, 0)  v 22 (-22.413595, 0)  v 23 (-35.344987, 0)
+                 v 24 (-27.658171, 0)
 ```
 
+The curve reads `stepped` where the spec says `"ease": "swell"`, and that is
+§4.5's hold rule rather than a discrepancy: the next key emits these same 25
+offsets, so the segment between them would draw nothing and is written the way
+the editor writes it.
+
 📌 **Float behaviour, stated.** The closed forms are evaluated in float64 and
 quantised to six decimals like every other emitted number, so the same spec emits
 the same bytes and `A18_DETERMINISTIC_EMIT` proves it on a second compile. The
@@ -2701,6 +2739,7 @@ triangles. It is a report and it never gates: `explain` takes no `--profile` and
 exits 0 on a rig `build` would refuse, so the figures are readable on the build
 that is failing.
 
+**No run reproduces this:** abridged — the `WORST` rollup follows key 1 here, where the run prints `head/head`'s other two keys and all four of `hair_bang/hair_bang` between them
 ```
 deform  (what each key does to the geometry — figures with names, never a bar; issue #316)
   ..    every key measured at its OWN time against the same pose with the deform CLEARED, so the
@@ -2797,8 +2836,12 @@ clothes. The quantity that does move — how much art each drawn pixel now carri
 📘 **[FACE.md](FACE.md) §9.2** is this block on real art, as three builds of
 `gallery/portrait`: the good one, one with a band inverted, and one folded. The
 inverted build is the case worth reading — `A39` passes it (correctly: nothing
-reverses), and the block is what says `x1.362834` where the model's own table
-says `x1.319121`, with no reference render anywhere.
+reverses), and the block is what says `x1.362834` on the band the model's own key
+reports as `x0.637174`, with no reference render anywhere. ⭐ The comparison is
+per **triangle** and that is what makes it a reading: the block names one beside
+every ratio, so the two blocks can be lined up band against band instead of worst
+against worst — which on this build would have paired the inverted band with an
+untouched one and called the difference mild.
 
 📘 **[`gallery/nod`](https://github.com/firejune/rigc/tree/main/gallery/nod)'s
 README is a second reading of the same block** (repository material, hence the
@@ -2823,15 +2866,23 @@ the frames just before it are drawn, nearly folded, and land on no key at all. O
 the turn probe that is **8 reversed triangles at alpha 0.20, gating green**.
 
 ⇒ `A39` now scans every interval between two consecutive deform keys as well, and
-refuses one with its own sentence:
-
-```
-FAIL  A39_DEFORM_KEEPS_TRIANGLE_WINDING: animation "turn" deform head/head BETWEEN key 0
-      (t=0s) and key 1 (t=0.5s), at t=0.444089s — 88.8% of the way from one to the other:
-      8 of 32 triangle(s) reverse winding — triangle 0 [0,15,16] 1890.001 -> -272.314px²; …
-      NO KEY LANDS THERE: the runtime interpolates between the two keys, and the mesh is
-      inside out for part of the way, drawing its texture backwards at alpha 0.1118 …
-```
+refuses one with its own sentence. No spec this repository ships produces one — the
+rig it was written from is a probe `selftest.ts` generates and nothing else can
+invoke — so the sentence is described here rather than transcribed.
+
+**What it carries**, in the order it says it: `BETWEEN key <i> (t=…s) and key <j>
+(t=…s)` where a key refusal puts one index; the time the closed form solved for, and
+how far along the segment that is — or `(a stepped segment)` instead, which
+interpolates nothing and holds the earlier key's geometry across the span; the
+reversed count out of the triangle total, with the first four named and each one's
+vertex ids and its signed area before and after; `NO KEY LANDS THERE` in those words,
+then whether the runtime interpolates across the span or holds it; the alpha read at
+that same instant, present only where it is not 1; and the ways out — for an
+interpolating span the four the table below gives, the fade one among them only
+where the alpha is not 1, and for a stepped one the key it holds instead, with
+`invariants.deformMayFold` the last resort either way.
+[`src/validate.ts`](../src/validate.ts) builds it, beside the key sentence §4.11.2
+quotes.
 
 **What to change when you see it**, in the order worth trying:
 
@@ -2899,7 +2950,13 @@ value = from + (time − to) / scale         what A39 sets the dial to
 
 🔒 **The `DEFORM` block prints the frame on every key**, because the derivation
 changed and a block that went on printing the same figures under a changed meaning
-would be worse than the red it replaced:
+would be worse than the red it replaced. `gallery/look`'s `turn` is the animation
+a slider applies, and this is one of its keys:
+
+```bash
+bun cli.ts explain --rig gallery/look/rig.json \
+                   --motion gallery/look/motion.json --out /tmp/explain-look
+```
 
 ```
   DEFORM  turn  default/head/head  key 6  t=1.900000  transform yaw  depth=true degrees=19
@@ -3221,6 +3278,7 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 
 The report prints one line per assertion:
 
+**No run reproduces this:** assembled — one line of each verdict kind; the `PASS` and the `PROF` are verbatim from a `build` this page states, the `SKIP` is cut at the ellipsis and only `--profile spine-html` prints it, and the `FAIL` is invented, because a green build prints none
 ```
   PASS  A08_REGION_NAMES_MATCH_ATTACHMENTS
   SKIP  A21_MESH_RIM_PINNED: the skeleton has no weighted mesh attachment, …

package/docs/FACE.md

@@ -40,16 +40,25 @@ hold its results.
   measures §5's foreshortening at **0.863–1.176** against the yaw's 0.892–1.064
   below — a wider span at the same 12°, because a face is taller than it is deep.
   Read it after this page, not instead of it
-
-🚨 **Nothing in this toolchain measures what a `deform` key does, and that is the
-one gap you have to author around.** The setup geometry is measured and printed —
-coverage, overshoot, hole. The *deformed* geometry is not. A key that turns a
-mesh inside out gates green — **26 PASS on `--profile spine-html`, the same as
-the good build, and the same coverage line reporting the setup pose at
-100.00%.** §9.2 demonstrates that with three builds and §9.3 gives you the
-differential audit that works today;
-[issue #296](https://github.com/firejune/rigc/issues/296) is the instrument that
-would close it. Reference it, do not wait for it.
+- **The turn driven by a value instead of played as a time** — the same keys, on
+  an axis: §8's *The turn as a value rather than a time* derives the range,
+  **AUTHORING §3.5.2** is the `slider` constraint that does it, and
+  [`gallery/look`](https://github.com/firejune/rigc/tree/main/gallery/look) is
+  the worked case. Read it when the angle has to follow something outside the
+  animation — a pointer, a gaze target, a game value
+
+🚨 **A `deform` key's winding is gated; how far it moved the geometry is not, and
+that half is the one you have to author around.** Since 2026-09-03
+`A39_DEFORM_KEEPS_TRIANGLE_WINDING` refuses a key that turns the mesh inside out —
+by name, by key and by triangle — and the build writes nothing. What no assertion
+has an opinion about is **magnitude**: a band that stretches where the projection
+says it should compress keeps every triangle's winding, so it gates green, beside
+the same `MESH` coverage line as the good build, because coverage reports the
+*setup* pose. §9.2 is that pair as three builds of one rig — the good one, one
+wrong and green, one refused. For the half still ungated, `explain`'s `DEFORM`
+block prints each key's area and stretch ratios per triangle with no reference
+render (§9.2, AUTHORING §4.11.2), and §9.3 is the differential audit, the three
+things it cannot do, and the procedure that survives them.
 
 📐 **Where the numbers on this page come from.** Every figure marked **derived**
 is re-computed from the closed form in §1 and reproduces to the digits printed.
@@ -69,6 +78,7 @@ internal shape:
 | a face that **blinks**, **breathes**, **looks around** | ordinary MOTION.md tracks. A lid, a chest, an iris. Nothing on this page is needed |
 | a face that **turns** | a list of `(x, z)` — every part's position across the screen and its **depth** — plus one line of arithmetic evaluated at each of them |
 | a face that turns **far** (a three-quarter view) | ⛔ a different rig, and §8 says where the line is. Not a format problem: a parts-and-labour problem |
+| a face that turns **by however much something outside it says** — a pointer, a gaze target, a game value | the same list and the same arithmetic, reached by a **value** instead of by a playhead: the turn animation becomes a `slider`'s lookup table (§8's last subsection, AUTHORING §3.5.2). What changes is not the geometry, it is the range — which stops being a choice and becomes a measurement |
 
 ⭐ **The turn is the only part of a face that is not already MOTION.md's job**,
 and it is 90% of this page. A blink is a translating plate (§6); a gaze is
@@ -524,6 +534,7 @@ asked for.** The `MEMBER` block (AUTHORING §4.5.2) is a row per member — the
 emitted value, the `x` it read off the rig, and the depth the spec stated — so the
 nose diagnostic below is now a line you read rather than arithmetic you redo:
 
+**No run reproduces this:** abridged — the five derivation lines the run prints between this record's head and its rows are cut; AUTHORING §4.5.2 quotes them
 ```
   MEMBER  turn  group "features".translatex  t=0.620000  6 member(s)  derive yaw  degrees=12 carried=170  -> the displacement
             eye_l       5.513083  <- -62 at depth 150
@@ -746,8 +757,7 @@ shows the listing beside the order.
 over an oval face has transparent corners, and the line says so:
 
 ```
-MESH  head  authored 25 vertices / 32 triangles  (budget 32)  bones=[head]
-            attachments=[head]  covers 100.00% of the art, reaching 95.90px past it
+  MESH  head         authored 25 vertices / 32 triangles  (budget 32)  bones=[head]  attachments=[head]  covers 100.00% of the art, reaching 95.90px past it
 ```
 
 **`covers 100.00%` is what matters** — nothing of the drawing is outside the
@@ -923,6 +933,22 @@ stack (`headroll_idle` under `headroll_layer`) — but both are runtime or rig
 decisions the motion spec cannot express, so nothing warns an author that two of
 their animations will fight.**
 
+🚨 **A `slider` is a third way for two animations to meet on one property, and it
+is an overwrite rather than a blend — so allocate it in this table too.** An
+animation a slider applies (AUTHORING §3.5.2) is never on a track: the constraint
+applies it every frame, at whatever time its own bone currently points at. At
+`mix: 1` with `additive` left at its default that apply **writes the property
+outright**, which erases both any earlier slider on the same property and the
+**playing** animation on the bones its animation keys — including at its own
+neutral, where it looks switched off. ⇒ Every face axis that shares a target
+declares `"additive": true`, and unlike the two collisions above this one **is**
+gated: `A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET` names the bone, the property,
+every slider keying it in array order and which one wins today. ⛔ The one case
+`additive` cannot rescue is a **slot colour, an attachment swap, a draw order or
+a sequence**: those timelines ignore the flag entirely, so a fade — §8's way of
+taking a part off the screen before its own ceiling — belongs *inside* the single
+animation one slider applies, never in a second slider beside it.
+
 ⛔ **And the cost is real, so name it rather than discovering it by shipping.** In
 the worked example `idle` keys **nothing** on the iris, on purpose, even though a
 completely still eye reads as a mannequin. The iris is `gaze`'s channel; an
@@ -1057,6 +1083,111 @@ authoring concept**: the on-axis pair's shared `cos t` now falls out of the same
 closed form as everybody else's value, so `axis` is gone from the spec while
 `look_l`/`look_r` stay — because those two really are one shared number (§5).
 
+### The turn as a value rather than a time
+
+Everything above prices a turn as an animation somebody plays. The same geometry
+also runs on an **axis**: a `slider` constraint reads a driving bone, maps that
+bone's rotation to a time inside the turn animation, and applies the animation
+there (AUTHORING §3.5.2). Nothing in §1–§5 changes — the keys are still §1's line
+evaluated at each angle — but what selects among them is a **value** rather than a
+playhead, so the face follows a number somebody else is holding: a pointer, a gaze
+target, a game state.
+
+⭐ **The object offers a dial and does not decide when it turns.** That is the
+whole of the claim and it is deliberately not a larger one: what the rig
+guarantees is the axis — its range, its arithmetic, and that every angle on it is
+sound — and what moves the dial belongs to whoever is using the face. The
+paragraphs below are the part that is ours.
+
+#### The range stops being a choice and becomes a measurement
+
+This is the half an author has no other way to get right. §4.2's fold angle is not
+a rule of thumb once the angle is a dial position: it is the **top of the dial**,
+because past it a triangle turns inside out and `A39` refuses the build by name.
+`build` prints that angle for every depth mesh it compiles (AUTHORING §3.4), so
+the whole mapping falls out of one reading:
+
+```
+ceiling    the largest turn this depth mesh admits — printed by `build`, not guessed
+range      the largest whole degree strictly INSIDE the ceiling
+from       -range        max  +range        local  true   (AUTHORING §3.5.2's circle)
+scale      seconds per degree — the one number here you choose
+duration   2 x range x scale
+time       to + (degrees - from) x scale    the slider's own mapping
+```
+
+📐 **Worked, on [`gallery/look`](https://github.com/firejune/rigc/tree/main/gallery/look)**,
+whose face is a 21 × 9 `grid` over one depth sheet:
+
+```bash
+bun cli.ts build --rig gallery/look/rig.json \
+                 --motion gallery/look/motion.json \
+                 --out gallery/look/build
+```
+
+```
+  MESH  head         grid     189 vertices / 320 triangles  (budget 320)  bones=[head]  attachments=[head]
+        depth "face_depth.png" bf156ea0cfc970a3 near=white zScale=194 z=[0, 194]
+        80 of 189 vertices sample a texel the part image does not draw — their z is the sheet's reading of somewhere the part is not
+        turn ceiling  yaw +19.32° / -19.32°   pitch +22.92° / -26.94°
+          1st pct     yaw +19.32° x1.000 of 80 / -19.32° x1.000 of 80   pitch +22.92° x1.000 of 102 / -26.94° x1.000 of 130
+                      first to fold: yaw + at 19.32°, triangle 174 [119,138,139], the sheet steps 28.50 level(s) across it, which is 0.112 of the range this mesh sampled
+```
+
+⇒ the ceiling is **±19.32°**, so the range is **19** — `floor(19.32)`, and
+*strictly inside* is the whole of the rule. At the **0.05 s per degree** that rig
+chooses, `turn` runs `2 × 19 × 0.05` = **1.9 s** and the map is
+`time = 0 + (degrees + 19) × 0.05`, which is the constraint as its rig spec
+declares it: `"from": -19, "to": 0, "scale": 0.05, "max": 19, "local": true,
+"additive": true`. ⭐ **The only two numbers there that anybody chose are `scale`
+and `to`** — and `to: 0` says nothing more than *the bottom of the range is the
+animation's first frame*. `from`, `max` and the duration are all the ceiling.
+
+🔸 **And `scale` is chosen for the endpoint.** rigc rounds every number it emits
+to six decimals, so a `scale` that is not exact there moves the top of the dial:
+`1/60` ships as `0.016667`, and a 60° turn then applies at 1.00002 s rather than
+1 s — the last frame under `loop: false`, the *first* under `loop: true`
+(AUTHORING §3.5.2). `0.05` is exact at six decimals, which is the only reason the
+example can put its endpoint exactly on the duration. Pick a `scale` that is not,
+and land the endpoint inside the duration instead.
+
+⚠️ **The ceiling is per mesh, and the face's is not the smallest one on the
+face.** The same run prints one for every depth mesh, and in this example each
+sidelock reads `yaw +17.04° / -45.80°`: it folds at **17.04°** on one side, which
+is *inside* the ±19° the face itself admits, and not until 45.80° on the other.
+The asymmetry is the sheet's, not a coincidence — each of those sheets is
+steepest at the edge where the strand curves away, and a yaw folds a pair of
+vertices only in the direction their depth is rising.
+
+⇒ **A part whose ceiling is lower than the range has to be gone before the turn
+reaches it.** That is AUTHORING §3.4's third way to live with a ceiling: fade the
+slot to alpha 0 **inside the animation the slider applies**, landing the alpha-0
+key *before* the key that folds rather than on it. §7's paragraph on sliders is
+why that fade cannot be a second slider.
+
+⭐ **A lookup table wants linear keys, and that is not a style note.** The slider
+makes the pose a function of the dial, so an easing curve between two keys makes
+it a **non-linear** function of a number the consumer may be holding perfectly
+still — the face would drift and settle while the value sits where it was put.
+Anticipation and follow-through fail for the same reason, not a weaker one
+(MOTION §3.6, §3.7): both are functions of time, and there is no time on this
+axis. [MOTION §0.1](MOTION.md) is that split written out, and it is also where the
+shaping *does* belong — in whatever animation moves the dial.
+
+⚠️ **Two axes on one face need `"additive": true` on both.** A `pitch` dial
+beside the `yaw` is the ordinary case and it is the one the format's default
+breaks the moment the two share a target — in the worked example both `turn` and
+`tilt` key `headroll`. §7's paragraph on sliders is the mechanism and
+`A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET` is the refusal.
+
+⚠️ **What none of this measures: the Spine editor.** No editor export in this
+repository carries a slider, so whether the editor preserves two of them, their
+`additive` and `local` flags, and their order in the constraints array is
+**unknown**. `tools/editor_roundtrip.ts` on a machine with a licensed editor is
+what would answer it, and until somebody runs it the editor half of a parameter
+axis is untested. The runtime half is not: every figure above came back through
+`spine-core`.
+
 ---
 
 ## 9. Looking at it, and the audit gap
@@ -1105,7 +1236,7 @@ problem — two eyes whose upper lash is heaviest at the **inner** corner read a
 angry whatever the brow above them does. Worth knowing before spending a pass on
 the wrong part.
 
-### 9.2 🚨 What nothing measures — three builds, all green
+### 9.2 🚨 The half nothing measures — three builds, one of them refused
 
 **The setup geometry is measured; the deformed geometry was not, and one half of
 it still is not.** Here is that
@@ -1123,11 +1254,15 @@ bun cli.ts render --candidate gallery/portrait/build --fps 25 --max 640 \
 ```
 
 ```
-  MESH  head  authored 25 vertices / 32 triangles  (budget 32)  bones=[head]
-              attachments=[head]  covers 100.00% of the art, reaching 95.90px past it
-  …  26 PASS, 13 SKIP
+  MESH  head         authored 25 vertices / 32 triangles  (budget 32)  bones=[head]  attachments=[head]  covers 100.00% of the art, reaching 95.90px past it
 ```
 
+Green, and the tally is left to the tool: `bun run selftest` prints this build's
+live assertion and skip counts on its `GALLERY_EXAMPLE_IS_GREEN[portrait/spine-html]`
+line. One written here would be a figure nothing in the tree compares against a
+run, sitting inside a fence that reads as a transcript — and rigc prints no tally
+line, so it never was one.
+
 Now break the projection two ways. Both scripts write a variant motion spec
 beside the originals and touch nothing in the repository:
 
@@ -1137,14 +1272,21 @@ beside the originals and touch nothing in the repository:
 #     the head reads as turning the other way at its own edge. This one has to
 #     REPLACE the transform with a table: an inverted band is not the closed
 #     form at any angle, and §1.1 refuses a `transform` beside a `vertices` run.
+#     Each vertex takes the shift for THE COLUMN IT IS IN, looked up in the rig:
+#     a `vertices` run is positional, so a script that assumes the list's order
+#     rather than reading it breaks in silence the day the list is renumbered.
 bun -e '
+const r = await Bun.file("gallery/portrait/rig.json").json();
 const m = await Bun.file("gallery/portrait/motion.json").json();
+const v = r.skins.default.head.head.vertices;
 const d = m.animations.turn.deform.find(x => x.slot === "head");
-const row = [-22.414, 0, -7.175, 0, -35.345, 0, -27.658, 0, -14.255, 0];
+const shift = {"-162": -22.414, "-120": -7.175, "0": -35.345, "120": -27.658, "162": -14.255};
+const run = [];
+for (let i = 0; i < v.length / 2; i++) run.push(shift[v[i * 2]], 0);
 for (const k of d.keys) if (k.transform) {
   delete k.transform;
   k.fromVertex = 0;
-  k.vertices = [...row, ...row, ...row, ...row, ...row];
+  k.vertices = run;
 }
 await Bun.write("/tmp/swapped.motion.json", JSON.stringify(m, null, 2));
 '
@@ -1172,15 +1314,33 @@ is a doc command silently passing rather than silently failing, which is the
 worse of the two: build (b) reported `A39 PASS` and the table below said `FAIL`.
 Both are re-run above.
 
+⚠️ **And script (a) broke a second time, the same way, on 2026-09-04.** It wrote
+one row of five shifts and repeated it five times, which was the mesh's own
+column order while the vertex list was row-major.
+[#375](https://github.com/firejune/rigc/issues/375) renumbered both gallery
+grids along their outline walk — perimeter first, then the interior, the order
+Spine's `hull` needs — and the row went on landing at the same *positions* in a
+list that no longer meant columns. The build stayed green and stayed wrong, so
+nothing on the page moved; what it stopped being was **an inverted band**, which
+is the one thing the table below reads it as. The figures in that table were
+right the whole time and the command under them had stopped producing
+them — a stale figure shows up at one site, and a broken command shows up at
+every figure it feeds, which is how the two are told apart: this one also
+contradicted §9.3's `check` row, `0.33 / 0.61` against a table saying
+`0.20 / 0.38`. ⭐ **The repair is the doctrine's own**: the script resolves each
+shift through the vertex's coordinate instead of its index, so the next
+renumbering cannot move it. A `vertices` run is positional by format — that is
+`fromVertex`'s whole job — and a *generator* of one has no reason to be.
+
 **What comes back from both:**
 
 | | good | (a) one band inverted | (b) mesh folded |
 | --- | --- | --- | --- |
-| `--profile spine-html`, **before `A39`** | 26 PASS / 13 SKIP | **26 PASS / 13 SKIP** | **26 PASS / 13 SKIP** |
+| `--profile spine-html`, **before `A39`** | green | **green, and the same counts** | **green, and the same counts** |
 | `A35_DEFORM_KEYS_FIT_THE_ATTACHMENT` | PASS | **PASS** | **PASS** |
 | the `MESH` coverage line | 100.00%, 95.90px past | **byte-identical** | **byte-identical** |
 | 🆕 `A39_DEFORM_KEEPS_TRIANGLE_WINDING` | PASS | PASS | **FAIL, both keys, 8 of 32 triangles** |
-| `--profile spine-html`, **today** | 27 PASS / 13 SKIP | 27 PASS / 13 SKIP | **26 PASS / 13 SKIP / 2 FAIL** |
+| `--profile spine-html`, **today** | green | green | **refused, and nothing written** |
 | 🆕 the `DEFORM` block, `head` key 1 `area` | x0.637174 … x1.319122 | **x0.765250 … x1.362834** | **x−0.288121 … x1.820211** |
 | 🆕 … and its `winding` | 32 of 32 kept | 32 of 32 kept | **24 of 32 kept** |
 
@@ -1193,22 +1353,46 @@ it mean anything.
 
 ⭐ **The two `DEFORM` rows are the ones that separate (a) from the good build**,
 and nothing else in the toolchain does that without a reference render. `A39` is
-right to pass (a) — no triangle reverses — and the block prints **x1.362834**
-where the model's own table says x1.319121, and **x0.765250** where it says
-x0.637174. That is this section's own prose, *"stretches 1.363 where it should
-compress to 0.637"*, as a figure the tool produces.
+right to pass (a) — no triangle reverses — so the whole of the difference is a
+pair of ratios, and the way to read them is to ask the tool rather than to copy
+them down:
 
-`rigc explain` is the instrument that prints every other timeline's actual values,
-and on a deform it used to print the shape of the run rather than the run:
+```bash
+bun cli.ts explain --rig gallery/portrait/rig.json \
+                   --motion /tmp/swapped.motion.json --out /tmp/explain-swapped
+```
 
 ```
-    default/head/head.deform  4 key(s)
-      t=0       back to the setup pose                         bezier[4]
-      t=0.62    deform[0..50]  25 pair(s)                      bezier[4]
-      t=1.5     deform[0..50]  25 pair(s)                      bezier[4]
-      t=2.2     back to the setup pose                         linear
+  DEFORM  turn  default/head/head  key 1  t=0.620000  authored table
+          frame      played on a track
+          moved      25 of 25 vertices, worst 35.3450px at v10
+          area       min x0.765250 tri 19   max x1.362834 tri 1   (32 triangles, 0 with no area at the cleared pose, band 0.146694px²)
+          stretch    max x1.362834 tri 1   min x0.765250 tri 26
+          winding    32 of 32 kept, 0 collapsed
 ```
 
+🚨 **Read it band by band, because the extremes have swapped ends and comparing
+worst to worst hides that.** The block names the triangle beside every ratio, and
+§4.1's table says what each band should be. `tri 1` spans **−162 → −120**, the
+band §4.1 puts at **0.637** and the good build's own block reports as
+`x0.637174 tri 17` — the same band, and here it comes back at **x1.362834**. That
+is this section's prose, *"stretches 1.363 where it should compress to 0.637"*, as
+a figure the tool produces, and it is the far edge turning the wrong way. `tri 19`
+spans **−120 → 0**, tabled at 0.892 and measured at **x0.765250**: the swapped
+column is the boundary between those two bands, so the compression the far band
+gave up lands next door. ⚠️ Read as min-against-min and max-against-max instead,
+the very same four figures say 1.319 → 1.363 and 0.637 → 0.765 — two comparisons
+across *different* bands, both of them mild, neither of them what happened. Only
+the two bands the swapped columns bound move at all: the 0 → 120 and 120 → 162
+bands still read **1.064** and **1.319**, exactly as §4.1 tables them. `authored table` on the key line is the other half of the diagnosis:
+the model is gone, so nothing is left to check the ratios against but the ratios.
+
+`rigc explain` is the instrument that prints every other timeline's actual values,
+and on a deform it used to print the shape of the run rather than the run: the
+head's four keys came back as four lines, each giving a time, a curve kind, and
+either `back to the setup pose` or `deform[0..50]  25 pair(s)` — the extent of the
+run and how many pairs are in it, and not one of the numbers.
+
 ⇒ **`25 pair(s)` was the whole of what `explain` would tell you about a face
 turn**, against a scalar track two lines up in the same report printing
 `value=-35.345`. That asymmetry is
@@ -1224,6 +1408,7 @@ bun cli.ts explain --rig gallery/portrait/rig.json \
 
 ```
   DEFORM  turn  default/head/head  key 1  t=0.620000  transform yaw  radius=170 degrees=12
+          frame      played on a track
           moved      25 of 25 vertices, worst 35.3450px at v2
           area       min x0.637174 tri 17   max x1.319122 tri 31   (32 triangles, 0 with no area at the cleared pose, band 0.146694px²)
           stretch    max x1.319121 tri 22   min x0.637175 tri 8
@@ -1299,13 +1484,13 @@ area is a *quadratic in the interpolation fraction* — the fold is a root of it
 solved for rather than searched, with no sample spacing anybody would have to
 defend. What that arithmetic names is then posed and measured by the same code
 that measures a key, **alpha read at that same instant**, so the fade a correct
-rig relies on is not refused and the frames it does not cover are:
-
-```
-FAIL  A39_DEFORM_KEEPS_TRIANGLE_WINDING: animation "turn" deform head/head BETWEEN key 0
-      (t=0s) and key 1 (t=0.5s), at t=0.444089s — 88.8% of the way from one to the other:
-      8 of 32 triangle(s) reverse winding … NO KEY LANDS THERE … at alpha 0.1118
-```
+rig relies on is not refused and the frames it does not cover are. The sentence names
+the two keys the fold lies between rather than one key index, the time it solved for
+and how far along the segment that is, the reversed triangles with their signed areas,
+`NO KEY LANDS THERE` in those words, and the alpha read at that same instant — so what
+it refuses is legible as a frame rather than as a key. AUTHORING §4.11.3 reads it field
+by field and [`src/validate.ts`](../src/validate.ts) builds it; no spec this repository
+ships produces one, the turn probe being `selftest.ts`'s own.
 
 ⇒ The rule this section gave — *fade out over the run up to the angle you cannot
 take, so that every key past the ceiling is one that draws nothing* — is
@@ -1371,9 +1556,9 @@ to call an audit:**
 
 📌 **`explain`'s `DEFORM` block (§9.2, AUTHORING §4.11.2) takes half of limits 1
 and 2 away, and none of limit 3.** It is reference-free, so it says something
-about a first authoring; and it is *per key*, so the band inversion above reads
-as `x1.362834` beside a model stating x1.319121 rather than as 0.20 of 255 in an
-aggregate. What it still cannot say is whether **12° was the angle the shot
+about a first authoring; and it is *per key and per triangle*, so the band
+inversion above reads as `x1.362834` on `tri 1` where the same band is `x0.637174`
+in the model, rather than as 0.20 of 255 in an aggregate. What it still cannot say is whether **12° was the angle the shot
 wanted** — that needs the picture, which is why the procedure below survives the
 block as it survived `A39`.
 
@@ -1458,8 +1643,8 @@ with no `build/`, `render/` or `preview.html` in that directory:
 
 | Command | What came back |
 | --- | --- |
-| `build --profile spine` | green — **18 PASS, 7 SKIP**, 14 excluded by profile |
-| `build --profile spine-html` | green — **26 PASS, 13 SKIP**, including `A13_MESH_BUDGET` and `A15_IDLE_NO_MESH_BONE_KEYS` |
+| `build --profile spine` | green, and the report names what the profile leaves out rather than this page counting it: `profile spine — 7 renderer-policy and 8 archetype assertion(s) do not apply` |
+| `build --profile spine-html` | green — `profile spine-html — every assertion applies`, `A13_MESH_BUDGET` and `A15_IDLE_NO_MESH_BONE_KEYS` among the ones the row above excludes |
 | both `MESH` lines | `head` **100.00%** covered, reaching 95.90px past the art; `hair_bang` 100.00%, 55.22px |
 | `render --fps 25 --max 640` | **81 + 39 + 56 frames**, 478×640, three contact sheets |
 | `loop_seam.ts` ×3 | **0 / 255**, **0 of 305 920 pixels** differing, for all three |
@@ -1523,6 +1708,22 @@ cost off the keyboard and onto the **parts**: per-eye meshes, a meshed neck, a
 second art layer for the far cheek (§8). Whether to pay *that* is a project's
 decision and this page does not make it.
 
+🚫 **No Live2D file is read or written, and none ever will be — a boundary
+rather than an unbuilt feature, and it runs in both directions.** rigc's inputs
+are a rig spec and a motion spec; its outputs are Spine 4.3 skeleton data and an
+atlas. There is no importer, no exporter and no converter for `.moc3`, `.cmo3`,
+`.model3.json` or anything else in that family, and nothing in this repository
+claims compatibility with that format in either direction
+([#399](https://github.com/firejune/rigc/issues/399) is where that was settled).
+⭐ **What is in scope is an authoring idea, stated on its own terms rather than
+as anybody's feature: that a face angle can be a value rather than a time.**
+§8's *The turn as a value rather than a time* is that idea on Spine's own
+`slider` constraint, and every mechanism under it is Spine's — the arithmetic,
+the flags, the readers and the failure modes are all in AUTHORING §3.5.2 and all
+measured against `spine-core`. ⚠️ Nothing on this page is a statement about how
+any other tool works inside, and nothing above implies one: what this repository
+has measured is its own format.
+
 🚫 **No per-eye mesh recipe.** §8 says the eyes need their own deform meshes past
 about 26°, and nobody has built that here. The column-placement arithmetic in
 §4.2 applies to any grid over any curved patch, so the tangent limit is the part

package/docs/INGEST.md

@@ -607,14 +607,11 @@ rigc validate examples/spineboy/export/spineboy-pro.json \
 rigc: green
 ```
 
-**Why it is worth a section anyway.** That line used to be two `FAIL`s:
-
-```
-  FAIL  A35_DEFORM_KEYS_FIT_THE_ATTACHMENT: … key 1: offset 1 is odd, so the run's x values land on y slots and back again
-  FAIL  A35_DEFORM_KEYS_FIT_THE_ATTACHMENT: … key 1: the run holds 147 numbers and the deform array is x, y pairs
-```
-
-and nothing was wrong with the data. `hoverboard-board` is an unweighted mesh with 148
+**Why it is worth a section anyway.** That line used to be two `FAIL`s on the same key —
+one for an **odd `offset`**, on the reading that the run's x values would land on y slots
+and back again, and one for an **odd-length run**, on the reading that the deform array is
+x, y pairs — and nothing was wrong with the data, so neither sentence exists in the tool
+any more. `hoverboard-board` is an unweighted mesh with 148
 floats; the key carries `offset: 1` and 147 values, covering `1..148` — the whole array
 minus a leading zero the editor trimmed. A trim can land on a y component, so an odd
 offset is what a trimmed run looks like, and Spine's own parser copies the run in at the
@@ -846,13 +843,12 @@ rig spec; the discipline is in what you check afterwards.
 `parent`, a slot's `bone`, a constraint's `bones` and `target`, a draw-order key's
 `slot`, an authored mesh's vertex `weights` — and, across the two files, the motion
 spec's `archetype` against the rig spec's `name`. That last one is the first refusal a
-rename produces, before anything else has a chance to go wrong:
-
-```
-rigc compile error: …/work/renamed/pendulum-rig.motion.json: motion spec names
-archetype "3-timing-and-spacing-ess" but the rig spec at
-…/work/renamed/pendulum-rig.rig.json is called "pendulum-rig"
-```
+rename produces, before anything else has a chance to go wrong: a `rigc compile error`
+naming the motion spec's path, the `archetype` that spec states, the path of the rig spec
+it was handed, and the `name` that rig actually carries — both sides of the mismatch in
+one sentence. [`src/compile.ts`](../src/compile.ts) builds it; the renamed copies this
+section works on are not committed, for the reason the Appendix gives, so the figure is
+described here rather than transcribed off one.
 
 ⭐ **A rename is therefore mostly safe by construction, and its failures arrive as
 sentences naming both sides.** That is the reason to do it in the specs rather than in

package/docs/MOTION.md

@@ -80,6 +80,52 @@ and the last hop is the one that matters: a `both-unacceptable` tie means **prop
 again from a different axis** (§4), not *nudge the same candidate*. §5 has the
 detail.
 
+### 0.1 When the axis is not time — an animation a `slider` applies
+
+⛔ **One shape of request does not normalise to the table above, and carrying it
+through §3 anyway produces a defect nothing on this page can measure.** A `slider`
+constraint (AUTHORING §3.5.2) applies an animation as a function of a **value**: it
+reads a driving bone's transform property, maps it with
+`time = to + (value − from) × scale`, and applies the animation at that time on
+every frame. What it applies is an ordinary animation in the motion spec — same
+tracks, same keys, the same `duration` — but **nothing plays it**. It is a lookup
+table, and `t` in it is a coordinate on the axis rather than a moment.
+
+⇒ **So the constructs in §3 that are functions of time are not available to it,
+and each fails in its own way rather than merely reading oddly:**
+
+| §3 construct | On an animation a slider applies |
+| --- | --- |
+| §3.4 slow in and slow out | an easing curve makes the pose a **non-linear** function of the dial. The consumer moves the value at one rate and the face moves at another, and at a value held still the pose is still whatever the curve says there |
+| §3.6 anticipation | places a counter-pose at a dial *position*, so the pose runs backwards while the value runs forwards. Nothing anticipates a number |
+| §3.8 overshoot and settle | there is no settle: at a held value the pose is what the table says at that value, indefinitely. An overshoot keyed past the extreme is just a wrong pose at the top of the dial |
+| §3.7 follow-through and the offset table | wants parts to arrive at different **times**. Here they differ by **amount** at every value, which is §3.7.1's construct and not this one |
+| §3.3 timing | the key times are the axis's own coordinates — one per angle, position or level the table states — so spacing them is choosing where to sample, not choosing a rhythm |
+
+⭐ **What is still this page's job is whatever moves the dial**, and that is an
+ordinary animation with §3 applying to it unchanged. The split is visible in the
+worked example: in
+[`gallery/look`](https://github.com/firejune/rigc/tree/main/gallery/look) the two
+lookup tables `turn` and `tilt` carry **no easing at all**, and `sweep` — the one
+animation there meant to be played — carries every `ease` in the file.
+
+```bash
+bun -e 'const m = JSON.parse(await Bun.file("gallery/look/motion.json").text());
+for (const [name, a] of Object.entries(m.animations))
+  console.log(name, (JSON.stringify(a).match(/"ease"/g) ?? []).length);'
+```
+
+⚠️ **And two of §4's candidate axes stop being axes.** *Anticipation* and
+*Termination* are both readings of how a movement is placed in time, so a ballot
+spread on either of them over a slider-applied animation is asking a person to
+choose between two wrong answers. The axes that survive are the ones about
+**amount** — *Part amount*, *Path*, *Key density* — because those are still
+readings of the value.
+
+📘 The face case is worked end to end in [FACE.md](FACE.md): its §8 derives the
+slider's range from the turn ceiling `build` reports, which is the one number on
+that axis an author cannot guess.
+
 ---
 
 ## 1. Prompt grammar — what a request is made of
@@ -259,6 +305,12 @@ would not exist even if the user had more pictures of the same two poses. Everyt
 below is therefore authored knowledge, and it is sourced the way AUTHORING §10 sourced
 the editor's conventions.
 
+⚠️ **All of it assumes the axis is time.** If what you are authoring is an
+animation a `slider` applies — a face angle, a dial, a suspension that compresses
+as the wheel rises — §0.1 is the exception, and it is not a small one: the easing,
+the anticipation and the overshoot below each produce a specific defect there
+rather than merely reading oddly.
+
 ### 3.1 Where these come from, and how each line is marked
 
 Two public bodies of material, and nothing else: **the twelve basic principles of

package/package.json

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

package/src/diff.ts

@@ -685,10 +685,20 @@ function diffAttachments(c: Json, r: Json): DiffSection {
     // The issue's diagnosis was that Spine's exporter omits `width`/`height`
     // when they match the atlas region, so a rigc rig — which always states
     // them (AUTHORING R1/R5) — could never agree. That is not what the corpus
-    // says: all twelve reference exports state a size on every one of their 168
-    // regions, so there is nothing for an atlas lookup to resolve and the
-    // `--atlas` plumbing the issue proposed would be dead code against every
-    // rung on the ladder.
+    // says: all twelve reference exports state a size on every one of their
+    // regions, and no region omits either field — so there is nothing for an
+    // atlas lookup to resolve and the `--atlas` plumbing the issue proposed
+    // would be dead code against every rung on the ladder.
+    //
+    // ⛔ No count on that claim, deliberately, and this was the fourth copy of
+    // the one issue #490 struck off `docs/LADDER.md`: nothing derives the
+    // figure — not the plainest reading, every `region` attachment under
+    // `skins` in the twelve `export/*.json` skeletons, and not counting by
+    // skin, by slot, by attachment name, by atlas path or by atlas region. The
+    // claim carries the argument without one, because it is universal and a
+    // single counterexample refutes it: after `bun run fetch-examples`, read
+    // the region attachments of those twelve files and check that each states
+    // both `width` and `height`.
     //
     // What the measure actually reported was the naming gap, a third time. It
     // was keyed by `skin/slot/attachment`, so it could never exceed the name