spine-rigc 0.29.0 → 0.30.0

package/src/compile.ts

@@ -19,7 +19,7 @@
  */
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
-import { readPngInfo } from './png.ts';
+import { readPngHeader, readPngInfo } from './png.ts';
 import {
   DEPTH_TONE_IDENTITY,
   DepthError,
@@ -95,7 +95,14 @@ import {
   type AtlasRegion,
   type ParsedAtlas,
 } from './atlas.ts';
-import { KEY_TIME_EPSILON, physicsKeyRefusal, physicsRuleFor, type PhysicsPoseRule } from './timelines.ts';
+import {
+  KEY_TIME_EPSILON,
+  physicsKeyRefusal,
+  physicsRuleFor,
+  SLOT_COLOR_CHANNELS,
+  type PhysicsPoseRule,
+  type SlotColorChannel,
+} from './timelines.ts';
 import { evaluateDeformTransform } from './deformgen.ts';
 import { evaluateTrackDerive, TRACK_DERIVE_PROJECTIONS, type TrackDeriveMember } from './trackgen.ts';
 import {
@@ -783,6 +790,60 @@ function rgba2Hex(v: number[]): { light: string; dark: string } {
   return { light: v.slice(0, 4).map(channelHex).join(''), dark: v.slice(4, 7).map(channelHex).join('') };
 }
 
+/** The five slot colour timelines, which are every `SLOT_TRACKS` shape but `attachment`. */
+type SlotColourShape = 'rgba' | 'rgb' | 'alpha' | 'rgba2' | 'rgb2';
+
+/**
+ * How one colour key is written, per timeline: how many channels its `v`
+ * carries, how the refusal spells that `v`, and the JSON fields the emitted key
+ * states them as.
+ *
+ * ⭐ **Every row is the parser's own reading, and the `v` is always the
+ * channels in the order `readCurve` indexes a curve array by** — which is what
+ * keeps a key and its raw curve parallel on every shape:
+ *
+ * - `rgba` → `color: "rrggbbaa"`, four channels (`RGBATimeline`, `frames << 2`).
+ * - `rgb` → `color: "rrggbb"`, three. `SkeletonJson`'s `rgb` branch reads the
+ *   same `Color.fromString(keyMap.color)` and hands `setFrame` r, g and b alone,
+ *   so an alpha pair written there would be read into a colour and dropped one
+ *   line later — six digits is emitting what is read.
+ * - `alpha` → `value: a`, one channel, read by `readTimeline1` with a per-key
+ *   default of **0**. It is a number rather than hex because the format stores
+ *   it as one, so it is not quantised onto a byte the way the four hex shapes
+ *   are.
+ * - `rgba2` → `light: "rrggbbaa"`, `dark: "rrggbb"`, seven (see `rgba2Hex`).
+ * - `rgb2` → `light: "rrggbb"`, `dark: "rrggbb"`, six: `RGB2Timeline.setFrame`
+ *   takes r g b and r2 g2 b2, and neither colour's alpha.
+ *
+ * The count is checked before anything is written, with one sentence for all
+ * five (`rgba value needs 4 channels, got 3`), because `rgbaHex` and `rgba2Hex`
+ * already said exactly that for their two and a family whose members refuse in
+ * different words is a family an author has to learn twice.
+ */
+const COLOUR_KEYS: Record<SlotColourShape, { channels: number; spelling: string; write: (v: number[]) => Record<string, string | number> }> = {
+  rgba: { channels: 4, spelling: '[r,g,b,a]', write: (v) => ({ color: rgbaHex(v) }) },
+  rgb: { channels: 3, spelling: '[r,g,b]', write: (v) => ({ color: v.map(channelHex).join('') }) },
+  alpha: { channels: 1, spelling: '[a]', write: (v) => ({ value: r6(v[0]) }) },
+  rgba2: { channels: 7, spelling: '[lr,lg,lb,la,dr,dg,db]', write: (v) => rgba2Hex(v) },
+  rgb2: {
+    channels: 6,
+    spelling: '[lr,lg,lb,dr,dg,db]',
+    write: (v) => ({ light: v.slice(0, 3).map(channelHex).join(''), dark: v.slice(3, 6).map(channelHex).join('') }),
+  },
+};
+
+/** The colour of one key, as its timeline writes it — after the channel count the whole family refuses in one sentence. */
+function colourKey(shape: SlotColourShape, v: number[]): Record<string, string | number> {
+  const { channels, write } = COLOUR_KEYS[shape];
+  if (v.length !== channels) {
+    throw new CompileError(`${shape} value needs ${channels} channel${channels === 1 ? '' : 's'}, got ${v.length}`);
+  }
+  return write(v);
+}
+
+/** A slot colour channel as a sentence names it. */
+const CHANNEL_WORDS: Record<SlotColorChannel, string> = { rgb: 'light rgb', alpha: 'alpha', dark: 'dark colour' };
+
 /**
  * One timeline a `MotionValueTrack` can name: the JSON fields a key carries, the
  * per-key default the parser uses for each, and — where the runtime has one — the
@@ -940,8 +1001,18 @@ const SLIDER_TRACKS: Record<string, ValueTrackShape> = {
  * ⚠️ The KEY is the timeline name as the file carries it, and the VALUE names
  * the branch below that writes its keys — so an entry added here without a
  * branch to write it is an entry emitted in some other timeline's shape, which
- * is the defect this table closed rather than a new affordance. The format has
- * three more (`rgb`, `alpha`, `rgb2`) and rigc emits none of them.
+ * is the defect this table closed rather than a new affordance.
+ *
+ * 🎨 `rgb`, `alpha` and `rgb2` joined in issue #730, which makes this the
+ * format's whole slot switch (`SkeletonJson.readAnimation`'s six cases, in its
+ * order). They are the SEPARABLE colour timelines — each poses a subset of the
+ * slot's channels and leaves the rest where they were (`SLOT_COLOR_CHANNELS`)
+ * — and they are not spellings of `rgba`. Folding an `rgb` and an `alpha` with
+ * their own key times into one `rgba` would have to state each channel at the
+ * other's key times, which is a value nobody keyed; and a lone `alpha` has no
+ * `rgba` spelling at all, because an `rgba` key poses the light rgb too. So
+ * each is emitted as itself, and two tracks of one slot that pose a shared
+ * channel are refused rather than layered (see the claim check in `compile`).
  *
  * 🎨 `rgba2` joined in issue #690, and what it adds is the half of the two-colour
  * tint that moves: a slot's `dark` has been an emitted setup field all along
@@ -952,10 +1023,13 @@ const SLIDER_TRACKS: Record<string, ValueTrackShape> = {
  * never applies it; `--profile spine-html` is where it fires. Emitting a
  * construct one consumer drops is exactly what a profile is for.
  */
-export const SLOT_TRACKS: Record<string, 'attachment' | 'rgba' | 'rgba2'> = {
+export const SLOT_TRACKS: Record<string, 'attachment' | SlotColourShape> = {
   attachment: 'attachment',
   rgba: 'rgba',
+  rgb: 'rgb',
+  alpha: 'alpha',
   rgba2: 'rgba2',
+  rgb2: 'rgb2',
 };
 
 /**
@@ -1068,8 +1142,14 @@ const CONSTRAINT_TIMELINES: Record<'ik' | 'transform', ConstraintTimelineShape>
   },
 };
 
-/** Physics constraint fields and their parser defaults (SkeletonJson.js:295-319). */
-const PHYSICS_COMPONENTS = ['x', 'y', 'rotate', 'scaleX', 'shearX'] as const;
+/**
+ * Physics constraint fields and their parser defaults (SkeletonJson.js:295-319).
+ *
+ * `PHYSICS_COMPONENTS` is exported for `ingest.ts`, which omits a constraint that
+ * drives none of them (issue #731) and must read "drives" off the same five
+ * names this module refuses an empty constraint with, not off a copy.
+ */
+export const PHYSICS_COMPONENTS = ['x', 'y', 'rotate', 'scaleX', 'shearX'] as const;
 const PHYSICS_PARAMS: Array<[string, number]> = [
   ['inertia', 0.5],
   ['strength', 100],
@@ -1404,7 +1484,12 @@ function fromLoosePng(
     // the rig. The validator's messages are the UI, and so are these.
     throw new CompileError(`image "${relPath}" is not on disk at ${absPath}`);
   }
-  const info = readPngInfo(absPath);
+  // A loose part IS a page of the atlas this route emits, so it is refused the
+  // way a pack's page is (issue #732): by the one reader's sentence, as a
+  // CompileError, rather than as that reader's throw with a stack under it.
+  const header = readPngHeader(absPath);
+  if (header.problem !== null) throw new CompileError(`image "${relPath}": ${header.problem}`);
+  const info = header.info;
   // Page name is the PNG path *relative to the atlas file*, so the viewer
   // resolves it the way every Spine consumer does: against the atlas URL.
   // The PNGs are not copied: they pass through untouched, and the atlas points
@@ -1436,6 +1521,25 @@ function readAtlasIn(path: string): AtlasSource {
     }
   }
   if (byName.size === 0) throw new CompileError(`--atlas-in ${path} declares no regions`);
+  // 🔒 **What each page IS, where the pack is opened** (issue #732). Every page
+  // the pack names reaches the gate — the atlas this build emits is the pack's
+  // own text — so a page no reader can open is refused here, all of them in
+  // one sentence, rather than one region at a time or at `A06` after the whole
+  // compile. A page that is not on disk is left to the region that sits on it,
+  // which already names it; saying so twice would be two refusals of one fact.
+  const unread: string[] = [];
+  for (const page of parsed.pages) {
+    const abs = resolve(dirname(path), page.name);
+    if (!existsSync(abs)) continue;
+    const { problem } = readPngHeader(abs);
+    if (problem !== null) unread.push(`page "${page.name}": ${problem}`);
+  }
+  if (unread.length > 0) {
+    throw new CompileError(
+      `--atlas-in ${path}: ${unread.length} of its ${parsed.pages.length} page(s) cannot be read as PNG, and ` +
+        `nothing was compiled against the pack — ${unread.join('; ')}`,
+    );
+  }
   return { path, dir: dirname(path), parsed, byName };
 }
 
@@ -2504,6 +2608,30 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
             );
           }
           claimed.add(claim);
+          // Two colour timelines of one slot that pose a shared channel are not
+          // two layers of it: each poses its channels at every time, the setup
+          // value before its first key included, so the one the file states
+          // later overwrites the other everywhere (`SLOT_COLOR_CHANNELS`). The
+          // claim above cannot see it — `rgba` and `alpha` are two properties —
+          // and before issue #730 nothing could reach it, because `rgba` and
+          // `rgba2` were the only two and a slot keying both was already a
+          // slot keying its light colour twice. Raised before any key is shaped:
+          // the fault is the pair, not a key.
+          if (family === null && !isBoneTrack) {
+            const mine = SLOT_COLOR_CHANNELS[track.property] ?? [];
+            for (const other of Object.keys(slotTimelines[target] ?? {})) {
+              const shared = (SLOT_COLOR_CHANNELS[other] ?? []).filter((channel) => mine.includes(channel));
+              if (shared.length === 0) continue;
+              throw new CompileError(
+                `animation "${animName}" slot "${target}": tracks "${other}" and "${track.property}" both key the slot's ` +
+                  `${shared.map((channel) => CHANNEL_WORDS[channel]).join(' and ')} — a colour timeline poses its ` +
+                  'channels at every time, its setup value before its first key included, so the one the file states ' +
+                  'later overwrites the other everywhere and the first one\'s keys there are read by nothing. Key each ' +
+                  'channel once: "rgb" and "alpha" move the light colour\'s two halves on their own key times, "rgba" ' +
+                  'moves them together, and "rgb2" / "rgba2" add the dark colour',
+              );
+            }
+          }
 
           const shift = (track.lag ?? 0) + (track.stagger ?? 0) * index;
           const keys =
@@ -7252,12 +7380,18 @@ function compileTrack(
   // …')` inside `RGBA2Timeline.apply1`. That is a crash in the consumer's
   // process, from a file every parser accepts — the exact silence this compiler
   // exists to convert into a name (issue #690).
-  if (shape === 'rgba2' && !darkSlots.has(target)) {
+  //
+  // `rgb2` is the same pairing and was measured the same way before it joined
+  // this refusal (issue #730): the forged file loads, `setupPose.darkColor` is
+  // `null`, and `state.apply` throws `TypeError: null is not an object
+  // (evaluating 'dark.r = …')` inside `RGB2Timeline.apply1`. The way out it
+  // names is its own light-only sibling, which for `rgb2` is `rgb`.
+  if ((shape === 'rgba2' || shape === 'rgb2') && !darkSlots.has(target)) {
     throw new CompileError(
-      `${where}: slot "${target}" declares no setup "dark", and an "rgba2" timeline poses a slot's dark colour — ` +
+      `${where}: slot "${target}" declares no setup "dark", and an "${shape}" timeline poses a slot's dark colour — ` +
         'the runtime allocates one only for a slot whose setup pose has it, so applying this animation throws ' +
         `instead of tinting. Give slot "${target}" a \`dark\` in the rig spec (the colour it holds at rest), or ` +
-        'key "rgba" if only the light colour moves',
+        `key "${shape === 'rgba2' ? 'rgba' : 'rgb'}" if only the light colour moves`,
     );
   }
   if (!track.keys.length) throw new CompileError(`${where}: no keys`);
@@ -7298,21 +7432,33 @@ function compileTrack(
       continue;
     }
 
-    // rgba / rgba2 — the two colour shapes `SLOT_TRACKS` names, and between them
-    // the only ways left to reach here: `attachment` returned above and a
-    // property the table does not carry was refused before any key was shaped.
+    // The five colour shapes `SLOT_TRACKS` names, and between them the only ways
+    // left to reach here: `attachment` returned above and a property the table
+    // does not carry was refused before any key was shaped.
     //
-    // ⚠️ The two differ in three places and nowhere else, so they are read out of
-    // `shape` rather than forked into two loops: how many channels a `v` carries,
-    // which FIELDS the emitted key spells them as (`color`, or `light` + `dark`),
-    // and therefore how long a raw curve array is. Everything else — the
-    // ease/curve exclusivity, the stepped case, the hold test, the last-key
-    // refusals — is one rule, and a second copy of it is a second thing to keep
-    // in step.
-    const spelling = shape === 'rgba2' ? '[lr,lg,lb,la,dr,dg,db]' : '[r,g,b,a]';
-    const channels = shape === 'rgba2' ? 7 : 4;
-    const colourOf = (v: number[]): Record<string, string> => (shape === 'rgba2' ? rgba2Hex(v) : { color: rgbaHex(v) });
+    // ⚠️ The five differ in three places and nowhere else, so they are read out
+    // of `COLOUR_KEYS` rather than forked into five loops: how many channels a
+    // `v` carries, which FIELDS the emitted key spells them as (`color`,
+    // `value`, or `light` + `dark`), and therefore how long a raw curve array
+    // is. Everything else — the ease/curve exclusivity, the stepped case, the
+    // hold test, the last-key refusals — is one rule, and a second copy of it is
+    // a second thing to keep in step.
+    const { spelling, channels } = COLOUR_KEYS[shape];
+    const colourOf = (v: number[]): Record<string, string | number> => colourKey(shape, v);
     if (!Array.isArray(key.v)) throw new CompileError(`${where}: ${shape} key value must be ${spelling}`);
+    if (shape === 'alpha' && key.v.length === 1 && !(Number.isFinite(key.v[0]) && key.v[0] >= 0 && key.v[0] <= 1)) {
+      // The one colour shape written as a number rather than a byte, so the one
+      // that is not clamped onto 0..1 by `channelHex` on the way out. The
+      // runtime clamps the POSED alpha (`AlphaTimeline.apply`: `color.a = a < 0
+      // ? 0 : a > 1 ? 1 : a`) but interpolates the stored value first, so a key
+      // of 1.5 reaches 1 at a different time from a key of 1 — a curve nobody
+      // keyed, from a value no pose ever holds. Refused rather than clamped:
+      // clamping is choosing the value.
+      throw new CompileError(
+        `${where}: key at t=${key.t} is ${String(key.v[0])}; an alpha is a number from 0 to 1 — the runtime clamps ` +
+          'the posed alpha to that range after interpolating, so a value outside it is one no pose ever holds',
+      );
+    }
     const entry: SpineTimelineKey = { time, ...colourOf(key.v) };
     if (key.ease !== undefined && key.curve !== undefined) {
       throw new CompileError(`${where}: a key carries both a named easing and a raw curve; pick one`);
@@ -7334,8 +7480,9 @@ function compileTrack(
         }
         const t2 = keyTime(next.t + shift);
         // 4 numbers per channel, in the format's own channel order — 16 for
-        // `rgba` (r g b a), 28 for `rgba2` (light r g b a, then dark r g b, which
-        // is the order `readCurve` indexes them in). Short arrays become NaN
+        // `rgba` (r g b a), 12 for `rgb`, 4 for `alpha`, 28 for `rgba2` (light r
+        // g b a, then dark r g b, which is the order `readCurve` indexes them in)
+        // and 24 for `rgb2`. Short arrays become NaN
         // curves with no error. The hold test reads the emitted hex rather than
         // the authored floats: two colours that quantise to one byte are one
         // colour in the file, and for `rgba2` that has to be true of BOTH — a key

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 -------------------------------------------------------------
@@ -1247,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 => {
@@ -1338,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) {
@@ -1413,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(', ')}`
+              : ''),
         );
       }
     }