spine-rigc 0.21.0 → 0.22.0

package/cli.ts

@@ -2411,8 +2411,14 @@ function cmdExplain(flags: Record<string, string>): void {
   }
 
   console.log('\nslots  (array order IS the draw order)');
+  // The DEFAULT skin's placeholders, resolved by name. It was `skins[0]` until
+  // issue #541, which is the same thing only because rigc pins `default` at
+  // index 0 — a property of the emitter that this report should not be quietly
+  // relying on. Reading it by name means a change to the skins ORDER cannot turn
+  // this line into a report about some other skin.
+  const defaultSkin = result.skeleton.skins.find((skin) => skin.name === 'default');
   for (const s of result.skeleton.slots) {
-    const atts = Object.keys(result.skeleton.skins[0].attachments[s.name] ?? {});
+    const atts = Object.keys(defaultSkin?.attachments[s.name] ?? {});
     console.log(
       `  ${s.name.padEnd(12)} bone=${s.bone.padEnd(12)} setup=${(s.attachment ?? 'null').padEnd(22)} color=${s.color ?? 'ffffffff'}  attachments=[${atts.join(', ')}]`,
     );

package/docs/AUTHORING.md

@@ -540,6 +540,15 @@ in the skeleton and the size in the atlas cannot drift apart. The **region name
 PNG's basename**; when your placeholder name differs from it, rigc writes a `path`
 so the attachment still joins to the region.
 
+**Every** attachment that names an `image` is measured, whichever skin it sits in.
+The atlas holds **one region per file**, so two skins filling one placeholder from
+two files put two regions in it and each attachment draws its own (§3.4.2), while
+two attachments naming the same file share the one region that file made. What
+cannot be reconciled is two *different* files whose basenames collide — only one of
+them can be region `patch` — so rigc refuses the build and names both paths rather
+than letting one of them silently draw the other's pixels
+([#555](https://github.com/firejune/rigc/issues/555)).
+
 **R6 — A key carries `ease` or `curve`, never both.** A named easing says "this
 shape, wherever it is used" and is the recommended path. `curve` is the escape
 hatch: the absolute `(time, value)` control points, verbatim, for when every key
@@ -612,6 +621,33 @@ only repair was *rename* — the one repair a transcription cannot take. Emittin
 member of the family instead moves no byte on any set the old rule accepted; it
 just stops refusing the ones it did.
 
+**R11 — The `skins` array is written with `default` first and the rest in the
+editor's order, and skin names that have no one order are refused.** The same rule
+as R10, in the collection that was believed exempt from it. A skin is a **name** in
+the JSON half of the format and an **ordinal** in the binary half —
+`skins[readInt()]` for an attachment timeline, `skins[skinIndex]` for a linked mesh
+— so an editor that writes the array in another order repoints every such
+reference, silently, in a file that still parses. Measured: a rig built
+`default, zulu, mike, alpha` exported `default, alpha, mike, zulu`
+([#541](https://github.com/firejune/rigc/issues/541)).
+
+⚠️ **The refusal here is wider than R10's, and deliberately.** R10 can be narrow
+because #539 measured two animation-name pairs and thereby *refuted* a codepoint
+sort. The skins measurement refutes nothing — `alpha, mike, zulu` is the answer
+codepoint, folding and natural order all give — so the editor's skin comparator is
+**not established**, and rigc refuses any pair those candidates could disagree
+about. In practice that is R10's four rows plus two more: a pair a case fold
+reverses (`Zulu` against `mike`) and two digit runs of unequal width (`mike10`
+against `mike2`). Both of those *build* as animation names and are refused as skin
+names, and the two refusals say which is which.
+
+**R12 — A placeholder that more than one skin fills gets a per-skin attachment
+`name`.** rigc writes `"name": "<skin>/<placeholder>"` on each of those entries,
+and restates `path` beside it so the texture still resolves where it did. You do
+not author this and there is nothing to do about it — but it is visible in the
+emitted file, so §3.4.2 says what it is and why. A placeholder only one skin fills
+is emitted exactly as before.
+
 ---
 
 ## 3. The rig spec, field by field
@@ -709,7 +745,7 @@ the default `type`:
 | `type` | `"region"`, or omit |
 | `image` | **rigc extension.** A PNG relative to the rig's `images` directory; rigc measures it (R5) |
 | `width`, `height` | required by the format — give them, or give an `image` |
-| `path` | the atlas region to resolve; defaults to the attachment's own name. rigc sets it for you when the PNG basename differs from the placeholder |
+| `path` | the atlas region to resolve; defaults to the attachment's own name. rigc sets it for you when the PNG basename differs from the placeholder, and whenever it composes a `name` because more than one skin fills this placeholder (§3.4.2) |
 | `x`, `y` | offset from the bone, in the bone's local space |
 | `rotation` | degrees; cancels a rotated bone for a plate authored screen-upright |
 | `scaleX`, `scaleY`, `color` | as Spine |
@@ -1372,6 +1408,70 @@ beside them is refused rather than ignored (an ignored slot is an attachment tha
 vanishes), and a rig with a *slot* of one of those names is refused too, because
 there the two forms are genuinely ambiguous. Rename the slot.
 
+#### 3.4.2 Two skins, one placeholder — the `name` rigc writes for you
+
+Two skins putting different art under one placeholder is what a skin is *for*, and
+it is the one shape rigc emitted wrongly until
+[#541](https://github.com/firejune/rigc/issues/541). Without a `name` field an
+attachment's name **is** its placeholder (`SkeletonJson.ts:526`), so four skins
+filling `patch` are four different attachments all called `patch`. spine-core never
+notices — its skin table is keyed by placeholder, so the two never meet — and the
+whole gate is green. The Spine editor refuses the import outright:
+
+```
+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
+```
+
+⇒ rigc now writes each of those entries a name of its own, composed from the two
+names you already gave it:
+
+```json
+"skins": {
+  "default": { "patch": { "patch": { "image": "patch_a.png" } } },
+  "zulu":    { "patch": { "patch": { "image": "patch_a.png", "x": 4 } } }
+}
+```
+
+emits
+
+```json
+{ "name": "default/patch", "path": "patch", "width": 64, "height": 64 }
+{ "name": "zulu/patch",    "path": "patch", "width": 64, "height": 64, "x": 4 }
+```
+
+Three things to know about it and nothing to author:
+
+- **`path` is restated, and it has to be.** `path` defaults to the attachment's
+  **name**, not to its placeholder, so an entry given a name and no path would
+  resolve its texture at `zulu/patch` and find no such region. `A00_ROUNDTRIP_PARSE`
+  says so in the parser's own words if it is ever dropped.
+- **Only contested placeholders are touched.** One skin filling a placeholder, or
+  two skins filling a slot under *different* placeholders, emit exactly what they
+  always did — every rig in this repository is byte-identical across the change.
+- **A composed name that collides is a compile error, not a surprise.** If some
+  other placeholder in the same slot is literally called `zulu/patch`, rigc refuses
+  and names both sites rather than emitting two attachments with one name again.
+  (`/` is the separator because it appears in **0** of the 160 placeholder names and
+  159 atlas region names in `examples/` and `gallery/`, where `-` appears in 85 and
+  `_` in 37.)
+- **Each skin's art is measured and atlased on its own.** The example above points
+  both skins at one PNG, so there is one region; point them at two and there are
+  two, each attachment's `path` resolving to the file that attachment named and its
+  `width`/`height` measured off that file. Until
+  [#555](https://github.com/firejune/rigc/issues/555) only the first skin's PNG was
+  ever opened, and the second skin's art reached neither the atlas nor the
+  measurement — so name the two files **distinctly**, because the region name is
+  the basename and `a/patch.png` beside `b/patch.png` is refused (R5).
+
+⚠️ **The uniqueness scope is the slot, not the skeleton.** `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 reuses `hoverglow-small` across eight slots. So
+a name shared between slots is normal and rigc leaves it alone; what #541 refused
+was one slot holding two.
+
 ### 3.5 `constraints` — 4.3's single typed array
 
 Spine 4.3 folds every constraint into one `constraints` array with a `type`
@@ -3365,6 +3465,8 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `the triangles do not tile the outline: …` / `the triangles' outline is not one closed loop: …` | §3.4 — a doubled triangle, an unused vertex, a pinch or a hole in `triangles` |
 | `image "X.png" is not on disk at …` | fix the name, or point `--images` at the right directory |
 | `duplicate region name "X"` | two PNGs share a basename; one part, one page, one name |
+| `"b/X.png" and the art already atlased as region "X" are two different files — … Rename one of the PNGs.` | R5 — the region name is the basename, so only one of the two can hold it. Rename a file (not a placeholder: the placeholder is free to repeat) |
+| `the image "X.png" was never added to the atlas, so there is no region "X" …` | nothing in the spec — every image an attachment names is measured, so this says rigc skipped one. Report it ([#555](https://github.com/firejune/rigc/issues/555)) |
 | `motion spec names archetype "A" but the rig spec at … is called "B"` | make `archetype` equal the rig's `name` |
 | `animation "A" declares duration Ns but its last key is at Ms` | R7 — fix whichever of the two you meant |
 | `animation "A" slot "X" attachment: key at Ns is Ms past the declared duration Ds` | §4.5 — the key is past the end of the animation and nothing will sample it. Move the key onto `duration`, or raise `duration` |
@@ -3426,6 +3528,8 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `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" / "Turn" (case) — they are one name in two cases, and which of them the editor puts first is not measured; rename one of them so they differ by more than letter case` | **R10** — rename until no pair is left. The kind in brackets says which of the editor comparator's four UNMEASURED choices decides the pair: `case` (a pure case tie), `number` (one number written two ways, or a run of digits against a word) or `separator` (make the first character that differs a letter or a digit). rigc keys `animations` in the editor's own comparator — natural and case-insensitive ([#539](https://github.com/firejune/rigc/issues/539), [#543](https://github.com/firejune/rigc/issues/543)) — so a pair that comparator settles is emitted rather than refused, and only the four choices nobody has measured are a compile error; on those, the editor's re-key repoints every slider whose animation moves index ([#535](https://github.com/firejune/rigc/issues/535)) |
+| `N pair(s) of skin names have no one order: … "Zulu" / "mike" (case) — folded to one case "Zulu" and "mike" order the other way round, so whether the editor folds SKIN names decides this pair` | **R11** — rename until no pair is left. The same shape as the row above with a **wider** family: #539 measured the editor's comparator for animation names and thereby ruled codepoint out, and nothing has ruled anything out for skin names, so a pair the candidates could disagree about is refused even where the animation rule would emit it. `Zulu`/`mike` and `mike10`/`mike2` build as animation names and are refused as skin names ([#541](https://github.com/firejune/rigc/issues/541)) |
+| `N attachment name collision(s): a placeholder that more than one skin fills is emitted with the name "<skin>/<placeholder>" … slot "patch": skin "default" placeholder "zulu/patch" and skin "zulu" placeholder "patch" would both be named "zulu/patch"` | **R12** — rename the placeholder or the skin. rigc composes an attachment name for every placeholder more than one skin fills (§3.4.2), and this fires when the composed name is one another entry in the same slot already answers to. Both sites are named; either rename ends it |
 
 ### 5.2 Assertions — the gate
 
@@ -4972,12 +5076,17 @@ 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 editor re-keys every name-keyed OBJECT, and leaves `bones`, `slots` and
+`constraints` 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.
+
+🚨 **Not every array: `skins` it re-sorts.** That sentence read *"leaves every
+ARRAY alone"* for two releases, on those three arrays and nothing else, and
+`skins` is the one it was wrong about — see the paragraph at the end of this
+section.
 
 ⚠️ **The order it sorts them into is natural and case-insensitive, not
 codepoint.** This paragraph said codepoint until
@@ -5008,20 +5117,31 @@ 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.
 
-⚠️ **Read *"leaves every ARRAY alone"* above as bones, slots and constraints —
-`skins` is the array that round trip was not taken over.** `gallery/look` declares
-one skin, as does every other rig in this repository and all twelve editor exports
-in `examples/`, and a one-element array comes back in order whatever the editor
-does to it — so nothing here is
-evidence about `skins`, and a pull request that once called them *measured
-preserved* was reading a vacuous result ([#544](https://github.com/firejune/rigc/issues/544)).
-It matters because `skins` carries ordinals in the binary half too —
-`skins[readInt()]` for an attachment timeline and a linked mesh's skin index — so
-a re-order there would repoint them the way the `animations` re-key repoints a
-slider. ⛔ And it cannot be measured today: the editor refuses a four-skin rig on
-import without writing a project file or printing a word
-([#541](https://github.com/firejune/rigc/issues/541)). ⇒ **If you author more than
-one skin, nothing on this page says the editor survives it.**
+🚨 **`skins` is re-sorted, with `default` pinned first — measured, and it is the
+first array measured to move.** A four-skin rig built `default, zulu, mike, alpha`
+exported `default, alpha, mike, zulu`
+([#541](https://github.com/firejune/rigc/issues/541)), and the deform timelines
+came back keyed `mike, zulu` rather than `zulu, mike` with it. Note `alpha` sorts
+before `default` under every candidate comparator and still came back second: the
+default skin is **pinned**, not sorted. It matters for the same reason `animations`
+does — `skins` carries ordinals in the binary half, `skins[readInt()]` for an
+attachment timeline and `skins[skinIndex]` for a linked mesh — so this is the
+`animations` defect (#535) in the collection nobody had checked. ⇒ in rigc: R11.
+
+⚠️ **What that measurement does *not* settle is which comparator.** `alpha, mike,
+zulu` is the order codepoint, case-folding and natural order all produce, so unlike
+the animations case nothing here refutes anything, and rigc refuses any skin-name
+pair the candidates could disagree about (R11).
+
+✅ **The two readings this replaces.** A pull request once called `skins` *measured
+preserved*, on the strength of a one-skin rig where a one-element array comes back
+in order whatever the editor does to it;
+[#544](https://github.com/firejune/rigc/issues/544) corrected that to *unmeasured*,
+and added that it could not be measured because the editor refused a four-skin rig
+on import without printing a word. Both readings were the same generalisation — *an
+editor does not move arrays* — off the three arrays that were measured, and the
+"without a word" was rigc's own harness discarding the editor's stderr, which had
+named the cause all along (§3.4.2).
 
 ### 10.2 Draw order
 

package/docs/SPEC_COVERAGE.md

@@ -602,6 +602,15 @@ with the member's own `skin: true` — either half alone is refused, because `Sk
 | `clipping` | ✅ under `--profile spine` · 🚫 under `spine-html` | `end` (refused when it names no slot), `convex`, `inverse`, `vertexCount`, geometry, `color`. **A33**, and **A11_NO_CLIPPING_ATTACHMENTS** is the renderer-profile refusal |
 | `sequence` block | ❌ | |
 
+Across all five types, rigc emits the attachment's own **`name`** in exactly one case: a placeholder
+that more than one skin fills (`compile.ts`'s `nameSkinAttachment`). Part 1-5 above states why it
+matters — `name` defaults to the placeholder and `path` defaults to `name` — so several skins under
+one placeholder are several attachments with one name, which spine-core accepts and the Spine editor
+refuses on import ([#541](https://github.com/firejune/rigc/issues/541)). The composed name is
+`<skin>/<placeholder>`, `path` is restated beside it so the region still resolves, and a placeholder
+one skin fills is emitted with neither. Nothing else in the tree carries a `name`: of the twelve
+editor exports in `examples/`, **0** attachments do, because all twelve declare one skin.
+
 Mesh geometry is generated by exactly three procedural generators (`mesh.ts`): `buildRingMesh`
 (three concentric rings + hub, outer two pinned), `buildRibbonMesh` (a two-wide strip along a bone
 chain) and `buildContourMesh` (marching-squares trace of the part's own alpha → Douglas-Peucker →

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.21.0",
+  "version": "0.22.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": {
@@ -59,6 +59,7 @@
     "validate": "bun cli.ts validate",
     "explain": "bun cli.ts explain",
     "selftest": "bun selftest.ts",
+    "smoke": "bun scripts/install_smoke.ts",
     "typecheck": "bunx tsc --noEmit",
     "typecheck:runs": "bunx tsc --noEmit -p tsconfig.runs.json",
     "lint": "bunx eslint .",

package/src/compile.ts

@@ -58,6 +58,7 @@ import {
   type RigMeshBinding,
   type RigPathAttachment,
   type RigRegionAttachment,
+  type RigSkinParts,
   type RigSpec,
   type RigVertexGeometry,
   type RigDepthMap,
@@ -248,7 +249,7 @@ function editorAnimationOrder<T>(animations: Record<string, T>): Record<string,
   // 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);
+  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.
@@ -258,6 +259,66 @@ function editorAnimationOrder<T>(animations: Record<string, T>): Record<string,
   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 member of the measured family agrees
  * on: the digits and, once case is folded, the lower-case ASCII letters.
@@ -417,14 +478,112 @@ function measuredOrder(a: string, b: string): number | Ambiguity {
   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, and hand back the verdict for every pair that survived — the check that
- * lets `editorAnimationOrder` sort by the measured family without choosing a
- * member of it.
+ * 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.
+ */
+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
@@ -435,8 +594,17 @@ const PAIRS_SPELLED_OUT = 8;
  * 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[]): Map<string, Map<string, number>> {
+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>();
@@ -447,7 +615,7 @@ function refuseNamesTheEditorCouldKeyDifferently(names: readonly string[]): Map<
   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 = measuredOrder(names[i], names[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);
@@ -459,12 +627,7 @@ function refuseNamesTheEditorCouldKeyDifferently(names: readonly string[]): Map<
   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 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). ' +
+    `${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)` : ''),
   );
@@ -1286,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:
@@ -1308,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
@@ -1490,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 --------------------------------------------------------------
   //
@@ -1657,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,
@@ -1672,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;
     }
@@ -2088,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.
@@ -2263,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
 // ---------------------------------------------------------------------------
@@ -2632,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
@@ -2889,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) {
@@ -3396,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;
@@ -3479,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;
 }
@@ -3522,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
@@ -3621,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;
 }

package/src/types.ts

@@ -702,7 +702,24 @@ export interface SpineSlot {
   blend?: string;
 }
 
+/**
+ * The attachment's own name, as distinct from the placeholder it is filed under.
+ *
+ * `readAttachment` reads `const name = getValue(map, "name", placeholder)`
+ * (`SkeletonJson.ts:526`), so an absent field means "the placeholder is also the
+ * name" — which is what rigc emitted for every attachment until issue #541, and
+ * what makes several skins' entries under one placeholder **several attachments
+ * with one name**. spine-core does not care; the Spine editor refuses the import
+ * outright, naming the section, the attachment and the rule.
+ *
+ * 🚨 Writing it moves a second field with it. For the two types that carry
+ * texture art, `path` defaults to **`name`**, not to the placeholder
+ * (`:529`, `:559`), so an attachment given a name and no path resolves its region
+ * at the new name and the atlas lookup misses. `nameSkinAttachment` in
+ * `compile.ts` is the one place that writes either, and it always writes both.
+ */
 export interface SpineRegionAttachment {
+  name?: string;
   path?: string;
   /** Required. Omitting these yields NaN with no error. */
   width: number;
@@ -727,6 +744,8 @@ export interface SpineRegionAttachment {
  */
 export interface SpineMeshAttachment {
   type: 'mesh';
+  /** See `SpineRegionAttachment.name` — and it takes `path` with it. */
+  name?: string;
   path?: string;
   uvs: number[];
   triangles: number[];
@@ -761,6 +780,8 @@ export interface SpineMeshAttachment {
  */
 export interface SpineBoundingBoxAttachment {
   type: 'boundingbox';
+  /** See `SpineRegionAttachment.name`. No `path`: this type reads none. */
+  name?: string;
   vertexCount: number;
   /** Unweighted x/y pairs, or the weighted run — same encoding as a mesh's. */
   vertices: number[];
@@ -769,6 +790,8 @@ export interface SpineBoundingBoxAttachment {
 
 export interface SpineClippingAttachment {
   type: 'clipping';
+  /** See `SpineRegionAttachment.name`. No `path`: this type reads none. */
+  name?: string;
   /** The last slot the clip applies to. Absent = to the bottom of the order. */
   end?: string;
   convex?: boolean;
@@ -790,6 +813,8 @@ export interface SpineClippingAttachment {
  */
 export interface SpinePathAttachment {
   type: 'path';
+  /** See `SpineRegionAttachment.name`. No texture `path`: this type reads none. */
+  name?: string;
   closed?: boolean;
   constantSpeed?: boolean;
   vertexCount: number;
@@ -884,19 +909,29 @@ export interface SpineSkeletonJson {
    *   #543, with the refusal widened to cover every pair codepoint could order
    *   differently; that refused both rigs above, which are the only two anybody
    *   has measured, and it moved no byte to stop doing so.
-   * - **`skins` was on the safe side of this list and has no measurement behind
-   *   it.** The arrays the round trip actually returned element for element were
-   *   `bones` (30), `slots` (24) and `constraints` (3). Every rig in this tree
-   *   declares exactly ONE skin, and a one-element array comes back in order
-   *   whatever the editor does with it — #537's pull request called skins
-   *   "measured preserved" on that evidence, and vacuous is not preserved. Nor
-   *   can it be measured today: the editor refuses a four-skin rig on import
-   *   without a word (#541), so there is no export to read. ⇒ `bones` / `slots`
-   *   / `constraints` are the references an editor was measured not to move;
-   *   `skins` is unmeasured, and `SkeletonBinary` addresses it by ordinal too
-   *   (`skins[readInt()]` for an attachment timeline, `skins[skinIndex]` for a
-   *   linked mesh), so it is the collection to measure first if that ever
-   *   becomes possible.
+   * - 🚨 **`skins` is NOT an array the editor leaves alone. It is the first one
+   *   measured moved** (#541). A four-skin rig built `default, zulu, mike,
+   *   alpha` came back `default, alpha, mike, zulu`: `default` is pinned first
+   *   and the rest are re-sorted, and the deform timelines came back keyed
+   *   `mike, zulu` rather than `zulu, mike` with it. `SkeletonBinary` addresses
+   *   skins by ORDINAL — `skins[readInt()]` for an attachment timeline,
+   *   `skins[skinIndex]` for a linked mesh — so this is #535 in the collection
+   *   nobody had checked. rigc emits `default` first and the rest in that
+   *   order since #541; see `compile.ts`'s `editorSkinOrder`.
+   *
+   *   ⚠️ **The two readings this replaces, kept because the second is the one
+   *   that cost something.** #537's pull request called `skins` "measured
+   *   preserved"; #544 corrected that to *unmeasured*, on the grounds that the
+   *   arrays the round trip actually returned element for element were `bones`
+   *   (30), `slots` (24) and `constraints` (3), that every rig in this tree
+   *   declares exactly ONE skin, and that a one-element array comes back in
+   *   order whatever the editor does with it. Both readings were reached by
+   *   generalising from the three arrays that *were* measured — "an editor does
+   *   not move arrays" — and the generalisation is what was false. #544 also
+   *   said the measurement could not be taken, because the editor refused a
+   *   four-skin rig on import without a word: that refusal was rigc's own
+   *   harness discarding the editor's stderr, and the editor had named the
+   *   cause all along.
    */
   events?: Record<string, SpineEvent>;
   animations: Record<

package/tools/editor_roundtrip.ts

@@ -260,6 +260,53 @@ interface Ran {
   timedOut: boolean;
 }
 
+/**
+ * Everything the editor printed on a step that did not do what it was for.
+ *
+ * 🚨 This is the defect issue #541 is half about, and it was this tool's. A
+ * four-skin rig would not import; the report said
+ *
+ *     ## 1 import  (json -> project)
+ *       exit=1
+ *     rigc editor_roundtrip: the editor wrote no project file; the import did not happen
+ *
+ * and the card was filed as *"the editor refuses it without a word"*. The editor
+ * had not been silent at all — it named the section, the attachment and the rule:
+ *
+ *     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
+ *
+ * `run` captured both streams and the report printed neither. A day of bisecting
+ * the emitted file rediscovered what one of those lines says outright, and the
+ * repository whose whole doctrine is *convert silence into a named failure* had
+ * manufactured the silence.
+ *
+ * ⭐ The refusal is unchanged and stays unchanged: a step that did not produce
+ * its artifact is still a refusal by name, and this adds the reason rather than
+ * softening the verdict. What it prints is the editor's own words, quoted and
+ * attributed to the stream they came off, and never rewritten — a harness that
+ * summarised them would be the same defect with a smaller radius.
+ */
+function editorSaid(ran: Ran): string[] {
+  const lines: string[] = [];
+  for (const [stream, text] of [
+    ['stdout', ran.stdout],
+    ['stderr', ran.stderr],
+  ] as const) {
+    const body = text.replace(/\s+$/, '');
+    if (body === '') continue;
+    lines.push(`  the editor's ${stream}:`);
+    for (const line of body.split('\n')) lines.push(`    | ${line}`);
+  }
+  // Silence is a finding too, and it has to be stated rather than left to look
+  // like a harness that forgot to print. The card above is what an unstated one
+  // costs.
+  if (lines.length === 0) lines.push('  the editor printed nothing on stdout or stderr');
+  return lines;
+}
+
 function run(cmd: string, args: string[], timeoutS: number): Ran {
   const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: timeoutS * 1000 });
   return {
@@ -405,24 +452,47 @@ function shapeDiff(before: Shape, after: Shape): string[] {
 function main(): void {
   const opts = parseArgs(process.argv.slice(2));
   const rigc = rigcCommand();
+
+  const source = join(opts.build, 'skeleton.json');
+  const log: string[] = [];
+  const emit = (line: string): void => {
+    console.log(line);
+    log.push(line);
+  };
+  const logPath = join(opts.out, 'roundtrip.log');
+  /**
+   * Write what the run has said so far, wherever it stops.
+   *
+   * ⚠️ `roundtrip.log` used to be written on the last line of `main`, so a run
+   * that REFUSED wrote none — and issue #541's card cites the log as the place to
+   * read the editor's output, which on a failed import was a file that did not
+   * exist. A record kept only for the runs that went well is not a record.
+   */
+  const keepLog = (): void => {
+    // Nothing said, nothing to keep: the refusals that fire before the first
+    // `emit` (no build directory) would otherwise leave an empty file and a
+    // directory the run never used.
+    if (log.length === 0) return;
+    try {
+      mkdirSync(opts.out, { recursive: true });
+      writeFileSync(logPath, `${log.join('\n')}\n`);
+    } catch {
+      // A log this cannot write is not worth failing a refusal over; the same
+      // lines already went to stdout.
+    }
+  };
   const fail = (message: string): never => {
+    keepLog();
     console.error(`rigc editor_roundtrip: ${message}`);
     process.exit(1);
   };
 
-  const source = join(opts.build, 'skeleton.json');
   if (!existsSync(source)) fail(`no skeleton.json in the build directory ${opts.build}`);
 
   rmSync(opts.out, { recursive: true, force: true });
   mkdirSync(join(opts.out, 'export'), { recursive: true });
   mkdirSync(join(opts.out, 'export-cand'), { recursive: true });
 
-  const log: string[] = [];
-  const emit = (line: string): void => {
-    console.log(line);
-    log.push(line);
-  };
-
   emit(`## 0 versions`);
   emit(`  rigc     ${rigc.how}`);
   emit(`  ${run(rigc.cmd, [...rigc.prefix, '--version'], 60).stdout.trim()}`);
@@ -467,16 +537,33 @@ function main(): void {
     const project = join(opts.out, `${opts.name}.spine`);
     const imported = run(opts.editor, [...pin, '-i', source, '-o', project, '-r', opts.name], opts.timeoutS);
     emit(`  exit=${imported.status}${imported.timedOut ? `  TIMED OUT after ${opts.timeoutS}s` : ''}`);
+    // A step "went wrong" if it reported failure OR did not leave the artifact
+    // it exists to leave. Both are cases where the editor's own words are the
+    // next thing anybody needs, and both used to print only `exit=`.
+    const importWrong = imported.status !== 0 || imported.timedOut || !existsSync(project);
+    if (importWrong) for (const line of editorSaid(imported)) emit(line);
     if (imported.timedOut) fail(`the editor did not return within ${opts.timeoutS}s on import — that is a hang, not a result`);
-    if (!existsSync(project)) fail('the editor wrote no project file; the import did not happen');
+    if (!existsSync(project)) {
+      fail(`the editor wrote no project file; the import did not happen — what it printed is above and in ${logPath}`);
+    }
 
     emit('');
     emit('## 2 export  (project -> json, default settings)');
     const exported = run(opts.editor, [...pin, '-i', project, '-o', join(opts.out, 'export'), '-e', 'json'], opts.timeoutS);
     emit(`  exit=${exported.status}${exported.timedOut ? `  TIMED OUT after ${opts.timeoutS}s` : ''}`);
+    const written = existsSync(join(opts.out, 'export'))
+      ? readdirSync(join(opts.out, 'export')).filter((f) => f.endsWith('.json'))
+      : [];
+    if (exported.status !== 0 || exported.timedOut || written.length === 0) {
+      for (const line of editorSaid(exported)) emit(line);
+    }
     if (exported.timedOut) fail(`the editor did not return within ${opts.timeoutS}s on export — that is a hang, not a result`);
-    const written = readdirSync(join(opts.out, 'export')).filter((f) => f.endsWith('.json'));
-    if (written.length === 0) fail('the editor wrote no json; stopping before the re-gate rather than measuring nothing');
+    if (written.length === 0) {
+      fail(
+        'the editor wrote no json; stopping before the re-gate rather than measuring nothing — what it printed ' +
+          `is above and in ${logPath}`,
+      );
+    }
     exportedJson = join(opts.out, 'export', written[0]);
   }
 
@@ -547,9 +634,9 @@ function main(): void {
   if (rows.length === 0) emit('  nothing at this resolution: same version, counts, animations and timeline kinds');
   for (const row of rows) emit(`  ${row}`);
 
-  writeFileSync(join(opts.out, 'roundtrip.log'), `${log.join('\n')}\n`);
+  keepLog();
   emit('');
-  emit(`log: ${join(opts.out, 'roundtrip.log')}`);
+  emit(`log: ${logPath}`);
   // The verdict is the gate's and the check's, not this tool's opinion of them.
   process.exit(gate.status === 0 && check.status === 0 ? 0 : 1);
 }