spine-rigc 0.21.0 → 0.22.1

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`
@@ -1423,7 +1523,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 |
@@ -3244,7 +3344,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 |
@@ -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
 
@@ -4911,9 +5015,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
 
@@ -4972,12 +5086,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 +5127,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
 
@@ -5476,6 +5606,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`.
@@ -5486,7 +5647,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
@@ -5494,7 +5784,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,11 +597,20 @@ 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.
+
 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.1",
   "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 .",