spine-rigc 2.0.1 → 2.0.3

package/src/diff.ts

@@ -689,6 +689,43 @@ interface AttachmentFact {
    * — see `attachments.runtime_name`.
    */
   runtimeName: string;
+  /**
+   * Every name the attachment resolves, as `<field>:<name>` and sorted — see
+   * `attachmentRefTokens` for which fields and why.
+   */
+  refs: string;
+  /** The same tokens as a list, for the note that spells a disagreement out. */
+  refList: string[];
+}
+
+/**
+ * The names an attachment resolves (issue #1085): the atlas region a region or
+ * a mesh draws, a clipping polygon's end slot, and the mesh a linked mesh takes
+ * its geometry from — with the skin and slot it is found under, where stated.
+ *
+ * ⭐ The region is read as the runtime resolves it, `path`, else the stated
+ * `name`, else the placeholder (SPEC_COVERAGE §1.5's three-level indirection),
+ * for the reason `runtime_name` reads its name that way: a file that spells the
+ * path out and one that leaves it to the parser name the same region, and a
+ * measure that called those different would score every export against every
+ * writer that states its paths. Every other field is a token only when the file
+ * states it — absent is no token, never a default, as in `constraints.refs`.
+ *
+ * Measured on public builds through spine-core: a region's `path` moved to the
+ * other eye of `spineboy-pro` changes 94 of its 99 sampled draws, its clipping
+ * polygon's `end` moved six slots on changes the clipping of 9, and a linked
+ * mesh on `gallery/nod` taking `ear_r` instead of `ear_l` as its source changes
+ * all 18 of its sampled poses. `diff` compared none of the three, and two of them occur in
+ * none of the twelve editor exports (a stated `path` and a linked mesh).
+ */
+function attachmentRefTokens(type: string, key: string, att: Json): string[] {
+  const out: string[] = [];
+  if (type === 'region' || type === 'mesh' || type === 'linkedmesh') out.push(`path:${str(att.path) ?? str(att.name) ?? key}`);
+  for (const field of ['end', 'source', 'skin', 'slot'] as const) {
+    const s = str(att[field]);
+    if (s !== null) out.push(`${field}:${s}`);
+  }
+  return out.sort();
 }
 
 function attachmentFacts(root: Json): { skins: Set<string>; byKey: Map<string, AttachmentFact> } {
@@ -725,6 +762,8 @@ function attachmentFacts(root: Json): { skins: Set<string>; byKey: Map<string, A
           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,
+          refs: attachmentRefTokens(type, attName, att).join(' '),
+          refList: attachmentRefTokens(type, attName, att),
         });
       }
     }
@@ -795,6 +834,22 @@ function diffAttachments(c: Json, r: Json): DiffSection {
       counted([...ar.values()].map((f) => f.size)),
       counted([...br.values()].map((f) => f.size)),
     ),
+    wiringAgreement(
+      'attachments.refs',
+      'each attachment resolves the same region, clipping end and linked-mesh source',
+      a.byKey,
+      b.byKey,
+      (key) => `attachment ${JSON.stringify(key)}`,
+      '`attachments.names`',
+    ),
+    wiringAgreement(
+      'attachments.skin_members',
+      'each skin activates the same skin-required bones and constraints',
+      skinMembers(c),
+      skinMembers(r),
+      (skin) => `skin ${JSON.stringify(skin)}`,
+      '`attachments.skins`',
+    ),
   ],
   undefined,
   // ── reported (issue #46) ────────────────────────────────────────────────
@@ -853,6 +908,67 @@ function diffAttachments(c: Json, r: Json): DiffSection {
   ]);
 }
 
+/**
+ * What each skin activates (issue #1085): the `bones` and the per-kind
+ * constraint lists a skin declares, as `<list>:<name>` tokens, sorted — a skin's
+ * MEMBERSHIP, which is what decides whether a bone or constraint marked
+ * `skin: true` is active under it.
+ *
+ * Measured on public builds through spine-core: a `gallery/look` bone made
+ * skin-required and left out of the skin's `bones` moves every one of its 27
+ * sampled poses, and `gallery/walk`'s `leg_b_ik` left out of the skin's `ik`
+ * moves all 9. None of the twelve editor exports declares a membership list, so
+ * every one of them reads `1/1` per skin here — two empty lists agree — which is
+ * the comparison being made rather than an absence of one.
+ */
+function skinMembers(root: Json): Map<string, { refs: string; refList: string[] }> {
+  const out = new Map<string, { refs: string; refList: string[] }>();
+  for (const skin of objs(root.skins)) {
+    const name = str(skin.name) ?? 'default';
+    const refList: string[] = [];
+    for (const list of ['bones', 'ik', 'transform', 'path', 'physics', 'slider'] as const) {
+      for (const member of arr(skin[list])) {
+        const s = str(member);
+        if (s !== null) refList.push(`${list}:${s}`);
+      }
+    }
+    refList.sort();
+    out.set(name, { refs: refList.join(' '), refList });
+  }
+  return out;
+}
+
+/**
+ * `agreement` over the larger roster on a `refs` string, with the note
+ * `constraints.refs` writes: each entry both sides hold whose names differ,
+ * field by field and candidate first, then a count of the entries one side holds
+ * alone, which `elsewhere` is the measure that names.
+ */
+function wiringAgreement<T extends { refs: string; refList: string[] }>(
+  id: string,
+  what: string,
+  a: Map<string, T>,
+  b: Map<string, T>,
+  label: (key: string) => string,
+  elsewhere: string,
+): DiffMeasure {
+  const base = agreement(id, what, a, b, (x, y) => x.refs === y.refs);
+  const missed = base.total - base.matched;
+  if (missed === 0) return base;
+  const differ: string[] = [];
+  for (const [key, fact] of a) {
+    const other = b.get(key);
+    if (other !== undefined && other.refs !== fact.refs) differ.push(refsDisagreement(label(key), fact, other));
+  }
+  const oneSided = missed - differ.length;
+  const spelled = differ.slice(0, REFS_SPELLED_OUT);
+  const note =
+    (differ.length === 0 ? '' : `${differ.length} differ: ${spelled.join('; ')}`) +
+    (differ.length > spelled.length ? `; …and ${differ.length - spelled.length} more` : '') +
+    (oneSided === 0 ? '' : `${differ.length === 0 ? '' : '; '}${oneSided} on one side only, which ${elsewhere} names`);
+  return { ...base, note };
+}
+
 /**
  * `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.
@@ -884,8 +1000,15 @@ function runtimeNames(a: Map<string, AttachmentFact>, b: Map<string, AttachmentF
 
 interface ConstraintFact {
   type: string;
-  /** Every bone or slot the constraint names, sorted — its wiring. */
+  /**
+   * Every name the constraint resolves, as `<field>:<name>` and sorted — its
+   * wiring: the bones and slots it reads and writes, a slider's animation, and
+   * the properties a slider or a transform maps (`property:rotate`,
+   * `property:x>y`). See `constraintFacts` for which fields and why.
+   */
   refs: string;
+  /** The same tokens as a list, for the note that spells a disagreement out. */
+  refList: string[];
 }
 
 /**
@@ -898,6 +1021,29 @@ interface ConstraintFact {
  * way, so the report read 1.000 while its own header line counted one constraint
  * more than `constraints.count` did, measured at 14/14 against 13/13 on the
  * export that made the card.
+ *
+ * ⭐ **What the wiring is** (issue #1078): every field of a 4.3 constraint whose
+ * value is a NAME the parser resolves — `SPEC_COVERAGE.md` §1.4, field by field.
+ * `bones`, `bone`, `target`, `source` and `slot` name a bone or a slot; a
+ * slider's `animation` names an animation; a slider's `property` and the
+ * `from`/`to` keys of a transform's `properties` name the property read and the
+ * property written, from a closed set the parser throws outside of. Every other
+ * field is a number, a flag or a mode — a value, which this file does not compare
+ * on either side of any split; the value walk (`diffSkeletonValues`) does.
+ *
+ * 🔍 Until #1078 the list stopped at the five bone and slot fields, so an editor
+ * import that repointed both sliders of a probe (`yaw -> "5"` came back as
+ * `yaw -> "-a"`, issue #1040) read 1.000 on every constraint measure. The two
+ * property fields were blinder still: measured on `gallery/look` and `6-arcs-pro`,
+ * a slider moved from `rotate` to `x` and a transform remapped from `x>x` to
+ * `x>y` moved no measure here and no value in the value walk either (its skip
+ * list named `properties`), so nothing in the tree compared them at all. Since
+ * issue #1084 the walk reads both, by class (`property/kind`, `properties/FromX/to/ToY`).
+ *
+ * ⚠️ Absent is no token, never a default: a transform with no `properties` maps
+ * nothing, and two sides that both omit a field agree about it. And the tokens
+ * are a set, so the order a file writes `properties` in — an object, re-keyed by
+ * any writer — is not a difference.
  */
 function constraintFacts(root: Json): Map<string, ConstraintFact> {
   const out = new Map<string, ConstraintFact>();
@@ -910,11 +1056,115 @@ function constraintFacts(root: Json): Map<string, ConstraintFact> {
       const s = str(b);
       if (s !== null) refs.add(`bone:${s}`);
     }
-    for (const key of ['bone', 'target', 'source', 'slot'] as const) {
+    for (const key of ['bone', 'target', 'source', 'slot', 'animation', 'property'] as const) {
       const s = str(con[key]);
       if (s !== null) refs.add(`${key}:${s}`);
     }
-    out.set(at, { type: str(con.type) ?? '(none)', refs: [...refs].sort().join(' ') });
+    if (isObj(con.properties)) {
+      for (const [from, entry] of Object.entries(con.properties)) {
+        const to = isObj(entry) && isObj(entry.to) ? Object.keys(entry.to) : [];
+        // A `from` with no `to` maps nothing at runtime, but it is still a
+        // statement the file makes, so it is a token of its own rather than
+        // silently equal to the key being absent.
+        if (to.length === 0) refs.add(`property:${from}>`);
+        for (const t of to) refs.add(`property:${from}>${t}`);
+      }
+    }
+    const refList = [...refs].sort();
+    out.set(at, { type: str(con.type) ?? '(none)', refs: refList.join(' '), refList });
+  }
+  return out;
+}
+
+/** How many disagreeing constraints `constraints.refs`' note spells out before it counts the rest. */
+const REFS_SPELLED_OUT = 3;
+
+/**
+ * One constraint's disagreement, by field: `slider constraint "yaw": animation
+ * "5" vs "-a"` — the candidate's names for each field that differs, then the
+ * reference's, `none` where a side has none.
+ */
+function refsDisagreement(at: string, a: { refList: string[] }, b: { refList: string[] }): string {
+  const byField = (f: { refList: string[] }): Map<string, string[]> => {
+    const m = new Map<string, string[]>();
+    for (const token of f.refList) {
+      const colon = token.indexOf(':');
+      const field = token.slice(0, colon);
+      m.set(field, [...(m.get(field) ?? []), token.slice(colon + 1)]);
+    }
+    return m;
+  };
+  const af = byField(a);
+  const bf = byField(b);
+  const fields = [...new Set([...af.keys(), ...bf.keys()])].sort();
+  const spell = (names: string[] | undefined): string =>
+    names === undefined ? 'none' : names.map((n) => JSON.stringify(n)).join(', ');
+  const parts = fields
+    .filter((f) => (af.get(f) ?? []).join(' ') !== (bf.get(f) ?? []).join(' '))
+    .map((f) => `${f} ${spell(af.get(f))} vs ${spell(bf.get(f))}`);
+  return `${at}: ${parts.join(', ')}`;
+}
+
+/**
+ * `constraints.refs`: `agreement` over the constraints, unchanged in what it
+ * counts, with a note naming each disagreement and both sides' names — the
+ * figure alone says that some constraint is wired differently, and a reader
+ * acting on it needs to know which one and to what (issue #1078).
+ *
+ * The note's two counts partition the misses: a constraint both sides hold whose
+ * wiring differs is spelled out, and one only one side holds is counted, since
+ * `constraints.names` is the measure that names it.
+ */
+function constraintRefs(a: Map<string, ConstraintFact>, b: Map<string, ConstraintFact>): DiffMeasure {
+  const base = agreement(
+    'constraints.refs',
+    'each constraint names the same bones, slots, animation and properties',
+    a,
+    b,
+    (x, y) => x.refs === y.refs,
+  );
+  const differ: string[] = [];
+  for (const [at, fact] of a) {
+    const other = b.get(at);
+    if (other !== undefined && other.refs !== fact.refs) differ.push(refsDisagreement(at, fact, other));
+  }
+  const missed = base.total - base.matched;
+  if (missed === 0) return base;
+  const oneSided = missed - differ.length;
+  const spelled = differ.slice(0, REFS_SPELLED_OUT);
+  const note =
+    (differ.length === 0 ? '' : `${differ.length} wired differently: ${spelled.join('; ')}`) +
+    (differ.length > spelled.length ? `; …and ${differ.length - spelled.length} more` : '') +
+    (oneSided === 0
+      ? ''
+      : `${differ.length === 0 ? '' : '; '}${oneSided} on one side only, which \`constraints.names\` names`);
+  return { ...base, note };
+}
+
+/**
+ * The constraints in the order the file declares them, by kind and name — the
+ * key `constraintFacts` uses, so that `leg` as an ik and as a transform are two
+ * entries here as well.
+ *
+ * 🔍 **Why the order is data** (issue #1085). 4.3 folds every constraint into one
+ * array and applies them in its order, so two files with the same constraints
+ * wired the same way can pose differently. Measured by reversing the array and
+ * posing both through spine-core: `spineboy-pro` moves 98 of its 99 sampled
+ * poses, `6-arcs-pro` 8 of 9 and `sack-pro` 8 of 36 (33 of 36 with physics
+ * stepped); swapping `aim-torso-ik` and `aim-torso-transform` alone moves the 9
+ * samples of `aim`. Before this nothing in the tree compared it — the value walk
+ * keys constraints by name, so it is blind to the order by construction.
+ *
+ * ⚠️ Not every swap poses differently, and the measure does not pretend to know
+ * which do: `gallery/look`'s two sliders and `gallery/walk`'s two legs drive
+ * disjoint bones and read the same pose either way. A reordering is reported as
+ * what the file states, the way `bones.order` reports one.
+ */
+function constraintOrder(root: Json): string[] {
+  const out: string[] = [];
+  for (const con of objs(root.constraints)) {
+    const name = str(con.name);
+    if (name !== null) out.push(constraintAt(str(con.type) ?? '(none)', name));
   }
   return out;
 }
@@ -922,6 +1172,12 @@ function constraintFacts(root: Json): Map<string, ConstraintFact> {
 function diffConstraints(c: Json, r: Json): DiffSection {
   const a = constraintFacts(c);
   const b = constraintFacts(r);
+  const ao = constraintOrder(c);
+  const bo = constraintOrder(r);
+  const shared = ao.filter((n) => b.has(n));
+  const sharedOther = bo.filter((n) => a.has(n));
+  const inOrder = lcs(shared, sharedOther);
+  const max = Math.max(a.size, b.size);
   return sectionOf('constraints', [
     measure('constraints.count', 'how many constraints', Math.min(a.size, b.size), Math.max(a.size, b.size)),
     jaccard('constraints.names', 'the constraint names', new Set(a.keys()), new Set(b.keys())),
@@ -932,10 +1188,33 @@ function diffConstraints(c: Json, r: Json): DiffSection {
       counted([...b.values()].map((f) => f.type)),
     ),
     agreement('constraints.type_by_name', 'each constraint is the same type', a, b, (x, y) => x.type === y.type),
-    agreement('constraints.refs', 'each constraint names the same bones and slots', a, b, (x, y) => x.refs === y.refs),
+    constraintRefs(a, b),
+    measure(
+      'constraints.order',
+      'the constraints are declared, and so applied, in the same order',
+      inOrder,
+      max,
+      [
+        ...(inOrder === shared.length ? [] : [outOfOrder(shared, sharedOther)]),
+        ...(shared.length === max ? [] : [`${max - shared.length} of the larger roster not on both sides, which \`constraints.names\` names`]),
+      ].join('; ') || undefined,
+    ),
   ]);
 }
 
+/**
+ * `constraints.order`'s note when the shared constraints are not in one order:
+ * both sides' order of them, candidate first, spelled out to a limit.
+ */
+function outOfOrder(a: string[], b: string[]): string {
+  const spell = (list: string[]): string =>
+    list.slice(0, ORDER_SPELLED_OUT).join(', ') + (list.length > ORDER_SPELLED_OUT ? `, …and ${list.length - ORDER_SPELLED_OUT} more` : '');
+  return `${a.length - lcs(a, b)} out of order: candidate ${spell(a)}; reference ${spell(b)}`;
+}
+
+/** How many constraints `constraints.order`'s note lists per side before it counts the rest. */
+const ORDER_SPELLED_OUT = 6;
+
 interface AnimationFacts {
   names: string[];
   /** `<anim>` -> last key time. Skeleton JSON has no duration field. */
@@ -993,6 +1272,136 @@ function animationFacts(root: Json): AnimationFacts {
   return facts;
 }
 
+/**
+ * The names the animations resolve, as two multisets of tokens (issue #1085).
+ *
+ * `animationFacts` keeps each timeline's kind and drops its target on purpose —
+ * a candidate's own vocabulary would otherwise be counted against it a second
+ * time inside `timeline_kinds` (#21) — and reads no key's contents beyond its
+ * time and curve. So until this, a bone timeline moved onto another bone, an
+ * attachment key naming another attachment, a draw-order key naming another slot
+ * and an event key firing another event each moved no measure in this file, and
+ * every one of them poses or draws differently: measured on public builds
+ * through spine-core, a retargeted bone timeline moves 7 of `gallery/look`'s 27
+ * sampled poses, two slots' attachment keys swapped move 9 of `spineboy-pro`'s
+ * 99, a draw-order offset moved to the next slot moves 9 of `spineboy-ess`'s 72
+ * and an event key renamed to a second event moves the event block of one sample.
+ *
+ * - `targets`: one token per timeline, `<animation>|<group>|<target>` — the
+ *   bone, slot or constraint it keys, a deform's or sequence's
+ *   `skin/slot/attachment`, and each slot a draw-order folder holds. The
+ *   timeline's own kind is left out on purpose: it is `timeline_kinds`'
+ *   subject, and a rotate keyed as a scale on the same bone moves that measure
+ *   and must not move this one too.
+ * - `keyed`: one token per name a KEY carries, with its position in the
+ *   timeline — an attachment key's attachment (`(none)` for a key that clears
+ *   the slot), each draw-order offset's slot, an event key's event.
+ *
+ * Both are names, so both are name-matched, and a candidate with its own names
+ * reads low here exactly as it does on `names` — the name-agnostic block is
+ * where that rig is read. ⚠️ No key VALUE is read: a key's time, an offset's
+ * distance and an event's payload are the value walk's.
+ */
+interface AnimationRefs {
+  targets: Map<string, number>;
+  keyed: Map<string, number>;
+}
+
+/** The physics group's empty name, which applies a timeline to every physics constraint. */
+const EVERY_PHYSICS_CONSTRAINT = '(every physics constraint)';
+
+function animationRefs(root: Json): AnimationRefs {
+  const targets = new Map<string, number>();
+  const keyed = new Map<string, number>();
+  const bump = (m: Map<string, number>, k: string): void => {
+    m.set(k, (m.get(k) ?? 0) + 1);
+  };
+  if (!isObj(root.animations)) return { targets, keyed };
+  for (const [anim, body] of Object.entries(root.animations)) {
+    if (!isObj(body)) continue;
+    for (const group of ['bones', 'slots', 'path', 'physics', 'slider'] as const) {
+      const held = body[group];
+      if (!isObj(held)) continue;
+      for (const [target, timelines] of Object.entries(held)) {
+        if (!isObj(timelines)) continue;
+        const named = group === 'physics' && target === '' ? EVERY_PHYSICS_CONSTRAINT : target;
+        for (const [timeline, keys] of Object.entries(timelines)) {
+          if (!Array.isArray(keys)) continue;
+          bump(targets, `${anim}|${group}|${named}`);
+          if (group === 'slots' && timeline === 'attachment') {
+            keys.forEach((key, i) => {
+              if (isObj(key)) bump(keyed, `${anim}|attachment key ${i}|${target}: ${str(key.name) ?? '(none)'}`);
+            });
+          }
+        }
+      }
+    }
+    for (const group of ['ik', 'transform'] as const) {
+      const held = body[group];
+      if (!isObj(held)) continue;
+      for (const [target, keys] of Object.entries(held)) if (Array.isArray(keys)) bump(targets, `${anim}|${group}|${target}`);
+    }
+    if (isObj(body.attachments)) {
+      for (const [skin, bySlot] of Object.entries(body.attachments)) {
+        if (!isObj(bySlot)) continue;
+        for (const [slot, byAttachment] of Object.entries(bySlot)) {
+          if (!isObj(byAttachment)) continue;
+          for (const [attachment, timelines] of Object.entries(byAttachment)) {
+            if (!isObj(timelines)) continue;
+            for (const keys of Object.values(timelines)) {
+              if (Array.isArray(keys)) bump(targets, `${anim}|attachments|${skin}/${slot}/${attachment}`);
+            }
+          }
+        }
+      }
+    }
+    const offsets = (label: string, keys: unknown): void => {
+      arr(keys).forEach((key, i) => {
+        if (!isObj(key)) return;
+        for (const offset of objs(key.offsets)) bump(keyed, `${anim}|${label} key ${i}|${str(offset.slot) ?? '(none)'}`);
+      });
+    };
+    offsets('drawOrder', body.drawOrder);
+    objs(body.drawOrderFolder).forEach((folder, f) => {
+      for (const slot of arr(folder.slots)) bump(targets, `${anim}|drawOrderFolder ${f}|${str(slot) ?? '(none)'}`);
+      offsets(`drawOrderFolder ${f}`, folder.keys);
+    });
+    arr(body.events).forEach((key, i) => {
+      if (isObj(key)) bump(keyed, `${anim}|event key ${i}|${str(key.name) ?? '(none)'}`);
+    });
+  }
+  return { targets, keyed };
+}
+
+/** How many tokens a names histogram's note spells out per side before it counts the rest. */
+const TOKENS_SPELLED_OUT = 3;
+
+/**
+ * `histogram`, with a note naming what each side holds that the other does not —
+ * the figure alone says some name moved, and a reader acting on it needs which.
+ */
+function namesHistogram(id: string, what: string, a: Map<string, number>, b: Map<string, number>): DiffMeasure {
+  const base = histogram(id, what, a, b);
+  if (base.matched === base.total) return base;
+  // A token one side holds more often than the other, with how many more — a
+  // bone keyed by three timelines on one side and one on the other is `×2`.
+  const only = (x: Map<string, number>, y: Map<string, number>): string[] => {
+    const out: string[] = [];
+    for (const [k, v] of x) {
+      const extra = v - (y.get(k) ?? 0);
+      if (extra > 0) out.push(`${JSON.stringify(k)}${extra > 1 ? ` ×${extra}` : ''}`);
+    }
+    return out;
+  };
+  const spell = (side: string, list: string[]): string =>
+    list.length === 0
+      ? ''
+      : `${side} only: ${list.slice(0, TOKENS_SPELLED_OUT).join(', ')}` +
+        (list.length > TOKENS_SPELLED_OUT ? `, …and ${list.length - TOKENS_SPELLED_OUT} more` : '');
+  const parts = [spell('candidate', only(a, b)), spell('reference', only(b, a))].filter((p) => p !== '');
+  return { ...base, note: `${base.total - base.matched} differ — ${parts.join('; ')}` };
+}
+
 /**
  * What a side's keying costs, in the two shapes that separate the two ways a
  * key total can differ: more timelines, or more keys inside a timeline.
@@ -1161,6 +1570,8 @@ function diffAnimations(c: Json, r: Json, pairsStated: readonly DiffAnimationPai
   const at = keyingTotals(a);
   const bt = keyingTotals(b);
   const paired = pairAnimations(a, b, pairsStated);
+  const refsA = animationRefs(c);
+  const refsB = animationRefs(r);
   const perSecond = (t: KeyingTotals): number => (t.seconds === 0 ? 0 : t.keys / t.seconds);
   const perTimeline = (t: KeyingTotals): number => (t.timelines === 0 ? 0 : t.keys / t.timelines);
   return sectionOf('animations', [
@@ -1179,6 +1590,18 @@ function diffAnimations(c: Json, r: Json, pairsStated: readonly DiffAnimationPai
     histogram('animations.event_keys', 'as many event firings', a.events, b.events),
     agreement('animations.draw_order', 'a draw-order timeline is present or absent alike', a.hasDrawOrder, b.hasDrawOrder, (x, y) => x === y),
     agreement('animations.deform', 'a deform timeline is present or absent alike', a.hasDeform, b.hasDeform, (x, y) => x === y),
+    namesHistogram(
+      'animations.targets',
+      'each timeline keys the same bone, slot, constraint or attachment',
+      refsA.targets,
+      refsB.targets,
+    ),
+    namesHistogram(
+      'animations.keyed_names',
+      'each key names the same attachment, draw-order slot or event',
+      refsA.keyed,
+      refsB.keyed,
+    ),
   ],
   // ── the same two skeletons' shots, paired rather than named (issue #720) ──
   //
@@ -1523,7 +1946,7 @@ export const VALUE_PARSED_ULP = 2 ** -23;
  * Both terms are derived rather than fitted: the first is rigc's models' grid,
  * the second is the parser's storage. Measured over the twelve editor exports
  * in `examples/`, the widest gap between a rebuild and the file it was read
- * from is **0** — none of 188,339 numeric values differs at all, since issue
+ * from is **0** — none of 189,699 numeric values differs at all, since issue
  * #716 made every emitted number its float's own name (it was 0.81 of this
  * bound, over 56,951 values that differed, while rigc emitted six decimals) —
  * so the corpus sits inside a bound that was not drawn around it, and no
@@ -1552,7 +1975,11 @@ const VALUE_MEASURES: ReadonlyArray<{ id: string; what: string; prefix: string }
   { id: 'values.bones', what: 'every bone setup pose, its length and its colour', prefix: 'bones/' },
   { id: 'values.slots', what: 'every slot colour, dark colour, blend mode and setup attachment', prefix: 'slots/' },
   { id: 'values.attachments', what: 'every attachment offset, size, vertex, weight, uv and triangle', prefix: 'skins/' },
-  { id: 'values.constraints', what: 'every constraint pose field and flag', prefix: 'constraints/' },
+  {
+    id: 'values.constraints',
+    what: 'every constraint field the parser reads: pose, flags, offsets, and the property map and its kinds',
+    prefix: 'constraints/',
+  },
   { id: 'values.events', what: 'every event payload in the setup pose', prefix: 'events/' },
   { id: 'values.key_times', what: 'every key time, and each animation\'s duration', prefix: 'animations/' },
   { id: 'values.key_values', what: 'every keyed value: poses, deform vertices, draw orders, event payloads', prefix: 'animations/' },

package/src/png.ts

@@ -154,11 +154,14 @@ function whatItIs(buf: Uint8Array): string {
  * decode PNG …: unexpected end of file`, and reached `build --atlas-in` as a
  * stack trace — three sentences about one file, and none said what it was.
  *
- * It says three things and decodes nothing: what the file is instead (by the
+ * It says four things and decodes nothing: what the file is instead (by the
  * signature it does carry, with its first bytes in hex either way), whether a
- * file that begins as a PNG ends before its chunks do, and whether IHDR comes
- * first. The chunk walk reads only the eight-byte chunk headers, so it costs a
- * skip through the file and no inflate.
+ * file that begins as a PNG ends before its chunks do, whether IHDR comes
+ * first, and whether IHDR states a size of at least 1x1 (issue #1073). The
+ * chunk walk reads only the eight-byte chunk headers, so it costs a skip
+ * through the file and no inflate — which is also why it cannot say whether
+ * the image data decodes: that is `imageDataProblem` in
+ * [`tools/plate.ts`](../tools/plate.ts), beside the decoder (issue #1074).
  *
  * ⚠️ **"Truncated" is judged by the chunk walk, not by a length floor.** The
  * floor that stood here (`buf.length < 26`, "too short") never said truncated,
@@ -208,6 +211,28 @@ export function pngProblem(buf: Uint8Array, path: string): string | null {
         `its ${type} chunk at byte ${at} declares ${length} byte(s) of data, which with its CRC runs to byte ${next}`,
       );
     }
+    if (type === 'IHDR') {
+      // 🔒 **A dimension of 0 is a file that describes no texel** (issue
+      // #1073), and the format says so: IHDR's width and height are each at
+      // least 1. Accepted here, such a page was read as a valid PNG of the
+      // wrong size — A06 printed its grid sentence over a ratio of 0.0000, A19
+      // a "not measured" line once per region on the page (13 on one export),
+      // the compiler took the 0 as a loose part's size and was refused by A03
+      // and A10 (`non-positive size`, `x NaN`) or by the mesher (`bad part
+      // size 0x150`) without the file named, and `render` drew it in silence.
+      // Refused here, it is one fact about one file, said by the one reader
+      // every other reader asks first.
+      const width = view.getUint32(at + 8);
+      const height = view.getUint32(at + 12);
+      if (width === 0 || height === 0) {
+        const zero = width === 0 && height === 0 ? 'its width and its height are' : width === 0 ? 'its width is' : 'its height is';
+        return (
+          `${path} is a PNG whose IHDR chunk states its size as ${width}x${height}: ${zero} 0, where the format ` +
+          'requires each dimension to be at least 1, so the file describes no texel and nothing in it can be ' +
+          'measured or drawn. Re-export it'
+        );
+      }
+    }
     if (type === 'IEND') return null;
     previous = `its ${type} chunk at byte ${at}`;
     at = next;
@@ -216,9 +241,11 @@ export function pngProblem(buf: Uint8Array, path: string): string | null {
 
 /**
  * A file that is not a PNG rigc can read, thrown by the readers that return a
- * value or nothing (`readPngInfo`, `readPlate`). The message is `pngProblem`'s,
- * whole; a caller that owns a named failure — the gate, a `CompileError` —
- * reads the sentence instead of catching the throw (`readPngHeader`).
+ * value or nothing (`readPngInfo`, `readPlate`). The message is `pngProblem`'s
+ * — or, from `readPlate`, `imageDataProblem`'s for a file whose header reads
+ * and whose image data does not decode (issue #1074) — whole; a caller that
+ * owns a named failure — the gate, a `CompileError` — reads the sentence
+ * instead of catching the throw (`readPngHeader`).
  */
 export class NotAPngError extends Error {
   readonly path: string;

package/src/spine_side.ts

@@ -63,6 +63,21 @@ export const SURVEY_RUNTIME_TAIL =
  */
 export const SPINE_SIDE_ABSENT = 'the runtime side is not installed in this entry, which links nothing of spine-core';
 
+/**
+ * What an entry that registered no Spine side adds after the tail: where the
+ * runtime is (issue #1079). On an install `bin/rigc.cjs` runs this entry
+ * wherever `@esotericsoftware/spine-core` does not resolve, so "the runtime is
+ * not linked" there means "it is not installed" — and a clone runs it as
+ * `bun cli_core.ts`, so both routes are named, each for its reader.
+ *
+ * ⚠️ Only the absent side says it. A runtime that is linked and fails to load
+ * (`./render.ts`, `./deformmeasure.ts`) is installed already, and "install it
+ * beside the package" would be the wrong sentence there.
+ */
+export const SPINE_SIDE_ROUTE =
+  'the entry that links it runs them — installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; ' +
+  'from a source checkout, `bun cli.ts`';
+
 /** The one sentence a run that needs the runtime and cannot use it is refused in — `tail` says what the runtime is for. */
 export function spineRuntimeSentence(label: string, why: string, reason: string, tail: string): string {
   return `${label} is posed through spine-core (${why}), and the runtime could not be used: ${reason}. ${tail}`;
@@ -107,13 +122,13 @@ export function registerSpineSurvey(side: SpineSurveySide): void {
 
 /** The posing side, or a refusal of `label` (needed for `why`) naming the runtime as absent. */
 export function spinePosingFor(label: string, why: string): SpinePosingSide {
-  if (posing === null) throw new SpineRuntimeError(spineRuntimeSentence(label, why, SPINE_SIDE_ABSENT, POSING_RUNTIME_TAIL));
+  if (posing === null) throw new SpineRuntimeError(spineRuntimeSentence(label, why, SPINE_SIDE_ABSENT, `${POSING_RUNTIME_TAIL}; ${SPINE_SIDE_ROUTE}`));
   return posing;
 }
 
 /** The survey side, or a refusal of `label` (needed for `why`) naming the runtime as absent. */
 export function spineSurveyFor(label: string, why: string): SpineSurveySide {
-  if (survey === null) throw new SpineRuntimeError(spineRuntimeSentence(label, why, SPINE_SIDE_ABSENT, SURVEY_RUNTIME_TAIL));
+  if (survey === null) throw new SpineRuntimeError(spineRuntimeSentence(label, why, SPINE_SIDE_ABSENT, `${SURVEY_RUNTIME_TAIL}; ${SPINE_SIDE_ROUTE}`));
   return survey;
 }