spine-rigc 0.20.2 → 0.20.3

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
@@ -3273,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
 
@@ -4817,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

@@ -1180,13 +1180,38 @@ breaks the moment the two share a target — in the worked example both `turn` a
 `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`.
+✅ **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`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.20.2",
+  "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<