spine-rigc 0.30.0 → 0.31.0

package/src/compile.ts

@@ -39,8 +39,9 @@ import { parseJsonWithPosition } from './json-position.ts';
 // of it — the same search serves `refuseUnknownKeys`, and a second copy here with
 // a threshold edited is how such a pair drifts apart.
 import { nearMisses } from './keys.ts';
-import { parseMotionSpec } from './motion.ts';
+import { EVERY_GLOBAL_PHYSICS, parseMotionSpec } from './motion.ts';
 import {
+  BONE_INHERIT_KNOWN,
   constraintAt,
   declaresNoStage,
   parseRigSpec,
@@ -50,6 +51,7 @@ import {
   RIG_PATH_SPACING_MODES,
   RIG_SCALE_Y_MODES,
   RIG_SKIN_CONSTRAINT_KEYS,
+  resolveBoneInherit,
   splitRigSkin,
   type RigAttachment,
   type RigBone,
@@ -89,6 +91,8 @@ import { Plate, readPlate } from '../tools/plate.ts';
 import {
   extractRegion,
   pageFootprint,
+  pageGridSaid,
+  pageGridSentence,
   parseAtlasText,
   rewritePageNames,
   writeAtlasText,
@@ -864,6 +868,17 @@ interface ValueTrackShape {
   fields: string[];
   identity: number[];
   bounds?: Array<PhysicsPoseRule | null>;
+  /**
+   * A timeline whose key holds one NAMED value instead of numbers — the JSON
+   * field it is written as, and the resolver that turns a spelling into the
+   * name the file carries (or `undefined` for one the runtime cannot resolve).
+   *
+   * ⚠️ Such a timeline is stepped by the format rather than by choice: its
+   * reader builds no curve at all, so an `ease` or a `curve` on its key would be
+   * accepted by the parser and never read. `compileValueTrack` refuses both.
+   * One entry has it — the bone's `inherit` (issue #733).
+   */
+  named?: { field: string; resolve: (value: unknown) => string | undefined; known: string };
 }
 
 /**
@@ -898,6 +913,12 @@ const BONE_TRACKS: Record<string, ValueTrackShape> = {
   shearx: { fields: ['value'], identity: [0] },
   sheary: { fields: ['value'], identity: [0] },
   rotate: { fields: ['value'], identity: [0] },
+  // The eleventh case of the runtime's bone switch, and the one that keys no
+  // number: `InheritTimeline` sets `pose.inherit` at the key and
+  // `updateWorldTransform` reads it that frame. Resolved by the SAME call the
+  // setup field is (`resolveBoneInherit`), so the five a key may name are the
+  // five a bone may rest in and a refusal prints the one list (issue #733).
+  inherit: { fields: [], identity: [], named: { field: 'inherit', resolve: resolveBoneInherit, known: BONE_INHERIT_KNOWN } },
 };
 
 /**
@@ -1505,6 +1526,11 @@ interface AtlasSource {
   parsed: ParsedAtlas;
   /** Trimmed region name -> the region, first occurrence wins (as `findRegion` does). */
   byName: Map<string, { region: AtlasRegion; page: ParsedAtlas['pages'][number] }>;
+  /**
+   * Page name -> what its file is against what the atlas declares, for every
+   * page on disk whose PNG is not the declared size, in page order (issue #750).
+   */
+  grids: Map<string, NonNullable<CompiledImage['pageGrid']>>;
 }
 
 function readAtlasIn(path: string): AtlasSource {
@@ -1527,12 +1553,28 @@ function readAtlasIn(path: string): AtlasSource {
   // 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.
+  //
+  // 📐 **What each page MEASURES, read in the same pass and not refused here**
+  // (issue #750). A page whose PNG is not the size the atlas declares is a
+  // file every runtime still draws — the region mapping is a fraction of the
+  // declared size — and the only readers it breaks are the ones that address
+  // it in texels. Refusing it here would refuse every pack that has one,
+  // including a pack of region attachments nothing reads a texel of, and on
+  // `build` it would replace `A06`'s verdict with a compile error for the same
+  // fact: `A06` already refuses the pack, names the ratio and prints the
+  // `scale:` repair, before anything is written. So the page is RECORDED, as
+  // `pageGridSentence` states it, and the readers that would take a figure off
+  // its texels decline to on the part that asks (`partTexels` below).
   const unread: string[] = [];
+  const grids: AtlasSource['grids'] = new Map();
   for (const page of parsed.pages) {
     const abs = resolve(dirname(path), page.name);
     if (!existsSync(abs)) continue;
-    const { problem } = readPngHeader(abs);
+    const { info, problem } = readPngHeader(abs);
     if (problem !== null) unread.push(`page "${page.name}": ${problem}`);
+    if (info === null) continue;
+    const sentence = pageGridSentence(page, info, page.regions);
+    if (sentence !== null) grids.set(page.name, { said: pageGridSaid(page, info), sentence });
   }
   if (unread.length > 0) {
     throw new CompileError(
@@ -1540,7 +1582,7 @@ function readAtlasIn(path: string): AtlasSource {
         `nothing was compiled against the pack — ${unread.join('; ')}`,
     );
   }
-  return { path, dir: dirname(path), parsed, byName };
+  return { path, dir: dirname(path), parsed, byName, grids };
 }
 
 /**
@@ -1634,6 +1676,7 @@ function resolveFromAtlas(
   const info = readPngInfo(absPath);
   const page = relative(outDir, absPath).split('\\').join('/');
   const scale = found.page.scale;
+  const grid = atlas.grids.get(found.page.name);
   return {
     region,
     page,
@@ -1647,6 +1690,7 @@ function resolveFromAtlas(
     isBase,
     atlas: found.region,
     ...(scale === 1 ? {} : { atlasScale: scale }),
+    ...(grid === undefined ? {} : { pageGrid: grid }),
   };
 }
 
@@ -2395,6 +2439,16 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   /** kind -> the names it declares, for the "the rig declares: …" half of one. */
   const constraintNamesOfKind = new Map<string, string[]>();
   const declareConstraint = (name: string, type: string): void => {
+    // Reserved, because a track's `"physics": "*"` is the timeline that names no
+    // constraint (issue #726): a physics constraint of that name is one no track
+    // could key by name without meaning every global one instead.
+    if (type === 'physics' && name === EVERY_GLOBAL_PHYSICS) {
+      throw new CompileError(
+        `physics constraint "${EVERY_GLOBAL_PHYSICS}": the name is reserved — a motion spec's \`"physics": ` +
+          `"${EVERY_GLOBAL_PHYSICS}"\` is the timeline that names no constraint and drives every physics constraint ` +
+          'declaring the keyed property global, so a constraint called that could not be keyed by name. Rename it',
+      );
+    }
     constraintDeclared.add(constraintAt(type, name));
     constraintKinds.set(name, [...(constraintKinds.get(name) ?? []), type]);
     constraintNamesOfKind.set(type, [...(constraintNamesOfKind.get(type) ?? []), name]);
@@ -2568,7 +2622,40 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         const perMember = resolveMemberTrack(track, animName, targets, bones, trackDerivations);
         targets.forEach((target, index) => {
           const resolved = perMember.get(target)!;
-          if (family !== null) {
+          // The timeline that names no constraint (issue #726). Resolved against
+          // the constraints' own `…Global` flags rather than a name, and refused
+          // when it reaches none — the runtime would walk every physics
+          // constraint, skip each one, and the file would parse and do nothing.
+          const everyGlobal = family === 'physics' && target === EVERY_GLOBAL_PHYSICS;
+          if (everyGlobal && track.physics === undefined) {
+            throw new CompileError(
+              `animation "${animName}": group "${String(track.group)}" lists "${EVERY_GLOBAL_PHYSICS}", which is not a ` +
+                `constraint but the target that names none — write it as the track's \`"physics": "${EVERY_GLOBAL_PHYSICS}"\``,
+            );
+          }
+          if (everyGlobal) {
+            const physics = constraints.filter((one) => one.type === 'physics');
+            const flag = `${track.property}Global`;
+            const reached =
+              track.property === 'reset'
+                ? physics
+                : physics.filter((one) => one[flag] === true);
+            if (reached.length === 0) {
+              throw new CompileError(
+                `animation "${animName}" keys physics "${EVERY_GLOBAL_PHYSICS}" ${track.property}, the timeline that ` +
+                  `names no constraint and drives every physics constraint ` +
+                  (track.property === 'reset' ? 'the rig has' : `declaring "${flag}": true`) +
+                  ', and ' +
+                  (physics.length === 0
+                    ? 'the rig declares no physics constraint'
+                    : `none of ${physics.map((one) => `"${one.name}"`).join(', ')} does`) +
+                  ' — it would parse and move nothing. ' +
+                  (track.property === 'reset'
+                    ? 'Declare a physics constraint, or remove the track'
+                    : `Set "${flag}": true on the constraints it is for, or key one by name`),
+              );
+            }
+          } else if (family !== null) {
             const label = CONSTRAINT_TRACK_FAMILIES[family].label;
             // Resolved by name AND by type in the parser
             // (`findConstraint(name, PathConstraintData)`), which returns null on
@@ -2650,7 +2737,8 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
                 ? compileValueTrack(resolved, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
                 : compileTrack(resolved, motion, animName, anim.duration, target, shift, attachmentIndex, darkSlots);
           for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
-          if (family !== null) (familyTimelines[family][target] ??= {})[track.property] = keys;
+          // Under the empty name, which is the file's own spelling of it.
+          if (family !== null) (familyTimelines[family][everyGlobal ? '' : target] ??= {})[track.property] = keys;
           else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
           else (slotTimelines[target] ??= {})[track.property] = keys;
         });
@@ -2887,6 +2975,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     skeletonText: `${JSON.stringify(skeleton, null, 2)}\n`,
     atlasText,
     images,
+    pageGrids: atlasIn === null ? [] : [...atlasIn.grids].map(([page, grid]) => ({ page, said: grid.said })),
     droppedStates,
     absentParts,
     declaredDurations,
@@ -3986,11 +4075,20 @@ function encodeNamedWeights(weights: RigMeshBinding[][], where: string, ctx: Att
  * what `extractRegion` does, so there is no unmeasurable case left for this
  * function to report and no catch here to keep reachable.
  */
-function measureAuthoredFit(att: RigMeshAttachment, ctx: AttachmentContext): MeshFitReport | null {
+function measureAuthoredFit(
+  att: RigMeshAttachment,
+  ctx: AttachmentContext,
+): MeshFitReport | { withheld: string } | null {
   if (att.image === undefined || att.uvs === undefined || att.triangles === undefined) return null;
   const region = basename(att.image, '.png');
   const img = ctx.images.find((im) => im.region === region);
   if (!img) return null;
+  // A third case, and neither of the two above (issue #750): there IS art to
+  // compare against, and its texels cannot be located, because its page's file
+  // is not the size the atlas declares. Withheld and said, rather than measured
+  // over whatever the declared coordinates land on — on a half-resolution pack
+  // that read 68.49% where the page it was packed from reads 100.00%.
+  if (img.pageGrid !== undefined) return { withheld: img.pageGrid.said };
   const plate = partPlate(img);
   const alpha = new Uint8Array(plate.width * plate.height);
   for (let i = 0; i < alpha.length; i++) alpha[i] = plate.data[i * 4 + 3];
@@ -4159,7 +4257,8 @@ function buildRigMesh(
   // read this and skip rather than measuring a ring that was never a ring.
   ctx.meshBones.add(ctx.anchorBone);
   for (const name of boundBones) ctx.meshBones.add(name);
-  const fit = measureAuthoredFit(att, ctx);
+  const measured = measureAuthoredFit(att, ctx);
+  const fit = measured === null || 'withheld' in measured ? null : measured;
   ctx.meshes.push({
     slot: ctx.slotName,
     kind: 'authored',
@@ -4169,6 +4268,7 @@ function buildRigMesh(
     bones: boundBones.length ? boundBones : [ctx.anchorBone],
     coverage: fit === null ? undefined : r6(fit.coverage),
     overshoot: fit?.overshoot,
+    ...(measured !== null && 'withheld' in measured ? { fitWithheld: measured.withheld } : {}),
   });
   return out;
 }
@@ -4526,8 +4626,13 @@ function sampleMeshDepth(
    *
    * The two are different questions and the header says why. This one has no
    * refusal behind it: it is counted, reported, and left to the author.
+   *
+   * `unlocated` in its place when the part's texels cannot be located — a
+   * region lifted off a page whose file is not its declared size (issue #750),
+   * carrying `pageGridSaid`'s clause — and the count is then `null` with that
+   * clause beside it: withheld, rather than taken off another part of the page.
    */
-  partAlpha: Uint8Array,
+  partAlpha: Uint8Array | { unlocated: string },
   partWidth: number,
   partHeight: number,
   where: string,
@@ -4587,7 +4692,7 @@ function sampleMeshDepth(
       // Zero, not a threshold: "the part image draws nothing here" is a fact
       // about the file, and any other cut-off would be rigc deciding how faint
       // a texel has to be before it stops counting as art.
-      if (partAlpha[at] === 0) drawn = false;
+      if (partAlpha instanceof Uint8Array && partAlpha[at] === 0) drawn = false;
     }
     if (!opaqueEverywhere && !covered) uncovered.push(v);
     if (!drawn) undrawn++;
@@ -4632,7 +4737,7 @@ function sampleMeshDepth(
       zScale: spec.zScale,
       tone,
       range: [r6(lo), r6(hi)],
-      undrawn,
+      ...(partAlpha instanceof Uint8Array ? { undrawn } : { undrawn: null, unlocated: partAlpha.unlocated }),
       ceiling: turnCeiling(
         points.map(([px, py]) => toBind(px, py)),
         z,
@@ -4870,7 +4975,11 @@ function buildGridAttachment(
           geometry.points,
           geometry.triangles,
           (px, py) => toBoneLocal(anchor, anchor.worldX + px * toArt - w / 2, anchor.worldY + h / 2 - py * toArt),
-          plateAlpha(plate),
+          // The lattice's geometry takes nothing off the texels — its window is
+          // the plate's size, which is the atlas's own `offsets` — so a page
+          // whose file is not its declared size costs a grid only this one
+          // count, and the count is what is withheld (issue #750).
+          img.pageGrid === undefined ? plateAlpha(plate) : { unlocated: img.pageGrid.said },
           plate.width,
           plate.height,
           where,
@@ -4959,6 +5068,24 @@ function buildContourAttachment(
     );
   }
   const img = atlasedImage(att.image, where, ctx);
+  // 🔒 **A trace needs the part's texels, and on a page that is not its
+  // declared size the lift does not have them** (issue #750). `extractRegion`
+  // addresses the page at the coordinates the atlas states; on a file of any
+  // other size those are a different part of the picture — measured on a
+  // half-resolution pack, the lift came back with no pixel above alpha 0 and
+  // the build refused with "there is no silhouette to trace", a true sentence
+  // about the wrong texels. Unlike an authored mesh's fit, which is a
+  // measurement and is withheld, this outline IS the geometry: there is no mesh
+  // to build without it, and the compiler invents none. So it is refused, with
+  // `A06`'s own sentence, which names the ratio and the repair — on `build`
+  // this refusal arrives before the gate, where `A06` would have said it.
+  if (img.pageGrid !== undefined) {
+    throw new CompileError(
+      `${where}: a "contour" generator traces the part's own alpha, and "${att.image}" is lifted off a packed ` +
+        'page at the coordinates the atlas states, which on this file are not where its texels are — so there is ' +
+        `no silhouette here to trace, only another part of the page. ${img.pageGrid.sentence}`,
+    );
+  }
   // ⚠️ Nothing here reads the PNG's colour type. `hasAlpha` answers "where does
   // this file keep its alpha", not "is any pixel of it transparent" — a tRNS
   // chunk is real transparency (issue #215) and an all-255 alpha channel is
@@ -5968,6 +6095,26 @@ function compileValueTrack(
       throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`);
     }
     checkKeyTime(where, time, key.t, duration);
+    // A named-value timeline (`inherit`): the key's `v` is one name, stepped by
+    // the format. The name is resolved rather than copied, and what is WRITTEN
+    // is the resolver's spelling — so `NoScale`, which the runtime also reads,
+    // emits as the `noScale` an editor writes, and a spelling the runtime
+    // cannot resolve never reaches the file at all.
+    if (shape.named !== undefined) {
+      if (key.ease !== undefined || key.curve !== undefined) {
+        throw new CompileError(
+          `${where} key at t=${key.t} carries ${key.ease !== undefined ? `an easing ("${key.ease}")` : 'a curve'}, and ` +
+            `this timeline is stepped by the format — its reader builds no curve, so the mode changes AT the key and ` +
+            'holds until the next one. Remove it',
+        );
+      }
+      const mode = shape.named.resolve(key.v);
+      if (mode === undefined) {
+        throw new CompileError(`${where} key at t=${key.t} names mode ${JSON.stringify(key.v)}; ${shape.named.known}`);
+      }
+      out.push({ time, [shape.named.field]: mode });
+      continue;
+    }
     // A no-field timeline (`reset`) is an event: the key IS the value, so it
     // carries none. Anything else must match the field count exactly.
     if (shape.fields.length === 0) {

package/src/ingest.ts

@@ -54,8 +54,8 @@ import {
   spineGeneration,
   TOPLEVEL_CONSTRAINT_ARRAYS,
 } from './generation.ts';
-import { MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
-import { parseRigSpec, RIG_KEYS, RIG_SPEC_VERSION, type RigSpec } from './rig.ts';
+import { EVERY_GLOBAL_PHYSICS, MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
+import { parseRigSpec, resolveBoneInherit, RIG_KEYS, RIG_SPEC_VERSION, type RigSpec } from './rig.ts';
 import type { MotionSpec } from './types.ts';
 
 /**
@@ -374,6 +374,18 @@ const BONE_TRACKS: Record<string, TrackShape> = {
   rotate: [['value', 0]],
 };
 
+/**
+ * The bone timeline whose key holds a NAME rather than numbers — `inherit`,
+ * `{ time, inherit }`, stepped by the format (its reader builds no curve). The
+ * field and the default `SkeletonJson`'s `inherit` branch reads where a key
+ * omits it: `getValue(aFrame, "inherit", "Normal")`, which the table spells
+ * `normal`. Inverts `compileValueTrack`'s named branch (issue #733).
+ */
+const INHERIT_TRACK = { property: 'inherit', field: 'inherit', dflt: 'normal' } as const;
+
+/** Every bone timeline the motion spec has a track for, in the order the refusal prints them. */
+const BONE_TRACK_NAMES = [...Object.keys(BONE_TRACKS), INHERIT_TRACK.property];
+
 /**
  * The eight physics timelines — `PHYSICS_TRACKS` in `compile.ts`, same order.
  * `reset` carries no value at all — `compileValueTrack`'s zero-field branch.
@@ -516,7 +528,7 @@ export const UNSPELT_SLOT_TRACKS = Object.keys(CHANNELS_BY_KIND.slot).filter((na
 export const INGEST_VOCABULARY = {
   attachments: ATTACHMENT_TYPES,
   constraints: Object.keys(CONSTRAINT_FIELDS),
-  boneTracks: Object.keys(BONE_TRACKS),
+  boneTracks: BONE_TRACK_NAMES,
   slotTracks: SLOT_TRACKS,
   path: Object.keys(PATH_TRACKS),
   physics: Object.keys(PHYSICS_TRACKS),
@@ -1448,6 +1460,16 @@ function ingestAnimation(
    * `lossy`, on the argument that the rebuilt skeleton plays identically — is
    * a decision about all three families and is not made here.
    */
+  /**
+   * The physics constraints the rebuild carries — every one the file declares
+   * but those `ingest` omits as inert — which is what an unnamed physics
+   * timeline can reach in it.
+   */
+  const carriedPhysics = arr(root.constraints)
+    .map(obj)
+    .filter((one) => one.type === 'physics' && !(typeof one.name === 'string' && inert.has(one.name)));
+  /** Unnamed physics timelines that reach nothing in the rebuild, said once the duration is known. */
+  const unreached: Array<{ property: string; lastKey: number }> = [];
   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)) {
@@ -1471,6 +1493,26 @@ function ingestAnimation(
           note('blocker', `${group.toUpperCase()}_TIMELINE`, where, `timeline "${property}" is not in the motion spec`);
           continue;
         }
+        // The empty name is the physics group's timeline that names no
+        // constraint (issue #726), which the motion spec spells `"*"`. It
+        // writes every carried constraint declaring the property global —
+        // `reset` every one — and one that reaches none is a no-op the rebuild
+        // would be refused over by name, so it goes, and is said, instead.
+        if (group === 'physics' && name === '') {
+          const reaches =
+            property === 'reset' ? carriedPhysics.length > 0 : carriedPhysics.some((one) => Boolean(one[`${property}Global`]));
+          if (!reaches) {
+            let lastKey = 0;
+            for (const raw of keys) {
+              const t = obj(raw).time;
+              if (typeof t === 'number' && t > lastKey) lastKey = t;
+            }
+            unreached.push({ property, lastKey });
+            continue;
+          }
+          valueTrack({ physics: EVERY_GLOBAL_PHYSICS }, property, keys, shape, where);
+          continue;
+        }
         valueTrack({ [group]: name }, property, keys, shape, where);
       }
     }
@@ -1480,12 +1522,46 @@ function ingestAnimation(
     for (const [property, keys] of arrEntries(timelines)) {
       const shape = BONE_TRACKS[property];
       const where = `animation "${animName}" bone "${bone}" ${property}`;
+      if (property === INHERIT_TRACK.property) {
+        // `{ time, inherit }` -> `{ t, v: mode }`. The mode is carried in the
+        // table's spelling, which is what `build` writes back; a key that omits
+        // it, or spells it with a capital the runtime also folds, is a key the
+        // rebuild states differently and is counted as such. A spelling the
+        // runtime cannot resolve at all is carried as written — the file plays
+        // no mode there, and `build` refuses it by name rather than guessing one.
+        let restated = 0;
+        const out = keys.map((raw) => {
+          const key = obj(raw);
+          const entry: JsonObject = { t: timeOf(key) };
+          const written = key[INHERIT_TRACK.field];
+          const mode = written === undefined ? INHERIT_TRACK.dflt : resolveBoneInherit(written);
+          if (mode !== written && mode !== undefined) restated++;
+          entry.v = mode ?? (written as JsonObject[string]);
+          for (const field of Object.keys(key)) {
+            if (field === 'time' || field === INHERIT_TRACK.field) continue;
+            note('blocker', 'TIMELINE_FIELD', where, `key field "${field}" is not part of this timeline's shape`);
+          }
+          return entry;
+        });
+        if (restated > 0) {
+          note(
+            'lossy',
+            'TIMELINE_KEY_RESTATED',
+            where,
+            `${restated} key(s) omit the mode or spell it with a capital first letter, and are written out as the ` +
+              `mode the runtime reads there (an omitted one is ${INHERIT_TRACK.dflt}) — the same mode, in the ` +
+              'spelling the editor writes',
+          );
+        }
+        tracks.push({ bone, property, keys: out });
+        continue;
+      }
       if (shape === undefined) {
         note(
           'blocker',
           'BONE_TIMELINE',
           where,
-          `timeline "${property}" has no track in the motion spec — a bone track is ${Object.keys(BONE_TRACKS).join(', ')} ` +
+          `timeline "${property}" has no track in the motion spec — a bone track is ${BONE_TRACK_NAMES.join(', ')} ` +
             'and nothing else, so the rebuild plays nothing here',
         );
         continue;
@@ -1667,6 +1743,26 @@ function ingestAnimation(
     });
   }
 
+  for (const { property, lastKey } of unreached) {
+    const flag = `${property}Global`;
+    note(
+      'lossy',
+      'PHYSICS_GLOBAL_REACHES_NOTHING',
+      `animation "${animName}" physics "" ${property}`,
+      'names no constraint, so the runtime writes it into every physics constraint ' +
+        (property === 'reset' ? 'the skeleton has' : `declaring "${flag}"`) +
+        ', and the rebuild carries ' +
+        (carriedPhysics.length === 0
+          ? 'no physics constraint'
+          : `none that does (${carriedPhysics.map((one) => `"${String(one.name)}"`).join(', ')})`) +
+        ` — it moves nothing, and \`build\` would refuse its \`"physics": "${EVERY_GLOBAL_PHYSICS}"\` track by name. ` +
+        'The motion spec omits it' +
+        (lastKey > maxT
+          ? `, and an animation's duration is the last key it has left, so the rebuilt animation ends at ${maxT}s rather than ${lastKey}s`
+          : '; the rebuild differs from the source by exactly this no-op'),
+    );
+  }
+
   for (const group of Object.keys(anim)) {
     if (ANIMATION_GROUPS.includes(group)) continue;
     note(

package/src/motion.ts

@@ -59,6 +59,24 @@ import type { MotionSpec } from './types.ts';
 
 export const MOTION_SPEC_VERSION = 'rigc-motion/1';
 
+/**
+ * A track's `physics` target for the timeline that names NO constraint (issue
+ * #726) — the one the runtime applies to every physics constraint whose own data
+ * declares the keyed property global (`"strengthGlobal": true` for `strength`,
+ * and so on; `reset` resets every physics constraint and asks no flag).
+ * `compile` emits it under the empty name, which is the skeleton file's own
+ * spelling of it (`SkeletonJson.js:1048-1054`).
+ *
+ * 🔑 Not the empty string itself, and that is the choice rather than a detail:
+ * `""` is the likeliest shape of a value somebody forgot to fill in, and a
+ * forgotten target that silently became "every global constraint" is the exact
+ * silence this format exists to name. So `"physics": ""` is refused by name and
+ * points here, and `"*"` is reserved the other way round: `compile` refuses a
+ * physics constraint that is CALLED `"*"`, because a track naming it could not
+ * say which of the two it meant.
+ */
+export const EVERY_GLOBAL_PHYSICS = '*';
+
 /**
  * The six fields that pick a track's target family. Listed here as well as in
  * `compile`'s `resolveTargets` because the two ask different questions of it:
@@ -292,7 +310,15 @@ function parsePhysics(raw: unknown, where: string): void {
   const table = needObj(raw, where, 'physics', 'it is a table keyed by constraint name, `{ "<name>": { "bone": … } }`');
   for (const [name, entry] of Object.entries(table)) {
     const key = `physics."${name}"`;
-    const spec = needObj(entry, where, key, 'a physics constraint is an object naming the bone it drives and the components it drives it in');
+    if (name === EVERY_GLOBAL_PHYSICS) {
+      throw new CompileError(
+        `${where}: \`${key}\` names a physics constraint "${EVERY_GLOBAL_PHYSICS}", and that name is reserved: a ` +
+          `track's \`"physics": "${EVERY_GLOBAL_PHYSICS}"\` is the timeline that names no constraint and drives ` +
+          'every one declaring the keyed property global, so a constraint called ' +
+          `"${EVERY_GLOBAL_PHYSICS}" could not be keyed by name. Give it another name`,
+      );
+    }
+    const spec = needObj(entry, where, key,'a physics constraint is an object naming the bone it drives and the components it drives it in');
     known(spec, 'MotionPhysics', where, key);
     needString(spec.bone, where, `${key}.bone`, 'a physics constraint drives one bone, named here');
     for (const field of PHYSICS_NUMBERS) {
@@ -378,6 +404,17 @@ function parseTracks(raw: unknown, where: string, at: string): void {
     for (const field of TARGET_FIELDS) {
       optString(track[field], where, `${key}.${field}`, `a track's "${field}" is the name of the ${field === 'slot' || field === 'bone' ? field : `${field} it targets`}`);
     }
+    if (track.physics === '') {
+      refuse(
+        where,
+        `${key}.physics`,
+        track.physics,
+        'the empty name is how a skeleton file spells a physics timeline that names no constraint, and a motion ' +
+          `spec spells that "${EVERY_GLOBAL_PHYSICS}" — it drives every physics constraint that declares the keyed ` +
+          'property global (`"strengthGlobal": true` for `strength`). Name one constraint, or write ' +
+          `"${EVERY_GLOBAL_PHYSICS}"`,
+      );
+    }
     optFinite(track.lag, where, `${key}.lag`, '"lag" is seconds added to every key time of this track, so a finite number — a string is CONCATENATED onto each time and a boolean adds 1');
     optFinite(track.stagger, where, `${key}.stagger`, '"stagger" is the extra per-member delay inside a group, in seconds, so a finite number');
     const keys = needArray(track.keys, where, `${key}.keys`, 'it is an array of `{ t, v }` keys');

package/src/rig.ts

@@ -162,6 +162,38 @@ export const RIG_BONE_INHERIT: readonly RigBoneInherit[] = [
   'noScaleOrReflection',
 ];
 
+/**
+ * The mode a spelling of `inherit` resolves to, in the table's own spelling —
+ * or `undefined` for one the runtime cannot resolve.
+ *
+ * ⭐ **One rule for both places the format spells a mode**: a bone's setup
+ * `inherit` and an `inherit` timeline key are read by the same call,
+ * `Utils.enumValue(Inherit, name)`, which is `Inherit[name[0].toUpperCase() +
+ * name.slice(1)]` — the FIRST letter is folded and nothing else. So `noScale`
+ * and `NoScale` resolve and `NOSCALE` or `noscale` do not, and a spelling that
+ * misses loads as `undefined`: the setup pose holds no mode at all and a
+ * timeline frame holds NaN, and in both cases `updateWorldTransform`'s switch
+ * matches no case and leaves the world matrix where it was. Nothing throws.
+ *
+ * 🚨 The setup check was **case-insensitive** until issue #733, which is wider
+ * than the runtime's rule by exactly that silence: `"inherit": "NOSCALE"`
+ * compiled, gated green on all 45 assertions, and loaded `setupPose.inherit ===
+ * undefined`. Measured, not argued — and a key read through the same wide rule
+ * would have shipped the same spelling into a timeline.
+ */
+export function resolveBoneInherit(value: unknown): RigBoneInherit | undefined {
+  if (typeof value !== 'string' || value.length === 0) return undefined;
+  const folded = value[0].toLowerCase() + value.slice(1);
+  return RIG_BONE_INHERIT.find((mode) => mode === folded);
+}
+
+/**
+ * The value REQUIRED, as both refusals of an unresolvable mode print it: the
+ * five, and the one liberty the runtime's lookup allows.
+ */
+export const BONE_INHERIT_KNOWN =
+  `known: ${RIG_BONE_INHERIT.join(', ')} — the runtime folds the case of the first letter and of nothing else`;
+
 /**
  * Take a bone's setup transform from the cut manifest rather than from a literal.
  *
@@ -1802,9 +1834,9 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
         `${where}: bone "${bone.name}" names parent ${JSON.stringify(bone.parent)}, which is not declared before it`,
       );
     }
-    if (bone.inherit !== undefined && !RIG_BONE_INHERIT.some((v) => v.toLowerCase() === String(bone.inherit).toLowerCase())) {
+    if (bone.inherit !== undefined && resolveBoneInherit(bone.inherit) === undefined) {
       throw new CompileError(
-        `${where}: bone "${bone.name}" has inherit ${JSON.stringify(bone.inherit)}; known: ${RIG_BONE_INHERIT.join(', ')}`,
+        `${where}: bone "${bone.name}" has inherit ${JSON.stringify(bone.inherit)}; ${BONE_INHERIT_KNOWN}`,
       );
     }
     const from = bone.from;