spine-rigc 0.18.0 → 0.19.0

package/cli.ts

@@ -768,9 +768,12 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
         (key.dial === null
           ? ''
           : `, dial ${key.dial.value.toFixed(6)}` +
+            // ⚠️ `reach.drive` names the field when it is NOT the one `property`
+            // names, which happens under `local: false` on a rotated parent — a
+            // bare figure there would read as a value of the wrong field (#419).
             (key.reach.local || key.dial.driven === key.dial.value
               ? ''
-              : ` (bone local ${key.dial.driven.toFixed(6)})`) +
+              : ` (bone local ${key.reach.drive === null ? '' : `${key.reach.drive} `}${key.dial.driven.toFixed(6)})`) +
             ` -> t=${key.dial.applied.toFixed(6)}`),
     );
     // A key at a time no dial selects: the figures below are the frame the

package/docs/AUTHORING.md

@@ -1406,27 +1406,172 @@ sharing one of those overwrite each other whatever you write. A40 names that cas
 separately, because the fix is different: key such a property from one slider
 only, or move both edits into the single animation one slider applies.
 
-🚨 **A `rotate`-driven slider with `local: false` cannot cross 0°.** `local: false`
-reads the bone's **world** rotation through `FromRotate.value`, which ends
-`if (value < 0) value += 360`. A yaw axis authored the natural way — neutral at 0°,
-range −15°..+15° — therefore never sees a negative value: the bone at −15° arrives
-as 345°, and `time = to + (value − from) * scale` lands far past the animation.
-[measured] with `from: 0, to: 0.5, scale: 0.033333` over a 1 s animation the dial
-at −15° applies time **12.000 s**, so with `loop: false` the entire negative half
-of the axis holds the last frame — 15° of face jumping between −0.001° and 0°, with
-nothing anywhere reporting it. The same rig with `"local": true` ramps
-0 s → 0.5 s → 1 s as written.
-
-⇒ **`local: true` is the form a face axis wants.** It reads `source.rotation`
-signed and unwrapped, which for a dial bone is the number you authored. rigc
-refuses the crossing case at compile, with that arithmetic in the message; the
-alternative it leaves open is to move the range so it does not cross 0° (a neutral
-at 180°, say), which is the only form `local: false` can express.
-
-⚠️ **The refusal is on the LOW end only.** `[0, 360)` is the whole of what
-`FromRotate.value` returns, so a range running past **360°** is dead in the same
-way and compiles clean. Nothing refuses that at compile; `A39` reports it from the
-artifact side as a key at a time no dial selects (§4.11.4).
+#### 3.5.2.1 What each `property` can actually be read AS
+
+**A `property` under `local: false` is read through the world transform, and four
+of those readings are bounded.** A range that names values the reader cannot
+return is dead there: the dial moves, the reading does not follow, and nothing at
+runtime says so. [measured] against `spine-core` 4.3.13, one reader at a time —
+`bench/studies/2026-09-06-readers`:
+
+| `property` | `"local"` | Reads | Producible floor | Producible ceiling |
+| --- | --- | --- | --- | --- |
+| `rotate` | `false` | `FromRotate`, world | `0`, reached | `360`, reached |
+| `rotate` | `true` | `FromRotate`, local | none | none |
+| `x` | `false` | `FromX`, world | none | none |
+| `x` | `true` | `FromX`, local | none | none |
+| `y` | `false` | `FromY`, world | none | none |
+| `y` | `true` | `FromY`, local | none | none |
+| `scaleX` | `false` | `FromScaleX`, world | `0`, reached | none |
+| `scaleX` | `true` | `FromScaleX`, local | none | none |
+| `scaleY` | `false` | `FromScaleY`, world | `0`, reached | none |
+| `scaleY` | `true` | `FromScaleY`, local | none | none |
+| `shearY` | `false` | `FromShearY`, world | `-449.99999468`, reached | `269.99999468`, reached |
+| `shearY` | `true` | `FromShearY`, local | none | none |
+
+- **`none` is not "very large"** — those readers are `source.<field> + offset` and
+  the field is whatever the animation wrote, so there is nothing there to bound.
+- **Every world row assumes the offsets are zero**, and a slider cannot make them
+  anything else: `Slider.offsets` is a private all-zero array. The same six
+  classes serve a transform constraint, which passes its own — there the scale
+  floors move to the offset and the `shearY` window slides by it.
+- **`scaleX` / `scaleY` under `local: false` lose the sign.** The reader is
+  `Math.sqrt(a² + c²)`, so a bone at `scaleX: −1` reads **`+1`**, not `−1`: a
+  squash axis driven through negative scale gets the mirror of the dial you wrote.
+  The floor `0` is *reached*, not approached — a bone whose own scale or whose
+  parent's is 0 reads exactly 0 — so a range whose bottom is exactly 0 is fine and
+  one that dips below it is dead.
+- **`shearY` under `local: false` wraps like `rotate` does, and worse.** It is a
+  difference of two `atan2` calls, so at any one bone orientation the readable
+  window is 360° wide — `(−270 − θx, 90 − θx]`, where `θx` is the bone's world
+  x-axis angle. The bound in the table is the union over every orientation. ⇒ the
+  seam is **not at a fixed value of the driven field**; it is wherever the bone is
+  pointing. Prefer `local: true` for a shear axis.
+- **The bounds are not round numbers because `MathUtils.PI` is `3.1415927`** — the
+  float32 π of the reference runtime. Every degree in spine-core passes through
+  `180 / 3.1415927`, so a full turn converts as `359.99999468178214` and a bone at
+  360° reads 5.3e-6° rather than 0°. `shearY`'s two ends are `±2π · radDeg − 90`.
+- 🔸 A negative `skeleton.scaleX` / `scaleY` — how a consumer mirrors a character —
+  changes **nothing**: every world reader divides the same factor back out, and
+  [measured] the readings are identical to the digit at (1,1), (−1,1), (1,−1),
+  (−1,−1), (2,0.5) and (−0.5,3). A `skeleton` scale of **zero** makes every world
+  reader `NaN`, and `Math.max(0, NaN)` is NaN — but nothing in skeleton data sets
+  that field, so it is the consumer's to avoid.
+
+⚠️ **`local: true` reads the number you authored only on a bone nothing else
+drives.** `Slider.update` calls `bone.appliedPose.validateLocalTransform` first,
+and on a bone a constraint moved that recomputes the local pose *from the world
+matrix* — `atan2Deg` for the angles and `Math.sqrt` for `scaleX`. [measured] on
+one rig, the same slider: a free bone at `rotation: −500` reads `−500` and the
+same bone inside a transform constraint's `bones` reads `−140.000006`; at
+`scaleX: −2` the free bone reads `−2` and the constrained one reads `+2`. The
+producible *set* is unbounded either way — the free case is in it — but if
+`local: true` is your repair for a world reader's floor, check that the driving
+bone is not itself constrained.
+
+#### 3.5.2.2 The circle a `rotate` world dial has to stay inside
+
+🚨 **A `rotate`-driven slider with `local: false` has to stay inside the circle
+`[0, 360]`.** `local: false` reads the bone's **world** rotation through
+`FromRotate.value`, which is a `Math.atan2` — so `(−180, 180]` — with
+`if (value < 0) value += 360` on the end, and the `offsets` a slider hands it are
+all zero. `[0, 360]` is therefore the whole set of values that reader can ever
+return, and a range leaving it on either side is a wall:
+
+- **Below 0°.** A yaw axis authored the natural way — neutral at 0°, range
+  −15°..+15° — never sees a negative value: the bone at −15° arrives as 345°, and
+  `time = to + (value − from) * scale` lands far past the animation. [measured]
+  with `from: 0, to: 0.5, scale: 0.033333` over a 1 s animation the dial at −15°
+  applies time **12.000 s**, so with `loop: false` the entire negative half of the
+  axis holds the last frame — 15° of face jumping between −0.001° and 0°.
+- **Past 360°.** There is nothing above 360 to wrap *from*, so the value arrives
+  360 **lower** instead. [measured] with `from: 300, to: 0, scale: 0.005` over a
+  1 s animation the range is 300°..500°; the bone turned to 500° has a world
+  rotation of 140°, is read as 140°, and applies time **−0.800 s** —
+  `Math.max(0, time)` under `loop: false`. Swept through spine-core, that rig
+  reaches only **0.000 s..0.2995 s of its own 1 s animation**: the top 140° of the
+  dial does not merely fail to arrive, it arrives somewhere else.
+
+Both are refused at compile, each with its own arithmetic in the message and its
+own repair — *"move the range so it does not cross 0°"* and *"move the range so it
+does not run past 360°"*.
+
+⭐ **The reading in that message is a modulo, not one turn** — the wrap the bone's
+matrix has already applied by the time `atan2` reads it, so a range that leaves
+the circle by *more* than 360° is folded all the way back into `[0, 360)`. The two
+examples above each sit within one turn, where a single ±360 gives the same
+answer; past that only the modulo does. [measured] through spine-core, a bone
+parked at **−500°** drives the slider to **3.600000 s**, which is exactly where a
+bone parked at **220°** drives it — so the reading is 220°, not −140°, and a
+refusal naming −140° would be naming a value that reader cannot return at all
+(issue [#431](https://github.com/firejune/rigc/issues/431)). The same on the other
+side: **900°** drives it to **0.200000 s**, the time a bone at **180°** selects.
+
+📐 **The consequence in that message is computed, not described.** Both refusals
+end on two numbers read off `[0, 360]` met with the driving values that reach the
+animation — the same two the message has already printed:
+
+```
+reachable = { to + (v − from) × scale : v ∈ [0, 360] } ∩ [0, duration]
+held      = { v ∈ [0, 360] : the mapped time falls outside [0, duration] }
+```
+
+so the 300°..500° dial above is refused with *"This dial reaches only
+0.000s..0.300s of the animation's 1s, and 83.3% of the circle — every reading
+below 300.000° — is held on the frame at 0.000s"*, and the −15°..15° one with
+*"…only 0.500s..1.000s of the animation's 1s, and 95.8% of the circle — every
+reading above 15.000° — is held on the frame at 1.000s"*. [measured] the first of
+those reproduces a 0.1° sweep of the rig through `spine-core` to **3.2e-8 s**,
+which is the reader's own `atan2` noise.
+
+⚠️ **`loop: true` gets a different sentence, because it is a different runtime.**
+`Slider.js:63-66` is `p.time = duration + (p.time % duration)` when the slider
+loops and `Math.max(0, p.time)` when it does not, so nothing is held on a looping
+slider — [measured] the same 300°..500° rig pins 5⁄6 of the circle to frame 0 at
+the default and pins *nothing* under `loop: true`. The refusal says so: *"Nothing
+is held: `"loop": true` wraps the time as `duration + (time % duration)`, so the
+140.000° of the range past 360° selects nothing a reading inside the circle does
+not already select."* The range is still refused either way — a bone cannot be
+read at 500°, whatever happens to the time afterwards.
+
+⭐ **The degrees in that sentence are a *width*** — how much of `lowest..highest`
+lies outside `[0, 360]` — and not the reach from the boundary to the far end. The
+two are the same number for a range that *straddles* a boundary, as `300°..500°`
+does. A range lying **wholly** outside is told its own width instead: `400°..500°`
+reads *"the 100.000° of the range past 360°"*, and `-500°..-300°` *"the 200.000°
+of the range below 0°"* (issue
+[#434](https://github.com/firejune/rigc/issues/434) — both used to print the
+reach, which on the first of those was 140.000°, wider than the 100°-wide range
+it was describing).
+
+⭐ **A range ending exactly on 360° is legal**, and that is the whole turn: a
+wheel, a turntable, a head that goes all the way round, written `from: 0` with a
+`scale` that puts 360° on the last frame. It misses **nothing**: [measured] the
+wrap `value += 360` on a reading a hair below zero *rounds*, and bisecting the
+runtime's own `v + 360 === 360` puts the threshold at exactly half an ulp of 360 —
+so every reading in `[-2.842170943040401e-14°, 0°)` is read as exactly `360`, and
+the top of that range is reached rather than approached. Nor is 360 a separate
+dial position: a bone at 360° *is* a bone at 0°, and [measured] it poses the
+skeleton to within **4e-7°** of it, an `atan2` artefact rather than a frame. (The
+other half of that same `atan2` leaves a 5.3e-6°-wide hole at 180°, between
+`179.99999734…` and `180.00000265…` — measured, reported for completeness, and
+narrower than any dial anybody writes.) Swept at 0.1° over the circle, `from: 0,
+scale: 0.0025` on a 0.9 s animation lands every reading within **1.7e-8 s** of the
+time the mapping asks for; on `loop: true` the endpoint is not even distinct,
+closing on **0.900000 s** exactly. Use `loop: true` for a dial that really does go
+round, so the seam at 0°/360° is the wrap it is meant to be.
+
+⇒ **`local: true` is the form a face axis wants**, and it is the first repair both
+messages name. It reads `source.rotation` signed and unwrapped, which for a dial
+bone is the number you authored — 500° included — because `FromRotate`'s wrap is
+not on that path at all. The alternative each refusal leaves open is to move the
+range inside the circle (a neutral at 180°, say), which is the only form
+`local: false` can express.
+
+⚠️ **An artifact can still carry a dead range** — one exported from the editor,
+hand-edited, or built by an older rigc. `A39` reports that from the artifact side
+as a key at a time no dial selects (§4.11.4); the compile refusal above is what
+stops a rig spec in this repository from producing one.
 
 📌 **A slider's animation is measured in the slider's own frame** — `A39` inverts
 the mapping above and drives the bone to the value it names, rather than playing
@@ -2519,7 +2664,7 @@ deform  (what each key does to the geometry — figures with names, never a bar;
 | Row | What it is |
 | --- | --- |
 | the `DEFORM` line | `animation`, the `skin/slot/attachment` triple the timeline is keyed on, the key's index — **the same index `A39`'s message names** — its time, and its model: the `transform` kind and parameters the spec stated (§4.11.1), or `authored table` |
-| `frame` | how the animation was reached, which is the pose everything below was measured in: `played on a track`, or the slider that applies it with the dial value its mapping inverts this time to (§4.11.4). On a key at a time no dial selects, an `unreachable` line follows it and the figures below belong to the frame the runtime landed on instead |
+| `frame` | how the animation was reached, which is the pose everything below was measured in: `played on a track`, or the slider that applies it, the property that slider reads off its bone **as the emitted skeleton names it**, and the dial value its mapping inverts this time to (§4.11.4). Under `local: false` a further clause appears when the field that measurably moves the reading is not the one the skeleton names, or when two fields move it equally — reported, never resolved out of sight. On a key at a time no dial selects, an `unreachable` line follows it and the figures below belong to the frame the runtime landed on instead |
 | `moved` | how many vertices this key moves at all, and the largest **world** displacement with the vertex carrying it. Not the same number as §4.11.1's `largest offset`: that one is the offset the spec stated, this one is where the vertex ended up after the bones |
 | `area` | signed area **after ÷ before**, its smallest and largest over the triangles, each with the triangle. `x0.637` is a band compressed to 64%; **a negative ratio is a triangle turned inside out** |
 | `stretch` | the two singular values of the map from the cleared triangle to the deformed one — the worst stretch and the worst squash the **drawing** takes. `σ₁·σ₂ = \|area ratio\|`, so the two rows are two readings of one map and cannot disagree |
@@ -2714,13 +2859,14 @@ dial and not reached at all through another.
 - ⚠️ **A key at a time no dial can select is named, not passed.** The cause is
   [#405](https://github.com/firejune/rigc/issues/405)'s wrap: `FromRotate.value`
   under `local: false` is an `atan2` ending `if (value < 0) value += 360`, so
-  **`[0, 360)` is the whole of its range** and a mapping needing anything outside
-  it selects nothing. 🚨 The compiler refuses a range that dips **below** 0°
-  (§3.5.2) and says nothing about one running **past 360°** — `from: 300` with
-  `scale: 0.005` over a 1 s animation needs 300°..500° and compiles clean — so
-  this is the surface that sees the second half. `A39` measures the frame the
-  runtime *does* land on, leaves the key out of `deformKeysMeasured`, and names
-  it:
+  **`[0, 360]` is the whole of its range** and a mapping needing anything outside
+  it selects nothing. 🚨 A **rig spec** can no longer ask for one — the compiler
+  refuses both ends of that circle (§3.5.2), the low one since #405 and the high
+  one since [#417](https://github.com/firejune/rigc/issues/417) — but an
+  **artifact** can, because it may have come from the editor, from a hand edit or
+  from an older rigc, and this is the surface that reads what actually shipped.
+  `A39` measures the frame the runtime *does* land on, leaves the key out of
+  `deformKeysMeasured`, and names it:
 
 ```
 deformKeysUnreachable=2 deformUnreachable=turn/head/head#0@10.800000,turn/head/head#1@11.300000
@@ -2730,6 +2876,83 @@ deformSpansNotScanned=2
   — the `@` is the time the runtime lands on instead — with the `DEFORM` block
   giving the whole sentence and the spans those keys bound left unscanned rather
   than scanned over two poses of some other time.
+- 🚨 **A dial past `±16777216` is named, not printed.** The drive is a number you
+  are meant to act on — *set `knob.scaleX` to this* — and past 2²⁴ a float32 no
+  longer separates consecutive integers, so a figure up there is not one anybody
+  can set and read back. `A39` leaves the bone at its setup value instead, counts
+  the key as unreachable, and says so with both numbers:
+
+```
+unreachable A39 gates nothing here: the dial for t=1s is out of bounds: slider "dial" maps
+that time back to 17000000.000000, which needs knob.rotate at 1.7000e+7 — past the ±16777216
+this solve will drive a bone field to. …
+```
+
+  The usual cause is a `from` or a `scale` that puts the animation's own range out
+  of reach; check the two against `value = from + (time − to) / scale` above.
+
+#### Which property the `frame` line names
+
+The name on the `frame` line — `off yaw_dial.rotate (local)` — is read off the
+**emitted skeleton**: it is whichever `FromProperty` the parser built out of your
+`property` field, so it is the word you wrote. rigc *also* probes all six local
+fields of the driving bone to find which one moves the reading, because under
+`local: false` the reader goes through the world transform and only a measurement
+can say what drives it there. **The two answers must agree, and when they do not
+the line says so rather than picking one silently.**
+
+- Under `local: true` they always agree and the line carries nothing extra.
+- Under `local: false` they can legitimately differ, because the reading is a
+  *world* one. A bone whose parent is turned 90° has a world x that its own local
+  `x` does not move at all and its local `y` moves entirely, so the line reads
+  `off knob.x (world), driven through knob.y — the probe moves the reading by
+  knob.y 1.000e+0 while the skeleton says the reader is knob.x, which moves it by
+  2.321e-8. The two disagree and both are reported…`, and the `bone local` figure
+  beside the dial names its field (`bone local y 398.999991`).
+- At 45° the two fields move it *equally*, which no ranking can separate; the line
+  says the probe did not settle it and that the skeleton's own reader broke the
+  tie. ⛔ Neither case is a refusal and neither is guessed past — an ambiguous
+  discovery is a thing to report.
+
+**And a `build` says it too, on `A39`'s stats line**
+([#427](https://github.com/firejune/rigc/issues/427)) — because `explain` is not
+the loop you run, and until this the whole finding lived on a line only `explain`
+prints. Nothing appears on a rig where the two answers agreed, which is every
+`local: true` slider and every gallery example:
+
+```
+deformDialsTied=1 deformDialTied=dial|artifact:knob.x@7.071e-1|tied:knob.y@7.071e-1
+deformDialsDisagreed=1 deformDialDisagreed=dial|artifact:knob.x@2.321e-8|reaches:0.000000..0.003893s|probe:knob.y@1.000e+0|reaches:0.000000..1.000000s|outside:0.500000s+1.000000s
+```
+
+- `artifact:` is the field the **skeleton** names and what one unit of it moves the
+  reading by; `probe:` is the field that **measurably** moves it and by how much.
+- `reaches:` is the part of that animation's own `0..duration` each of them can
+  select. It is bounded by the same `±16777216` the dial figure is: a field that
+  barely moves the reading needs an unsettable value to move it a whole second.
+- `outside:` is the key times this survey posed through `probe:` that **no
+  settable value of the field the skeleton names reaches**. Each one is posed
+  through that field and the runtime is asked where it landed, so the list is a
+  measurement. ⭐ `outside:none` is a reading, not an absence — it says both
+  answers select every frame that was measured, so the disagreement changed
+  nothing about what `A39` looked at.
+- A **tie** never carries `probe:`, `reaches:` or `outside:`, and never counts as a
+  disagreement. There is one belief there, not two.
+
+⛔ **None of it refuses a build**, and the reason is measured rather than chosen.
+The field the survey drives is the largest response the probe found, so its reach
+always *contains* the artifact's: a disagreement cannot make `A39` miss a frame the
+runtime reaches. And every frame it does pose is checked against `SliderPose.time`
+by spine-core itself, so it cannot make `A39` pose one that never happens either.
+What is left is a rig naming a property no settable value of turns far enough —
+which the line above tells you, and which no edit rigc could demand would fix,
+because the rig may be perfectly correct and driven through the other field.
+
+None of this needs anything from you unless a `frame` line or one of those stats
+readings appears. If one does, it is telling you the dial bone's parent transform
+is doing something you may not have intended — and if `outside:` names times, it is
+telling you the dial cannot be turned to them through the property your rig spec
+declares.
 
 ⚠️ **What the artifact cannot say, and rigc therefore does not:** whether a
 slider's animation is *also* played on a track somewhere. Nothing in skeleton data
@@ -2905,7 +3128,8 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `rig constraint "X": applies animation "Y", which the motion spec does not declare (it declares: …)` | §3.5.2 — fix the slider's `animation`, or add it to the motion spec |
 | `rig constraint "X": declares both a "bone" and "time"` | §3.5.2 — `bone` picks the model and `time` belongs to the other one |
 | `rig constraint "X": declares "property" but no "bone"` | §3.5.2 — name the driving bone, or key `slider.<name>.time` instead |
-| `rig constraint "X": drives off bone "Y" rotate with "local": false, and the driving values that reach animation "A" (0s..Ds) run from −15.000° to 15.000° …` | §3.5.2 — add `"local": true`, which reads the bone's own rotation signed and unwrapped, or move the range so it does not cross 0°. A world rotation is wrapped into `[0, 360)` before the slider maps it, so the negative half of the range is unreachable and pins to one frame |
+| `rig constraint "X": drives off bone "Y" rotate with "local": false, and the driving values that reach animation "A" (0s..Ds) run from −15.000° to 15.000° … the whole part of the range below 0° is dead` | §3.5.2 — add `"local": true`, which reads the bone's own rotation signed and unwrapped, or move the range so it does not cross 0°. A world rotation is wrapped into `[0, 360]` before the slider maps it, so the negative half of the range is unreachable and pins to one frame |
+| `… run from 300.000° to 500.000° … the whole part of the range past 360° is dead` | §3.5.2 — the same wall at the other end, and the same first repair: `"local": true`, or move the range so it does not run past 360°. `[0, 360]` is the whole of what that reader returns, so a bone turned to 500° is read as 140° and selects a time far from the one the range asked for. Ending *exactly* on 360° is fine — that is the full turn, and it misses nothing: the wrap rounds, so a bone a hair below 0° is read as exactly 360 |
 | `skin "S" activates bone "B", but that bone does not declare \`"skin": true\`` | §3.4.1 — the list and the flag are one switch; add the flag or drop the list |
 | `bone "B" declares \`"skin": true\` but no skin activates it` | §3.4.1 — the other half: list it in the skin it belongs to, or drop the flag |
 | `skin "S": uses the long form … and also has a key "X"` | §3.4.1 — move the slot inside `attachments` |

package/package.json

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

package/src/compile.ts

@@ -3265,6 +3265,21 @@ type RigConstraintInput = { name: string; type: string } & Record<string, unknow
 /** The six property names a transform constraint may map between (`:241`, `:521`). */
 const TRANSFORM_PROPERTIES = ['rotate', 'x', 'y', 'scaleX', 'scaleY', 'shearY'];
 
+/**
+ * How far past a boundary an end of a `rotate` slider's driving range may sit
+ * before the refusal below fires, in degrees.
+ *
+ * ⭐ **Outward at both ends**, which is the whole reason it is named: 0° and 360°
+ * are the two values an author of a face axis or a full-circle dial actually aims
+ * at, and `from − to / scale` is three authored numbers and a division, so an
+ * intended 0° can arrive as `-1e-13` and an intended 360° as `360.0000000001`.
+ * The slack exists so arithmetic noise around either aim is not a refusal.
+ *
+ * Nothing is tuned. The failure it separates from is gross: a wrapped reading
+ * moves the applied time by `360 · scale`.
+ */
+const SLIDER_WRAP_SLACK = 1e-6;
+
 /** What a constraint's names resolve against. */
 interface ConstraintContext {
   boneNames: Set<string>;
@@ -3467,11 +3482,14 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
       //   let value = Math.atan2(source.c / sy, source.a / sx) * radDeg + …;
       //   if (value < 0) value += 360;
       //
-      // so a driving value below 0° is one the runtime never produces: it arrives
-      // as `value + 360` instead, and `time = to + (value - from) * scale` then
-      // lands far outside the animation. A yaw axis with its neutral at 0° — the
-      // natural way to author a face — therefore has its entire negative half
-      // pinned to one frame, and nothing anywhere says so (issue #402).
+      // `Math.atan2` returns `(-180, 180]` and the `offsets` a slider hands that
+      // reader are `Slider.offsets`, a private all-zero array — so **`[0, 360)`
+      // is the whole of what it can ever produce**. A driving value outside that
+      // is one the runtime never returns: it arrives 360° away, and
+      // `time = to + (value - from) * scale` then lands far outside the
+      // animation. A yaw axis with its neutral at 0° — the natural way to author
+      // a face — therefore has its entire negative half pinned to one frame, and
+      // nothing anywhere says so (issue #402).
       //
       // ⭐ Refused here rather than documented, and rather than left to the gate,
       // for three reasons. The failure is invisible AND total, so a note in a
@@ -3483,10 +3501,35 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
       // has in front of it: the range of driving values that can reach a frame is
       // exactly `[to, to + duration]` mapped back through `scale`.
       //
+      // ⚠️ **Both ends, out of one piece of arithmetic** (issue #417). As #405
+      // landed it, `highest` was computed and never tested, so a range running
+      // PAST 360° — `"from": 300, "scale": 0.005` over a 1 s animation asks for
+      // 300°..500° — compiled clean with everything above 360° just as dead: turn
+      // the bone to 500° and its world rotation is 140°, read as 140°, mapped to
+      // a time nowhere near the one the author meant. A copy-pasted second branch
+      // with a sign edited is how such a pair drifts apart, so the two ends share
+      // `dead` below and every number in the message comes off it.
+      //
+      // ⭐ **And the line is PAST 360°, not at it** — measured before it was
+      // written, because the two are one degree of arc apart and only one of them
+      // costs an author anything. A range ending exactly on 360° misses exactly
+      // one value, its own supremum, and that value is not a dial position: a
+      // bone at 360° IS a bone at 0°, reads within 5.3e-6° of it and poses the
+      // skeleton identically. Swept through spine-core over 0°..360° at 0.1°, a
+      // `from: 0, scale: 0.0025` dial on a 0.9 s animation lands every reading
+      // within **1.7e-8 s** of the time the mapping asks for, and on `loop: true`
+      // the endpoint is not even distinct — the circle closes on 0.900000 s
+      // exactly. Above 360° the dead set has width instead: 300°..500° reaches
+      // only 0.000 s..0.2995 s of its own 1 s animation, and the dial positions
+      // an author would set for the top 140° of it are read as something else and
+      // land on a wrong frame. That silent wrong answer is the hazard, and it
+      // starts strictly above 360.
+      //
       // The refusal is deliberately narrow: `rotate` only, because `FromRotate` is
       // the one property whose reader wraps, and only when the range actually
-      // crosses (or sits below) 0°, because a dial authored at 340°..20° is how
-      // you write this axis under `local: false` and it works.
+      // runs outside `[0, 360]`, because a dial inside that circle — 20°..340°,
+      // or the whole turn 0°..360° — is how you write this axis under
+      // `local: false` and it works.
       if (property === 'rotate' && spec.local !== true) {
         const fromValue = spec.from === undefined ? 0 : needNumber(spec.from, 'from');
         const toTime = spec.to === undefined ? 0 : needNumber(spec.to, 'to');
@@ -3497,18 +3540,176 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
         const atEnd = fromValue + (duration - toTime) / perUnit;
         const lowest = Math.min(atStart, atEnd);
         const highest = Math.max(atStart, atEnd);
-        if (lowest < -1e-6) {
-          const readAs = lowest + 360;
-          const lands = toTime + (readAs - fromValue) * perUnit;
+        // Which end of the circle the range leaves. One record, so the end, its
+        // reading, the time it lands on and the two clauses that name the side
+        // are derived once rather than twice.
+        //
+        // The two tests ARE each other's mirror, and that is deliberate: each
+        // gives its own boundary — 0° and 360°, the two values an author aims at
+        // — the same outward slack, so only a range that genuinely leaves the
+        // closed circle `[0, 360]` is refused.
+        const dead =
+          lowest < -SLIDER_WRAP_SLACK
+            ? {
+                end: lowest,
+                side: 'below 0°',
+                repair: 'move the range so it does not cross 0°',
+              }
+            : highest > 360 + SLIDER_WRAP_SLACK
+              ? {
+                  end: highest,
+                  side: 'past 360°',
+                  repair: 'move the range so it does not run past 360°',
+                }
+              : null;
+        if (dead !== null) {
+          /**
+           * What `FromRotate.value` actually returns for a bone at that end: a
+           * MODULO, not one subtraction (issue #431).
+           *
+           * 🚨 `lowest + 360` / `highest - 360` is right only while the range
+           * stays within one turn of the circle, which every fixture in this
+           * tree happened to be. Further out it printed a number the reader
+           * cannot return, inside a refusal whose entire subject is which
+           * readings the reader CAN return: `from: -500, scale: 0.005` over a
+           * 1 s animation said *"the bone at -500.000° is read as -140.000° and
+           * maps to time 1.800s"*, and -140° is not in `[0, 360)` at all. Both
+           * figures in that sentence were wrong. Measured through spine-core,
+           * a bone parked at -500° drives `Slider.appliedPose.time` to
+           * 3.600000s — the same six decimals a bone parked at 220° drives it
+           * to — so the reading is 220° and the time is 3.600s.
+           *
+           * ⭐ Derived off `dead.end` rather than inside the two branches, so
+           * the wrap is written ONCE. That is what #424 collapsed the two ends
+           * into one record for, and a second copy of `% 360` with a sign
+           * edited is how the pair drifts apart again.
+           *
+           * ⚠️ The consequence clause below does NOT go through here and does
+           * not need to: `reachLo`/`reachHi` intersect the driving window with
+           * `[0, 360)` directly, which is the same set however many turns out
+           * the window sits. Swept through spine-core at 0.1° over the whole
+           * circle on both a beyond-a-turn low range (-500°..-300°) and a
+           * beyond-`+720°` high one (100°..900°), the held fraction and the
+           * frame the held arc pins to are the ones this clause names — 100.0%
+           * at 1.000s and 27.8% at 0.000s — and the runtime's own applied time
+           * tracks the closed form to 3.3e-8s.
+           */
+          const readAs = ((dead.end % 360) + 360) % 360;
+          /**
+           * The time this mapping puts a driving value at, before the runtime
+           * touches it — the one arithmetic every figure below comes off.
+           *
+           * ⚠️ **Computed, not asserted** (issue #423). This clause used to end
+           * *"— outside the animation's Ds. With `loop`: false that is
+           * `Math.max(0, time)` holding the last frame; with `loop`: true it
+           * wraps to some other frame"*, which states a consequence rather than
+           * measuring one — and is flatly false for a range spanning a full
+           * turn, where the wrapped reading lands INSIDE the animation. It also
+           * printed both loop modes and left the reader to pick. A message that
+           * hedges is a message that has not measured.
+           */
+          const timeAt = (value: number): number => toTime + (value - fromValue) * perUnit;
+          const lands = timeAt(readAs);
+          // `[0, 360)` is the whole of what `FromRotate.value` returns (issue
+          // #417), so the readings that reach the animation at all are that
+          // circle met with the driving window `lowest`..`highest` the range
+          // clause above already prints. A second derivation beside these two
+          // numbers is exactly how a pair drifts, which is why #417 collapsed
+          // the two ends into one `dead` record in the first place.
+          const reachLo = Math.max(0, lowest);
+          const reachHi = Math.min(360, highest);
+          const reaches = reachLo <= reachHi;
+          const intoFrame = (time: number): number => Math.min(Math.max(time, 0), duration);
+          const reachA = intoFrame(timeAt(reachLo));
+          const reachB = intoFrame(timeAt(reachHi));
+          const span = `${Math.min(reachA, reachB).toFixed(3)}s..${Math.max(reachA, reachB).toFixed(3)}s`;
+          // ⭐ Exactly ONE arc of the circle is ever left over, and that is what
+          // lets the message name one bound and one frame instead of a set: the
+          // refusal means `[lowest, highest]` already runs off one end of
+          // `[0, 360)`, so the part of the circle outside it is a single run.
+          // (Both ends outside means the whole circle reaches — `dead` is 0° wide
+          // — and neither end outside is not a refusal at all.)
+          const dark = reaches ? 360 - (reachHi - reachLo) : 360;
+          const heldAt = intoFrame(timeAt(reachLo > 0 ? 0 : 360));
+          const arc = !reaches
+            ? 'every reading'
+            : reachLo > 0
+              ? `every reading below ${reachLo.toFixed(3)}°`
+              : `every reading above ${reachHi.toFixed(3)}°`;
+          /**
+           * How much of the range is a bone position no reader ever returns:
+           * the WIDTH of `[lowest, highest]` lying outside `[0, 360]` (issue
+           * #434).
+           *
+           * 🚨 `-lowest` / `highest - 360` is the distance from the boundary to
+           * the FAR end, and that equals the dead width only while the range
+           * STRADDLES the boundary. A range lying wholly outside had the gap
+           * between the boundary and its NEAR end counted too: `400°..500°` —
+           * inside one turn and reachable today — was told `140.000°` of it is
+           * dead, wider than the 100° range itself, and `-500°..-300°` was told
+           * `500.000°` against a true 200°. Clamping the near end to the
+           * boundary is the whole of the fix, and it moves ONLY the ranges that
+           * lie wholly outside: measured, a range straddling either boundary, a
+           * range ending exactly on one, and a range hanging off both at once
+           * all print what they printed before. `PS45` is the two that move and
+           * `PS46` is the four that must not.
+           *
+           * ⭐ **Third instance of one shape in this clause.** #417 tested one
+           * end of the range because its fixture only ever left the circle at
+           * that end; #431 wrapped by a single subtraction because every
+           * fixture sat within one turn; this measured to the far end because
+           * `PS42` — the only control that reads this string — straddles 360°,
+           * where the two arithmetics agree to the bit. Every time, a
+           * computation right about the case its fixture happened to be and
+           * silent about the case beside it, with no second fixture standing
+           * anywhere else to say so.
+           *
+           * ⭐ Why it read as a measurement rather than as a bug: the wrong
+           * figure is always a number ALREADY IN THE SENTENCE. Past 360°,
+           * `highest - 360` reproduces `readAs` — `400°..500°` printed the same
+           * `140.000°` twice, once as the reading and once as a width. Below 0°,
+           * `-lowest` reproduces `dead.end` with its sign dropped.
+           *
+           * ⚠️ Each term stays BEHIND the test that says its side is the one
+           * that crossed, and those guards are load-bearing rather than tidy —
+           * measured, not argued. Drop `lowest < 0` and the low term on
+           * `400°..500°` is `Math.min(0, 500) - 400 = -400`, a negative
+           * contribution to a width: the refusal prints `-300.000°`, and
+           * `300°..500°` and `100°..900°` move to `-160.000°` and `440.000°`.
+           * Drop `highest > 360` and `-340°..-305°` prints `-630.000°`. Neither
+           * is a width, and a width is what the sentence says it is.
+           */
+          const outside =
+            (lowest < 0 ? Math.min(0, highest) - lowest : 0) + (highest > 360 ? highest - Math.max(360, lowest) : 0);
+          // ⚠️ WHICH consequence the runtime produces is the slider's own `loop`,
+          // read rather than guessed: `Slider.js:63-66` is
+          // `p.time = duration + (p.time % duration)` when it is true and
+          // `Math.max(0, p.time)` when it is false, so a reading held on one
+          // frame under the second is replayed from elsewhere under the first and
+          // nothing is dead in time at all. Swept through spine-core at 0.1° over
+          // the whole circle before this was written, both ways.
+          const consequence =
+            spec.loop === true
+              ? `Nothing is held: "loop": true wraps the time as \`duration + (time % duration)\`, so the ` +
+                `${outside.toFixed(3)}° of the range ${dead.side} selects nothing a reading inside the circle does ` +
+                'not already select.'
+              : !reaches
+                ? `This dial reaches none of the animation's ${duration}s — the whole circle is held on the frame at ` +
+                  `${heldAt.toFixed(3)}s.`
+                : dark === 0
+                  ? `This dial reaches only ${span} of the animation's ${duration}s, and no reading of the circle ` +
+                    'reaches the rest of it.'
+                  : `This dial reaches only ${span} of the animation's ${duration}s, and ` +
+                    `${((dark / 360) * 100).toFixed(1)}% of the circle — ${arc} — is held on the frame at ` +
+                    `${heldAt.toFixed(3)}s.`;
           throw new CompileError(
             `${where}: drives off bone "${String(spec.bone)}" rotate with "local": false, and the driving values ` +
               `that reach animation "${animation}" (0s..${duration}s) run from ${lowest.toFixed(3)}° to ${highest.toFixed(3)}°. ` +
               'A world rotation is read through `FromRotate.value`, which ends `if (value < 0) value += 360`, so the bone ' +
-              `at ${lowest.toFixed(3)}° is read as ${readAs.toFixed(3)}° and maps to time ${lands.toFixed(3)}s — outside ` +
-              `the animation's ${duration}s. With "loop": false that is \`Math.max(0, time)\` holding the last frame; with ` +
-              '"loop": true it wraps to some other frame. Either way the whole part of the range below 0° is dead and ' +
+              `at ${dead.end.toFixed(3)}° is read as ${readAs.toFixed(3)}° and maps to time ${lands.toFixed(3)}s. ` +
+              `${consequence} The whole part of the range ${dead.side} is dead and ` +
               'nothing at runtime reports it. Add `"local": true` to read the bone\'s own rotation signed and unwrapped — ' +
-              'that is the form a face axis wants — or move the range so it does not cross 0°.',
+              `that is the form a face axis wants — or ${dead.repair}.`,
           );
         }
       }