spine-rigc 0.22.0 → 0.22.2

package/docs/AUTHORING.md

@@ -642,11 +642,17 @@ against `mike2`). Both of those *build* as animation names and are refused as sk
 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.
+`name`, and the `default` skin may not be one of those skins.** 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 that 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. What you *do* author is where the shared art lives: a
+placeholder the `default` skin shares with a named skin is a **compile error**,
+because the Spine editor has no representation for it in either spelling (#567,
+measured on 4.3.26 — named, the export re-keys it and the default skin draws
+nothing; unnamed, the import is refused). Put the shared entry in a named skin —
+`base` — and every filler is a named skin. A placeholder only one skin fills is
+emitted exactly as before, in the default skin or anywhere else.
 
 ---
 
@@ -1430,18 +1436,62 @@ names you already gave it:
 
 ```json
 "skins": {
-  "default": { "patch": { "patch": { "image": "patch_a.png" } } },
+  "default": { "block": { "block": { "image": "block.png" } } },
+  "base":    { "patch": { "patch": { "image": "patch_a.png" } } },
   "zulu":    { "patch": { "patch": { "image": "patch_a.png", "x": 4 } } }
 }
 ```
 
-emits
+emits, for slot `patch`
 
 ```json
-{ "name": "default/patch", "path": "patch", "width": 64, "height": 64 }
-{ "name": "zulu/patch",    "path": "patch", "width": 64, "height": 64, "x": 4 }
+{ "name": "base/patch", "path": "patch", "width": 64, "height": 64 }
+{ "name": "zulu/patch", "path": "patch", "width": 64, "height": 64, "x": 4 }
 ```
 
+🚨 **Every skin that shares a placeholder has to be a named one — the default
+skin may not be among them, and rigc refuses the rig if it is.** That is not a
+style rule; it is the editor's model, and two round trips through Spine
+**4.3.26** established it by ruling out both of the only two spellings there are
+([#567](https://github.com/firejune/rigc/issues/567)):
+
+- **Give the default skin's entry a name of its own** (`"name": "default/patch"`)
+  and the import succeeds — then the export comes back with that name as the
+  JSON **key** (`"default/patch": { … }`, the `name` field gone), because the
+  editor's default skin holds no skin placeholders: an attachment there hangs on
+  the slot and is known by its name alone. The slot's setup `attachment: "patch"`
+  now names a key the default skin does not have, so the default skin **draws
+  nothing** — `diff` read `attachments.names 3/5`, `check` read 98.52 mean MAE
+  with `drewSlots: 0` on that chain, and `validate --profile spine` stayed green
+  throughout.
+- **Leave it as its placeholder** (no `name`, which is the obvious repair) and
+  the editor **refuses the import**:
+
+  ```
+  ERROR: Unable to import skeleton.
+  Cause: [error] Error reading attachment: mike/patch (nSX)
+  Cause: [error] Multiple attachments have the same name:
+  patch
+  patch
+  ```
+
+  In one slot, a default-skin attachment name and a named skin's placeholder name
+  are the same namespace, and both are `patch`.
+
+⇒ **The rule: move the shared art into a named skin.** Call it `base`. Every
+filler of that placeholder is then a named skin, rigc composes all of them, and
+the names are unique within the slot — which is all
+[#541](https://github.com/firejune/rigc/issues/541) needed: `base/patch`,
+`zulu/patch` and `mike/patch` are three names. That shape is the one the editor
+does hold: the same three fillers in named skins imported, exported and measured
+**0.00 mean MAE** with names and paths intact.
+
+📎 **The earlier reading, kept because it was reasonable and wrong.** Between the
+two trips this guide said *compose off the default skin only* — keep the default
+skin's entry as its placeholder and name the others. Trip 7 supported it and trip
+8 refuted it: that is the spelling the editor refuses at the door. There is no
+third spelling, which is why this is a refusal rather than a naming scheme.
+
 Three things to know about it and nothing to author:
 
 - **`path` is restated, and it has to be.** `path` defaults to the attachment's
@@ -1454,6 +1504,9 @@ Three things to know about it and nothing to author:
 - **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.
+  The walk covers every *uncontested* entry's plain name too, the default skin's
+  included — a name that composed nothing can still be the one another skin
+  composes.
   (`/` 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.)
@@ -1523,7 +1576,7 @@ curve instead of in the keys.
 | --- | --- |
 | `bones` | at least one, in the order they ride the path |
 | `slot` | **required.** The slot whose path attachment they follow (§3.4) |
-| `positionMode` | default `"Percent"`: `position` is a fraction of the arc length. `"Fixed"` makes it world units |
+| `positionMode` | default `"Percent"`: `position` is a fraction of the measured `lengths` total — **not** of the arc, see §10.6. `"Fixed"` makes it world units, which is the mode a wrong total is visible in |
 | `spacingMode` | default `"Length"` — `Length`, `Fixed`, `Percent` or `Proportional` |
 | `rotateMode` | default `"Tangent"`: each bone turns to the curve's tangent where it sits. `"Chain"`, `"ChainScale"` |
 | `rotation` | default 0. Degrees added after the path's own rotation |
@@ -3344,7 +3397,7 @@ tell a working traversal from a plausible one.
 
 | Group | `property` | Channels | Note |
 | --- | --- | --- | --- |
-| `path` | `position` | 1 | a fraction of the arc length, or world units under `positionMode: "fixed"` |
+| `path` | `position` | 1 | a fraction of the measured `lengths` total (§10.6 — not the arc), or world units under `positionMode: "fixed"` |
 | `path` | `spacing` | 1 | in the unit `spacingMode` chose |
 | `path` | `mix` | **3** | `[mixRotate, mixX, mixY]` in one key, so a raw `curve` is 12 numbers |
 | `slider` | `time` | 1 | the bone-less slider's own time. A slider WITH a bone takes its time from the bone and this timeline is not what drives it |
@@ -3529,7 +3582,8 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `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 |
+| `slot "patch": placeholder "patch" is filled by the "default" skin AND by skins "zulu", "mike", and the Spine editor has no way to hold that … Move the default skin's entry for this slot into a named skin — call it "base"` | **R12** — do what it says: move that entry out of `default` into a named skin. The editor has no representation for a placeholder the default skin shares with a named one, in either spelling, and §3.4.2 has both measurements. Renaming the placeholder does not help; the shape is what is refused |
+| `N attachment name collision(s): a placeholder that more than one skin fills is emitted with the name "<skin>/<placeholder>" … slot "patch": skin "base" 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 a composed name is one another entry in the same slot already answers to — including a plain name in the default skin, which composed nothing. Both sites are named; either rename ends it |
 
 ### 5.2 Assertions — the gate
 
@@ -5015,9 +5069,19 @@ frames. Every line is marked with where it comes from:
 
 - 📗 **stated** — quoted or paraphrased from the page linked in the line.
 - 🧩 **inferred** — this guide's reading of those pages. Spine does not say it.
-- 🔬 **observed** — read off the editor's own export of a rigc build in the round
-  trip of [issue #285](https://github.com/firejune/rigc/issues/285) (Spine 4.3.23),
-  not from a page. Used only where rigc now emits the same thing.
+- 🔬 **observed** — read off the editor's own export of a rigc build, not from a
+  page. Two round trips stand behind these: [issue
+  #285](https://github.com/firejune/rigc/issues/285) (Spine 4.3.23) and the
+  eight-rig trip of 2026-09-16 (Spine **4.3.26**), whose findings are collected in
+  §10.6. ⚠️ This legend said *"used only where rigc now emits the same thing"*,
+  which was true while every observation had already been adopted; §10.6 then
+  carried one that had **not** been — the path `lengths` disagreement — so an
+  observation is now marked by where it was read, and each says for itself
+  whether rigc agrees with it. ⭐ That outstanding one has since been adopted
+  ([#560](https://github.com/firejune/rigc/issues/560)) and the legend is kept in
+  this shape anyway: the reason to mark an observation by its source rather than
+  by whether rigc follows it is that the second fact goes stale and the first
+  does not.
 
 ### 10.1 Structure
 
@@ -5596,6 +5660,37 @@ never write any of them by hand — and rigc's own output always carries all
 three, because the editor's *import* treats their absence as an export made
 without the box and rebuilds the hull on its own.
 
+🔬 🚨 **And the CLI's default export has that box ON, so for anything driven from
+the command line the ⇒ above is the exception rather than the case.** The
+sentence is still true of an export made without the box; what is measured is
+that `-e json` with no export-settings file does not make one. Every field on the
+nonessential list came back present, unchanged and not zero on round trip 6
+(2026-09-16, Spine 4.3.26): the header's `fps` (24 on `fields`, the one rig that
+declares it) and `images`; a mesh's `width`/`height` (64/48) and `edges`
+(16 entries, identical); the editor colours of a **bounding box** (`3cff6bff`), a
+**clipping** polygon (`ff3c6bff`) and a **path** (`ff6b3cff`); and a bone's
+`icon` (`circle`) with its `color`. All eight exports also carry
+`"audio": "./audio"` — a field rigc never wrote and none of those rigs has any
+use for — which is the list's own last member arriving unasked. The runtime says
+the same thing from the other side: `PathAttachment.js`'s doc comment on `color`
+reads *"Available only when nonessential data was exported"*, and the colour is
+there.
+
+📗 The CLI page documents the form but not the setting: *"If `json` or `binary` is
+specified instead of a path to an export settings JSON file, then a JSON or
+binary export is performed using default settings"* —
+[Command line interface](https://esotericsoftware.com/spine-command-line-interface).
+❓ **Neither that page nor the Export page states whether nonessential is on in
+those defaults**, so the answer above is measured here and documented nowhere.
+⇒ In practice: do not plan around fields being dropped. An export you did not
+personally make without the box is an export that has them, and the round trip is
+therefore **richer** than the build rather than poorer — which is why #368's
+hull-and-edges degradation does not return on a second trip (no import warning in
+any of the eight `roundtrip.log`s, and a five-vertex mesh's `hull: 4` came back
+`4` rather than recomputed to `5`). A nonessential-**off** trip would need an
+export-settings JSON, and ❓ the key name inside that file is not documented
+either.
+
 ⚠️ **A region's `width`/`height` are not on that list.** They are documented with no
 *"assume … if omitted"* default — the same fact R5 states from the parser's side:
 omit them in raw JSON and every UV collapses, in silence. Name an `image`.
@@ -5606,7 +5701,136 @@ omitted"* — and **rigc deliberately does the opposite** (R1, §2). Writing `x:
 legitimate here. The habit worth carrying over is not *omit defaults*, it is
 *declare only what the shot needs*.
 
-### 10.6 What this section does not claim
+### 10.6 What a round trip gives back
+
+Everything above is what the editor **does**. This is what it **returns** — which
+matters to you for one reason: a construct nobody has carried through the editor
+is a construct that might vanish there, and an agent cannot see that it did.
+
+🔬 The source is one run: eight discriminator rigs, each built to isolate a group
+of fields, compiled by rigc **0.21.0** (emitting 4.3.13), imported into a licensed
+Spine **4.3.26** through the documented CLI and exported back on 2026-09-16, with
+the predictions written down before anything was opened. **Seven of the eight came
+back differing from their build in three header fields and nothing else** —
+`hash` and `audio`, which the editor adds, and `spine`, which it stamps with its
+own version. The eighth is the path rig, and it is the last bullet here.
+
+⚠️ *"Nothing else"* is under two normalisations, both of which are the exporter
+being ordinary rather than the editor changing anything: **float spelling** (`48`
+comes back `48.0`) and **omitted defaults** — the export drops any field equal to
+its parser default, so the header loses `x: 0` and `y: 0`, a bone loses `x: 0`, and
+a key at t=0 loses its `"time": 0`. Every name-keyed object is also re-sorted, per
+§10.1. None of those is a loss of information, and each is worth knowing before
+you read a `diff`.
+
+⚠️ Read every line below as *this construct survived*, never as *this construct is
+recommended*. §10.1–§10.5 are the recommendations; this subsection is only the
+evidence that the format will carry what you write.
+
+- 🔬 **A transform constraint survives whole.** 4.3's `source` plus its
+  `properties` map — including a nested `to` with `offset`, `max` and `scale` —
+  came back field for field, with `localSource`, `localTarget`, `additive`,
+  `clamp`, `mixRotate` and `mixY` beside it.
+- 🔬 **The `transform` timeline survives** — the group shape that maps a
+  constraint name straight to a key array (§4.10), with its per-key mixes and
+  curves intact.
+- 🔬 **`shear`, `shearx` and `sheary` bone timelines survive**, paired and
+  single-axis, with both channels of a paired key and all their curve control
+  points.
+- 🔬 **A bone's setup `scaleX`, `scaleY`, `shearX`, `shearY` and `inherit`
+  survive**, a non-default `inherit` included — `noScale`, `onlyTranslation` and
+  `noRotationOrReflection` were all carried on one rig.
+- 🔬 ⭐ **A bone's `color` and `icon` survive** — 4.3's bone icons round-trip
+  (`circle`, `ff7f00ff`). They are nonessential data, so this is also a reading of
+  §10.5's caveat.
+- 🔬 **The `drawOrder` timeline survives, offsets and all — including the empty
+  key.** A key with no `offsets` restores the setup order (§4.7), and it came back
+  **empty** rather than spelled out as an identity permutation, which is the
+  spelling that would have made every later diff read as a change.
+- 🔬 **Slot `color`, `dark` and `blend` survive**, `blend: multiply` and
+  `blend: additive` included.
+- 🔬 **A path constraint's non-default modes survive**: `positionMode: fixed`,
+  `spacingMode: proportional`, `rotateMode: chainScale`.
+- 🔬 **A path attachment's `closed: true` and `constantSpeed: false` survive**, and
+  so do its `position`, `spacing` and three-channel `mix` timelines — all three
+  channels of every `mix` key, and all twelve curve numbers on each key that
+  carries a curve. ⚠️ Its `lengths` did **not**, which is the last bullet — and
+  since [#560](https://github.com/firejune/rigc/issues/560) they do, because rigc
+  now emits the numbers the editor recomputes rather than numbers near them.
+- 🔬 **`physics.mix` and `physics.reset` timelines survive**, the `reset` key
+  included — a key that carries a time and no value at all — and so does the
+  physics constraint's setup `mix`.
+- 🔬 **A time-driven slider survives** — one with no `bone`, carrying `loop`, a
+  setup `time` and a setup `mix`, with both its `time` and `mix` timelines.
+- 🔬 **`boundingbox` and `clipping` attachments survive whole**: `vertexCount`,
+  `vertices`, the clipping `end` slot, `convex`, and both editor colours.
+- 🔬 **An unweighted mesh survives and its `hull` is kept, not recomputed** — a
+  five-vertex mesh declaring `hull: 4` came back `4`, with its `edges`, `color`,
+  `uvs` and `triangles` unchanged. Beside it, on the same rig: the header's
+  `referenceScale`, a region's `rotation` / `scaleX` / `scaleY` / `color`, and an
+  attachment whose `path` differs from its placeholder (the mechanism of
+  [#552](https://github.com/firejune/rigc/issues/552)) all survive. A `--pack`
+  build round-trips too.
+
+🚨 **The one thing that did not come back is a path attachment's `lengths`, and it
+moved the drawing.** The editor recomputes them at export from the geometry —
+the imported project holds the numbers it was given — and it measures each curve
+with the **runtime's own four-sample forward difference**, not with an arbitrarily
+fine one. `PathConstraint`'s `constantSpeed` re-measure is that same computation:
+its constants are `0.1875 = 3t²`, `0.09375 = 6t³` and `(cx1 − x1) · 0.75 = 3t` at
+**t = 1/4**, four `Math.sqrt` terms per curve. A 4-sample chord sum over the same
+control points reproduces the editor to every digit it prints, on a closed path
+under 4.3.26 (`[152.7006, 305.4012, 458.1019, 610.8025]`) and on an open one under
+4.3.23 (`[430.8389, 838.0142, 1127.736, …]`).
+
+⚠️ **That last reading settles the model and cannot settle the spelling.** A
+4-sample chord sum agrees with the runtime's forward difference to about **nine
+significant digits** — *below* what float32 can hold, which is why both spellings
+reproduce both exports exactly, and *above* the six decimals rigc emits, which is
+why the file can tell them apart. On both rigs above they round apart on the
+**last** curve, where the running total has accumulated most: `610.802519` against
+`610.802520`, `1127.735817` against `1127.735818`. So the editor is the evidence
+for *what* is computed, and only `PathConstraint` itself is evidence for *how*.
+
+⭐ **rigc emits the forward difference itself** since
+[#560](https://github.com/firejune/rigc/issues/560) — `pathCurveLengths` in
+[`src/compile.ts`](../src/compile.ts) is those runtime lines transcribed, down to
+`Math.sqrt(dx * dx + dy * dy)` rather than `Math.hypot` and `0.16666667` rather
+than `1 / 6`, both of which change the emitted file. All seven entries of the two
+exports above now come back at the precision the editor prints them, so a path rig
+built here and one authored in the editor parameterise identically. ⚠️ The
+consequence for you is a vocabulary one: `lengths` is **not** an arc length. It
+sits about 0.5 % below the arc by construction, so a physical quantity — how far a
+wheel rolls, how long a ribbon is — has to be measured off the curve and not read
+out of the artifact.
+
+🔬 **And the editor always writes `vertexCount / 3` entries, computing the
+wrap-around curve even on an open path** — that open path's fourth entry,
+`2136.228`, is the closed-chain cumulative. ⚠️ Neither array is wrong: the parser
+allocates `vertexCount / 3` and copies whatever is there, and `PathConstraint`
+reads at most `lengths[curveCount]`, so the trailing entry is never read.
+
+⇒ **What this means for you.** `lengths` is the one number in a path rig you
+cannot check by looking: `diff` does not compare it, and `A33` asks only that it
+strictly increase, which any plausible array does. A total that is a fraction of a
+percent out was measured at **4.9612 mean MAE** on the one rig of that run with a
+path constraint, against **0.0000** on the other seven. If you are comparing a
+path rig against an editor reference and everything structural agrees while the
+picture does not, this is the first place to look.
+
+⚠️ **What decides whether it moves a pixel is the POSITION mode**, and an earlier
+reading of this paragraph put it on `spacingMode: proportional`, which is the one
+mode it cannot be: proportional spacing scales *with* the total, and that is
+exactly what cancels. The rig that drifted is `positionMode: fixed`, where an
+absolute `position` is compared against a total that moved. Under
+`positionMode: percent` the position scales with the total too, so a uniform
+change cancels out of both — measured across #560, `gallery/ride` is
+percent/percent and every one of its 74 rendered frames came back **byte
+identical** on an emitted array all three of whose numbers moved. ⇒ Read a
+`lengths` disagreement as *certainly wrong data, and visible only under
+`positionMode: fixed`*.
+
+### 10.7 What this section does not claim
 
 Conventions that are visible in reference exports but that **no public Spine page
 states** are deliberately absent. A guide that asserted them would be handing you an
@@ -5614,7 +5838,10 @@ answer read off the exports:
 
 - any figure for keys per second, or for how key density scales with frame rate;
 - which curve type any particular example project or studio actually shipped;
-- whether a given export was made with Nonessential data checked;
+- whether a **corpus** export — one somebody else made, out of the editor's own
+  dialog — was made with Nonessential data checked. ⚠️ §10.5 now answers this for
+  the **CLI's** `-e json`, where it is measured; that measurement says nothing
+  about an export you were handed, and the two must not be read as one;
 - how many bones, slots or timelines a rig of a given size ought to have;
 - whether a shipped rig prefers automatic Bezier handles or hand-placed ones.
 

package/docs/SPEC_COVERAGE.md

@@ -597,19 +597,25 @@ with the member's own `skin: true` — either half alone is refused, because `Sk
 | `mesh` | 🟡 | emits `type`, `uvs`, `triangles`, `vertices` (**weighted encoding only**), `hull`, `width`, `height`, `edges` (`compile.ts:1343`, and part 4's rung-6 entry measures it byte-identical to the reference), `path`, `color`. ❌ `sequence`. Unweighted meshes are 🚫 **A20_MESH_WEIGHTS_COHERENT** (`validate.ts:430-433`) |
 | `linkedmesh` | ❌ | deliberately deferred — never appears in the corpus (part 3-1) |
 | `boundingbox` | ✅ | `vertexCount` (required and cross-checked), `vertices` **or** by-name `weights`, `color`. **A33_VERTEX_ATTACHMENT_GEOMETRY** |
-| `path` | ✅ | `vertexCount` (required, and checked as a multiple of 3 — the parser's own `vertexCount / 3` takes a fractional size in silence), `vertices` **or** by-name `weights`, `closed`, `constantSpeed`, `color`, and a **measured** `lengths`: the cumulative setup arc length of each curve, taken through each influence's own bone, refused if authored. **A33_VERTEX_ATTACHMENT_GEOMETRY** re-checks the structure and the array's monotonicity. ❌ a `deform` timeline on one |
+| `path` | ✅ | `vertexCount` (required, and checked as a multiple of 3 — the parser's own `vertexCount / 3` takes a fractional size in silence), `vertices` **or** by-name `weights`, `closed`, `constantSpeed`, `color`, and a **measured** `lengths`: the cumulative setup length at the end of each curve, taken through each influence's own bone and measured as `PathConstraint` measures it — its own four-sample forward difference, which is what the editor writes too and is about 0.5 % below the arc (AUTHORING §10.6) — refused if authored. **A33_VERTEX_ATTACHMENT_GEOMETRY** re-checks the structure and the array's monotonicity. ❌ a `deform` timeline on one |
 | `point` | ❌ | deliberately deferred — never appears in the corpus (part 3-1) |
 | `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.
+that more than one skin fills (`compile.ts`'s `composeSkinAttachmentName` and `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. ⚠️ The **`default` skin may not be one of those skins**, and that is a
+`CompileError` rather than an emission rule: the editor holds no placeholder the default skin shares
+with a named one in either spelling — named, the export re-keys the attachment by its name and the
+slot's setup attachment stops resolving; unnamed, the import is refused with `Multiple attachments
+have the same name` ([#567](https://github.com/firejune/rigc/issues/567), Spine 4.3.26, round trips
+7 and 8). 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

package/package.json

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

package/src/compile.ts

@@ -1900,9 +1900,12 @@ export function compile(opts: CompileOptions): CompileResult {
         // 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;
+        // `null` is an entry that carries no `name` field, which is every
+        // uncontested placeholder. A contested one the DEFAULT skin fills never
+        // reaches here: it is refused above (issue #567), because the editor
+        // holds no such shape in either spelling.
+        const composed = composeSkinAttachmentName(skinName, placeholder, shared?.has(placeholder) === true);
+        perSlot[placeholder] = composed === null ? built : nameSkinAttachment(built, composed, placeholder);
       }
       tableFor(skinName)[rigSlot.name] = perSlot;
     }
@@ -2528,6 +2531,92 @@ function skinAttachmentName(skinName: string, placeholder: string): string {
   return `${skinName}${SKIN_ATTACHMENT_SEPARATOR}${placeholder}`;
 }
 
+/**
+ * The `name` one skin's entry for a placeholder is emitted with, or `null` for
+ * the entries that carry no `name` field at all.
+ *
+ * Stated once, and called by both the emit and `contestedPlaceholders`'
+ * collision walk, because two readings of one rule is how issue #567 happened.
+ * By the time either caller runs, a contested placeholder the **default** skin
+ * fills has already been refused — see `refuseDefaultSkinContest` — so every
+ * entry this composes for is a named skin's.
+ */
+function composeSkinAttachmentName(skinName: string, placeholder: string, contested: boolean): string | null {
+  return contested ? skinAttachmentName(skinName, placeholder) : null;
+}
+
+/**
+ * Refuse a placeholder that the **default** skin and a named skin both fill.
+ *
+ * 🚨 This is issue #567 and it is not a naming problem, which took two editor
+ * round trips to establish because each of them looked like one.
+ *
+ * ## What the editor's model is, bracketed by two trips
+ *
+ * Both on Spine **4.3.26**, on a rig whose three skins fill one placeholder
+ * `patch` from three PNGs of three sizes, with a second slot `block` that one
+ * skin fills as the fixed point.
+ *
+ * **Trip 7 — the default skin's attachment given a name of its own**
+ * (`"name": "default/patch"`, as issue #552 emitted it). The editor IMPORTS it,
+ * and exports the default skin's entry re-keyed by that name:
+ *
+ *     built     "default": { "patch": { "patch":         { "name": "default/patch", … } } }
+ *     exported  "default": { "patch": { "default/patch": {                          … } } }
+ *
+ * The editor's default skin holds no skin placeholders — an attachment there
+ * hangs on the slot and is known by its name alone — so the name becomes the
+ * key. The slot's setup `attachment: "patch"` then resolves in no default-skin
+ * key and the default skin draws NOTHING: `check` read mean MAE 98.52 with
+ * `drewSlots: 0` on the `patch` chain while `validate --profile spine` stayed
+ * green, because the file is well-formed and only the editor's model says what
+ * a key means.
+ *
+ * **Trip 8 — the default skin's attachment left as its placeholder** (no `name`,
+ * the obvious repair). The editor REFUSES the import:
+ *
+ *     ERROR: Unable to import skeleton.
+ *     Cause: [error] Error reading attachment: mike/patch (nSX)
+ *     Cause: [error] Multiple attachments have the same name:
+ *     patch
+ *     patch
+ *
+ * The default skin's attachment `patch` hangs on the slot; the named skins'
+ * placeholder `patch` is that slot's other child. **In one slot, a default-skin
+ * attachment name and a named skin's placeholder name are the same namespace.**
+ *
+ * ⇒ The two trips close the case: name it and the setup attachment resolves
+ * nowhere, do not name it and the import is refused. **The editor has no
+ * representation for a placeholder the default skin and a named skin both
+ * fill** — its own convention is shared art in the default skin, per-skin art in
+ * placeholders, and a slot's one setup `attachment` string naming one or the
+ * other. There is no third spelling to find, so this is a `CompileError` and not
+ * a scheme, in the shape issue #543 used: refuse by name and say what to do.
+ *
+ * ⚠️ What this does NOT touch, and the trips measured that half too: a
+ * placeholder that two or more NAMED skins fill keeps #552's composition
+ * exactly. Trip 8's second rig — two named skins filling `patch`, the default
+ * skin holding `block` only — imported, exported and measured **0.0000 mean
+ * MAE**, names and paths intact. The remedy this refusal states is that rig:
+ * move the default skin's entry into a named skin.
+ */
+function refuseDefaultSkinContest(slotName: string, placeholder: string, skins: readonly string[]): never {
+  const named = skins.filter((skin) => skin !== DEFAULT_SKIN);
+  throw new CompileError(
+    `slot "${slotName}": placeholder "${placeholder}" is filled by the "${DEFAULT_SKIN}" skin AND by ` +
+      `${named.length === 1 ? 'skin' : 'skins'} ${named.map((skin) => `"${skin}"`).join(', ')}, and the Spine ` +
+      'editor has no way to hold that. Measured on 4.3.26 in both spellings: give the default skin\'s attachment a ' +
+      `name of its own ("${DEFAULT_SKIN}${SKIN_ATTACHMENT_SEPARATOR}${placeholder}") and the editor re-keys it by ` +
+      `that name on export, so the slot's setup attachment "${placeholder}" resolves in no default-skin key and the ` +
+      'default skin draws nothing; leave it as the placeholder and the import is refused outright with ' +
+      `"Multiple attachments have the same name: ${placeholder} ${placeholder}", because a default-skin attachment ` +
+      "hangs on the slot beside the named skins' placeholder of that name. Move the default skin's entry for this " +
+      `slot into a named skin — call it "base" — so every skin filling "${placeholder}" is a named one. Two or more ` +
+      'named skins sharing a placeholder is the shape the editor does hold, and rigc composes their names for them ' +
+      '(#541, #552).',
+  );
+}
+
 /**
  * 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.
@@ -2551,7 +2640,7 @@ function skinAttachmentName(skinName: string, placeholder: string): string {
  * 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
+ * ## Only the contested pairs are named, and the default skin may not contest
  *
  * 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
@@ -2559,6 +2648,14 @@ function skinAttachmentName(skinName: string, placeholder: string): string {
  * multi-skin rig whose skins use distinct placeholders does not move either,
  * because nothing there is ambiguous to begin with.
  *
+ * ⚠️ A contested placeholder the **default** skin fills is refused before any
+ * of this runs — `refuseDefaultSkinContest`, issue #567 — because two editor
+ * round trips showed the editor holds no such shape in either spelling. So
+ * every entry the walk below composes for belongs to a named skin, and the
+ * emitted name comes off `composeSkinAttachmentName`, which this function calls
+ * rather than restates: the emit and the refusal disagreeing about one name is
+ * the defect both of them exist to prevent.
+ *
  * ⚠️ 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
@@ -2596,12 +2693,26 @@ function contestedPlaceholders(
   const collisions: string[] = [];
   for (const [slotName, perSlot] of fillers) {
     const shared = new Set([...perSlot].filter(([, skins]) => skins.length > 1).map(([placeholder]) => placeholder));
+    // 🚨 Before anything is composed: a contested placeholder the DEFAULT skin
+    // fills has no representation in the editor at all, in either spelling
+    // (issue #567, round trips 7 and 8). It is refused here rather than emitted,
+    // and the refusal comes first because renaming cannot repair it — the
+    // remedy is a different rig, not a different string.
+    for (const placeholder of shared) {
+      const skins = perSlot.get(placeholder)!;
+      if (skins.includes(DEFAULT_SKIN)) refuseDefaultSkinContest(slotName, placeholder, skins);
+    }
     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;
+        // The emitted name, read off the one function that decides it — so the
+        // refusal and the emit cannot drift into two readings. An UNCONTESTED
+        // entry is claimed under its bare placeholder, the default skin's
+        // included: a named skin whose composed name equals it is a collision,
+        // and one this walk sees for the same reason it sees every other.
+        const name = composeSkinAttachmentName(skinName, placeholder, shared.has(placeholder)) ?? placeholder;
         const site = `skin "${skinName}" placeholder "${placeholder}"`;
         const taken = claimed.get(name);
         if (taken === undefined) claimed.set(name, site);
@@ -2888,19 +2999,6 @@ function setupWorldVertices(
   return out;
 }
 
-/**
- * How many samples per curve the arc-length measurement takes.
- *
- * 64 is a choice about accuracy, and the accuracy that matters is against the
- * runtime rather than against calculus: `PathConstraint` re-measures a
- * `constantSpeed` path with a **4-sample** forward difference per curve, so the
- * number here only has to be fine enough that the two agree to well inside the
- * tolerance anything downstream compares at. It is a constant rather than a
- * parameter because a per-call sample count would make `lengths` depend on the
- * caller, and A18 compares two emits byte for byte.
- */
-const PATH_LENGTH_SAMPLES = 64;
-
 /**
  * The knot-and-handle chain a path attachment's vertices actually form, in the
  * runtime's own order (`PathConstraint.computeWorldPositions`).
@@ -2919,11 +3017,43 @@ function pathChain(points: Array<[number, number]>, closed: boolean): Array<[num
 }
 
 /**
- * Cumulative arc length at the end of each curve of the chain, in world units.
+ * Cumulative arc length at the end of each curve of the chain, in world units —
+ * **the runtime's own measurement, restated line for line**.
  *
  * One entry per curve, which is what `lengths[curve]` indexes: the parser walks
  * curves with `if (p > lengths[curve]) continue`, and reads `lengths[curveCount]`
  * — where `curveCount` is the LAST curve's index — as the total path length.
+ *
+ * ⭐ **What this is not: an approximation of the arc length.** `lengths` is not a
+ * fact about the Bezier, it is the number the consumer of the field computes for
+ * itself when it is not given one. `PathConstraint.computeWorldPositions`
+ * (`PathConstraint.js:289-324` in `@esotericsoftware/spine-core` 4.3.13) measures
+ * a `constantSpeed` path with a cubic **forward difference** taken at `t = 1/4`
+ * — `0.1875 = 3t²`, `0.09375 = 6t³`, `0.75 = 3t`, `0.16666667` standing in for
+ * 1/6 — accumulating four `Math.sqrt` terms per curve into a running
+ * `pathLength`, and writing the running value into `curves[i]` at each curve's
+ * end. The Spine editor's exported `lengths` are that same computation: measured
+ * against two editor exports, one open path from 4.3.23 and one closed path from
+ * 4.3.26, this reproduces every digit the editor printed. So the loop below is a
+ * transcription, not a sampler that happens to agree — and the two are not the
+ * same thing, which is the reason the transcription is here.
+ *
+ * ⚠️ rigc measured this with a 64-chord sum until issue #560, and the comment
+ * that stood here argued the difference was inside anything's tolerance. It was
+ * not: 0.70 % high, uniformly, worth **4.96 px mean MAE** on the round trip of a
+ * rig whose path constraint reads the field. A 4-chord sum is *also* not the
+ * repair — it agrees with the forward difference only to about nine significant
+ * digits, which is below what float32 can hold (so no editor export can tell the
+ * two apart) and above rigc's own six-decimal rounding (so the emitted file can):
+ * on both measured rigs the two spellings differ in `r6` on the LAST curve, where
+ * the accumulated difference is largest. `PS67`–`PS69` in `selftest.ts` compare
+ * this against `PathConstraint`'s own `curves` array read off a posed skeleton,
+ * which is the only oracle that can see that gap.
+ *
+ * 🔒 The transcription is deliberate down to the spelling: `Math.sqrt(dx * dx +
+ * dy * dy)` rather than `Math.hypot`, `0.16666667` rather than `1 / 6`, and the
+ * running total carried across curves rather than restarted. Each of those is a
+ * place where a more accurate line would emit a different file.
  */
 function pathCurveLengths(chain: Array<[number, number]>): number[] {
   const out: number[] = [];
@@ -2933,21 +3063,26 @@ function pathCurveLengths(chain: Array<[number, number]>): number[] {
     const [cx1, cy1] = chain[c + 1];
     const [cx2, cy2] = chain[c + 2];
     const [x2, y2] = chain[c + 3];
-    let px = x1;
-    let py = y1;
-    for (let s = 1; s <= PATH_LENGTH_SAMPLES; s++) {
-      const t = s / PATH_LENGTH_SAMPLES;
-      const u = 1 - t;
-      const a = u * u * u;
-      const b = 3 * u * u * t;
-      const d = 3 * u * t * t;
-      const e = t * t * t;
-      const x = a * x1 + b * cx1 + d * cx2 + e * x2;
-      const y = a * y1 + b * cy1 + d * cy2 + e * y2;
-      total += Math.hypot(x - px, y - py);
-      px = x;
-      py = y;
-    }
+    const tmpx = (x1 - cx1 * 2 + cx2) * 0.1875;
+    const tmpy = (y1 - cy1 * 2 + cy2) * 0.1875;
+    const dddfx = ((cx1 - cx2) * 3 - x1 + x2) * 0.09375;
+    const dddfy = ((cy1 - cy2) * 3 - y1 + y2) * 0.09375;
+    let ddfx = tmpx * 2 + dddfx;
+    let ddfy = tmpy * 2 + dddfy;
+    let dfx = (cx1 - x1) * 0.75 + tmpx + dddfx * 0.16666667;
+    let dfy = (cy1 - y1) * 0.75 + tmpy + dddfy * 0.16666667;
+    total += Math.sqrt(dfx * dfx + dfy * dfy);
+    dfx += ddfx;
+    dfy += ddfy;
+    ddfx += dddfx;
+    ddfy += dddfy;
+    total += Math.sqrt(dfx * dfx + dfy * dfy);
+    dfx += ddfx;
+    dfy += ddfy;
+    total += Math.sqrt(dfx * dfx + dfy * dfy);
+    dfx += ddfx + dddfx;
+    dfy += ddfy + dddfy;
+    total += Math.sqrt(dfx * dfx + dfy * dfy);
     out.push(total);
   }
   return out;

package/src/rig.ts

@@ -676,12 +676,18 @@ export interface RigClippingAttachment extends RigVertexGeometry {
  * six then straddle the knots, and the constraint slides bones along a curve
  * nobody drew.
  *
- * ⚠️ `lengths` is NOT authored here. It is the cumulative arc length at the end
- * of each curve in the SETUP pose, in world units — a measurement of the
- * geometry above, and the same relationship `image` has to `width`/`height`: a
- * restated number can disagree with the vertices, and when it does, a
+ * ⚠️ `lengths` is NOT authored here. It is the cumulative length at the end of
+ * each curve in the SETUP pose, in world units — a measurement of the geometry
+ * above, and the same relationship `image` has to `width`/`height`: a restated
+ * number can disagree with the vertices, and when it does, a
  * `constantSpeed: false` path traverses a length that is not the length of the
  * curve, silently. So rigc measures it and refuses an authored one by name.
+ *
+ * 🔸 *Which* length, exactly, is `SpinePathAttachment`'s subject in
+ * [`types.ts`](types.ts) and it is not the arc: it is `PathConstraint`'s own
+ * four-sample forward difference, about 0.5 % below the arc, which is what the
+ * Spine editor writes back too (issue #560). This comment said "arc length"
+ * until then.
  */
 export interface RigPathAttachment extends RigVertexGeometry {
   type: 'path';

package/src/types.ts

@@ -717,6 +717,20 @@ export interface SpineSlot {
  * (`: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.
+ *
+ * ⚠️ And the **`default` skin may never be one of the skins sharing that
+ * placeholder** — a fact about the editor rather than about the format (issue
+ * #567, Spine 4.3.26, round trips 7 and 8), and a `CompileError` rather than a
+ * spelling. The editor's named skins hold *skin placeholders*, a key holding a
+ * named attachment, and come back untouched. Its default skin holds no
+ * placeholders: an attachment there hangs on the slot and is known by its name
+ * alone. So writing a name there gets it re-keyed by that name on export and
+ * the slot's setup `attachment` stops resolving (trip 7), and NOT writing one
+ * makes that attachment's name collide with the named skins' placeholder of the
+ * same name, which the editor refuses at import (trip 8). Both spellings are
+ * measured, so there is no third; `refuseDefaultSkinContest` in `compile.ts` is
+ * where that lives, and `composeSkinAttachmentName` beside it decides the name
+ * for the skins that are left.
  */
 export interface SpineRegionAttachment {
   name?: string;
@@ -804,12 +818,80 @@ export interface SpineClippingAttachment {
 /**
  * A composite cubic Bezier, for a path constraint to slide bones along.
  *
- * `lengths` is the cumulative arc length at the end of each curve in the setup
- * pose — one entry per curve, so `vertexCount / 3 - 1` of them on an open path
- * and `vertexCount / 3` on a closed one. It has no parser default and the parser
+ * `lengths` is the cumulative length at the end of each curve in the setup pose,
+ * measured **the way `PathConstraint` measures it** — a four-sample forward
+ * difference per curve (`PathConstraint.js:301-320`), which is also what the
+ * Spine editor exports and which reads about **0.5 % below the true arc**. One
+ * entry per curve, so `vertexCount / 3 - 1` of them on an open path and
+ * `vertexCount / 3` on a closed one. It has no parser default and the parser
  * dereferences `map.lengths.length` unconditionally, so an absent array is one of
  * the format's few loud failures; rigc measures the numbers off the geometry
  * rather than letting a spec restate them.
+ *
+ * ⚠️ That sentence read *"the cumulative **arc** length"* until issue #560, and
+ * the word was load-bearing in the wrong direction: this is not an arc length,
+ * and no refinement of the integral converges on it. It is the number the
+ * field's own consumer computes when it is not given one. ⇒ Do not derive a
+ * physical quantity from it — how far a wheel rolls, how long a ribbon is.
+ * `position` is stated against it; arc length is not it.
+ *
+ * ⚠️ **The EDITOR writes `vertexCount / 3` entries on BOTH — measured**
+ * (round trip 6, 2026-09-16, Spine 4.3.26). It computes the wrap-around curve
+ * even for an open path: `gallery/ride`'s 12-vertex open path came back with
+ * **four** entries on 2026-09-04 (4.3.23) and the fourth, `2136.228`, is the
+ * *closed*-chain cumulative. ⚠️ Neither array is wrong, and this is not a case
+ * of the editor knowing something rigc does not. `SkeletonJson.js:601` allocates
+ * `Utils.newArray(vertexCount / 3, 0)` and copies whatever is there, while
+ * `PathConstraint` reads at most `lengths[curveCount]` with
+ * `curveCount = verticesLength / 6 − (closed ? 1 : 2)` — index 2 on that path.
+ * The trailing entry the editor adds to an open path is never read by anything.
+ *
+ * 🚨 **What the editor writes INTO those entries is its own measurement, and it
+ * is the runtime's, not calculus'** (issue #560, measured on the same trip).
+ * `PathConstraint`'s `constantSpeed` re-measure is a four-sample forward
+ * difference per curve — its constants are `0.1875 = 3t²`, `0.09375 = 6t³` and
+ * `(cx1 − x1) · 0.75 = 3t` at **t = 1/4**, accumulating four `Math.sqrt` terms —
+ * and the editor's stored `lengths` are that same computation. A 4-sample chord
+ * sum over the same control points reproduces the editor to every digit it
+ * prints, on two rigs and two editor builds: `pathmodes` (closed, 4.3.26) came
+ * back `[152.7006, 305.4012, 458.1019, 610.8025]` and `ride` (open, 4.3.23)
+ * `[430.8389, 838.0142, 1127.736, …]`. It is a recomputation at **export** — the
+ * inflated `.spine` project holds the imported numbers verbatim — so a path rig
+ * is re-parameterised by the trip rather than corrupted by it.
+ *
+ * ⇒ **rigc emits that computation, not a sampler aimed at it** (issue #560).
+ * `pathCurveLengths` in [`compile.ts`](compile.ts) is `PathConstraint.js:301-320`
+ * transcribed, down to `Math.sqrt(dx * dx + dy * dy)` rather than `Math.hypot`
+ * and `0.16666667` rather than `1 / 6`; `PS67`–`PS69` in `selftest.ts` hold it
+ * there by requiring it to reproduce a real `PathConstraint.curves` array **bit
+ * for bit** on the runtime's own posed chain. Measured after the change, all
+ * seven entries of both editor exports above come back at the precision the
+ * editor prints them.
+ *
+ * ⚠️ This paragraph used to point at a constant — `PATH_LENGTH_SAMPLES` — and ask
+ * *how finely rigc should sample*. There is no such constant now, and the
+ * question was the wrong one. The chord-sum reading above is true and it is not
+ * sufficient: a 4-sample chord sum agrees with the forward difference to about
+ * **nine significant digits**, which is *below* what float32 can hold — so no
+ * editor export can tell the two apart, and that reading can only settle the
+ * MODEL — and *above* rigc's six-decimal rounding, so the emitted file can. On
+ * both rigs above the two spellings round apart on the **last** curve, where the
+ * running total has accumulated most: `610.802519` against `610.802520`, and
+ * `1127.735817` against `1127.735818`. So the editor is the evidence for what is
+ * being computed and only the runtime is evidence for how.
+ *
+ * 📌 For the record of what the disagreement cost when it was found: the build
+ * rigc **0.21.0** emitted for `pathmodes` sat a uniform **0.70 %** above the
+ * editor's four numbers, and `check` read **4.9612 mean MAE** against 0.0000 on
+ * the seven rigs of that run without a path. ⚠️ What decides whether that moves a
+ * pixel is the POSITION mode, not the spacing mode: `pathmodes` is
+ * `positionMode: fixed`, where an absolute `position` is compared against a total
+ * that scaled, so the bone slides. Under `positionMode: percent` a uniform scale
+ * cancels out of both the position and the spacing — `gallery/ride` is
+ * percent/percent and every one of its 74 rendered frames came back **byte
+ * identical** across this change, on an emitted array all three of whose numbers
+ * moved. `A33_VERTEX_ATTACHMENT_GEOMETRY` asks only that the array strictly
+ * increase, which both arrays do, and `diff` does not compare it at all.
  */
 export interface SpinePathAttachment {
   type: 'path';
@@ -932,6 +1014,28 @@ export interface SpineSkeletonJson {
    *   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.
+   *
+   * - ✅ **What round trip 6 added to the `constraints` line is TYPES, not
+   *   order** (2026-09-16, Spine 4.3.26, eight rigs). The three that stood here
+   *   were `gallery/look`'s, and they are two types: `yaw` and `tilt`
+   *   (**slider**) and `whip` (**physics**). The trip carried a `transform`
+   *   with its whole 4.3 `source` + `properties` map, a `path` with three
+   *   non-default modes, another `physics` and another `slider`, and every one
+   *   came back field for field — so the array is now measured over **four**
+   *   of the format's types. `ik` is in none of the rigs anybody has
+   *   round-tripped, which is why the count is four and not five.
+   *
+   *   ⚠️ **None of round 6's own constraint arrays can tell order preserved
+   *   from a name sort, and reading them as if they could would be #537's
+   *   mistake in a second collection.** The three rigs that carry constraints
+   *   hold `aim, hold` (xform), `hold, knob` (physlider) and `ride` alone
+   *   (pathmodes). All three came back in the order they were given — and all
+   *   three were *already* in name order, so a re-sort and a preservation are
+   *   the same picture there, exactly as a one-element array is for `skins`
+   *   above. ⇒ The order claim still rests entirely on `gallery/look`, whose
+   *   build order `yaw, tilt, whip` is **not** name order (`tilt < whip < yaw`)
+   *   and which #539 read back unchanged. That one rig is load-bearing and
+   *   nothing in this tree re-takes it.
    */
   events?: Record<string, SpineEvent>;
   animations: Record<

package/tools/editor_roundtrip.ts

@@ -384,7 +384,7 @@ function checkFigures(reportPath: string): string[] {
 }
 
 /** The shape of a skeleton file, for the field-by-field comparison. */
-interface Shape {
+export interface Shape {
   spine: string;
   bones: number;
   slots: number;
@@ -395,16 +395,43 @@ interface Shape {
   images: string | null;
 }
 
-function shapeOf(path: string): Shape {
+/**
+ * How many constraints of each `type`, read out of 4.3's single array.
+ *
+ * 🚨 This used to count four FIXED keys off the 4.1-era top-level arrays —
+ * `d.ik`, `d.transform`, `d.path`, `d.physics` — none of which a 4.3 file has
+ * (issue #561). Every row therefore read `0 -> 0` on every trip this tool has
+ * ever run, so the summary's answer to *"did the editor drop a constraint"* was
+ * a constant, printed with the same confidence as the rows that measure
+ * something. Measured on `round6/out/pathmodes/build/skeleton.json`, whose
+ * top-level keys are `skeleton, bones, slots, skins, animations, constraints`:
+ * the old reads returned `{ik: 0, transform: 0, path: 0, physics: 0}` beside one
+ * path constraint named `ride`.
+ *
+ * ⭐ The keys are now the types actually **present**, which is why `shapeDiff`
+ * unions them: a type that vanishes has a key on one side only, and a fixed key
+ * list would have to be kept by hand against a format that added `slider` in
+ * 4.3 and can add another.
+ */
+function constraintsByType(list: ReadonlyArray<{ type?: unknown }>): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const c of list) {
+    // A constraint with no usable `type` is what `A01` exists to catch, so it is
+    // counted under a name rather than dropped — a row nobody can read beats a
+    // row nobody gets.
+    const type = typeof c?.type === 'string' && c.type !== '' ? c.type : '(no type)';
+    counts[type] = (counts[type] ?? 0) + 1;
+  }
+  return counts;
+}
+
+export function shapeOf(path: string): Shape {
   interface Skel {
     skeleton?: { spine?: string; images?: string };
     bones?: unknown[];
     slots?: unknown[];
     skins?: Array<{ attachments?: Record<string, Record<string, unknown>> }>;
-    ik?: unknown[];
-    transform?: unknown[];
-    path?: unknown[];
-    physics?: unknown[];
+    constraints?: Array<{ type?: unknown }>;
     animations?: Record<string, Record<string, unknown>>;
   }
   const d = JSON.parse(readFileSync(path, 'utf8')) as Skel;
@@ -418,12 +445,7 @@ function shapeOf(path: string): Shape {
       (n, s) => n + Object.values(s.attachments ?? {}).reduce((m, v) => m + Object.keys(v).length, 0),
       0,
     ),
-    constraints: {
-      ik: (d.ik ?? []).length,
-      transform: (d.transform ?? []).length,
-      path: (d.path ?? []).length,
-      physics: (d.physics ?? []).length,
-    },
+    constraints: constraintsByType(d.constraints ?? []),
     animations: Object.keys(d.animations ?? {}).sort(),
     timelineKinds: [...kinds].sort(),
     images: d.skeleton?.images ?? null,
@@ -431,7 +453,7 @@ function shapeOf(path: string): Shape {
 }
 
 /** The rows where the two shapes disagree — what the editor rewrote. */
-function shapeDiff(before: Shape, after: Shape): string[] {
+export function shapeDiff(before: Shape, after: Shape): string[] {
   const rows: string[] = [];
   const cmp = (field: string, a: unknown, b: unknown): void => {
     const x = JSON.stringify(a);
@@ -443,7 +465,13 @@ function shapeDiff(before: Shape, after: Shape): string[] {
   cmp('bones', before.bones, after.bones);
   cmp('slots', before.slots, after.slots);
   cmp('attachments', before.attachments, after.attachments);
-  for (const k of Object.keys(before.constraints)) cmp(`${k} constraints`, before.constraints[k], after.constraints[k]);
+  // The UNION of both sides' types, not the build's: a constraint type the build
+  // has and the export does not is the case this row exists for, and iterating
+  // one side's keys would also miss a type only the export carries. Absent reads
+  // as 0 so the row says `build 1 -> export 0` rather than naming `undefined`.
+  for (const k of [...new Set([...Object.keys(before.constraints), ...Object.keys(after.constraints)])].sort()) {
+    cmp(`${k} constraints`, before.constraints[k] ?? 0, after.constraints[k] ?? 0);
+  }
   cmp('animations', before.animations, after.animations);
   cmp('timeline kinds', before.timelineKinds, after.timelineKinds);
   return rows;
@@ -489,6 +517,82 @@ function main(): void {
 
   if (!existsSync(source)) fail(`no skeleton.json in the build directory ${opts.build}`);
 
+  // 🚨 The art the EDITOR will look for, checked before the editor is started —
+  // issue #562. The editor's JSON import reads `skeleton.images` and finds each
+  // attachment's file by name under it; it never reads an atlas (#370, measured
+  // at the MISSING wall). So a build whose `images` no longer resolves imports
+  // as a skeleton with no pixels, and the run goes on to gate, `diff`, render
+  // and `check` a candidate whose every region is blank — a green-looking
+  // measurement of nothing, or a red one blaming the editor.
+  //
+  // ⚠️ This is a `--pack` build's ordinary shape, not a corner case. `--pack`
+  // writes ONE shared page into `--out` and no loose parts at all (measured:
+  // `round6/out/packed/build/` holds `skeleton.json`, `skeleton.atlas`,
+  // `skeleton.png` and nothing else), so `skeletonImagesPath` falls through to
+  // the loose parts directory and `images` necessarily points OUT of the build
+  // — `"../../../rigs/packed/parts/"` on that run. The build is self-contained
+  // for a runtime and is not for the editor, and the two directories go their
+  // separate ways the moment anybody moves either.
+  //
+  // 🔒 Why this refuses rather than pointing `images` inside `--out`: there is
+  // nothing in there to point AT. The editor would look for `crown.png` beside
+  // the skeleton and find one packed page, so the "fix" turns a path that
+  // resolves while the parts are in place into one that can never resolve at
+  // all. What the editor needs is loose files, which is what `--copy-images`
+  // makes — and `--pack --copy-images` is refused by `cli.ts`, correctly,
+  // because a packed atlas does not reference loose parts.
+  //
+  // ⛔ It is checked HERE, before step 1, rather than beside the atlas check
+  // further down, because each precondition sits before the step it protects:
+  // the atlas's page names matter to the harness's own copy in step 3, and this
+  // matters to the editor's import in step 1.
+  {
+    interface ImagesProbe {
+      skeleton?: { images?: string };
+      skins?: Array<{ attachments?: Record<string, Record<string, { type?: string; path?: string }>> }>;
+    }
+    const probe = JSON.parse(readFileSync(source, 'utf8')) as ImagesProbe;
+    const declared = probe.skeleton?.images;
+    if (declared !== undefined && declared !== '') {
+      const imagesDir = resolve(opts.build, declared);
+      // Only the two attachment types that read a texture. A boundingbox,
+      // clipping or path attachment names no image and would be a false
+      // refusal — `src/types.ts` says so for each of them.
+      const wanted = new Set<string>();
+      for (const skin of probe.skins ?? []) {
+        for (const slot of Object.values(skin.attachments ?? {})) {
+          for (const [placeholder, att] of Object.entries(slot)) {
+            if (att.type !== undefined && att.type !== 'mesh') continue;
+            wanted.add(att.path ?? placeholder);
+          }
+        }
+      }
+      const EXTENSIONS = ['.png', '.jpg', '.jpeg'];
+      const missing = [...wanted]
+        .sort()
+        .filter((name) => !EXTENSIONS.some((ext) => existsSync(join(imagesDir, `${name}${ext}`))));
+      if (!existsSync(imagesDir)) {
+        fail(
+          `the build's skeleton.images is "${declared}", which resolves to ${imagesDir} — and there is no ` +
+            'directory there. The editor finds a JSON import\'s art by that path and never by the atlas, so the ' +
+            'import would produce a skeleton with no pixels and every measurement after it would be of nothing. ' +
+            'A `--pack` build is a runtime artifact: its pages are in --out and its `images` names the loose parts ' +
+            'it was packed from, so it round-trips only while those parts are where they were at build time. ' +
+            'Rebuild with `--copy-images` (which puts the parts beside the skeleton), or put that directory back.',
+        );
+      }
+      if (missing.length > 0) {
+        fail(
+          `the build's skeleton.images is "${declared}" (${imagesDir}) and ${missing.length} of ${wanted.size} ` +
+            `attachment image(s) are not under it — the first is "${missing[0]}". The editor resolves each ` +
+            'attachment by name against that directory and never through the atlas, so those attachments would ' +
+            'import with no pixels. If this is a `--pack` build, its one packed page is in --out and its parts are ' +
+            'not: rebuild with `--copy-images`, which is the shape whose art travels with the skeleton.',
+        );
+      }
+    }
+  }
+
   rmSync(opts.out, { recursive: true, force: true });
   mkdirSync(join(opts.out, 'export'), { recursive: true });
   mkdirSync(join(opts.out, 'export-cand'), { recursive: true });
@@ -641,4 +745,11 @@ function main(): void {
   process.exit(gate.status === 0 && check.status === 0 ? 0 : 1);
 }
 
-main();
+// ⭐ Guarded so `shapeOf` and `shapeDiff` can be READ by a control that has no
+// editor (issue #561). Every other `ERT` case drives this file as a subprocess,
+// which is the right shape for a refusal; step 6's summary is a pure function of
+// two skeleton files, and driving an editor — or four rigc subcommands — to
+// reach it would be paying for a round trip to test arithmetic. Run as a
+// program this is unchanged: `bun tools/editor_roundtrip.ts …` makes this module
+// the entry, so `import.meta.main` is true.
+if (import.meta.main) main();