spine-rigc 0.35.0 → 0.36.0

package/src/diff.ts

@@ -683,6 +683,12 @@ interface AttachmentFact {
   edgesPresent: boolean | null;
   /** `<width>x<height>` as stated, or `unstated` — see `attachments.region_size`. */
   size: string;
+  /**
+   * The name the runtime gives the attachment: its stated `name`, else its
+   * placeholder key (`getValue(map, "name", placeholder)`, `SkeletonJson.js:526`)
+   * — see `attachments.runtime_name`.
+   */
+  runtimeName: string;
 }
 
 function attachmentFacts(root: Json): { skins: Set<string>; byKey: Map<string, AttachmentFact> } {
@@ -718,6 +724,7 @@ function attachmentFacts(root: Json): { skins: Set<string>; byKey: Map<string, A
           // "has edges" means.
           edgesPresent: type === 'mesh' ? 'edges' in att : null,
           size: num(att.width) !== null && num(att.height) !== null ? `${num(att.width)}x${num(att.height)}` : 'unstated',
+          runtimeName: str(att.name) ?? attName,
         });
       }
     }
@@ -820,9 +827,61 @@ function diffAttachments(c: Json, r: Json): DiffSection {
       bm,
       (x, y) => x.edgesPresent === y.edgesPresent,
     ),
+    // ── issue #796 ───────────────────────────────────────────────────────────
+    //
+    // The name the RUNTIME gives each attachment — `name` if stated, else the
+    // placeholder key — agreed per skin/slot/placeholder. Every measure above is
+    // keyed by the placeholder, so a rebuild that renamed every attachment while
+    // keeping every key read 1.000 across this whole section: that is what a
+    // rebuild did on two production rigs (a stated name respelled as `path`, and
+    // `<skin>/<placeholder>` composed over a name the file never stated), and it
+    // took a pose oracle comparing `slot.attachment.name` to see it.
+    //
+    // 🚫 Reported rather than in the mean, by the same test as `mesh_edges`: a
+    // name draws no pixel, so no reading of the frames could decide it. It is
+    // still a value a consumer reads — `slot.attachment.name` — which is why it
+    // is measured at all.
+    //
+    // ⚠️ Over the keys BOTH sides hold, not over the larger roster, and that is
+    // the one departure from `agreement` here. A key one side lacks is already
+    // `attachments.names` and `attachments.count`; scored again here it would
+    // move this measure on every rename of a key and every dropped attachment,
+    // and "the same key answers to another name" — the only thing nothing else
+    // reads — would be one term among many. The denominator this reports is the
+    // number of keys compared, so a report over few shared keys says so.
+    runtimeNames(a.byKey, b.byKey),
   ]);
 }
 
+/**
+ * `attachments.runtime_name`: of the skin/slot/placeholder keys both sides
+ * hold, how many answer to the same runtime name — see the note at its call.
+ */
+function runtimeNames(a: Map<string, AttachmentFact>, b: Map<string, AttachmentFact>): DiffMeasure {
+  let shared = 0;
+  let agree = 0;
+  const differ: string[] = [];
+  for (const [key, fact] of a) {
+    const other = b.get(key);
+    if (other === undefined) continue;
+    shared++;
+    if (fact.runtimeName === other.runtimeName) agree++;
+    else if (differ.length < 3) differ.push(`${key} "${fact.runtimeName}" vs "${other.runtimeName}"`);
+  }
+  const missed = shared - agree;
+  return measure(
+    'attachments.runtime_name',
+    'each attachment both sides hold answers to the same name at runtime (`name` if stated, else its placeholder)',
+    agree,
+    shared,
+    shared === 0
+      ? 'no skin/slot/placeholder key is on both sides, so no name was compared'
+      : missed === 0
+        ? undefined
+        : `${missed} renamed: ${differ.join('; ')}${missed > differ.length ? `; …and ${missed - differ.length} more` : ''}`,
+  );
+}
+
 interface ConstraintFact {
   type: string;
   /** Every bone or slot the constraint names, sorted — its wiring. */

package/src/ingest.ts

@@ -47,8 +47,6 @@
  * spec.
  */
 import {
-  composeSkinAttachmentName,
-  DEFAULT_SKIN,
   PHYSICS_COMPONENTS,
   SLOT_TRACKS as EMITTED_SLOT_TRACKS,
   SPINE_VERSION,
@@ -681,34 +679,6 @@ function hexToRgb(hex: string): number[] {
   return [0, 2, 4].map((i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255);
 }
 
-/**
- * Which placeholders more than one skin fills, per slot.
- *
- * 🔒 Inverts `contestedPlaceholders` + `nameSkinAttachment`: rigc writes an
- * attachment `name` exactly where a placeholder is contested, and the rig spec
- * has no field for one. So the name is DROPPED and re-derived — which is right
- * where the contest survives the round trip, and a loss anywhere else. This is
- * what lets that difference be reported rather than assumed.
- */
-function contestedPlaceholders(skins: readonly unknown[]): Map<string, Set<string>> {
-  const fillers = new Map<string, Map<string, number>>();
-  for (const skin of skins) {
-    for (const [slot, placeholders] of objEntries(obj(skin).attachments)) {
-      const perSlot = fillers.get(slot) ?? new Map<string, number>();
-      for (const placeholder of Object.keys(placeholders)) {
-        perSlot.set(placeholder, (perSlot.get(placeholder) ?? 0) + 1);
-      }
-      fillers.set(slot, perSlot);
-    }
-  }
-  const contested = new Map<string, Set<string>>();
-  for (const [slot, perSlot] of fillers) {
-    const shared = new Set([...perSlot].filter(([, count]) => count > 1).map(([placeholder]) => placeholder));
-    if (shared.size) contested.set(slot, shared);
-  }
-  return contested;
-}
-
 /**
  * Read a skeleton, write the two specs that rebuild it.
  *
@@ -791,7 +761,6 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
   });
 
   // -- skins and attachments ------------------------------------------------
-  const contested = contestedPlaceholders(arr(root.skins));
   const skins: JsonObject = {};
   for (const skin of arr(root.skins)) {
     const entry = obj(skin);
@@ -801,8 +770,6 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
       for (const [placeholder, att] of Object.entries(placeholders)) {
         perSlot[placeholder] = ingestAttachment(obj(att), placeholder, boneNames, opts, note, {
           where: `skin "${nameOf(entry)}" slot "${slot}" attachment "${placeholder}"`,
-          contested: contested.get(slot)?.has(placeholder) === true,
-          skin: nameOf(entry),
         });
       }
       table[slot] = perSlot;
@@ -1331,7 +1298,7 @@ function ingestAttachment(
   boneNames: readonly string[],
   opts: IngestOptions,
   note: Note,
-  at: { where: string; contested: boolean; skin: string },
+  at: { where: string },
 ): JsonObject {
   // `readAttachment` reads no `type` as `region` (`SkeletonJson:539`), and so
   // does `checkRigSpecKeys`. Both defaults are the parser's, not a guess.
@@ -1347,125 +1314,26 @@ function ingestAttachment(
   // construct the file does not contain (issue #691).
   const linked = (type === 'mesh' || type === 'linkedmesh') && typeof att.source === 'string' && att.source.length > 0;
 
-  // The three types the parser gives a texture `path` to, which is exactly the
-  // three that call `carryArt` below. `readAttachment` reaches
-  // `getValue(map, "path", name)` in the `region` branch (`SkeletonJson.js:529`)
-  // and in the shared `mesh`/`linkedmesh` branch (`:560`); `boundingbox`,
-  // `path`, `point` and `clipping` are constructed from the name alone and
-  // resolve no region at all.
+  // The three types the parser gives a texture `path` to — and reads a
+  // `sequence` on. `readAttachment` reaches `getValue(map, "path", name)` in the
+  // `region` branch (`SkeletonJson.js:529`) and in the shared `mesh`/`linkedmesh`
+  // branch (`:560`); `boundingbox`, `path`, `point` and `clipping` are
+  // constructed from the name alone and resolve no region at all.
   const resolvesRegion = linked || type === 'region' || type === 'mesh';
 
-  /**
-   * The atlas region a dropped `name` was carrying, which the rebuild has to
-   * state as `path` or lose.
-   *
-   * 🚨 **The name is not bookkeeping — it is the region key** (issue #742).
-   * `readAttachment` reads `name = getValue(map, "name", placeholder)` and then
-   * `path = getValue(map, "path", name)`, so `path` defaults to the NAME and not
-   * to the placeholder. A source that states a `name` and no `path` therefore
-   * draws the region that name spells; rigc drops the name (the rig spec has no
-   * field for one — see below) and used to write no `path` either, so the
-   * rebuild asked the atlas for the PLACEHOLDER. Measured on a forged export
-   * whose three attachments state `name` and no `path`: the source loads against
-   * its own pack and the rebuild failed `A08_REGION_NAMES_MATCH_ATTACHMENTS`
-   * three times and `A00_ROUNDTRIP_PARSE` with it.
-   *
-   * ⚠️ A name EQUAL to the placeholder resolves the same region either way, so
-   * nothing is written for it — the rebuild would otherwise spell a field the
-   * source did not, and `A18`'s reference is the source file.
-   *
-   * 🔑 This is not `at.contested`'s business, and that is the half the card
-   * nearly missed. Where a placeholder is contested rigc composes a name of its
-   * own and `nameSkinAttachment` pins `path` at the PLACEHOLDER — so a contested
-   * source naming its own regions lost them with no finding at all, which is
-   * quieter than the uncontested case rather than safer.
-   */
-  const keptPath =
-    att.path === undefined && resolvesRegion && typeof att.name === 'string' && att.name !== placeholder
-      ? att.name
-      : undefined;
-
-  /** What became of the atlas region once the name is gone — the same four shapes wherever the name is lost. */
-  const regionFate =
-    keptPath !== undefined
-      ? `That name was also the ATLAS REGION this attachment resolves, because \`path\` defaults to the name and ` +
-        `not to the placeholder (\`SkeletonJson.js:526\`, \`:529\`, \`:560\`) — so the region key is KEPT as ` +
-        `"path": ${JSON.stringify(keptPath)} and the name alone is lost`
-      : att.path !== undefined
-        ? `The region key is the source's own \`path\` ${JSON.stringify(att.path)}, carried unchanged, so the ` +
-          'name alone is lost'
-        : resolvesRegion
-          ? at.contested
-            ? 'The region is the placeholder\'s either way — the compiler pins a composed name\'s `path` at the ' +
-              'placeholder — so the name alone is lost'
-            : 'The name is the placeholder itself, so the rebuild resolves the same atlas region and no `path` is ' +
-              'written for it'
-          : `An attachment of type ${JSON.stringify(type)} resolves no atlas region — the parser builds it from ` +
-            'the name alone — so there is no region key to keep and the name is the whole loss';
-
-  // `name` is DERIVED by rigc — `composeSkinAttachmentName` writes one exactly
-  // where a placeholder is contested — so the rig spec has no field for it and
-  // it is dropped. Where one skin fills the placeholder every stated name is a
-  // loss, because the rebuild writes none.
-  if (att.name !== undefined && !at.contested) {
-    note(
-      'lossy',
-      'ATTACHMENT_NAME',
-      at.where,
-      `the attachment states name ${JSON.stringify(att.name)} and only ONE skin fills this placeholder, so rigc ` +
-        'writes no name on the rebuild — it composes "<skin>/<placeholder>" only for a contested placeholder (#541). ' +
-        regionFate,
-    );
-  }
-
-  /**
-   * 🚨 Where a placeholder IS contested the name is re-derived, and re-derived is
-   * not the same as kept (issue #746). The rebuild's attachment answers to what
-   * `composeSkinAttachmentName` returns; the source's answers to what it states,
-   * or to its placeholder where it states nothing (`readAttachment`'s
-   * `getValue(map, "name", placeholder)`, `SkeletonJson.js:526`). Only where
-   * those two strings differ is anything renamed, so only there is a line.
-   *
-   * ⚠️ Comparing is the whole rule, and its cheap neighbour was measured and
-   * rejected on #742: firing whenever a contested entry states a name puts a
-   * `LOSS` on every contested round trip of rigc's own emits, which state
-   * exactly the composed name and rebuild byte for byte.
-   *
-   * ⚠️ A contested placeholder the DEFAULT skin fills gets no line here: the
-   * compiler composes nothing for it — `refuseDefaultSkinContest` refuses the
-   * rebuild by name — so a line claiming a composed name would state one no
-   * build will ever emit.
-   */
-  const composed = composeSkinAttachmentName(at.skin, placeholder, at.contested);
-  const sourceName = att.name === undefined ? placeholder : att.name;
-  if (composed !== null && at.skin !== DEFAULT_SKIN && sourceName !== composed) {
-    note(
-      'lossy',
-      'ATTACHMENT_NAME',
-      at.where,
-      (att.name === undefined
-        ? `the attachment states no name, so the source names it by its placeholder ${JSON.stringify(placeholder)} ` +
-          '(`SkeletonJson.js:526`)'
-        : `the attachment states name ${JSON.stringify(att.name)}`) +
-        `, and more than one skin fills this placeholder, so rigc composes the name ${JSON.stringify(composed)} ` +
-        `on the rebuild (#541) — the rig spec has no field for a name, so the rebuilt attachment answers to ` +
-        `${JSON.stringify(composed)} where the source's answered to ${JSON.stringify(sourceName)}. ` +
-        regionFate,
-    );
-  }
-
   /** The texture side, which the skeleton does not encode. Inverts `buildRigRegion`'s tail. */
   const carryArt = (): void => {
     if (att.path !== undefined) out.path = att.path;
-    else if (keptPath !== undefined) out.path = keptPath;
     // `buildRigRegion` writes `path` when the image basename differs from the
-    // placeholder, so naming the image after the region this attachment RESOLVES
-    // reproduces the same `path` decision AND the same atlas region name. Read
-    // off `out.path` rather than off `att.path`, so that the region a dropped
-    // `name` was carrying names the loose PNG too — otherwise `path` and `image`
-    // would disagree and `attachmentPath` would emit the first while the atlas
-    // was packed under the second.
-    if (opts.art === 'loose') out.image = `${out.path === undefined ? placeholder : String(out.path)}.png`;
+    // name the attachment carries — its stated `name`, else the placeholder —
+    // so naming the image after the region this attachment RESOLVES
+    // (`path ?? name ?? placeholder`, the parser's own defaults at
+    // `SkeletonJson.js:526`, `:529`, `:560`) reproduces the same `path`
+    // decision AND the same atlas region name.
+    if (opts.art === 'loose') {
+      const region = att.path ?? (typeof att.name === 'string' ? att.name : placeholder);
+      out.image = `${String(region)}.png`;
+    }
     if (att.width !== undefined) out.width = att.width;
     if (att.height !== undefined) out.height = att.height;
   };
@@ -1592,7 +1460,17 @@ function ingestAttachment(
       );
     }
   }
-  return out;
+  // 🔑 The attachment's own `name`, carried VERBATIM wherever the source states
+  // one — and nowhere else (issue #796). It is the runtime's `Attachment.name`
+  // (`getValue(map, "name", placeholder)`, `SkeletonJson.js:526`) and, with no
+  // `path`, the region the attachment draws; the rig spec has a field for it
+  // and `compile` writes exactly what that field states, so nothing about it is
+  // lost and nothing is re-derived. A name equal to its placeholder is carried
+  // too: the source spelled it, and the rebuild is held to the source's text.
+  // Put right after `type`, the order `RIG_KEYS` gives the field.
+  if (att.name === undefined) return out;
+  const { type: carriedType, ...rest } = out;
+  return carriedType === undefined ? { name: att.name, ...rest } : { type: carriedType, name: att.name, ...rest };
 }
 
 /**

package/src/rig.ts

@@ -575,9 +575,36 @@ export type RigMeshGenerator = RigRingGenerator | RigRibbonGenerator | RigContou
 /** The four `kind` names a generator may carry, and the order `RIG_KEYS` takes them in. */
 export const RIG_GENERATOR_KINDS = ['ring', 'ribbon', 'contour', 'grid'] as const;
 
+/**
+ * The attachment's own NAME, as distinct from the placeholder key it is filed
+ * under — one field, the same on every attachment type (issue #796).
+ *
+ * `readAttachment` reads `name = getValue(map, "name", placeholder)`
+ * (`SkeletonJson.js:526`) for every type, so this is the runtime's
+ * `Attachment.name` — what a consumer reads off `slot.attachment.name` — and,
+ * on the three types that draw, the default of `path` (`:529`, `:560`). Absent,
+ * the runtime names the attachment by its placeholder.
+ *
+ * 🔑 Nothing in the format resolves BY it. A skin's table, a slot's setup
+ * `attachment`, an attachment or deform timeline and a linked mesh's `source`
+ * are all keyed by the placeholder (`:415-418`, `:433`, `:1140`) — measured: a
+ * link whose `source` spells its source's name rather than its key throws
+ * `Source mesh not found`. So two skins may give one placeholder two
+ * attachments of one name, and the runtime keeps both.
+ *
+ * ⭐ rigc writes this field exactly when the spec states it and never derives
+ * one. Until #796 it composed `<skin>/<placeholder>` for a placeholder several
+ * skins fill, and a transcribed name had no field to live in — so a rebuild of
+ * an editor export answered to other names than its source did, which a
+ * consumer reading `attachment.name` can see and no gate could.
+ */
+export type RigAttachmentName = string;
+
 /** `SkeletonJson.ts:540-559`. `type` defaults to `region` (`:539`). */
 export interface RigRegionAttachment {
   type?: 'region';
+  /** The runtime's attachment name — see `RigAttachmentName`. Absent, it is the placeholder. */
+  name?: RigAttachmentName;
   /** The atlas region to resolve. Defaults to the attachment's own name. */
   path?: string;
   /**
@@ -675,6 +702,8 @@ export interface RigMeshBinding {
 
 export interface RigMeshAttachment {
   type: 'mesh';
+  /** The runtime's attachment name — see `RigAttachmentName`. Absent, it is the placeholder. */
+  name?: RigAttachmentName;
   path?: string;
   image?: string;
   /** Its length defines `worldVerticesLength`; required with authored geometry. */
@@ -735,8 +764,11 @@ export interface RigMeshAttachment {
  * under in its skin — and not its `name`.** The resolution is
  * `skin.getAttachment(sourceSlotIndex, source)` (`SkeletonJson.js:433`), and a
  * skin's table is keyed by the JSON key `readSkin` iterated (`:415-418`), so a
- * contested placeholder rigc gives an attachment `name` of `<skin>/<placeholder>`
- * is still found under the placeholder alone.
+ * source that states a `name` of its own is still found under its placeholder
+ * alone — and a `source` spelling that name throws `Source mesh not found`.
+ * Two skins each filling the source's placeholder are told apart by `skin`,
+ * never by a name (issue #796, which retired #541's reading that a link
+ * resolves its source by name).
  *
  * 🚨 **A linked mesh states no geometry of its own, and the parser is silent
  * about one that does.** The `source` branch returns before `readVertices`
@@ -756,6 +788,8 @@ export interface RigMeshAttachment {
  */
 export interface RigLinkedMeshAttachment {
   type: 'linkedmesh';
+  /** The runtime's attachment name — see `RigAttachmentName`. Absent, it is the placeholder. */
+  name?: RigAttachmentName;
   /** The art this link draws, exactly as a mesh's: its own region. */
   path?: string;
   image?: string;
@@ -853,6 +887,8 @@ export interface RigVertexGeometry {
  */
 export interface RigBoundingBoxAttachment extends RigVertexGeometry {
   type: 'boundingbox';
+  /** The runtime's attachment name — see `RigAttachmentName`. Absent, it is the placeholder. */
+  name?: RigAttachmentName;
 }
 
 /**
@@ -869,6 +905,8 @@ export interface RigBoundingBoxAttachment extends RigVertexGeometry {
  */
 export interface RigClippingAttachment extends RigVertexGeometry {
   type: 'clipping';
+  /** The runtime's attachment name — see `RigAttachmentName`. Absent, it is the placeholder. */
+  name?: RigAttachmentName;
   /**
    * The last slot this clip applies to, by name. Absent leaves `endSlot` null,
    * which is the parser's own encoding for "clip everything after this one".
@@ -915,6 +953,8 @@ export interface RigClippingAttachment extends RigVertexGeometry {
  */
 export interface RigPathAttachment extends RigVertexGeometry {
   type: 'path';
+  /** The runtime's attachment name — see `RigAttachmentName`. Absent, it is the placeholder. */
+  name?: RigAttachmentName;
   /** Default false. When true the last knot joins the first. */
   closed?: boolean;
   /**
@@ -1672,21 +1712,21 @@ export const RIG_KEYS = {
   ],
   RigTransformProperty: ['offset', 'to'],
   RigTransformTo: ['offset', 'max', 'scale'],
-  RigRegionAttachment: ['type', 'path', 'image', 'x', 'y', 'rotation', 'scaleX', 'scaleY', 'width', 'height', 'color', 'sequence'],
+  RigRegionAttachment: ['type', 'name', 'path', 'image', 'x', 'y', 'rotation', 'scaleX', 'scaleY', 'width', 'height', 'color', 'sequence'],
   RigMeshAttachment: [
-    'type', 'path', 'image', 'uvs', 'triangles', 'vertices', 'weights', 'boneIndexing', 'hull', 'edges',
+    'type', 'name', 'path', 'image', 'uvs', 'triangles', 'vertices', 'weights', 'boneIndexing', 'hull', 'edges',
     'width', 'height', 'color', 'generator', 'sequence',
   ],
   RigLinkedMeshAttachment: [
-    'type', 'path', 'image', 'source', 'slot', 'skin', 'timelines', 'width', 'height', 'color', 'sequence',
+    'type', 'name', 'path', 'image', 'source', 'slot', 'skin', 'timelines', 'width', 'height', 'color', 'sequence',
     // Declared so the refusal can name them — see `RigLinkedMeshAttachment`.
     'uvs', 'triangles', 'vertices', 'weights', 'boneIndexing', 'hull', 'edges', 'generator',
   ],
   RigMeshBinding: ['bone', 'x', 'y', 'weight'],
   RigSequence: ['count', 'start', 'digits', 'setup'],
-  RigBoundingBoxAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type'],
-  RigClippingAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'end', 'convex', 'inverse'],
-  RigPathAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'closed', 'constantSpeed', 'lengths'],
+  RigBoundingBoxAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'name'],
+  RigClippingAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'name', 'end', 'convex', 'inverse'],
+  RigPathAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'name', 'closed', 'constantSpeed', 'lengths'],
   RigRingGenerator: ['kind', 'hull', 'center', 'inner', 'size', 'bias', 'controls'],
   RigRibbonGenerator: ['kind', 'size', 'rows', 'chain'],
   RigContourGenerator: ['kind', 'tolerance', 'margin', 'maxVertices', 'alpha', 'depth', 'soft'],

package/src/timelines.ts

@@ -494,12 +494,25 @@ export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
     timeline: 'damping',
     field: 'damping',
     toPose: (v) => v,
-    poseOk: (v) => v > 0 && v < 1,
+    poseOk: (v) => v >= 0 && v <= 1,
     keyOk: null,
     inertAtSetup: false,
     outside: null,
-    states: 'inside (0, 1)',
-    statesKeyed: 'inside (0, 1)',
+    states: 'inside [0, 1]',
+    statesKeyed: 'inside [0, 1]',
+    // 🔑 The interval is CLOSED (issue #794). `1 ** x` is 1 and `0 ** x` is 0
+    // for every positive exponent, so both ends are finite at every `fps` and
+    // both are rigs somebody can mean: 1 holds the jiggle, 0 follows the bone
+    // with no overshoot. [measured] through spine-core on the generated physics
+    // fixture, 120 steps from `Physics.reset` at 60, 45 and 30 fps under a
+    // displacing animation, as a setup value and as a key: every pose value
+    // finite, the velocity never 0 at 1 and 0 after every step at 0. And 1 is
+    // not only a choice: it is 4.2's own parser default for an omitted
+    // `damping` (`SkeletonJson.js:242` in 4.2.120,
+    // `getValue(constraintMap, "damping", 1)`; 4.3.13 reads 0.85 at `:308`), so a
+    // rig migrated from 4.2 that keys "the default" writes 1 and the editor
+    // exports it as it is. The open interval this replaced refused that rig.
+    //
     // ⚠️ The frame-rate half is why the bound cannot be checked by playing a rig
     // at 60 fps (issue #748): `step` is `1 / fps`, the constraint's own rate, so
     // the exponent is exactly 1 there and a negative damping only flips the
@@ -508,11 +521,13 @@ export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
     // steps of the key at 45 and at 120 (exponents 1.3333 and 0.5).
     why:
       'the per-step decay is `damping ** (60 * step)`, with `step` = 1 / the constraint\'s `fps`, and every velocity ' +
-      'is multiplied by it (`PhysicsConstraint.js:114,148,158,163,210,222,227`), so 1 never decays, above 1 ' +
-      'diverges, and 0 kills the velocity outright, at every rate. Below 0 the result depends on `fps`: where ' +
-      '`60 / fps` is a whole number a negative base stays finite — at 60 fps it is the velocity\'s sign flipped each ' +
-      'step, which can look like a jiggle settling — and at any other rate it is a negative number raised to a ' +
-      'fractional power, which is NaN (`(-0.5) ** (60 / 45)`), so a rig tried only at 60 fps never shows the failure',
+      'is multiplied by it (`PhysicsConstraint.js:114,148,158,163,210,222,227`), so above 1 every velocity grows on ' +
+      'every step and the offset diverges, at every rate. Below 0 the result depends on `fps`: where `60 / fps` is a ' +
+      'whole number a negative base stays finite — at 60 fps it is the velocity\'s sign flipped each step, which can ' +
+      'look like a jiggle settling — and at any other rate it is a negative number raised to a fractional power, ' +
+      'which is NaN (`(-0.5) ** (60 / 45)`), so a rig tried only at 60 fps never shows the failure. The two ends are ' +
+      'values the runtime plays at every rate: at 1 the velocity never decays, so the jiggle holds for as long as it ' +
+      'runs, and at 0 every velocity is zeroed on every step, so the offset follows the bone with no overshoot',
   },
 ];
 

package/src/types.ts

@@ -281,7 +281,7 @@ export type BoneProperty =
  * export; `PHYSICS_TRACKS` in `compile.ts` carries the argument.
  *
  * 🔒 **Four of them have a compile-time range** (issue #610): `mass` must be
- * `> 0`, `damping` strictly inside `(0, 1)`, and `mix` and `strength` `0` or
+ * `> 0`, `damping` inside the closed `[0, 1]`, and `mix` and `strength` `0` or
  * more. The bounds are `PHYSICS_POSE_RULES` in `src/timelines.ts` and they are
  * the runtime's, not a policy — `inertia`, `wind`, `gravity` and the top of
  * `mix` are bounded nowhere, because the runtime documents nothing for the first
@@ -826,18 +826,19 @@ export interface SpineSlot {
  *
  * `readAttachment` reads `const name = getValue(map, "name", placeholder)`
  * (`SkeletonJson.ts:526`), so an absent field means "the placeholder is also the
- * name" — which is what rigc emitted for every attachment until issue #541, and
- * what makes several skins' entries under one placeholder **several attachments
- * with one name**. spine-core does not care; the Spine editor refuses the import
- * outright, naming the section, the attachment and the rule.
+ * name". Nothing in the format resolves by it — skins, setup attachments,
+ * attachment and deform timelines and a linked mesh's `source` are keyed by the
+ * placeholder — so several skins' entries under one placeholder may carry one
+ * name, which is what the editor itself exports (issue #796).
  *
- * 🚨 Writing it moves a second field with it. For the two types that carry
+ * 🚨 It moves a second field's default with it. For the three types that carry
  * texture art, `path` defaults to **`name`**, not to the placeholder
- * (`:529`, `:559`), so an attachment given a name and no path resolves its region
- * at the new name and the atlas lookup misses. `nameSkinAttachment` in
- * `compile.ts` is the one place that writes either, and it always writes both.
+ * (`:529`, `:559`), so an attachment given a name and no path resolves the region
+ * that name spells. rigc emits it exactly when the rig spec states it
+ * (`RigAttachmentName` in `rig.ts`); from #541 to #796 it composed
+ * `<skin>/<placeholder>` for a placeholder several skins fill, and that is gone.
  *
- * ⚠️ And the **`default` skin may never be one of the skins sharing that
+ * ⚠️ And the **`default` skin may never be one of the skins sharing a
  * 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
@@ -848,8 +849,7 @@ export interface SpineSlot {
  * 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.
+ * where that lives.
  */
 export interface SpineRegionAttachment {
   name?: string;
@@ -888,7 +888,9 @@ export interface SpineMeshAttachment {
   type: 'mesh';
   /** See `SpineRegionAttachment.name` — and it takes `path` with it. */
   name?: string;
+  /** `path` and `color` are written right after `type` — `compile.ts`'s `meshTextureKeys` says where that is measured. */
   path?: string;
+  color?: string;
   uvs: number[];
   triangles: number[];
   /** Weighted encoding: boneCount, (boneIndex, bindX, bindY, weight)*n, repeated. */
@@ -910,7 +912,6 @@ export interface SpineMeshAttachment {
   /** Nonessential, but they make the mesh budget assertions readable. */
   width: number;
   height: number;
-  color?: string;
   sequence?: SpineSequence;
 }
 

package/src/validate.ts

@@ -570,7 +570,11 @@ const SETUP_POSE_SAYS: Record<
   // back and below 0 one that is pushed away, and the row's `why` — the key's
   // sentence — quotes the second from the same object.
   strength: (pose, _animations, rule) => `has strength ${pose.strength}; ${physicsOutsideSays(rule, pose.strength)}`,
-  damping: (pose) => `has damping ${pose.damping}; outside (0,1) it never settles`,
+  // The bound is read off the row, so the setup pose and a key cannot state two
+  // intervals; the reason is the two ways out, since the ends are inside (#794).
+  damping: (pose, _animations, rule) =>
+    `has damping ${pose.damping}; must be ${rule.states} — above 1 every velocity grows on every step, and below 0 ` +
+    'it is NaN at any fps where 60 / fps is not whole',
 };
 
 /**
@@ -3090,8 +3094,10 @@ export function validate(input: ValidateInput): ValidateReport {
     //
     // Every failure mode here is silent. The five component fields default to
     // 0, so a constraint can drive nothing at all; `mix` 0 mutes it; `mass` 0
-    // becomes an infinite massInverse; and `damping` >= 1 never settles, which
-    // on a mesh-driving bone means the canvas re-rasterises forever.
+    // becomes an infinite massInverse; and `damping` above 1 never settles, which
+    // on a mesh-driving bone means the canvas re-rasterises forever. 1 itself is
+    // inside the bound since issue #794: it never decays, which is finite and a
+    // choice, and what it costs a consumer's frame is the consumer's to judge.
     //
     // 🔑 **Two arms, one criterion.** The second arm below reads every physics
     // TIMELINE key, and it is written against `PHYSICS_POSE_RULES` — the table

package/tools/editor_roundtrip.ts

@@ -533,7 +533,13 @@ export function diffSummaryLines(reportPath: string): string[] {
 function checkFigures(reportPath: string): string[] {
   if (!existsSync(reportPath)) return ['(no check report was written, so nothing was read from one)'];
   interface Anim {
-    animation: string;
+    /**
+     * `null` on the row `check` writes for the SETUP pose (`dir: "setup"`) — which
+     * is the only row a rig with no animations gets. Read as a string, that report
+     * threw at step 5 on every animation-less build (issue #796's two editor fixtures).
+     */
+    animation: string | null;
+    dir?: string;
     compared: number;
     meanMae: number;
     worstMae: number;
@@ -546,7 +552,7 @@ function checkFigures(reportPath: string): string[] {
   if (animations.length === 0) return ['(the check report carried no animations — read it before believing this run)'];
   return animations.map(
     (a) =>
-      `  ${a.animation.padEnd(12)} ${a.compared} frame(s)  mean MAE ${a.meanMae.toFixed(4)}  worst ${a.worstMae.toFixed(4)}` +
+      `  ${(a.animation ?? `(${a.dir ?? 'setup'})`).padEnd(12)} ${a.compared} frame(s)  mean MAE ${a.meanMae.toFixed(4)}  worst ${a.worstMae.toFixed(4)}` +
       `  worst drift ${a.worstDrift.toFixed(3)}px${a.worstDriftSlot ? ` on ${a.worstDriftSlot} @ f${a.worstDriftFrame}` : ''}`,
   );
 }
@@ -844,7 +850,7 @@ function main(): void {
   {
     interface ImagesProbe {
       skeleton?: { images?: string };
-      skins?: Array<{ attachments?: Record<string, Record<string, { type?: string; path?: string }>> }>;
+      skins?: Array<{ attachments?: Record<string, Record<string, { type?: string; name?: string; path?: string }>> }>;
     }
     const probe = JSON.parse(readFileSync(source, 'utf8')) as ImagesProbe;
     const declared = probe.skeleton?.images;
@@ -858,7 +864,10 @@ function main(): void {
         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);
+            // The parser's own defaults: `path`, else the attachment's `name`,
+            // else its placeholder (`SkeletonJson.js:526`, `:529`, `:560`) — a
+            // stated `name` is the file the editor looks for (issue #796).
+            wanted.add(att.path ?? att.name ?? placeholder);
           }
         }
       }