spine-rigc 0.20.1 → 0.20.3

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

@@ -564,6 +564,37 @@ behind it writes literal `x`/`y` instead.
 
 **R9 — Nothing is written until every assertion is green.**
 
+**R10 — The `animations` object is keyed in the editor's order, not in yours, and
+names that have no one order are refused.** Declare animations in whatever order
+reads best; the emit keys them codepoint-ascending. This is the one place rigc
+reorders anything you wrote, and it is not cosmetic: a `slider`'s animation is a
+**name** in JSON and an **ordinal** in the format's binary half, so an editor that
+re-sorts the object repoints every slider whose animation moved index — silently,
+in a file that still parses and still gates green (§3.5.2,
+[#535](https://github.com/firejune/rigc/issues/535)). Nothing else moves: each
+animation's own body is byte-identical either way, and every other collection is
+emitted in the order you gave it.
+
+⚠️ **Codepoint is not the editor's comparator.** The editor sorts **natural and
+case-insensitive** — measured, two rigs, one axis each:
+`Turn, sweep, wave` came back `sweep, Turn, wave`, and `turn10, turn2, zoom` came
+back `turn2, turn10, zoom` ([#539](https://github.com/firejune/rigc/issues/539)).
+Codepoint agrees with it on most names and not on all, so rigc emits codepoint and
+**refuses the sets where the two could differ**, naming the pair. The rule you have
+to hold is therefore about *names*, and it is three things:
+
+| Do not let two animation names differ | Because | Instead |
+| --- | --- | --- |
+| by **case** at the character that orders them (`Turn` against `sweep`, or `Turn` against `turn`) | folding the case reverses them, and a pure case tie is settled by a tie-break nobody has measured | pick one case for all of them, or change a letter |
+| by a **number** read two ways (`turn2` against `turn10`, `turn01` against `turn1`, `1turn` against `turn`) | as text `turn10` sorts first and as a number it does not; `01` and `1` are one number written twice | pad the digits to the same width — `turn02` beside `turn10` |
+| by a **separator** — anything that is neither a letter nor a digit (`wave_x` against `wavea`, `wave` against `wave-`) | a collator may treat `-` or a space as ignorable, and `_` sits *between* `Z` and `a`, so folding up and folding down order it oppositely | rename so the first character that differs is a letter or a digit |
+
+⭐ **Capitals and digits are not what is refused** — only pairs whose order turns
+on them. `Sweep, Turn, Wave, Zoom02, Zoom10` builds: every comparator puts those
+five in one order, so codepoint *is* the editor's order for them. A set with no
+such pair is safe under **every** candidate comparator, which is why rigc does not
+have to reproduce the editor's sort to know your rig is safe under it.
+
 ---
 
 ## 3. The rig spec, field by field
@@ -1442,6 +1473,35 @@ parser resolves it in a **second pass** over the constraints array, after the
 animations are read, and a miss throws `Slider animation not found`; rigc refuses it
 where the message can name both files.
 
+🔒 **And it is the one field an editor round trip can repoint under you, which is
+why R10 exists.** In JSON the reference is a name on both sides. In the format's
+binary half it is an **ordinal** — `constraint.animation = animations[readInt()]`
+(`SkeletonBinary`) — so an editor holding that ordinal writes back whichever
+animation now stands at the position. `gallery/look` went into a licensed editor
+(data version 4.3.26) as `turn, tilt, sweep` with `yaw -> "turn"` and came back
+`sweep, tilt, turn` with **`yaw -> "sweep"`**: a file that parses, gates green and
+applies the wrong animation. ⭐ Its second slider is what named the mechanism
+rather than a second casualty — `tilt` survived because it sat at index 1 in both
+orderings. rigc now emits animations codepoint-ascending so the editor's re-sort
+moves no index ([#535](https://github.com/firejune/rigc/issues/535)); on the same
+rig through the same editor that restored `yaw -> "turn"` and took the
+re-rendered mean absolute error from 10.4655 / 8.4961 / 8.7140 down to
+0.3035 / 0.0769 / 0.0588.
+
+⚠️ Codepoint is not the editor's own comparator — it sorts natural and
+case-insensitive ([#539](https://github.com/firejune/rigc/issues/539)) — so the
+emit is only its order for names no comparator can put two ways, and the rest are
+a compile error. **R10** has the three shapes to avoid.
+
+⚠️ **What that repair does not reach: names a codepoint sort and a friendlier one
+disagree about.** Every animation name in every editor-authored file this
+repository has is lowercase ASCII with `-` or `_`, so nothing measured here
+separates codepoint order from a case-insensitive or digit-aware one. Names
+differing only in case (`Turn` / `turn`) or carrying unpadded digits (`turn2` /
+`turn10`) are where the two could part, and there the hazard returns. Until
+somebody round-trips such a pair, **name animations so that every ordering anyone
+might use agrees** — one case, and digits padded or absent.
+
 ⚠️ **The fields of the model you did not choose are refused, not ignored.** The
 parser reads `time` only in the bone-less branch and `property`/`from`/`to`/`scale`/
 `max`/`local` only in the other, so the losing half would be data no runtime ever
@@ -1668,6 +1728,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
@@ -3266,6 +3333,7 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `skin "S": uses the long form … and also has a key "X"` | §3.4.1 — move the slot inside `attachments` |
 | `animation "A" keys "X" as a path constraint, but the rig declares it as a "slider"` | §4.12 — a timeline group resolves by name AND type; use the field named after the constraint's own type |
 | `animation "A": "position" is a path constraint timeline, and this track names no constraint` | §4.12 — put the name in `"path"` |
+| `N pair(s) of animation names have no one order: … "Turn" / "sweep" (case) — codepoint puts "Turn" first only because of letter case; folded, "sweep" comes first; rename one of them so nothing but case has to be compared` | **R10** — rename until no pair is left. The kind in brackets is which of the three it is: `case`, `number` (pad the digit runs to the same width) or `separator` (make the first character that differs a letter or a digit). rigc keys `animations` codepoint-ascending and the editor sorts natural and case-insensitive ([#539](https://github.com/firejune/rigc/issues/539)); on names where those can disagree, the editor's re-key repoints every slider whose animation moves index ([#535](https://github.com/firejune/rigc/issues/535)) |
 
 ### 5.2 Assertions — the gate
 
@@ -4810,6 +4878,39 @@ low figure as a miss — say in the log that the art did not carry them.
 `default`"* and *"bones are ordered so that the parent always comes before a child
 bone"* — [JSON format](http://esotericsoftware.com/spine-json-format). §3.4.
 
+🔬 **The editor re-keys every name-keyed OBJECT and leaves every ARRAY alone.**
+Read off its export of a rigc build (Spine 4.3.26, `gallery/look`): the
+`animations` object, a skin's 24 `attachments` slot keys and two animations' 16
+and 2 bone-timeline keys all came back sorted, while the 30 `bones`, 24 `slots`
+and 3 `constraints` — arrays — came back in the build's own order, element for
+element, and each slider kept its place among them.
+
+⚠️ **The order it sorts them into is natural and case-insensitive, not
+codepoint.** This paragraph said codepoint until
+[#539](https://github.com/firejune/rigc/issues/539) measured it: `Turn, sweep,
+wave` came back `sweep, Turn, wave` and `turn10, turn2, zoom` came back
+`turn2, turn10, zoom`. The corpus says the same thing and always did — of its 105
+name-keyed collections, 102 are consistent with a codepoint sort and **3 are
+not**: `spineboy-pro.json` keys `portal-flare9` *before* `portal-flare10`, which
+no codepoint sort produces. Every natural comparator reproduces all 105. (The
+population is every object the format keys by a name and that carries more than
+one key, deform blocks counted at each of their three levels;
+[`src/compile.ts`](../src/compile.ts) states it in full beside
+`editorAnimationOrder`, so the count can be re-taken rather than trusted.)
+⇒ in rigc: only `animations` is emitted sorted (R10), because it is the one
+object measured here whose ORDER is also an index space — every reference into
+the re-sorted *other* objects is by name on both sides, so nothing moves when
+they are re-keyed. rigc emits **codepoint** and refuses the name sets on which
+codepoint and the editor's comparator could differ, rather than reproducing a
+comparator whose leading-zero, case-tie, digit-against-word and separator
+behaviour is still unmeasured.
+
+✅ **`events` is re-keyed too, and the references into it survive it.** The same
+session measured it: `zebra, mike, alpha` came back `alpha, mike, zebra`, and the
+firings still resolved **by name** — `0.3 -> mike`, `0.6 -> alpha`, payloads
+intact (#539). So the editor treats `events` and `animations` differently, and
+rigc emits events in the order you declare them.
+
 ### 10.2 Draw order
 
 📗 **An overlap change is a draw-order key.** The draw order *"can be keyed"*, and

package/docs/FACE.md

@@ -40,6 +40,12 @@ 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
+- **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
@@ -72,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
@@ -926,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
@@ -1060,6 +1083,136 @@ 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.
+
+✅ **The editor half, measured.** This paragraph said *unknown* until the round
+trip was taken with `tools/editor_roundtrip.ts` on a licensed editor (data
+version 4.3.26) against a 4.3.13 build of this worked example. What it found:
+
+- **Both sliders come back, and the parameter axis survives.** `additive`,
+  `local`, `bone`, `property`, `from`, `max` and `scale` are identical field for
+  field, and the two keep their places in the `constraints` array. `mix: 1` and
+  `to: 0` are dropped, and those are the format's own defaults (`SkeletonJson`
+  reads `mix` as 1 and `to` as 0 when absent) — an elision, not a loss.
+- ⚠️ **The animation each slider *names* did not come back, until rigc changed
+  what it emits.** The editor re-sorts the `animations` object and a slider's
+  animation is an ordinal in the format, so `yaw -> "turn"` returned as
+  `yaw -> "sweep"` — the first animation of the sorted list
+  ([#535](https://github.com/firejune/rigc/issues/535)). rigc now emits
+  animations codepoint-ascending; on the same rig through the same editor that
+  restored `yaw -> "turn"` and took the re-rendered mean absolute error from
+  10.4655 / 8.4961 / 8.7140 (`sweep` / `tilt` / `turn`) to
+  0.3035 / 0.0769 / 0.0588, worst drift 16.535 px to 3.947 px.
+- 🚨 **The physics constraint on the cowlick comes back driving nothing.**
+  `rotate: 1` is absent from the export, and an absent `rotate` parses as **0**
+  (`SkeletonJson`), so the returned file states *drives nothing* rather than
+  omitting a default — which is why `A23_PHYSICS_CONSTRAINT_EFFECTIVE` refuses it
+  by name. Independent of the ordering defect, and open as
+  [#536](https://github.com/firejune/rigc/issues/536).
+- 🔸 Unexplained: `diff` reports `animations.curve_kinds` moved on **196 of 200**
+  keys in every round trip taken, the clean one included. Visually small once the
+  ordering is fixed — but it is 98% of the keys, and *small* is not *explained*.
+
+⚠️ **What it still does not measure:** a rig carrying more than one skin or more
+than one event, which is where the same shape — an ordinal into an object the
+editor re-keys — could bite next (AUTHORING §10.1). The runtime half was never in
+doubt: every figure above came back through `spine-core`.
+
 ---
 
 ## 9. Looking at it, and the audit gap
@@ -1580,6 +1733,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/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.1",
+  "version": "0.20.3",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/src/compile.ts

@@ -136,6 +136,283 @@ export const SPINE_VERSION = '4.3.13';
 
 const FRAME = 1 / 60;
 
+/**
+ * The order the emitted `animations` object is keyed in: **codepoint-ascending
+ * by name**, which is the order the Spine editor writes it back out in.
+ *
+ * ## Why the emitter has an opinion about this at all
+ *
+ * A `slider` constraint names the animation it applies, and in JSON that is a
+ * name on both sides. The **binary** format is where the same reference is an
+ * ordinal — `SkeletonBinary.js`: `constraint.animation = animations[readInt()]`
+ * — and an editor whose own model holds that ordinal reads the name at import
+ * and writes back whatever now stands at that position. Round-tripped through a
+ * licensed editor (data version 4.3.26), `gallery/look` went in as
+ * `turn, tilt, sweep` with `yaw -> "turn"` and came back as `sweep, tilt, turn`
+ * with **`yaw -> "sweep"`** (issue #535). Nothing in the returned file says so;
+ * it parses, it validates, and it applies the wrong animation.
+ *
+ * ⭐ The second slider is the control that names the mechanism rather than a
+ * second victim: `tilt` survived because it sat at index 1 in *both* orderings
+ * and index 1 is called `tilt` in both.
+ *
+ * ⇒ Emitting in the editor's own order makes its re-sort a no-op, so no index
+ * moves and no reference is repointed. Measured on the same rig through the
+ * same editor: mean absolute error over the re-rendered frames fell from
+ * 10.4655 / 8.4961 / 8.7140 to 0.3035 / 0.0769 / 0.0588, and `yaw -> "turn"`
+ * came back intact.
+ *
+ * ## Codepoint is NOT the editor's comparator, and this is why it is still what
+ * is emitted
+ *
+ * ⚠️ This comment used to say that codepoint order "is what every editor-authored
+ * file on hand is in", and that sentence was false when it was written. The
+ * counterexample ships with the tests: `examples/spineboy/export/spineboy-pro.json`
+ * keys `portal-flare9` **before** `portal-flare10` — in its default skin's
+ * attachment map and in two of `portal`'s timeline maps — and no codepoint sort
+ * produces that.
+ *
+ * 🔢 The survey behind that, stated so it can be re-taken rather than believed:
+ * over the 12 skeletons in `examples/`, take **every object the format keys by a
+ * NAME that carries more than one key** — `animations` and `events`; each skin's
+ * `attachments` map and each per-slot map inside it; each animation's `bones`,
+ * `slots`, `ik`, `transform`, `path`, `physics`, `events`, and its deform
+ * `attachments` at **all three** of its levels (skin, then slot, then attachment
+ * name). Arrays are excluded because the editor leaves them alone. That is
+ * **105** collections, of which **102** are consistent with a codepoint sort and
+ * **3** are not; all 12 natural comparators and all 8 `Intl.Collator`
+ * configurations tried reproduce every one of the 105.
+ *
+ * ⚠️ The deform clause is the whole of what makes it 105 rather than 104, and it
+ * is one collection: `animations.hoverboard.attachments.default` in
+ * `spineboy-pro.json`, whose four keys are slot names. Counting the skin level
+ * of a deform block and stopping there needs an exception the sentence above
+ * cannot state — every level of it is keyed by a name, and the editor re-keys
+ * each one — so the rule is "every level", and that collection is in.
+ *
+ * The editor was then measured directly (issue #539). Two rigs, each varying one
+ * axis: `Turn, sweep, wave` came back `sweep, Turn, wave`, and
+ * `turn10, turn2, zoom` came back `turn2, turn10, zoom`. The intersection leaves
+ * one hypothesis — **natural order, case-insensitive**.
+ *
+ * ⇒ So why not sort that way? Because "natural, case-insensitive" is a family of
+ * comparators rather than one. Leading zeros (`turn01` against `turn1`), a pure
+ * case tie (`Turn` against `turn`), whether a digit run sorts before a word, and
+ * what a separator is worth are each a free choice, and **the editor's answers to
+ * them are not measured**. Writing a comparator means choosing all four, and a
+ * chosen-but-unmeasured comparator is exactly how #537 landed.
+ *
+ * 🔒 It is also the one claim in the emitter that no gate can see. spine-core
+ * reads back everything else rigc writes; it does not sort, so the emitted key
+ * order has no oracle behind it. What rigc *can* check, with no editor and no
+ * comparator, is much smaller and is the whole of what matters: whether the names
+ * in front of it are a set on which every candidate comparator agrees. On such a
+ * set codepoint **is** the editor's order, whatever the editor's comparator turns
+ * out to be — and on every other set the build stops with both names in the
+ * message. See `orderTurnsOnTheComparator`.
+ *
+ * Codepoint also stays locale-independent, which `A18` requires: `localeCompare`
+ * would make the emitted bytes a property of the machine.
+ */
+function editorAnimationOrder<T>(animations: Record<string, T>): Record<string, T> {
+  // One definition of "the order rigc emits", shared with the check below, so the
+  // two cannot drift into checking different things.
+  const names = Object.keys(animations).sort(codepoint);
+  refuseNamesTheEditorCouldKeyDifferently(names);
+  const ordered: Record<string, T> = {};
+  for (const name of names) ordered[name] = animations[name];
+  return ordered;
+}
+
+/**
+ * The characters whose relative order every candidate comparator agrees on: the
+ * digits and, once case is folded, the lower-case ASCII letters. Everything else
+ * — `-`, `_`, a space, an accented letter — is worth something different to a
+ * collator than to a codepoint compare, so a pair those decide is not settled.
+ */
+const SETTLED_CHARS = /[0-9a-z]/;
+
+/** Maximal runs of digits and of non-digits, which is what "natural" compares. */
+const runsOf = (name: string): string[] => name.match(/\d+|\D+/g) ?? [];
+
+const sign = (n: number): number => (n < 0 ? -1 : n > 0 ? 1 : 0);
+const codepoint = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/** What made a pair's order a matter of opinion, and what the author has to do. */
+interface Ambiguity {
+  kind: 'case' | 'number' | 'separator';
+  because: string;
+  repair: string;
+}
+
+/**
+ * Whether these two names can be ordered two ways — `null` when every comparator
+ * the editor could be using puts them in the order rigc emits them in.
+ *
+ * ## The predicate, and why it is a certificate rather than a hazard list
+ *
+ * Issue #539 proposed checking for "two names differing only in case, or sharing
+ * a prefix followed by digit runs of unequal length". **That list misses the rig
+ * that produced the measurement**: `Turn` and `sweep` differ in much more than
+ * case and carry no digits, and they are the pair the editor reordered. A list of
+ * hazards is open-ended — one was missing the day it was written — so what is
+ * implemented is the other direction: a pair is refused unless the position that
+ * decides it is one every candidate comparator must read the same way.
+ *
+ * There are exactly three ways to lose that, and each is a free choice in some
+ * real comparator:
+ *
+ * - **case** — folding reverses them (`Turn` before `sweep` by codepoint, after it
+ *   folded), or they fold together and only a tie-break separates them.
+ * - **number** — a digit run decides, and reading it as text disagrees with
+ *   reading it as a number (`turn10` before `turn2`), or two runs are the same
+ *   number written two ways (`turn01`, `turn1`), or a run meets a word and
+ *   comparators differ on which sorts first.
+ * - **separator** — the deciding character is neither a letter nor a digit. This
+ *   one covers two adversaries at once: a collator that treats `-` or a space as
+ *   ignorable, and the plain fact that `_` sits *between* `Z` and `a`, so
+ *   `x.toUpperCase()` and `x.toLowerCase()` order `wave_x` against `wavea`
+ *   oppositely. Neither name needs a capital in it for that to bite.
+ *
+ * ## What it was tested against
+ *
+ * 22 comparators — 12 hand-rolled naturals (fold up/down × three leading-zero
+ * tie-breaks × digits-before-words/after) , 2 plain case-insensitive ones, and 8
+ * `Intl.Collator`s (`numeric: true`, four sensitivities × `ignorePunctuation`) —
+ * over every pair of names up to 4 characters from `{a B 0 1 2 - _ space}`:
+ * **10,948,860 pairs, zero escapes**, where an escape is a pair some comparator
+ * reorders that this predicate calls safe. Two earlier drafts did have escapes,
+ * and both are why a clause above exists: `ignorePunctuation` found `arc-tracker`
+ * against `arcs`, and a terminal digit run found `a0` against `a00`.
+ *
+ * ⭐ The two-sided result is on real data. Across the same 105 collections the
+ * survey above defines, the ones this predicate refuses are **exactly** the 3
+ * whose own key order a codepoint sort cannot reproduce — no false positive, no
+ * false negative, against names the editor itself wrote.
+ *
+ * ⚠️ It does over-refuse, and the direction is deliberate: `flare1` against
+ * `flare10` is safe under all 22 and refused anyway, because the rule is stated
+ * on digit-run width rather than on a comparison, and the repair that fixes the
+ * genuinely broken sibling (`flare9` against `flare10`) fixes both.
+ */
+function orderTurnsOnTheComparator(a: string, b: string): Ambiguity | null {
+  const caseRepair = 'rename one of them so nothing but case has to be compared';
+  const numberRepair = 'pad the digit runs to the same width, or rename so no number decides the order';
+  const separatorRepair = 'rename so the first character that differs is a letter or a digit';
+  const la = a.toLowerCase();
+  const lb = b.toLowerCase();
+  if (la === lb) {
+    return {
+      kind: 'case',
+      because: `they are one name in two cases, and which of them the editor puts first is not measured`,
+      repair: caseRepair,
+    };
+  }
+  let i = 0;
+  while (i < la.length && i < lb.length && la[i] === lb[i]) i++;
+  if (i === la.length || i === lb.length) {
+    const longer = la.length > lb.length ? a : b;
+    const rest = (la.length > lb.length ? la : lb).slice(i);
+    if (!SETTLED_CHARS.test(rest)) {
+      return {
+        kind: 'separator',
+        because:
+          `"${longer}" is the other name followed by ${JSON.stringify(rest)}, which a comparator that ignores ` +
+          'punctuation reads as the same name',
+        repair: separatorRepair,
+      };
+    }
+  } else if (!SETTLED_CHARS.test(la[i]) || !SETTLED_CHARS.test(lb[i])) {
+    const deciding = SETTLED_CHARS.test(la[i]) ? lb[i] : la[i];
+    return {
+      kind: 'separator',
+      because:
+        `the first character that differs is ${JSON.stringify(deciding)}, which is neither a letter nor a digit, ` +
+        'and what that is worth is a property of the comparator',
+      repair: separatorRepair,
+    };
+  }
+  if (sign(codepoint(a, b)) !== sign(codepoint(la, lb))) {
+    return {
+      kind: 'case',
+      because: `codepoint puts "${a}" first only because of letter case; folded, "${b}" comes first`,
+      repair: caseRepair,
+    };
+  }
+  const ra = runsOf(la);
+  const rb = runsOf(lb);
+  for (let k = 0; k < Math.min(ra.length, rb.length); k++) {
+    const x = ra[k];
+    const y = rb[k];
+    if (x === y) continue;
+    const xIsDigits = /^\d/.test(x);
+    const yIsDigits = /^\d/.test(y);
+    if (xIsDigits && yIsDigits) {
+      if (BigInt(x) === BigInt(y)) {
+        return {
+          kind: 'number',
+          because: `"${x}" and "${y}" are the same number written two ways, so only a tie-break separates them`,
+          repair: numberRepair,
+        };
+      }
+      if (x.length === y.length) return null;
+      return {
+        kind: 'number',
+        because:
+          `"${x}" and "${y}" are runs of digits of different widths, so reading them as text and reading them as ` +
+          `the numbers ${BigInt(x)} and ${BigInt(y)} can disagree`,
+        repair: numberRepair,
+      };
+    }
+    if (xIsDigits !== yIsDigits) {
+      return {
+        kind: 'number',
+        because:
+          `one has the digits "${xIsDigits ? x : y}" where the other has "${xIsDigits ? y : x}", and comparators ` +
+          'differ on whether a number sorts before a word',
+        repair: numberRepair,
+      };
+    }
+    return null;
+  }
+  return null;
+}
+
+/** How many pairs a refusal spells out before it starts counting them instead. */
+const PAIRS_SPELLED_OUT = 8;
+
+/**
+ * Refuse a set of animation names the editor could key in an order rigc did not
+ * emit — the check that lets `editorAnimationOrder` sort by codepoint without
+ * claiming codepoint is the editor's rule.
+ *
+ * It is deliberately **not** conditional on the rig declaring a slider. A slider
+ * is what makes the difference bite today, but the emitted order is a claim about
+ * the editor either way, and a check that only ran when a slider was present would
+ * make the claim hold for some rigs and not others — with nothing saying which.
+ * Adding the slider is then the edit that refuses a rig that built yesterday.
+ */
+function refuseNamesTheEditorCouldKeyDifferently(sorted: readonly string[]): void {
+  const found: string[] = [];
+  for (let i = 0; i < sorted.length; i++) {
+    for (let j = i + 1; j < sorted.length; j++) {
+      const pair = orderTurnsOnTheComparator(sorted[i], sorted[j]);
+      if (pair) found.push(`"${sorted[i]}" / "${sorted[j]}" (${pair.kind}) — ${pair.because}; ${pair.repair}`);
+    }
+  }
+  if (!found.length) return;
+  const spelled = found.slice(0, PAIRS_SPELLED_OUT);
+  throw new CompileError(
+    `${found.length} pair(s) of animation names have no one order: rigc keys the emitted "animations" object ` +
+      'codepoint-ascending, which is the Spine editor\'s own order only for names whose order does not turn on ' +
+      'case, on a number, or on a separator. The editor sorts natural and case-insensitive (#539), a slider\'s ' +
+      'animation is an ORDINAL in the format\'s binary half, and an editor that keys these differently repoints ' +
+      'every slider whose animation moves index — silently, in a file that still parses (#535). ' +
+      `${spelled.join('. ')}` +
+      (found.length > spelled.length ? `. …and ${found.length - spelled.length} more pair(s)` : ''),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // number formatting — deterministic, and free of "-0"
 // ---------------------------------------------------------------------------
@@ -1810,7 +2087,13 @@ export function compile(opts: CompileOptions): CompileResult {
     // conditional spread rather than an assignment after the literal, so the key
     // lands in that position instead of at the end.
     ...(Object.keys(events).length ? { events } : {}),
-    animations,
+    // Keyed in the editor's own order rather than the motion spec's, because a
+    // slider's reference to an animation is an ordinal in the format and the
+    // editor re-sorts this object — see `editorAnimationOrder`. The sort is
+    // applied HERE and not to the loop above, so what the compiler reads, the
+    // order it reports durations in, and which animation a CompileError names
+    // first are all still the spec's own; only the emitted key order moves.
+    animations: editorAnimationOrder(animations),
   };
   if (constraints.length) skeleton.constraints = constraints;
 

package/src/types.ts

@@ -835,7 +835,21 @@ export interface SpineSkeletonJson {
   }>;
   /**
    * Event definitions, keyed by name (`SkeletonJson.ts:451-464`). An object, not
-   * an array — the one top-level collection in the format that is.
+   * an array — one of the **two** top-level collections in the format that are,
+   * `animations` being the other.
+   *
+   * ⚠️ This sentence said "the one" until issue #535, and the collection it was
+   * overlooking is where the defect that card is about lived. The distinction is
+   * not cosmetic: the binary format addresses both of these by ORDINAL
+   * (`SkeletonBinary`: `animations[readInt()]` for a slider's animation,
+   * `events[readInt()]` for an event key), and an editor round trip was measured
+   * to re-key every name-keyed object in codepoint order while returning every
+   * ARRAY in the order it was given. So a reference into either of these two is
+   * a reference whose ordinal an editor can move, and a reference into
+   * `bones` / `slots` / `skins` / `constraints` is not. `animations` is emitted
+   * in the editor's order for that reason (`compile.ts`'s
+   * `editorAnimationOrder`); whether `events` needs the same is unmeasured,
+   * because no editor export on hand carries more than one event.
    */
   events?: Record<string, SpineEvent>;
   animations: Record<