spine-rigc 0.20.3 → 0.22.0

package/src/compile.ts

@@ -35,6 +35,10 @@ import {
 } from './depth.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
 import { parseJsonWithPosition } from './json-position.ts';
+// The "did you mean" list on a missing atlas region, from the one implementation
+// of it — the same search serves `refuseUnknownKeys`, and a second copy here with
+// a threshold edited is how such a pair drifts apart.
+import { nearMisses } from './keys.ts';
 import { parseMotionSpec } from './motion.ts';
 import {
   parseRigSpec,
@@ -42,6 +46,7 @@ import {
   RIG_PATH_POSITION_MODES,
   RIG_PATH_ROTATE_MODES,
   RIG_PATH_SPACING_MODES,
+  RIG_SCALE_Y_MODES,
   RIG_SKIN_CONSTRAINT_KEYS,
   splitRigSkin,
   type RigAttachment,
@@ -53,6 +58,7 @@ import {
   type RigMeshBinding,
   type RigPathAttachment,
   type RigRegionAttachment,
+  type RigSkinParts,
   type RigSpec,
   type RigVertexGeometry,
   type RigDepthMap,
@@ -137,8 +143,23 @@ 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.
+ * The order the emitted `animations` object is keyed in: **the Spine editor's own
+ * comparator, as far as anybody has measured it** — natural and case-insensitive
+ * (#539) — with every name set refused on which one of that comparator's four
+ * UNMEASURED choices could decide a pair.
+ *
+ * ⚠️ This emitted **codepoint** order until issue #543, and the refusal was the
+ * thing that made codepoint agree with the editor: every pair the two could order
+ * differently was a `CompileError`. That is sound and it over-refuses by
+ * construction, because codepoint is not a member of the family it is being
+ * defended against — it is neither natural nor case-insensitive — so `Turn`
+ * against `sweep` and `turn10` against `turn2`, **the two pairs the editor was
+ * directly measured on**, were refused rather than emitted in the order the
+ * editor was measured returning. Sorting by a member of the measured family
+ * instead moves the refusal onto what is actually unmeasured, and moves no byte:
+ * on every set the codepoint rule accepted, the two orders are the same (that is
+ * what the rule guaranteed), which is why this change is invisible to every rig
+ * in the tree.
  *
  * ## Why the emitter has an opinion about this at all
  *
@@ -162,8 +183,7 @@ const FRAME = 1 / 60;
  * 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
+ * ## What the editor's comparator is, and which parts of it are known
  *
  * ⚠️ 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
@@ -195,47 +215,122 @@ const FRAME = 1 / 60;
  * `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
+ * ⚠️ "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 that sorts every name set 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.
+ * ⇒ 🔑 **So the family is never asked to sort a pair one of those four decides.**
+ * `measuredOrder` returns a verdict only where every member of the family must
+ * agree, and `refuseNamesTheEditorCouldKeyDifferently` stops the build on any pair
+ * where it cannot — which means the four choices below are **unobservable in the
+ * output**, and the claim the emit makes is the one #542 established, widened:
+ * *on this name set, every comparator consistent with what has been measured
+ * produces this order.* Checkable inside rigc, with no editor and no oracle.
+ *
+ * 🔒 The emitted key order is still the one claim in the emitter no gate can see.
+ * spine-core reads back everything else rigc writes; it does not sort. What
+ * replaces an oracle is the quantifier: the order is not *a* comparator's answer,
+ * it is the answer they all give.
+ *
+ * ⭐ The two-sided result is on editor-written data. Sorting each of the 105
+ * collections above by `measuredOrder` reproduces **105 of 105** — including the
+ * three no codepoint sort can — and refuses **none** of them. The codepoint rule
+ * reproduced 102 and refused those same 3.
+ *
+ * The family is hand-rolled and 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 names = Object.keys(animations);
+  // ⭐ The sort is the check's own OUTPUT rather than a second reading of the same
+  // names: the refusal walks every pair and hands back the verdict it certified
+  // for each, so "the order rigc emits" and "the order rigc checked" cannot drift
+  // into two readings the way a shared comparator still can.
+  const verdicts = refuseNamesTheEditorCouldKeyDifferently(names, ANIMATION_ORDER);
+  // Nested rather than keyed on a joined string: any character this could join
+  // on is one an animation name is allowed to contain, and two pairs that
+  // collided would silently share one verdict.
+  names.sort((a, b) => verdicts.get(a)?.get(b) ?? 0);
   const ordered: Record<string, T> = {};
   for (const name of names) ordered[name] = animations[name];
   return ordered;
 }
 
+/** The skin the editor keeps at index 0 whatever its name sorts as. */
+const DEFAULT_SKIN = 'default';
+
+/**
+ * The order the emitted `skins` array is written in: **`default` first, then the
+ * rest in the order the editor was measured returning them** — with every pair
+ * refused on which a comparator consistent with that measurement could disagree.
+ *
+ * ## Why the emitter has an opinion about this at all
+ *
+ * The same reason it has one about `animations` (#535), in the collection nobody
+ * had checked. `SkeletonBinary` addresses skins by ORDINAL — `skins[readInt()]`
+ * for an attachment timeline, `skins[linkedMesh.skinIndex]` for a linked mesh —
+ * so an editor that writes this array in another order repoints every such
+ * reference, silently, in a file that still parses.
+ *
+ * ⚠️ `src/types.ts` said for two releases that `skins` was one of the arrays an
+ * editor leaves alone, and #544 softened that to *unmeasured* rather than
+ * retracting it. Issue #541 measured it: a rig built `default, zulu, mike,
+ * alpha` exported `default, alpha, mike, zulu`. Three arrays — `bones` (30),
+ * `slots` (24), `constraints` (3) — had come back element for element, and the
+ * belief was a generalisation off those three.
+ *
+ * ## What is measured, and it is two separate facts
+ *
+ * - **`default` is pinned, not sorted.** `alpha` sorts before `default` under
+ *   every candidate comparator and came back *after* it. That is the whole
+ *   evidence, and it is decisive: the runtime's own `defaultSkin` is index 0.
+ * - **The rest came back `alpha, mike, zulu`.** ⚠️ Which separates nothing.
+ *   Those three names are lower-case ASCII with no digits and no separators, so
+ *   codepoint, case-folded, natural, and every collator agree on them. The
+ *   editor's skin comparator is **not established**, and a rig with `Zulu`,
+ *   `mike10`, `mike2` in it is what would establish it.
+ *
+ * 🔑 So this deliberately does NOT reuse `measuredOrder` alone. #539 measured
+ * the editor's comparator for `animations` and `events` — natural, and
+ * case-insensitive — and #543 narrowed the animation refusal onto what is left
+ * unmeasured *inside that family*. None of that is a measurement about skins:
+ * it is one program, and the inference that one program sorts two collections
+ * the same way is exactly the shape of the inference that put `skins` on the
+ * safe side of the list in the first place. `measuredSkinOrder` therefore
+ * certifies a pair only where the natural case-insensitive family **and plain
+ * codepoint** agree, which is the pre-#543 rule — correct here for the reason
+ * it was too strong there: for animations, codepoint had been *refuted*; for
+ * skins, nothing has refuted anything.
+ *
+ * ⇒ Every skin name in this tree is lower-case ASCII without digits, so no
+ * emitted byte moves and no rig is refused. What moves is the claim.
+ */
+function editorSkinOrder<T extends { name: string }>(skins: readonly T[]): T[] {
+  const pinned = skins.filter((skin) => skin.name === DEFAULT_SKIN);
+  const rest = skins.filter((skin) => skin.name !== DEFAULT_SKIN);
+  const verdicts = refuseNamesTheEditorCouldKeyDifferently(
+    rest.map((skin) => skin.name),
+    SKIN_ORDER,
+  );
+  rest.sort((a, b) => verdicts.get(a.name)?.get(b.name) ?? 0);
+  return [...pinned, ...rest];
+}
+
 /**
- * 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.
+ * The characters whose relative order every member of the measured family 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 that ignores punctuation than to one that does not, 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. */
@@ -246,58 +341,72 @@ interface Ambiguity {
 }
 
 /**
- * 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.
+ * How the editor's comparator orders these two names — or, when one of its four
+ * unmeasured choices is what decides them, what that choice is and what the
+ * author has to do about it.
  *
- * ## The predicate, and why it is a certificate rather than a hazard list
+ * ## It is a certificate, not 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.
+ * implemented is the other direction: a verdict is returned only where the
+ * position that decides the pair is one **every** comparator consistent with the
+ * measurement must read the same way, and everything else stops the build.
+ *
+ * ## The four choices this returns an `Ambiguity` for, and why each is free
+ *
+ * - **case** (`Turn` against `turn`) — the two fold together, so only a tie-break
+ *   separates them and nobody has measured which way it breaks.
+ * - **number**, one number written twice (`turn01` against `turn1`) — the runs are
+ *   numerically equal, so again only a tie-break separates them: shorter-first,
+ *   longer-first and lexicographic are all real implementations.
+ * - **number**, a digit run against a word (`1turn` against `turn`) — comparators
+ *   differ on whether a number sorts before a word.
  * - **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.
  *
+ * ⚠️ There used to be a fifth and a sixth, and both were artefacts of emitting
+ * codepoint rather than facts about the editor (issue #543). A pair folding the
+ * other way (`Turn` against `sweep`) and two digit runs of unequal width
+ * (`turn10` against `turn2`) are exactly the two pairs the editor **was**
+ * measured on, and every comparator in the family orders them the same way — so
+ * they are now emitted in that order rather than refused. `flare1` against
+ * `flare10`, the over-refusal #542 named and accepted, goes with them.
+ *
  * ## 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
+ * tie-breaks × digits-before/after words), 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.
+ * **10,948,860 pairs**. Three figures come off that bank and each is load-bearing:
+ *
+ * - **0 escapes**, where an escape is a pair some comparator orders differently
+ *   from the verdict returned here. Measured over the **20 natural** members —
+ *   the 12 hand-rolled and the 8 collators, all of which read a digit run as a
+ *   number. The 2 plain case-insensitive comparators do dissent (291,684 pairs),
+ *   and they are the two #539's own measurement refutes: a comparator that reads
+ *   `turn10` as text cannot return `turn2, turn10`.
+ * - **0 pairs move.** On every pair the codepoint rule accepted, this returns the
+ *   codepoint order — which is why no emitted byte in the tree changes.
+ * - the refusal covers **9,140,115** pairs where the codepoint rule covered
+ *   10,218,136: 1,078,021 pairs are now built instead of renamed.
+ *
+ * ⭐ And the two-sided result is on real data: across the 105 editor-written
+ * collections the survey above defines, sorting by this reproduces all 105 and
+ * refuses none. No false positive, no false negative, against names the editor
+ * itself wrote.
  */
-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';
+function measuredOrder(a: string, b: string): number | Ambiguity {
+  const caseRepair = 'rename one of them so they differ by more than letter case';
+  const zerosRepair = 'write the number one way — rename so the digit run has a single spelling, with leading zeros or without';
+  const wordRepair = 'rename so a run of digits never has to be compared against a word';
   const separatorRepair = 'rename so the first character that differs is a letter or a digit';
   const la = a.toLowerCase();
   const lb = b.toLowerCase();
@@ -332,13 +441,6 @@ function orderTurnsOnTheComparator(a: string, b: string): Ambiguity | null {
       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++) {
@@ -348,21 +450,16 @@ function orderTurnsOnTheComparator(a: string, b: string): Ambiguity | null {
     const xIsDigits = /^\d/.test(x);
     const yIsDigits = /^\d/.test(y);
     if (xIsDigits && yIsDigits) {
-      if (BigInt(x) === BigInt(y)) {
+      const nx = BigInt(x);
+      const ny = BigInt(y);
+      if (nx === ny) {
         return {
           kind: 'number',
           because: `"${x}" and "${y}" are the same number written two ways, so only a tie-break separates them`,
-          repair: numberRepair,
+          repair: zerosRepair,
         };
       }
-      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,
-      };
+      return nx < ny ? -1 : 1;
     }
     if (xIsDigits !== yIsDigits) {
       return {
@@ -370,44 +467,167 @@ function orderTurnsOnTheComparator(a: string, b: string): Ambiguity | null {
         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,
+        repair: wordRepair,
       };
     }
-    return null;
+    return codepoint(x, y);
   }
-  return null;
+  // One name's runs are a prefix of the other's — `wave` against `wave1`. Every
+  // comparator puts the shorter first; `la === lb` above already took the case
+  // where neither is longer.
+  return ra.length < rb.length ? -1 : 1;
+}
+
+/**
+ * How the editor orders two SKIN names — or what makes the pair a matter of
+ * opinion, under a family wider than `measuredOrder`'s by exactly one member.
+ *
+ * ## The extra member is plain codepoint, and it is here because nothing ruled
+ * it out
+ *
+ * #539 put two name sets through the editor and read them back, and what those
+ * two sets refute is that the editor sorts ANIMATIONS by codepoint: `Turn`
+ * before `sweep` and `turn10` before `turn2` are the codepoint answers, and the
+ * editor gave the other one both times. #543 is built on that refutation — it
+ * sorts by the natural, case-insensitive family and refuses only that family's
+ * four unmeasured choices.
+ *
+ * ⚠️ **The skins measurement refutes nothing.** `alpha, mike, zulu` is the
+ * answer every candidate gives, so codepoint is still standing for this
+ * collection. Carrying #543's narrowing over would be assuming that one editor
+ * sorts two collections by one comparator — plausible, unmeasured, and the same
+ * move that made `skins` "an array the editor leaves alone" for two releases.
+ *
+ * ⇒ A verdict is returned only where `measuredOrder` certifies the pair **and**
+ * codepoint agrees with it. On the pairs where they differ, the disagreement is
+ * itself the explanation: either folding the two reverses them, or reading a
+ * digit run as a number does, and the editor's choice between those readings is
+ * measured for animation names and not for skin names.
+ *
+ * 🔒 It is deliberately a *narrowing of `measuredOrder`* rather than a second
+ * comparator: one certificate, one place a family member is decided, and no way
+ * for the two to come to disagree about what "settled" means.
+ */
+function measuredSkinOrder(a: string, b: string): number | Ambiguity {
+  const verdict = measuredOrder(a, b);
+  if (typeof verdict !== 'number' || codepoint(a, b) === verdict) return verdict;
+  // `measuredOrder` and codepoint can only part company where folding or a digit
+  // run decides the pair — everything else it already refuses. Which of the two
+  // it is, is what the author has to read.
+  const foldingDecides = codepoint(a.toLowerCase(), b.toLowerCase()) !== codepoint(a, b);
+  return foldingDecides
+    ? {
+        kind: 'case',
+        because:
+          `folded to one case "${a}" and "${b}" order the other way round, so whether the editor folds SKIN ` +
+          'names decides this pair — and only its ANIMATION and EVENT names have been measured folded (#539)',
+        repair: 'rename one of them so their order does not turn on letter case',
+      }
+    : {
+        kind: 'number',
+        because:
+          `read as numbers the digit runs in "${a}" and "${b}" order the other way round from the same runs read ` +
+          'as text, so whether the editor sorts SKIN names naturally decides this pair — and only its ANIMATION ' +
+          'and EVENT names have been measured sorted naturally (#539)',
+        repair: 'pad the digit runs to the same width, or rename so no number decides the order',
+      };
 }
 
 /** 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.
+ * What one collection's order refusal has to say that the others' do not: what
+ * it is counting pairs of, which comparator family it certified them against,
+ * and what an order rigc got wrong would cost.
+ *
+ * Two collections share the walk below because they share the defect — a
+ * name-keyed collection whose ORDINAL is a reference in the format's binary half
+ * — and they must not share the sentence, because the family and the stakes are
+ * different and a reader acts on both.
  */
-function refuseNamesTheEditorCouldKeyDifferently(sorted: readonly string[]): void {
+interface OrderedCollection {
+  /** Plural, for "N pair(s) of …": `animation names`, `skin names`. */
+  noun: string;
+  /** The certificate. A number is an order; an `Ambiguity` stops the build. */
+  order: (a: string, b: string) => number | Ambiguity;
+  /** Why rigc has an opinion, and what the family leaves open. Ends on a space. */
+  why: string;
+}
+
+const ANIMATION_ORDER: OrderedCollection = {
+  noun: 'animation names',
+  order: measuredOrder,
+  why:
+    'rigc keys the emitted "animations" object in ' +
+    "the Spine editor's own comparator, which is natural and case-insensitive (#539) — but four of that " +
+    "comparator's choices have never been measured (a pure case tie, one number written two ways, a run of " +
+    'digits against a word, and what a separator is worth), and each pair below is decided by one of them. 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). ',
+};
+
+const SKIN_ORDER: OrderedCollection = {
+  noun: 'skin names',
+  order: measuredSkinOrder,
+  why:
+    'rigc writes the emitted "skins" array with "default" first and the rest in the order the editor was ' +
+    'measured returning them (#541) — but that measurement was taken on `alpha, mike, zulu`, which every ' +
+    "candidate comparator orders the same way, so the editor's skin comparator is not established and each " +
+    'pair below is one the candidates disagree about. A skin is an ORDINAL in the format\'s binary half — ' +
+    '`skins[readInt()]` for an attachment timeline, `skins[skinIndex]` for a linked mesh — so an editor that ' +
+    'writes them in another order repoints every such reference, silently, in a file that still parses. ',
+};
+
+/**
+ * Refuse a set of names the editor could write in an order rigc did not emit,
+ * and hand back the verdict for every pair that survived — the check that lets
+ * `editorAnimationOrder` and `editorSkinOrder` sort by a measured family without
+ * choosing a member of it.
+ *
+ * It is deliberately **not** conditional on anything: not on the rig declaring a
+ * slider, and not on the rig declaring the editor as a consumer. A slider is what
+ * makes the difference bite today and `invariants.editorRoundTrip` is how a rig
+ * says the editor is downstream, but the emitted order is a claim about the
+ * editor either way, and a check that only ran for some rigs would make the claim
+ * hold for some and not others with nothing in the file saying which — adding the
+ * slider, or the declaration, would then be the edit that refuses a rig that built
+ * yesterday. What issue #543 changed is the size of what is claimed, not who it is
+ * claimed for.
+ *
+ * ⚠️ `what` is a parameter and not a second copy of this walk because issue #541
+ * found the same defect in a second collection, and a copied loop is how the two
+ * come to check different things. What may NOT be shared is the family: `skins`
+ * and `animations` have been measured to different depths, and
+ * `OrderedCollection.order` is where each says which.
+ */
+function refuseNamesTheEditorCouldKeyDifferently(
+  names: readonly string[],
+  what: OrderedCollection,
+): Map<string, Map<string, number>> {
+  const verdicts = new Map<string, Map<string, number>>();
+  const put = (x: string, y: string, v: number): void => {
+    const row = verdicts.get(x) ?? new Map<string, number>();
+    row.set(y, v);
+    verdicts.set(x, row);
+  };
   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}`);
+  for (let i = 0; i < names.length; i++) {
+    put(names[i], names[i], 0);
+    for (let j = i + 1; j < names.length; j++) {
+      const verdict = what.order(names[i], names[j]);
+      if (typeof verdict === 'number') {
+        put(names[i], names[j], verdict);
+        put(names[j], names[i], -verdict);
+      } else {
+        found.push(`"${names[i]}" / "${names[j]}" (${verdict.kind}) — ${verdict.because}; ${verdict.repair}`);
+      }
     }
   }
-  if (!found.length) return;
+  if (!found.length) return verdicts;
   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). ' +
+    `${found.length} pair(s) of ${what.noun} have no one order: ${what.why}` +
       `${spelled.join('. ')}` +
       (found.length > spelled.length ? `. …and ${found.length - spelled.length} more pair(s)` : ''),
   );
@@ -1028,44 +1248,6 @@ function readAtlasIn(path: string): AtlasSource {
   return { path, dir: dirname(path), parsed, byName };
 }
 
-/**
- * How far apart two names are, for the "did you mean" list on a missing region.
- *
- * Plain Levenshtein. An atlas has tens of regions and this runs once per
- * refusal, so the O(n*m) table is free and a cheaper heuristic (shared prefix,
- * substring) would miss the commonest real case — a transposition or one wrong
- * character in a hand-typed `image`.
- */
-function nameDistance(a: string, b: string): number {
-  const rows = a.length + 1;
-  const cols = b.length + 1;
-  let previous = new Array<number>(cols);
-  for (let j = 0; j < cols; j++) previous[j] = j;
-  for (let i = 1; i < rows; i++) {
-    const current = new Array<number>(cols);
-    current[0] = i;
-    for (let j = 1; j < cols; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
-    }
-    previous = current;
-  }
-  return previous[cols - 1];
-}
-
-/** Up to five region names closest to the one that was not found. */
-function nearMisses(wanted: string, known: Iterable<string>): string[] {
-  const scored: Array<{ name: string; d: number }> = [];
-  for (const name of known) {
-    const d = nameDistance(wanted.toLowerCase(), name.toLowerCase());
-    // Half the name's length, floored at 2: "leg" must not suggest "arm", and a
-    // long name may still be recognisable through several typos.
-    if (d <= Math.max(2, Math.floor(wanted.length / 2))) scored.push({ name, d });
-  }
-  scored.sort((x, y) => x.d - y.d || (x.name < y.name ? -1 : 1));
-  return scored.slice(0, 5).map((s) => s.name);
-}
-
 /**
  * One part resolved out of a region of a pre-packed atlas — CLI `--atlas-in`.
  *
@@ -1267,6 +1449,16 @@ export function compile(opts: CompileOptions): CompileResult {
   const images: CompiledImage[] = [];
   const droppedStates: CompileResult['droppedStates'] = [];
   const seenRegions = new Set<string>();
+  /**
+   * Region name -> the absolute path of the file whose pixels that region holds.
+   *
+   * ⭐ A region is named by its PNG's **basename**, so two files in two
+   * directories can want one name, and the loser draws the winner's art with
+   * nothing said (issue #555). `seenRegions` answers "is this name taken"; this
+   * answers "by what", which is the half a refusal has to name — and it is the
+   * same record that lets one PNG legitimately serve two skins.
+   */
+  const regionSource = new Map<string, string>();
   /**
    * Every directory the spec names a part PNG in — `skeletonImagesPath` reads it.
    * Recorded from the spec's own path whether or not the pixels came from there:
@@ -1289,11 +1481,53 @@ export function compile(opts: CompileOptions): CompileResult {
         ? fromLoosePng(relPath, loosePath, region, isBase, outDir)
         : resolveFromAtlas(relPath, region, isBase, outDir, atlasIn);
     seenRegions.add(region);
+    regionSource.set(region, loosePath);
     partDirs.add(dirname(loosePath));
     images.push(img);
     return img;
   };
 
+  /**
+   * Measure and atlas the art ONE skin attachment names — once per file, not
+   * once per placeholder (issue #555).
+   *
+   * 🚨 The defect this replaces. The gather loop below deduplicated the slot's
+   * attachment NAMES, and the call to `addImage` stood behind that `continue`,
+   * so a placeholder two skins fill reached the atlas with the FIRST skin's art
+   * and every later skin's PNG was never opened. Measured on a two-skin rig
+   * before the repair: without stated sizes the compile refused with *a region
+   * needs width and height — give them, or give an "image" and rigc will measure
+   * the PNG*, which is the message telling the author to give the image they
+   * gave; with sizes stated it built and `A00_ROUNDTRIP_PARSE` refused the
+   * skeleton with *Region not found in atlas: patch_b*. Neither names the cause,
+   * and both are the doctrine's own second bullet inverted — a miss refused
+   * under somebody else's name.
+   *
+   * ⚠️ Two skins may legitimately share one PNG, which is why this is not simply
+   * `addImage` unguarded: `addImage` refuses any repeat of a region name, and a
+   * placeholder both skins point at the SAME file is one region on purpose. The
+   * distinction is the FILE, so that is what is compared — and two different
+   * files whose basenames collide are refused here by name rather than aliased,
+   * because the loser silently draws the winner's pixels at the winner's size
+   * and the whole gate stays green (measured: 15 assertions passed on exactly
+   * that rig).
+   */
+  const addSkinImage = (relPath: string, where: string): void => {
+    const region = basename(relPath, '.png');
+    const already = regionSource.get(region);
+    if (already === undefined) {
+      addImage(relPath, imagesDir, false);
+      return;
+    }
+    const wanted = resolve(imagesDir, relPath);
+    if (already === wanted) return; // one file, two attachments: one region, deliberately
+    throw new CompileError(
+      `${where}: "${relPath}" and the art already atlased as region "${region}" are two different files — ` +
+        `${wanted} and ${already}. An atlas region is named by its PNG's basename, so only one of the two can ` +
+        'hold that name and this attachment would draw the other file\'s pixels. Rename one of the PNGs.',
+    );
+  };
+
   // A manifest may name a part the cut does not carry. A formation can declare
   // more slots than any one cut fills, and a cut that shares a sprite with the
   // scene around it has no plate of its own to point at — the manifest then
@@ -1471,16 +1705,25 @@ export function compile(opts: CompileOptions): CompileResult {
       }
       const names = rigAttachmentNames.get(slotName) ?? [];
       for (const [placeholder, att] of Object.entries(placeholders)) {
-        if (names.includes(placeholder)) continue;
-        names.push(placeholder);
+        // Two concerns, two conditions. The list is the slot's PLACEHOLDER list
+        // and a placeholder several skins fill belongs in it once; the art is
+        // per ATTACHMENT, and there are as many of those as there are skins
+        // filling it. Standing behind one `continue`, the second was the first's
+        // arithmetic (issue #555).
+        if (!names.includes(placeholder)) names.push(placeholder);
         const image = (att as RigRegionAttachment).image;
-        if (typeof image === 'string' && !seenRegions.has(basename(image, '.png'))) {
-          addImage(image, imagesDir, false);
+        if (typeof image === 'string') {
+          addSkinImage(image, `skin "${skinName}" slot "${slotName}" attachment "${placeholder}"`);
         }
       }
       rigAttachmentNames.set(slotName, names);
     }
   }
+  // Which (slot, placeholder) pairs more than one skin fills — the pairs whose
+  // entries have to carry an attachment `name` of their own. Computed here, off
+  // the normalised skin table, so the slot loop below reads a decision rather
+  // than re-deriving one per attachment.
+  const contested = contestedPlaceholders(skinNames, skinParts);
 
   // -- 2. atlas --------------------------------------------------------------
   //
@@ -1638,9 +1881,10 @@ export function compile(opts: CompileOptions): CompileResult {
       const placeholders = skinParts.get(skinName)!.attachments[rigSlot.name];
       if (!placeholders) continue;
       const perSlot: Record<string, SpineAttachment> = {};
+      const shared = contested.get(rigSlot.name);
       for (const [placeholder, att] of Object.entries(placeholders)) {
         const where = `skin "${skinName}" slot "${rigSlot.name}" attachment "${placeholder}"`;
-        perSlot[placeholder] = buildRigAttachment(att, placeholder, where, {
+        const built = buildRigAttachment(att, placeholder, where, {
           images,
           bones,
           transforms,
@@ -1653,6 +1897,12 @@ export function compile(opts: CompileOptions): CompileResult {
           depths: attachmentDepths,
           slotNames: new Set(rig.slots.map((s) => s.name)),
         });
+        // The name is put on AFTER the builder rather than inside it: five
+        // builders write five shapes, the rule is one rule, and a rule that has
+        // to be remembered in five places is a rule that will be kept in four.
+        perSlot[placeholder] = shared?.has(placeholder)
+          ? nameSkinAttachment(built, skinAttachmentName(skinName, placeholder), placeholder)
+          : built;
       }
       tableFor(skinName)[rigSlot.name] = perSlot;
     }
@@ -2069,20 +2319,28 @@ export function compile(opts: CompileOptions): CompileResult {
     // `readSkeletonData`'s own order (`:372-443`). Every member list is a
     // conditional spread, so a rig that declares none emits the two-key entry it
     // always did, byte for byte.
-    skins: [...skinTables.entries()].map(([name, attachments]) => {
-      const parts = skinParts.get(name);
-      return {
-        name,
-        ...(parts?.bones.length ? { bones: parts.bones } : {}),
-        ...Object.fromEntries(
-          RIG_SKIN_CONSTRAINT_KEYS.filter((key) => parts?.constraints[key].length).map((key) => [
-            key,
-            parts!.constraints[key],
-          ]),
-        ),
-        attachments,
-      };
-    }),
+    //
+    // Ordered the way `animations` is and for the same reason — the editor
+    // rewrites this array and the binary half addresses it by ordinal — with the
+    // sort applied HERE rather than to `skinTables`, so everything upstream (the
+    // path-slot table, every refusal that lists skins) still reads the order the
+    // rig spec declared. See `editorSkinOrder`.
+    skins: editorSkinOrder(
+      [...skinTables.entries()].map(([name, attachments]) => {
+        const parts = skinParts.get(name);
+        return {
+          name,
+          ...(parts?.bones.length ? { bones: parts.bones } : {}),
+          ...Object.fromEntries(
+            RIG_SKIN_CONSTRAINT_KEYS.filter((key) => parts?.constraints[key].length).map((key) => [
+              key,
+              parts!.constraints[key],
+            ]),
+          ),
+          attachments,
+        };
+      }),
+    ),
     // Between `skins` and `animations`, which is where the editor writes it. A
     // conditional spread rather than an assignment after the literal, so the key
     // lands in that position instead of at the end.
@@ -2244,6 +2502,154 @@ function rotationOf(spec: RigBone, ctx: BoneContext): number | null {
   return spec.rotation ?? null;
 }
 
+// ---------------------------------------------------------------------------
+// attachment names, where one placeholder holds several attachments
+// ---------------------------------------------------------------------------
+
+/**
+ * What separates a skin's name from a placeholder's inside an attachment name.
+ *
+ * ⚠️ A separator is the one part of this that could collide with a name somebody
+ * wrote, so it is measured rather than picked: across the **160** distinct
+ * placeholder names and **159** distinct atlas region names in `examples/` and
+ * `gallery/` — every editor-authored name this repository has — `/` occurs in
+ * **0**, while `-` occurs in 85 / 86 and `_` in 37 / 37. It is also the character
+ * the format already has a structure for, since an attachment's name doubles as
+ * its texture path and a path is what `/` separates.
+ *
+ * 🔒 And the choice is not load-bearing anyway, which is the point of stating it
+ * this way: `contestedPlaceholders` refuses the build if the name it composes is
+ * one some other placeholder in the same slot already answers to. A separator
+ * nobody uses makes that refusal rare; the refusal is what makes it safe.
+ */
+const SKIN_ATTACHMENT_SEPARATOR = '/';
+
+function skinAttachmentName(skinName: string, placeholder: string): string {
+  return `${skinName}${SKIN_ATTACHMENT_SEPARATOR}${placeholder}`;
+}
+
+/**
+ * Which `(slot, placeholder)` pairs more than one skin fills — and, on the way,
+ * the refusal that keeps the composed names from colliding with authored ones.
+ *
+ * ## The defect this exists for
+ *
+ * Two skins putting different art under one placeholder is what a skin IS, and
+ * until issue #541 rigc emitted both entries with no `name`, which makes the
+ * placeholder the name of both (`SkeletonJson.ts:526`). spine-core is happy —
+ * its skin table is keyed by placeholder, so the two never meet. The Spine
+ * editor refuses the whole import, and says exactly why:
+ *
+ *     ERROR: Unable to import skeleton.
+ *     [error] Error reading skeleton: skins
+ *     Cause: [error] Error reading attachment: patch (MOw)
+ *     Cause: [error] Multiple attachments have the same name: patch patch
+ *
+ * Bisected on the emitted file: four skins REFUSED, deform timelines removed
+ * REFUSED, `default` + one skin REFUSED, `default` alone IMPORTS, the second skin
+ * given a distinct placeholder IMPORTS, and the same placeholder with **each
+ * entry given its own `name`** IMPORTS — all four skins. So it is neither the
+ * skin count nor the timelines; it is one name over several attachments.
+ *
+ * ## Only the contested pairs are named, and that is the whole rule
+ *
+ * A placeholder one skin fills keeps the emitted shape it has always had: no
+ * `name`, no `path` it did not already carry. Every rig in this tree declares
+ * exactly one skin, so **no emitted byte in the tree moves** — and a
+ * multi-skin rig whose skins use distinct placeholders does not move either,
+ * because nothing there is ambiguous to begin with.
+ *
+ * ⚠️ The scope of the editor's uniqueness rule is **not** skeleton-wide, and the
+ * corpus proves it rather than a hypothesis doing so: `spineboy-pro.json`, which
+ * the editor wrote, gives the name `head` to a region in slot `head` and to a
+ * bounding box in slot `head-bb`, and names one `hoverglow-small` across eight
+ * slots. What #541 refused was one slot. Composing from the skin makes the names
+ * unique within the slot, which satisfies that scope and every narrower one;
+ * nothing here claims to know which of them the editor actually applies, and an
+ * assertion that policed the emitted artifact would have to.
+ *
+ * ## Why a composed name is not the compiler inventing a value
+ *
+ * rigc has always decided this attachment's name — it decided it was the
+ * placeholder, silently, and that decision is the defect. What changes is the
+ * derivation, not who makes it, and the new one is a function of two names the
+ * spec wrote. Nothing is read off the art, and `path` — the field that says
+ * which texture to draw — stays exactly what the spec stated or what the
+ * attachment already resolved to.
+ */
+function contestedPlaceholders(
+  skinNames: readonly string[],
+  skinParts: Map<string, RigSkinParts>,
+): Map<string, Set<string>> {
+  /** slot -> placeholder -> the skins that fill it, in declaration order. */
+  const fillers = new Map<string, Map<string, string[]>>();
+  for (const skinName of skinNames) {
+    for (const [slotName, placeholders] of Object.entries(skinParts.get(skinName)!.attachments)) {
+      const perSlot = fillers.get(slotName) ?? new Map<string, string[]>();
+      for (const placeholder of Object.keys(placeholders)) {
+        perSlot.set(placeholder, [...(perSlot.get(placeholder) ?? []), skinName]);
+      }
+      fillers.set(slotName, perSlot);
+    }
+  }
+  const contested = new Map<string, Set<string>>();
+  const collisions: string[] = [];
+  for (const [slotName, perSlot] of fillers) {
+    const shared = new Set([...perSlot].filter(([, skins]) => skins.length > 1).map(([placeholder]) => placeholder));
+    if (shared.size) contested.set(slotName, shared);
+    /** Emitted attachment name -> the first entry that claimed it. */
+    const claimed = new Map<string, string>();
+    for (const [placeholder, skins] of perSlot) {
+      for (const skinName of skins) {
+        const name = shared.has(placeholder) ? skinAttachmentName(skinName, placeholder) : placeholder;
+        const site = `skin "${skinName}" placeholder "${placeholder}"`;
+        const taken = claimed.get(name);
+        if (taken === undefined) claimed.set(name, site);
+        else collisions.push(`slot "${slotName}": ${taken} and ${site} would both be named "${name}"`);
+      }
+    }
+  }
+  if (collisions.length) {
+    throw new CompileError(
+      `${collisions.length} attachment name collision(s): a placeholder that more than one skin fills is emitted ` +
+        `with the name "<skin>${SKIN_ATTACHMENT_SEPARATOR}<placeholder>", because the Spine editor refuses an import ` +
+        'in which one slot holds two attachments of one name (#541) — and here that composed name is one another ' +
+        'entry in the same slot already answers to. Rename the placeholder or the skin so the two differ. ' +
+        `${collisions.join('. ')}`,
+    );
+  }
+  return contested;
+}
+
+/**
+ * Give one attachment its own `name`, and pin the texture `path` that name would
+ * otherwise have taken with it.
+ *
+ * 🚨 The second half is the whole hazard. `readAttachment` reads
+ * `const name = getValue(map, "name", placeholder)` and then
+ * `const path = getValue(map, "path", name)` (`SkeletonJson.ts:526-529`, and
+ * again at `:559` for a mesh) — so `path` defaults to the NAME, not to the
+ * placeholder. Writing a name and leaving `path` alone silently repoints the
+ * attachment's texture lookup at a region no atlas has. Restating `path` at what
+ * the attachment already resolved to makes the name change invisible to
+ * everything but the editor's own uniqueness rule, which is the only thing it is
+ * for.
+ *
+ * ⚠️ `region` and `mesh` are exactly the two types that read `path`; the polygon
+ * types (`boundingbox`, `clipping`, `path`) have no texture and get the name
+ * alone. The list is the parser's own two `getValue(map, "path", …)` sites
+ * rather than a judgement about which attachments "have art".
+ */
+function nameSkinAttachment(att: SpineAttachment, name: string, placeholder: string): SpineAttachment {
+  const kind = (att as { type?: string }).type ?? 'region';
+  // Key order is the parser's reading order — `name`, then `path`, then the rest
+  // as the builder wrote it — for the same reason every other emitted object
+  // follows it: the file is read by people and diffed against references.
+  if (kind !== 'region' && kind !== 'mesh') return { name, ...att };
+  const { path, ...rest } = att as SpineRegionAttachment | SpineMeshAttachment;
+  return { name, path: path ?? placeholder, ...rest } as SpineAttachment;
+}
+
 // ---------------------------------------------------------------------------
 // rig-declared attachments
 // ---------------------------------------------------------------------------
@@ -2613,13 +3019,50 @@ function buildRigPath(att: RigPathAttachment, where: string, ctx: AttachmentCont
   };
 }
 
+/**
+ * The compiled image an attachment's `image` names — or a refusal that names the
+ * file and says what is actually wrong with it.
+ *
+ * 🚨 This exists because of what the four call sites used to do instead, which
+ * was nothing (issue #555). `ctx.images.find(...)` returning `undefined` fell
+ * through to the size branch, so an attachment that named a PNG rigc had not
+ * atlased was refused with *a region needs width and height — give them, or give
+ * an "image" and rigc will measure the PNG*: the remedy sentence handed to the
+ * one author who had already done both halves of it. The two mesh generators
+ * said `no compiled image for "x.png"`, which names the file and not the fault.
+ *
+ * ⭐ What the message may not do is guess at the spec. Every image a skin
+ * attachment names is measured and atlased, one per file, so an attachment
+ * standing in front of a region that does not exist is rigc having skipped a
+ * measurement — the author cannot repair it by writing anything. Saying so is
+ * the whole difference between a message that ends a session and one that starts
+ * a bug report, and it is why this refusal reads as an invariant rather than as
+ * advice. The near-miss list is `resolveFromAtlas`'s, for the case where the
+ * spec did misspell a name in a way something upstream let through.
+ */
+function atlasedImage(image: string, where: string, ctx: AttachmentContext): CompiledImage {
+  const region = basename(image, '.png');
+  const img = ctx.images.find((im) => im.region === region);
+  if (img) return img;
+  const near = nearMisses(region, ctx.images.map((im) => im.region));
+  const built = ctx.images.map((im) => im.region).sort();
+  throw new CompileError(
+    `${where}: the image "${image}" was never added to the atlas, so there is no region "${region}" for this ` +
+      'attachment to draw and no measurement of it to take a size from. Every image an attachment names is ' +
+      'measured and atlased — one per file, whichever skin names it (issue #555) — so reaching this means rigc ' +
+      'skipped one, not that the spec left anything out. ' +
+      (near.length ? `The nearest region(s) built are ${near.map((n) => JSON.stringify(n)).join(', ')}. ` : '') +
+      `The atlas holds ${built.length} region(s): ${built.join(', ')}`,
+  );
+}
+
 function buildRigRegion(
   att: RigRegionAttachment,
   placeholder: string,
   where: string,
   ctx: AttachmentContext,
 ): SpineRegionAttachment {
-  const img = att.image === undefined ? null : ctx.images.find((im) => im.region === basename(att.image!, '.png'));
+  const img = att.image === undefined ? null : atlasedImage(att.image, where, ctx);
   // ⭐ An IMPORTED region's size is not a default the spec may override. On the
   // loose path `att.width` and the PNG's width are two legitimate numbers — "draw
   // this drawing at this size" is a scale, and the region covers its page either
@@ -2870,7 +3313,7 @@ function buildRigMesh(
   // nor measurable it is a refusal, as it is for a region: 0 is not a size the
   // spec stated, and the editor shows whatever is written here as the image's
   // dimensions (it showed 32x32, its missing-image placeholder, for a 0x0 mesh).
-  const img = att.image === undefined ? undefined : ctx.images.find((im) => im.region === basename(att.image!, '.png'));
+  const img = att.image === undefined ? undefined : atlasedImage(att.image, where, ctx);
   const width = att.width ?? img?.width;
   const height = att.height ?? img?.height;
   if (width === undefined || height === undefined) {
@@ -3377,9 +3820,7 @@ function buildGridAttachment(
     );
   }
 
-  const region = basename(att.image, '.png');
-  const img = ctx.images.find((im) => im.region === region);
-  if (!img) throw new CompileError(`${where}: no compiled image for "${att.image}"`);
+  const img = atlasedImage(att.image, where, ctx);
   const plate = partPlate(img);
 
   let geometry;
@@ -3460,7 +3901,7 @@ function buildGridAttachment(
     height: r6(h),
   };
   if (att.path !== undefined) out.path = att.path;
-  else if (region !== placeholder) out.path = region;
+  else if (img.region !== placeholder) out.path = img.region;
   if (att.color !== undefined) out.color = att.color;
   return out;
 }
@@ -3503,9 +3944,7 @@ function buildContourAttachment(
         'there is nothing else here that says which pixels to measure',
     );
   }
-  const region = basename(att.image, '.png');
-  const img = ctx.images.find((im) => im.region === region);
-  if (!img) throw new CompileError(`${where}: no compiled image for "${att.image}"`);
+  const img = atlasedImage(att.image, where, ctx);
   // ⚠️ Nothing here reads the PNG's colour type. `hasAlpha` answers "where does
   // this file keep its alpha", not "is any pixel of it transparent" — a tRNS
   // chunk is real transparency (issue #215) and an all-255 alpha channel is
@@ -3602,7 +4041,7 @@ function buildContourAttachment(
   // basename, so a placeholder named anything else needs `path` written down or
   // the loader resolves nothing.
   if (att.path !== undefined) out.path = att.path;
-  else if (region !== placeholder) out.path = region;
+  else if (img.region !== placeholder) out.path = img.region;
   if (att.color !== undefined) out.color = att.color;
   return out;
 }
@@ -3704,7 +4143,12 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
   if (spec.type === 'ik') {
     out.bones = boneList();
     out.target = needBone(spec.target, 'target');
-    copy(['scaleY', 'mix', 'softness', 'bendPositive', 'compress', 'stretch', 'skin']);
+    // `scaleY` is the `ScaleYMode` enum, not a number or a flag: the parser runs
+    // it through `Utils.enumValue` (`:150`), which resolves an unknown name to
+    // `undefined` and assigns it without a word. Out of `copy` for that reason —
+    // see `RIG_SCALE_Y_MODES`.
+    if (spec.scaleY !== undefined) out.scaleY = needEnum(spec.scaleY, 'scaleY', RIG_SCALE_Y_MODES);
+    copy(['mix', 'softness', 'bendPositive', 'compress', 'stretch', 'skin']);
     return out;
   }
   if (spec.type === 'transform') {
@@ -4090,13 +4534,15 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
   }
   if (spec.type === 'physics') {
     out.bone = needBone(spec.bone, 'bone');
+    // The same `ScaleYMode` enum an ik constraint carries, under the same key
+    // and through the same silent `Utils.enumValue` (`:301`).
+    if (spec.scaleY !== undefined) out.scaleY = needEnum(spec.scaleY, 'scaleY', RIG_SCALE_Y_MODES);
     copy([
       'x',
       'y',
       'rotate',
       'scaleX',
       'shearX',
-      'scaleY',
       'limit',
       'fps',
       'inertia',
@@ -4199,6 +4645,7 @@ function buildRigInfo(
     meshKinds,
     meshSoftBones,
     deformMayFold,
+    editorRoundTrip: rig.invariants?.editorRoundTrip === true,
     meshSlotBudget: rig.invariants?.meshSlots ?? null,
     meshTriangleBudget: rig.invariants?.meshTriangles ?? null,
     contactDepth,