spine-rigc 0.28.0 → 0.30.0

package/src/ingest.ts

@@ -44,7 +44,7 @@
  * break `A18_DETERMINISTIC_EMIT` the first time anybody rebuilt from an ingested
  * spec.
  */
-import { SLOT_TRACKS as EMITTED_SLOT_TRACKS, SPINE_VERSION } from './compile.ts';
+import { PHYSICS_COMPONENTS, SLOT_TRACKS as EMITTED_SLOT_TRACKS, SPINE_VERSION } from './compile.ts';
 import { CompileError } from './errors.ts';
 import { CHANNELS_BY_KIND } from './timelines.ts';
 import {
@@ -292,6 +292,47 @@ const CONSTRAINT_FIELDS: Record<string, string[]> = {
   slider: carried('RigSliderConstraint', 'name', 'type'),
 };
 
+/**
+ * The physics constraints that drive nothing, by name, each with the component
+ * fields it DOES state — every one of them at most 0 (issue #731).
+ *
+ * 🔑 The runtime's own predicate, not a reading of it: `PhysicsConstraint.update`
+ * decides what it applies with `this.data.x > 0` and its four siblings
+ * (`PhysicsConstraint.js:112`) and nothing else, so a constraint with none of
+ * `PHYSICS_COMPONENTS` above 0 moves no bone. `build` refuses exactly that shape
+ * by name — `A23_PHYSICS_CONSTRAINT_EFFECTIVE` at the gate — so carrying one
+ * through made the decompiled spec of a file an editor exports unbuildable as a
+ * whole, over a constraint that did nothing in it.
+ *
+ * ⚠️ A component that is present and NOT a number is not inert: the parser takes
+ * it as written and `"0.5" > 0` is true in the runtime's comparison, so such a
+ * constraint is carried and rigc's own parser says what is wrong with it.
+ */
+function inertPhysics(root: JsonObject): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const raw of arr(root.constraints)) {
+    const constraint = obj(raw);
+    if (constraint.type !== 'physics' || typeof constraint.name !== 'string') continue;
+    const stated = PHYSICS_COMPONENTS.filter((field) => constraint[field] !== undefined);
+    if (!stated.every((field) => typeof constraint[field] === 'number' && !((constraint[field] as number) > 0))) continue;
+    out.set(
+      constraint.name,
+      stated.map((field) => `${field} ${String(constraint[field])}`),
+    );
+  }
+  return out;
+}
+
+/** What omitting one inert physics constraint took with it, for its finding. */
+interface PhysicsOmission {
+  /** `animation "<a>" <timeline>`, in file order. */
+  timelines: string[];
+  /** The skins whose `physics` member list named it. */
+  skins: string[];
+  /** Per animation, the latest key time on an omitted timeline of this constraint. */
+  lastKeys: Map<string, number>;
+}
+
 /**
  * The per-skin member lists (`SkeletonJson` reads them before `attachments`).
  *
@@ -446,8 +487,11 @@ const SLOT_TRACKS = Object.keys(EMITTED_SLOT_TRACKS);
 
 /**
  * The slot timelines the FORMAT has and the motion spec has no track for —
- * `rgb`, `alpha` and `rgb2` as this is written, and whatever is left the next
- * time the spec grows one.
+ * **none** since issue #730 spelled `rgb`, `alpha` and `rgb2`, which were the
+ * last three. It stays derived rather than deleted, because an empty
+ * difference of two tables is a measurement and a deleted one is a claim: the
+ * day the format grows a seventh slot timeline, this is where it appears, and
+ * the blocker's sentence names it without an edit.
  *
  * ⭐ Both sides are derived, and that is the whole reason it exists rather than
  * being spelled into the blocker's sentence. `docs/INGEST.md`'s row for this
@@ -588,6 +632,19 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
   // declares no stage; when it does, this is the one place that changes.
   const rigHeader = ingestHeader(obj(root.skeleton), opts, note);
 
+  // -- physics constraints that drive nothing (issue #731) ------------------
+  // Read before the skins, because a skin's `physics` member list is one of the
+  // three places such a constraint is named and each has to let go of it.
+  const inert = inertPhysics(root);
+  const omissions = new Map<string, PhysicsOmission>();
+  const omission = (name: string): PhysicsOmission => {
+    const found = omissions.get(name);
+    if (found !== undefined) return found;
+    const made: PhysicsOmission = { timelines: [], skins: [], lastKeys: new Map() };
+    omissions.set(name, made);
+    return made;
+  };
+
   // -- bones ----------------------------------------------------------------
   // Inverts `buildBone`, which copies every declared field and omits the rest.
   const bones = arr(root.bones).map((raw) => {
@@ -645,7 +702,17 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
     let anyList = false;
     for (const list of SKIN_LISTS) {
       if (entry[list] !== undefined) {
-        lists[list] = entry[list];
+        let members = entry[list];
+        if (list === 'physics' && Array.isArray(members)) {
+          const named = members.filter((member): member is string => typeof member === 'string' && inert.has(member));
+          for (const member of named) omission(member).skins.push(nameOf(entry));
+          members = members.filter((member) => !(typeof member === 'string' && inert.has(member)));
+          // A list that named nothing BUT omitted constraints goes with them: an
+          // empty list and an absent one read the same, and only one of them is
+          // what the rebuild writes for a skin with no physics member.
+          if (named.length > 0 && (members as unknown[]).length === 0) continue;
+        }
+        lists[list] = members;
         anyList = true;
       }
     }
@@ -669,6 +736,9 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
       note('blocker', 'CONSTRAINT_TYPE', who, `type ${JSON.stringify(constraint.type)} is not one of ${Object.keys(CONSTRAINT_FIELDS).join(', ')}`);
       continue;
     }
+    // Omitted rather than carried, and said below once the timelines it takes
+    // with it are known (`PHYSICS_DRIVES_NOTHING`).
+    if (type === 'physics' && typeof constraint.name === 'string' && inert.has(constraint.name)) continue;
     const out: JsonObject = { name: constraint.name, type };
     for (const field of fields) if (constraint[field] !== undefined) out[field] = constraint[field];
     for (const key of Object.keys(constraint)) {
@@ -681,7 +751,43 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
   // -- animations -----------------------------------------------------------
   const animations: JsonObject = {};
   for (const [animName, raw] of objEntries(root.animations)) {
-    animations[animName] = ingestAnimation(animName, raw, root, note);
+    animations[animName] = ingestAnimation(animName, raw, root, note, inert, (name, property, lastKey) => {
+      const one = omission(name);
+      one.timelines.push(`animation "${animName}" ${property}`);
+      one.lastKeys.set(animName, Math.max(one.lastKeys.get(animName) ?? 0, lastKey));
+    });
+  }
+
+  // One finding per inert constraint, in the file's own order, naming what went
+  // with it. ⚠️ An animation's duration is the largest key time it has LEFT, so
+  // an omitted timeline that held the last key shortens the rebuilt animation —
+  // the one place this omission is not a no-op, and the detail says so there.
+  for (const [name, stated] of inert) {
+    const gone = omission(name);
+    const shortened = [...gone.lastKeys]
+      .map(([animName, lastKey]) => [animName, lastKey, Number(obj(animations[animName]).duration)] as const)
+      .filter(([, lastKey, duration]) => lastKey > duration)
+      .map(
+        ([animName, lastKey, duration]) =>
+          `animation "${animName}" had its last key at ${lastKey}s on one of them, so the rebuilt animation ends at ${duration}s`,
+      );
+    note(
+      'lossy',
+      'PHYSICS_DRIVES_NOTHING',
+      `constraint "${name}" (physics)`,
+      `drives no component: ${PHYSICS_COMPONENTS.join(', ')} are ` +
+        (stated.length ? `absent or at most 0 (it states ${stated.join(', ')})` : 'all absent') +
+        ', and `PhysicsConstraint.update` applies one only above 0, so it moves no bone and `build` would refuse it ' +
+        'by name (A23_PHYSICS_CONSTRAINT_EFFECTIVE). The rig spec omits it' +
+        (gone.timelines.length
+          ? `, and with it the ${gone.timelines.length} timeline(s) keyed to it, which would name a constraint the ` +
+            `rebuild does not have: ${gone.timelines.join('; ')}`
+          : '; no timeline keys it') +
+        (gone.skins.length ? `; it is taken off the physics list of skin(s) ${gone.skins.map((skin) => `"${skin}"`).join(', ')}` : '') +
+        (shortened.length
+          ? `. One thing does move, because a duration is the last key an animation has left: ${shortened.join('; ')}`
+          : '. The rebuild differs from the source by exactly these no-ops'),
+    );
   }
 
   // -- assemble -------------------------------------------------------------
@@ -1053,6 +1159,53 @@ function ingestAttachment(
   const type = att.type === undefined ? 'region' : String(att.type);
   const out: JsonObject = {};
 
+  // A LINKED mesh, in either of the format's two spellings. The test is the
+  // parser's own — one branch for `mesh` and `linkedmesh`, and a truthy `source`
+  // decides (`SkeletonJson.js:568-569`, `:582`) — so `type: "mesh"` carrying
+  // `source` inverts to a link, and a `linkedmesh` with none does NOT: that map
+  // is read as an ordinary mesh, whose `uvs` it does not have, and the parser
+  // throws on it. Reading the second as a link would be this module inventing a
+  // 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.
+  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;
+
   // `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 the contest survives the round trip the same name comes
@@ -1063,17 +1216,34 @@ function ingestAttachment(
       '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)',
+        'writes no name on the rebuild — it composes "<skin>/<placeholder>" only for a contested placeholder (#541). ' +
+        (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
+              ? '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'),
     );
   }
 
   /** 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 `path ?? placeholder` reproduces
-    // the same `path` decision AND the same atlas region name.
-    if (opts.art === 'loose') out.image = `${att.path === undefined ? placeholder : String(att.path)}.png`;
+    // 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`;
     if (att.width !== undefined) out.width = att.width;
     if (att.height !== undefined) out.height = att.height;
   };
@@ -1094,15 +1264,6 @@ function ingestAttachment(
 
   const vertexCount = typeof att.vertexCount === 'number' ? att.vertexCount : undefined;
 
-  // A LINKED mesh, in either of the format's two spellings. The test is the
-  // parser's own — one branch for `mesh` and `linkedmesh`, and a truthy `source`
-  // decides (`SkeletonJson.js:568-569`, `:582`) — so `type: "mesh"` carrying
-  // `source` inverts to a link, and a `linkedmesh` with none does NOT: that map
-  // is read as an ordinary mesh, whose `uvs` it does not have, and the parser
-  // throws on it. Reading the second as a link would be this module inventing a
-  // construct the file does not contain (issue #691).
-  const linked = (type === 'mesh' || type === 'linkedmesh') && typeof att.source === 'string' && att.source.length > 0;
-
   if (linked) {
     out.type = 'linkedmesh';
     carryArt();
@@ -1192,7 +1353,14 @@ function ingestAttachment(
 }
 
 /** One animation. Inverts step 5 of `compile()` — the whole timeline half. */
-function ingestAnimation(animName: string, anim: JsonObject, root: JsonObject, note: Note): JsonObject {
+function ingestAnimation(
+  animName: string,
+  anim: JsonObject,
+  root: JsonObject,
+  note: Note,
+  inert: ReadonlyMap<string, unknown>,
+  omitted: (constraint: string, property: string, lastKey: number) => void,
+): JsonObject {
   const tracks: JsonObject[] = [];
   let maxT = 0;
   const seeT = (t: number): void => {
@@ -1283,6 +1451,20 @@ function ingestAnimation(animName: string, anim: JsonObject, root: JsonObject, n
   const family = (group: 'path' | 'physics' | 'slider', shapes: Record<string, TrackShape>): void => {
     for (const [name, timelines] of objEntries(anim[group])) {
       for (const [property, keys] of arrEntries(timelines)) {
+        // A timeline keyed to a physics constraint `ingest` omitted (issue #731)
+        // goes with it: carried, it names a constraint the rebuilt rig has not
+        // got, and `build` refuses the whole motion spec over it. Its keys are
+        // not seen by `seeT` — they are not in the rebuild — and their latest
+        // time is handed back so the finding can say when that shortened one.
+        if (group === 'physics' && inert.has(name)) {
+          let lastKey = 0;
+          for (const raw of keys) {
+            const t = obj(raw).time;
+            if (typeof t === 'number' && t > lastKey) lastKey = t;
+          }
+          omitted(name, property, lastKey);
+          continue;
+        }
         const shape = shapes[property];
         const where = `animation "${animName}" ${group} "${name}" ${property}`;
         if (shape === undefined) {
@@ -1358,14 +1540,58 @@ function ingestAnimation(animName: string, anim: JsonObject, root: JsonObject, n
             return entry;
           }),
         });
+      } else if (property === 'alpha') {
+        // Inverts `compileTrack`'s alpha branch, whose key is `{time, value}` —
+        // the one colour shape the format stores as a number, read by
+        // `readTimeline1` with a per-key default of **0**. That is a value
+        // track's shape exactly, so it goes through the same inversion and
+        // inherits its two findings: an omitted `value` is written out at 0 and
+        // reported as `TIMELINE_KEY_RESTATED`, and a field the shape has no
+        // place for is a `TIMELINE_FIELD` blocker (issue #730).
+        valueTrack({ slot }, property, keys, [['value', 0]], where);
+      } else if (property === 'rgb' || property === 'rgb2') {
+        // Inverts `compileTrack`'s other two separable shapes (issue #730):
+        // `rgb` is `{time, color: "rrggbb"}` and `rgb2` is `{time, light:
+        // "rrggbb", dark: "rrggbb"}`, and the spec's `v` is their channels in
+        // `readCurve`'s order. Each keeps its own name and its own key times:
+        // folding an `rgb` and an `alpha` into one `rgba` would state each
+        // channel at the other's key times, a value nobody keyed.
+        tracks.push({
+          slot,
+          property,
+          keys: keys.map((raw) => {
+            const key = obj(raw);
+            const v =
+              property === 'rgb'
+                ? hexToRgb(String(key.color))
+                : [...hexToRgb(String(key.light)), ...hexToRgb(String(key.dark))];
+            const entry: JsonObject = { t: timeOf(key), v };
+            easing(key, entry);
+            return entry;
+          }),
+        });
       } else {
+        // 🔒 Composed from both tables, so it says the true thing whichever of
+        // two states it is reached in. A name the FORMAT has and the spec does
+        // not is the first; since issue #730 carried the last three there is no
+        // such name (`UNSPELT_SLOT_TRACKS` is empty), and what still reaches
+        // here is a name the format does not have at all — which
+        // `SkeletonJson.readAnimation` throws on (`Invalid timeline type for a
+        // slot`), so the sentence says so instead of printing an empty
+        // "remaining" list about a file no runtime loads.
+        const inFormat = property in CHANNELS_BY_KIND.slot;
         note(
           'blocker',
           'SLOT_TIMELINE',
           where,
-          `timeline "${property}" is in the format and the motion spec has no track for it — a slot track is ` +
-            `${SLOT_TRACKS.join(' or ')} and nothing else, so the rebuild plays nothing here. The format's ` +
-            `remaining slot timelines are ${UNSPELT_SLOT_TRACKS.join(', ')}`,
+          (inFormat
+            ? `timeline "${property}" is in the format and the motion spec has no track for it`
+            : `timeline "${property}" is not a slot timeline the format has — the runtime's reader throws ` +
+              '"Invalid timeline type for a slot" on it, so no player loads this file') +
+            ` — a slot track is ${SLOT_TRACKS.join(' or ')} and nothing else, so the rebuild plays nothing here` +
+            (UNSPELT_SLOT_TRACKS.length > 0
+              ? `. The format's remaining slot timelines are ${UNSPELT_SLOT_TRACKS.join(', ')}`
+              : ''),
         );
       }
     }

package/src/png.ts

@@ -89,15 +89,170 @@ function scanForTrns(buf: Buffer): boolean {
   return false;
 }
 
-export function readPngInfo(path: string): PngInfo {
-  const buf = readFileSync(path);
-  if (buf.length < 26) throw new Error(`not a PNG (too short): ${path}`);
-  for (let i = 0; i < SIGNATURE.length; i++) {
-    if (buf[i] !== SIGNATURE[i]) throw new Error(`not a PNG (bad signature): ${path}`);
+function hexBytes(bytes: Uint8Array): string {
+  return [...bytes].map((b) => b.toString(16).toUpperCase().padStart(2, '0')).join(' ');
+}
+
+/** The signature every PNG begins with, as the messages below print it. */
+const PNG_SIGNATURE_HEX = hexBytes(Uint8Array.from(SIGNATURE));
+
+function startsWith(buf: Uint8Array, at: number, bytes: ReadonlyArray<number>): boolean {
+  if (buf.length < at + bytes.length) return false;
+  for (let i = 0; i < bytes.length; i++) if (buf[at + i] !== bytes[i]) return false;
+  return true;
+}
+
+const ascii = (text: string): number[] => [...text].map((c) => c.charCodeAt(0));
+
+/**
+ * The image formats a page file is found to be in instead, by their own
+ * signatures. Each entry is the format's fixed leading bytes and nothing
+ * inferred from them — rigc decodes none of these, so the one honest thing to
+ * say about such a file is what its first bytes are.
+ *
+ * ⭐ Named at all because a file's NAME is not evidence (issue #732): a
+ * production pack shipped WebP pages called `*.png`, and "bad signature" sent
+ * the author to look for corruption in a well-formed image of another format.
+ */
+const OTHER_FORMATS: ReadonlyArray<{ name: string; matches: (buf: Uint8Array) => boolean }> = [
+  // A RIFF container with the form type at byte 8. The first chunk's FourCC
+  // (`VP8 `, `VP8L`, `VP8X`) is printed beside it by `whatItIs`, never read.
+  { name: 'WebP', matches: (buf) => startsWith(buf, 0, ascii('RIFF')) && startsWith(buf, 8, ascii('WEBP')) },
+  { name: 'JPEG', matches: (buf) => startsWith(buf, 0, [0xff, 0xd8, 0xff]) },
+  { name: 'GIF', matches: (buf) => startsWith(buf, 0, ascii('GIF87a')) || startsWith(buf, 0, ascii('GIF89a')) },
+  { name: 'KTX', matches: (buf) => startsWith(buf, 0, [0xab, ...ascii('KTX 11'), 0xbb, 0x0d, 0x0a, 0x1a, 0x0a]) },
+  { name: 'KTX2', matches: (buf) => startsWith(buf, 0, [0xab, ...ascii('KTX 20'), 0xbb, 0x0d, 0x0a, 0x1a, 0x0a]) },
+];
+
+/** What a file that does not begin with the PNG signature is, as a phrase. */
+function whatItIs(buf: Uint8Array): string {
+  const found = OTHER_FORMATS.find((format) => format.matches(buf));
+  if (found === undefined) {
+    return (
+      'in no image format rigc recognises by its signature (it names ' +
+      `${OTHER_FORMATS.map((format) => format.name).join(', ')} when it meets them)`
+    );
+  }
+  if (found.name === 'WebP' && buf.length >= 16) {
+    const chunk = String.fromCharCode(buf[12], buf[13], buf[14], buf[15]);
+    return `a WebP image (a RIFF/WEBP container whose first chunk is ${JSON.stringify(chunk)})`;
   }
-  if (buf.toString('latin1', 12, 16) !== 'IHDR') {
-    throw new Error(`PNG does not start with IHDR: ${path}`);
+  return `a ${found.name} image`;
+}
+
+/**
+ * Why the bytes at `path` are not a PNG rigc can read, as one sentence — or
+ * `null` when they are.
+ *
+ * 🔒 **The one reader of a page file's identity** (issue #732). Every reader of
+ * a page goes through it: `readPngInfo` and `readPngHeader` below (the size
+ * `A06` judges, the alpha `A19` judges on a one-part page, the sizes the
+ * compiler takes from a loose part or a pack's page) and `readPlate` in
+ * [`tools/plate.ts`](../tools/plate.ts) (the renderer, `A19`'s scan of a shared
+ * page, the region lift and the packer). Before it, one WebP page reached the
+ * gate as `A06`'s `threw: not a PNG (bad signature)` and `A19`'s `threw: cannot
+ * 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
+ * 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.
+ *
+ * ⚠️ **"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,
+ * and a PNG cut anywhere after its IHDR passed it: measured on a packed page
+ * cut to 60 bytes, the default profile built it green and wrote a skeleton
+ * whose page no reader could decode. A PNG ends at its IEND chunk, so a file
+ * that runs out first is truncated wherever it runs out.
+ */
+export function pngProblem(buf: Uint8Array, path: string): string | null {
+  if (buf.length === 0) return `${path} is empty (0 bytes), and a PNG's first 8 bytes are ${PNG_SIGNATURE_HEX}`;
+  if (!startsWith(buf, 0, SIGNATURE.slice(0, Math.min(buf.length, SIGNATURE.length)))) {
+    const shown = buf.subarray(0, 12);
+    const byName = /\.png$/i.test(path) ? '; its name ends in .png, and it is the bytes that decide what a file is' : '';
+    return (
+      `${path} is ${whatItIs(buf)}, not a PNG: its first ${shown.length} byte(s) are ${hexBytes(shown)}, where a ` +
+      `PNG's first 8 are ${PNG_SIGNATURE_HEX}${byName}. rigc reads PNG and nothing else — its page-size and alpha ` +
+      'readers, its renderer and its region lift all decode PNG, and it links no decoder for any other format — ' +
+      'so nothing in this file was measured. Re-export it as PNG'
+    );
   }
+  const truncated = (where: string): string =>
+    `${path} is a truncated PNG: it is ${buf.length} byte(s) long and ${where}, so no reader can decode it. ` +
+    'Re-export or re-copy the file whole';
+  if (buf.length < SIGNATURE.length) return truncated(`ends ${buf.length} byte(s) into the 8-byte PNG signature`);
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  let at = SIGNATURE.length;
+  let previous = 'the signature';
+  for (;;) {
+    if (at + 8 > buf.length) {
+      return truncated(
+        at === buf.length
+          ? `ends after ${previous} with no IEND chunk`
+          : `ends ${buf.length - at} byte(s) into the header of the chunk after ${previous}`,
+      );
+    }
+    const length = view.getUint32(at);
+    const type = String.fromCharCode(buf[at + 4], buf[at + 5], buf[at + 6], buf[at + 7]);
+    if (at === SIGNATURE.length && type !== 'IHDR') {
+      return `${path} is a PNG whose first chunk is ${JSON.stringify(type)} rather than the IHDR the format requires first`;
+    }
+    if (type === 'IHDR' && length !== 13) {
+      return `${path} is a PNG whose IHDR chunk declares ${length} byte(s) of data, where the format's is 13`;
+    }
+    const next = at + 12 + length; // 4 length + 4 type + body + 4 CRC
+    if (next > buf.length) {
+      return truncated(
+        `its ${type} chunk at byte ${at} declares ${length} byte(s) of data, which with its CRC runs to byte ${next}`,
+      );
+    }
+    if (type === 'IEND') return null;
+    previous = `its ${type} chunk at byte ${at}`;
+    at = next;
+  }
+}
+
+/**
+ * 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`).
+ */
+export class NotAPngError extends Error {
+  readonly path: string;
+  constructor(path: string, message: string) {
+    super(message);
+    this.name = 'NotAPngError';
+    this.path = path;
+  }
+}
+
+/** `pngProblem` as a refusal, for the readers that return a value or throw. */
+export function assertPng(buf: Uint8Array, path: string): void {
+  const problem = pngProblem(buf, path);
+  if (problem !== null) throw new NotAPngError(path, problem);
+}
+
+/**
+ * A page's header, or the sentence that says why it has none — for a caller
+ * whose failures are named rather than thrown.
+ */
+export function readPngHeader(path: string): { info: PngInfo; problem: null } | { info: null; problem: string } {
+  const buf = readFileSync(path);
+  const problem = pngProblem(buf, path);
+  return problem === null ? { info: headerOf(buf), problem: null } : { info: null, problem };
+}
+
+export function readPngInfo(path: string): PngInfo {
+  const buf = readFileSync(path);
+  assertPng(buf, path);
+  return headerOf(buf);
+}
+
+/** The IHDR fields of a file `pngProblem` has already accepted. */
+function headerOf(buf: Buffer): PngInfo {
   const colourType = buf.readUInt8(25);
   const hasAlpha = COLOUR_TYPE_HAS_ALPHA[colourType] ?? false;
   // A file with an alpha channel cannot also carry tRNS, so the scan is skipped

package/src/rig.ts

@@ -1934,8 +1934,35 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
   // consumer's process, so they are refused here where the message can name the
   // rig spec. What the parser does NOT check is the pairing with `skin: true`,
   // and that half is silent in both directions (see `RigSkinEntry`).
-  const skinBoneUse = new Map<string, string>();
-  const skinConstraintUse = new Map<string, string>();
+  //
+  // ⭐ **Sets rather than "which skin owns this", because a name may be in
+  // several lists.** Until issue #725 these were `name -> the skin that claimed
+  // it first`, and a second skin naming the same bone or constraint was refused
+  // with *"a bone belongs to one skin"*. The rule was never the parser's and the
+  // comment above it said so; what it rested on was that "which skin am I for"
+  // has no answer for a name in two lists. It has one, and the runtime gives it:
+  // `Skeleton.updateCache` activates the bones of the skin being WORN, so a bone
+  // two mutually exclusive variants both list is active under either — measured
+  // on a hand-forged file the refusal used to prevent, `bone.active` true under
+  // each of the two skins, false under a third that lists nothing and false with
+  // no skin set. `Skin.addSkin` deduplicates by object identity, so even a
+  // consumer combining both variants gets the bone once. The format is a
+  // per-skin SET and rigc now says the same thing.
+  //
+  // ⚠️ **The worn skin, and only the worn skin.** `updateCache` reads
+  // `this.skin` and never `SkeletonData.defaultSkin` — the default-skin fallback
+  // is `getAttachment`'s and covers art alone — so a `skin: true` bone that only
+  // the `default` skin lists is measured INACTIVE under every other skin and
+  // with no skin set. That is why nothing here is a union, and it is the one
+  // shape an author is most likely to write expecting "always on".
+  //
+  // What the rule was really guarding — a second list that was meant to name a
+  // different bone — is not derivable from the file, so it is not refused. Every
+  // refusal that IS derivable stays: a name the rig does not declare, a name
+  // declared under another constraint kind, and both halves of the `skin: true`
+  // switch, each of which the rig suite now measures on a shared member.
+  const skinBoneUse = new Set<string>();
+  const skinConstraintUse = new Set<string>();
   if (spec.skins !== undefined) {
     if (!isObj(spec.skins)) throw new CompileError(`${where}: "skins" is an object keyed by skin name`);
     const collision = RIG_SKIN_KEYS.find((key) => slotNames.has(key));
@@ -1956,17 +1983,7 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
         if (!seen.has(bone)) {
           throw new CompileError(`${at} activates bone "${bone}", which this rig does not declare`);
         }
-        const previous = skinBoneUse.get(bone);
-        if (previous !== undefined && previous !== skinName) {
-          // Not a parser rule — a rig-spec one. `updateCache` activates the union
-          // of the current skin's bones, so a bone in two skins is a bone whose
-          // "which skin am I for" question has no answer, and the second list is
-          // usually a copy-paste that was meant to be a different bone.
-          throw new CompileError(
-            `${at} activates bone "${bone}", which skin "${previous}" already activates; a bone belongs to one skin`,
-          );
-        }
-        skinBoneUse.set(bone, skinName);
+        skinBoneUse.add(bone);
         const declared = spec.bones.find((b) => b.name === bone);
         if (declared?.skin !== true) {
           throw new CompileError(
@@ -1994,13 +2011,7 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
                 'a skin looks its constraints up by name AND type, so this one is a miss and the loader throws',
             );
           }
-          const previous = skinConstraintUse.get(constraintAt(type, name));
-          if (previous !== undefined && previous !== skinName) {
-            throw new CompileError(
-              `${at} activates ${type} constraint "${name}", which skin "${previous}" already activates; a constraint belongs to one skin`,
-            );
-          }
-          skinConstraintUse.set(constraintAt(type, name), skinName);
+          skinConstraintUse.add(constraintAt(type, name));
           if (!facts.skinRequired) {
             throw new CompileError(
               `${at} activates ${type} constraint "${name}", but that constraint does not declare \`"skin": true\`. ` +
@@ -2016,7 +2027,7 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
   // there is. Outside the block above on purpose — a rig with no `skins` at all
   // is the strongest case of it. A listed bone activates its ancestors too
   // (`Skeleton.ts:198-205`), so a parent reachable only that way is not dead.
-  const activated = new Set(skinBoneUse.keys());
+  const activated = new Set(skinBoneUse);
   const parentOf = new Map(spec.bones.map((b) => [b.name, b.parent]));
   for (const bone of [...activated]) {
     for (let cursor = parentOf.get(bone); cursor; cursor = parentOf.get(cursor)) activated.add(cursor);