spine-rigc 0.22.0 → 0.22.1

package/docs/AUTHORING.md

@@ -1523,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 |
@@ -3344,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 |
@@ -5015,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
 
@@ -5596,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`.
@@ -5606,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
@@ -5614,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,7 +597,7 @@ 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 | ❌ | |

package/package.json

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

package/src/compile.ts

@@ -2888,19 +2888,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 +2906,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 +2952,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

@@ -804,12 +804,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 +1000,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();