spine-rigc 0.22.1 → 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.)
@@ -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
 

package/docs/SPEC_COVERAGE.md

@@ -603,13 +603,19 @@ with the member's own `skin: true` — either half alone is refused, because `Sk
 | `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.1",
+  "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);

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;