spine-rigc 1.5.0 → 1.5.2

package/src/rig.ts

@@ -60,7 +60,8 @@
  * with no manifest at all declares them here.
  */
 import { CompileError, NotImplementedError } from './errors.ts';
-import { refuseUnknownKeys } from './keys.ts';
+import { dottedPath, refuseNumbersTheFileCannotCarry, refuseUnknownKeys, refuseValuesOfTheWrongType } from './keys.ts';
+import type { ShapeVisit, SpecValueType } from './keys.ts';
 
 export { CompileError, NotImplementedError };
 
@@ -1776,11 +1777,11 @@ function isObj(v: unknown): v is Record<string, unknown> {
  * Every key each shape of this format owns, keyed by the interface above that
  * declares it — the runtime shadow of the types, which TypeScript erases.
  *
- * 🔒 **Hand-written and mechanically held to the interfaces.** `KEY01` in
+ * 🔒 **Hand-written and mechanically held to the interfaces.** `CUR17` in
  * `selftest.ts` reads this file's own source, extracts each named interface's
  * field list and compares it to the entry here, so the pair cannot drift: adding
  * a field and forgetting this table is a red run, not a key an author cannot
- * write. `KEY02` closes the other direction — a key declared here and occurring
+ * write. `CUR18` closes the other direction — a key declared here and occurring
  * nowhere else in the tree is refused, which is exactly what `scaleYMode` was.
  *
  * ⚠️ `RigUnimplementedAttachment` is deliberately absent. It carries
@@ -1854,6 +1855,149 @@ export const RIG_KEYS = {
   RigSoftRegion: ['bone', 'mask'],
 } as const satisfies Record<string, readonly string[]>;
 
+/**
+ * The type every key of `RIG_KEYS` holds, shape by shape — what
+ * `refuseValuesOfTheWrongType` refuses a value against (issue #890).
+ *
+ * 🔒 **Beside the key table, and held equal to it twice.** `satisfies` over
+ * `RigTypeTable` makes a key typed here and absent there, or admitted there and
+ * untyped here, a type error; the selftest compares the two at runtime as well,
+ * and derives each checked type from the interface the row is named for, so a
+ * field declared `number` and typed `string` here is a red run rather than a
+ * refusal of correct work.
+ *
+ * Where an unchecked type (`object`, `enum`, `mixed` — see `SPEC_VALUE_TYPES`)
+ * is refused, and by what:
+ *
+ *   - the version tag `spec` — `parseRigSpec`, before anything else;
+ *   - `inherit` — `resolveBoneInherit`; `blend` — the slot loop
+ *     (`RIG_SLOT_BLEND`); `consumerDrivenMix[].type` — the invariants block;
+ *   - a constraint's `type` — `buildRigConstraint`; `scaleY` on ik, a path
+ *     constraint's three modes and a slider's `property` — the builder of that
+ *     constraint kind, each listing the names that exist;
+ *   - an attachment's `type` — the attachment reader; `depth.near` — the depth
+ *     map reader;
+ *   - `RigSegmentsGenerator.bones` (`mixed`: a name, a chain of names or a span)
+ *     — the segments generator, by index.
+ *
+ * 🚨 Measured when this table was written, three `enum` keys have **no** owner,
+ * and the table does not pretend otherwise: `boneIndexing` built green at `5`
+ * and at `"foo"` (on a weighted mesh too), `from.rotation` built green at `5`
+ * and at `"foo"` on an anchored bone, and a generator `kind` of `5` or `"foo"`
+ * threw a `TypeError` (*undefined is not an object (evaluating
+ * 'generator.size')*) rather than the mesh builder's refusal. Each is a closed
+ * set of names with nobody holding the name, which is a value refusal and not a
+ * type one, so it is not fixed here. `scaleY` on a physics constraint was not
+ * measured.
+ */
+type RigTypeTable = {
+  readonly [S in keyof typeof RIG_KEYS]: { readonly [K in (typeof RIG_KEYS)[S][number]]: SpecValueType };
+};
+
+export const RIG_TYPES = {
+  RigSpec: {
+    spec: 'enum', name: 'string', note: 'string', skeleton: 'object', images: 'string', bones: 'object[]', slots: 'object[]',
+    skins: 'map of object', constraints: 'object[]', events: 'map of object', invariants: 'object',
+  },
+  RigSkeletonHeader: {
+    x: 'number', y: 'number', width: 'number | null', height: 'number | null', fps: 'number', referenceScale: 'number',
+    images: 'string', audio: 'string | null',
+  },
+  RigBone: {
+    name: 'string', parent: 'string', length: 'number', x: 'number', y: 'number', rotation: 'number', scaleX: 'number',
+    scaleY: 'number', shearX: 'number', shearY: 'number', inherit: 'enum', skin: 'boolean', color: 'string', icon: 'string',
+    from: 'object',
+  },
+  RigBoneFrom: { anchor: 'string', slotWindow: 'string', meshCenter: 'string', rotation: 'enum' },
+  RigSlot: { name: 'string', bone: 'string', attachment: 'string | null', color: 'string', dark: 'string', blend: 'enum' },
+  RigEvent: { int: 'number', float: 'number', string: 'string', audio: 'string', volume: 'number', balance: 'number' },
+  RigInvariants: {
+    meshSlots: 'number', meshTriangles: 'number', axisBone: 'string', massBone: 'string', detached: 'object[]',
+    deformMayFold: 'object[]', editorRoundTrip: 'boolean', consumerDrivenMix: 'object[]', idleDrivesMeshes: 'object',
+  },
+  RigIdleDrivesMeshes: { why: 'string' },
+  RigDetachedRule: { bone: 'string', notUnder: 'string', why: 'string' },
+  RigDeformFoldExemption: { slot: 'string', why: 'string' },
+  RigConsumerDrivenMix: { constraint: 'string', type: 'enum', why: 'string' },
+  RigSkinEntry: {
+    attachments: 'map of object', bones: 'string[]', ik: 'string[]', transform: 'string[]', path: 'string[]',
+    physics: 'string[]', slider: 'string[]',
+  },
+  RigIkConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bones: 'string[]', target: 'string', scaleY: 'enum', mix: 'number',
+    softness: 'number', bendPositive: 'boolean', compress: 'boolean', stretch: 'boolean',
+  },
+  RigTransformConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bones: 'string[]', source: 'string', localSource: 'boolean',
+    localTarget: 'boolean', additive: 'boolean', clamp: 'boolean', properties: 'map of object',
+    rotation: 'number', x: 'number', y: 'number', scaleX: 'number', scaleY: 'number', shearY: 'number',
+    mixRotate: 'number', mixX: 'number', mixY: 'number', mixScaleX: 'number', mixScaleY: 'number', mixShearY: 'number',
+  },
+  RigPathConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bones: 'string[]', slot: 'string', positionMode: 'enum',
+    spacingMode: 'enum', rotateMode: 'enum', rotation: 'number', position: 'number', spacing: 'number',
+    mixRotate: 'number', mixX: 'number', mixY: 'number',
+  },
+  RigPhysicsConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bone: 'string', x: 'number', y: 'number', rotate: 'number',
+    scaleX: 'number', shearX: 'number', scaleY: 'enum', limit: 'number', fps: 'number', inertia: 'number',
+    strength: 'number', damping: 'number', mass: 'number', wind: 'number', gravity: 'number', mix: 'number',
+    inertiaGlobal: 'boolean', strengthGlobal: 'boolean', dampingGlobal: 'boolean', massGlobal: 'boolean',
+    windGlobal: 'boolean', gravityGlobal: 'boolean', mixGlobal: 'boolean',
+  },
+  RigSliderConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', animation: 'string', mix: 'number', additive: 'boolean',
+    loop: 'boolean', bone: 'string', property: 'enum', from: 'number', to: 'number', scale: 'number', max: 'number',
+    local: 'boolean', time: 'number',
+  },
+  RigTransformProperty: { offset: 'number', to: 'map of object' },
+  RigTransformTo: { offset: 'number', max: 'number', scale: 'number' },
+  RigRegionAttachment: {
+    type: 'enum', name: 'string', path: 'string', image: 'string', x: 'number', y: 'number', rotation: 'number',
+    scaleX: 'number', scaleY: 'number', width: 'number', height: 'number', color: 'string', sequence: 'object',
+  },
+  RigMeshAttachment: {
+    type: 'enum', name: 'string', path: 'string', image: 'string', uvs: 'number[]', triangles: 'number[]',
+    vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', hull: 'number', edges: 'number[]',
+    width: 'number', height: 'number', color: 'string', generator: 'object', sequence: 'object',
+  },
+  RigLinkedMeshAttachment: {
+    type: 'enum', name: 'string', path: 'string', image: 'string', source: 'string', slot: 'string', skin: 'string',
+    timelines: 'boolean', width: 'number', height: 'number', color: 'string', sequence: 'object',
+    uvs: 'number[]', triangles: 'number[]', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum',
+    hull: 'number', edges: 'number[]', generator: 'object',
+  },
+  RigMeshBinding: { bone: 'string', x: 'number', y: 'number', weight: 'number' },
+  RigSequence: { count: 'number', start: 'number', digits: 'number', setup: 'number' },
+  RigBoundingBoxAttachment: {
+    vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
+  },
+  RigClippingAttachment: {
+    vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
+    end: 'string', convex: 'boolean', inverse: 'boolean',
+  },
+  RigPathAttachment: {
+    vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
+    closed: 'boolean', constantSpeed: 'boolean', lengths: 'number[]',
+  },
+  RigRingGenerator: {
+    kind: 'enum', hull: 'number[][]', center: 'number[]', inner: 'number', size: 'number[]', bias: 'object',
+    controls: 'string[]',
+  },
+  RigRibbonGenerator: { kind: 'enum', size: 'number[]', rows: 'number', chain: 'string[]' },
+  RigContourGenerator: {
+    kind: 'enum', tolerance: 'number', margin: 'number', maxVertices: 'number', alpha: 'number', depth: 'object',
+    soft: 'object',
+  },
+  RigGridGenerator: { kind: 'enum', us: 'number[]', vs: 'number[]', cols: 'number', rows: 'number', depth: 'object', soft: 'object' },
+  RigSegmentsGenerator: { kind: 'enum', cell: 'number', bones: 'mixed', falloff: 'object', alpha: 'number', anchor: 'number[]' },
+  RigSegmentsFalloff: { power: 'number', radius: 'number', maxBones: 'number', minWeight: 'number' },
+  RigSegmentSpan: { bone: 'string', from: 'number[]', to: 'number[]' },
+  RigMeshBias: { axis_deg: 'number', ramp: 'number[]' },
+  RigDepthMap: { image: 'string', near: 'enum', zScale: 'number', gamma: 'number', contrast: 'number', bias: 'number' },
+  RigSoftRegion: { bone: 'string', mask: 'string' },
+} as const satisfies RigTypeTable;
+
 /**
  * The five constraint `type` names, and the shape each one's keys come from.
  *
@@ -1925,6 +2069,10 @@ function checkRigSequence(att: Record<string, unknown>, who: string, where: stri
   const whole = (field: string, min: number): void => {
     const value = seq[field];
     if (value === undefined) return;
+    // A number the file cannot carry is `refuseNumbersTheFileCannotCarry`'s,
+    // one sentence for the whole family. This check runs inside the key scan,
+    // before that walk, and printed a stated 1e309 as `null` (issue #881).
+    if (typeof value === 'number' && !Number.isFinite(Math.fround(value))) return;
     if (typeof value !== 'number' || !Number.isInteger(value) || value < min) {
       throw new CompileError(
         `${where}: ${at}.${field} is ${JSON.stringify(value) ?? String(value)}; it is a whole number` +
@@ -1946,7 +2094,7 @@ function checkRigSequence(att: Record<string, unknown>, who: string, where: stri
   whole('digits', 0);
   whole('setup', 0);
   const count = seq.count as number;
-  if (typeof seq.setup === 'number' && seq.setup >= count) {
+  if (typeof seq.setup === 'number' && Number.isFinite(Math.fround(seq.setup)) && Number.isFinite(Math.fround(count)) && seq.setup >= count) {
     throw new CompileError(
       `${where}: ${at}.setup is ${seq.setup}, and a ${count}-frame series has frames 0 to ${count - 1}. ` +
         '`Sequence.resolveIndex` clamps an index at or past the end to the LAST frame (measured: `setup: 7` on ' +
@@ -1980,22 +2128,25 @@ function checkRigSequence(att: Record<string, unknown>, who: string, where: stri
  * refusal, and naming its keys would be a second opinion on a fault already
  * reported (see the note at the head of `parseMotionSpec`).
  */
-function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
-  const at = (node: unknown, shape: keyof typeof RIG_KEYS, what: string): void => {
-    if (isObj(node)) refuseUnknownKeys(node, RIG_KEYS[shape], where, what);
+function checkRigSpecKeys(raw: Record<string, unknown>, where: string): Array<{ node: Record<string, unknown>; shape: keyof typeof RIG_KEYS; path: Array<string | number> }> {
+  const visits: Array<{ node: Record<string, unknown>; shape: keyof typeof RIG_KEYS; path: Array<string | number> }> = [];
+  const at = (node: unknown, shape: keyof typeof RIG_KEYS, what: string, path: Array<string | number>): void => {
+    if (!isObj(node)) return;
+    refuseUnknownKeys(node, RIG_KEYS[shape], where, what);
+    visits.push({ node, shape, path });
   };
 
-  at(raw, 'RigSpec', 'this rig spec');
-  at(raw.skeleton, 'RigSkeletonHeader', '"skeleton"');
+  at(raw, 'RigSpec', 'this rig spec', []);
+  at(raw.skeleton, 'RigSkeletonHeader', '"skeleton"', ['skeleton']);
 
   for (const [i, bone] of (Array.isArray(raw.bones) ? raw.bones : []).entries()) {
     const who = isObj(bone) && typeof bone.name === 'string' ? `bone "${bone.name}"` : `bones[${i}]`;
-    at(bone, 'RigBone', who);
-    if (isObj(bone)) at(bone.from, 'RigBoneFrom', `${who}'s "from"`);
+    at(bone, 'RigBone', who, ['bones', i]);
+    if (isObj(bone)) at(bone.from, 'RigBoneFrom', `${who}'s "from"`, ['bones', i, 'from']);
   }
 
   for (const [i, slot] of (Array.isArray(raw.slots) ? raw.slots : []).entries()) {
-    at(slot, 'RigSlot', isObj(slot) && typeof slot.name === 'string' ? `slot "${slot.name}"` : `slots[${i}]`);
+    at(slot, 'RigSlot', isObj(slot) && typeof slot.name === 'string' ? `slot "${slot.name}"` : `slots[${i}]`, ['slots', i]);
   }
 
   for (const [i, constraint] of (Array.isArray(raw.constraints) ? raw.constraints : []).entries()) {
@@ -2006,32 +2157,32 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
     // that exist; there is no key set to check it against and no honest one to
     // guess, so it goes past here to the message that can say something.
     if (shape === undefined) continue;
-    at(constraint, shape, `${named} (${String(constraint.type)})`);
+    at(constraint, shape, `${named} (${String(constraint.type)})`, ['constraints', i]);
     for (const [from, entry] of Object.entries(isObj(constraint.properties) ? constraint.properties : {})) {
-      at(entry, 'RigTransformProperty', `${named} properties."${from}"`);
+      at(entry, 'RigTransformProperty', `${named} properties."${from}"`, ['constraints', i, 'properties', from]);
       if (!isObj(entry)) continue;
       for (const [to, driven] of Object.entries(isObj(entry.to) ? entry.to : {})) {
-        at(driven, 'RigTransformTo', `${named} properties."${from}".to."${to}"`);
+        at(driven, 'RigTransformTo', `${named} properties."${from}".to."${to}"`, ['constraints', i, 'properties', from, 'to', to]);
       }
     }
   }
 
   for (const [name, event] of Object.entries(isObj(raw.events) ? raw.events : {})) {
-    at(event, 'RigEvent', `event "${name}"`);
+    at(event, 'RigEvent', `event "${name}"`, ['events', name]);
   }
 
   if (isObj(raw.invariants)) {
-    at(raw.invariants, 'RigInvariants', '"invariants"');
+    at(raw.invariants, 'RigInvariants', '"invariants"', ['invariants']);
     for (const [i, rule] of (Array.isArray(raw.invariants.detached) ? raw.invariants.detached : []).entries()) {
-      at(rule, 'RigDetachedRule', `invariants.detached[${i}]`);
+      at(rule, 'RigDetachedRule', `invariants.detached[${i}]`, ['invariants', 'detached', i]);
     }
     for (const [i, rule] of (Array.isArray(raw.invariants.deformMayFold) ? raw.invariants.deformMayFold : []).entries()) {
-      at(rule, 'RigDeformFoldExemption', `invariants.deformMayFold[${i}]`);
+      at(rule, 'RigDeformFoldExemption', `invariants.deformMayFold[${i}]`, ['invariants', 'deformMayFold', i]);
     }
     for (const [i, rule] of (Array.isArray(raw.invariants.consumerDrivenMix) ? raw.invariants.consumerDrivenMix : []).entries()) {
-      at(rule, 'RigConsumerDrivenMix', `invariants.consumerDrivenMix[${i}]`);
+      at(rule, 'RigConsumerDrivenMix', `invariants.consumerDrivenMix[${i}]`, ['invariants', 'consumerDrivenMix', i]);
     }
-    at(raw.invariants.idleDrivesMeshes, 'RigIdleDrivesMeshes', 'invariants.idleDrivesMeshes');
+    at(raw.invariants.idleDrivesMeshes, 'RigIdleDrivesMeshes', 'invariants.idleDrivesMeshes', ['invariants', 'idleDrivesMeshes']);
   }
 
   for (const [skinName, skin] of Object.entries(isObj(raw.skins) ? raw.skins : {})) {
@@ -2040,6 +2191,10 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
     // likeliest cause (a slot left outside `attachments`), so it is reused
     // rather than restated — one refusal per fault.
     const parts = splitRigSkin(skin as RigSkin, `${where}: skin "${skinName}"`);
+    // The long form's own lists are typed too; `splitRigSkin` has just refused
+    // a key outside them, so the row's keys are the node's keys.
+    if (parts.explicit) visits.push({ node: skin, shape: 'RigSkinEntry', path: ['skins', skinName] });
+    const base: Array<string | number> = parts.explicit ? ['skins', skinName, 'attachments'] : ['skins', skinName];
     for (const [slot, placeholders] of Object.entries(parts.attachments)) {
       if (!isObj(placeholders)) continue;
       for (const [placeholder, att] of Object.entries(placeholders)) {
@@ -2071,14 +2226,15 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
               'series would be dropped in silence. Remove it, or put it on a region or a mesh.',
           );
         }
-        at(att, shape, `${who} (${type})`);
+        const here = [...base, slot, placeholder];
+        at(att, shape, `${who} (${type})`, here);
         if (att.sequence !== undefined) {
-          at(att.sequence, 'RigSequence', `${who} "sequence"`);
+          at(att.sequence, 'RigSequence', `${who} "sequence"`, [...here, 'sequence']);
           checkRigSequence(att, who, where);
         }
         for (const [i, vertex] of (Array.isArray(att.weights) ? att.weights : []).entries()) {
           for (const [j, binding] of (Array.isArray(vertex) ? vertex : []).entries()) {
-            at(binding, 'RigMeshBinding', `${who} weights[${i}][${j}]`);
+            at(binding, 'RigMeshBinding', `${who} weights[${i}][${j}]`, [...here, 'weights', i, j]);
           }
         }
         if (!isObj(att.generator)) continue;
@@ -2087,17 +2243,54 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
         // Same rule as an unknown attachment type: an unknown `kind` is the mesh
         // builder's refusal, which can name the four that exist.
         if (genShape === undefined) continue;
-        at(gen, genShape, `${who} generator (${String(gen.kind)})`);
-        at(gen.bias, 'RigMeshBias', `${who} generator.bias`);
-        at(gen.depth, 'RigDepthMap', `${who} generator.depth`);
-        at(gen.soft, 'RigSoftRegion', `${who} generator.soft`);
-        at(gen.falloff, 'RigSegmentsFalloff', `${who} generator.falloff`);
+        at(gen, genShape, `${who} generator (${String(gen.kind)})`, [...here, 'generator']);
+        at(gen.bias, 'RigMeshBias', `${who} generator.bias`, [...here, 'generator', 'bias']);
+        at(gen.depth, 'RigDepthMap', `${who} generator.depth`, [...here, 'generator', 'depth']);
+        at(gen.soft, 'RigSoftRegion', `${who} generator.soft`, [...here, 'generator', 'soft']);
+        at(gen.falloff, 'RigSegmentsFalloff', `${who} generator.falloff`, [...here, 'generator', 'falloff']);
         for (const [i, entry] of (Array.isArray(gen.bones) ? gen.bones : []).entries()) {
-          at(entry, 'RigSegmentSpan', `${who} generator.bones[${i}]`);
+          at(entry, 'RigSegmentSpan', `${who} generator.bones[${i}]`, [...here, 'generator', 'bones', i]);
         }
       }
     }
   }
+  return visits;
+}
+
+
+/**
+ * A rig-spec path in the words the other refusals in this file use for it:
+ * `bone "hip" x`, `constraint "aim" mixRotate`, `skin "default" slot "tail"
+ * attachment "tail" weights[0][1].x`, `event "step" float`. Anything else is
+ * the dotted path, which names every number exactly.
+ */
+function rigPlace(raw: Record<string, unknown>): (path: ReadonlyArray<string | number>) => string {
+  const named = (list: unknown, i: number, kind: string, plural: string): string => {
+    const node = Array.isArray(list) ? list[i] : undefined;
+    return isObj(node) && typeof node.name === 'string' ? `${kind} ${JSON.stringify(node.name)}` : `${plural}[${i}]`;
+  };
+  const rest = (path: ReadonlyArray<string | number>): string => {
+    const tail = dottedPath(path);
+    return tail === '' ? '' : ` ${tail}`;
+  };
+  return (path) => {
+    const [head, second] = path;
+    if (typeof second === 'number') {
+      if (head === 'bones') return `${named(raw.bones, second, 'bone', 'bones')}${rest(path.slice(2))}`;
+      if (head === 'slots') return `${named(raw.slots, second, 'slot', 'slots')}${rest(path.slice(2))}`;
+      if (head === 'constraints') return `${named(raw.constraints, second, 'constraint', 'constraints')}${rest(path.slice(2))}`;
+    }
+    if (head === 'events' && typeof second === 'string') return `event ${JSON.stringify(second)}${rest(path.slice(2))}`;
+    if (head === 'skins' && typeof second === 'string') {
+      const inner = path[2] === 'attachments' ? path.slice(3) : path.slice(2);
+      const [slot, attachment] = inner;
+      if (typeof slot === 'string' && typeof attachment === 'string') {
+        return `skin ${JSON.stringify(second)} slot ${JSON.stringify(slot)} attachment ${JSON.stringify(attachment)}${rest(inner.slice(2))}`;
+      }
+      return `skin ${JSON.stringify(second)}${rest(path.slice(2))}`;
+    }
+    return dottedPath(path);
+  };
 }
 
 /**
@@ -2136,7 +2329,24 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
   // compiler does not read" for a format it has never read at all. The three
   // throws directly below are the required-key checks, and each of them is the
   // consequence a typo at the root produces.
-  checkRigSpecKeys(raw, where);
+  const visits = checkRigSpecKeys(raw, where);
+  const place = rigPlace(raw);
+  // Every value the scan admitted, against the type its key holds, before any
+  // reader — here or in `compile` — has done arithmetic on it (issue #890).
+  // ⚠️ It runs ahead of this function's own field checks on purpose: those read
+  // values too, and a reader that meets a wrong type names the wrong fault —
+  // `constraint.skin === true` reads `"skin": "true"` as a constraint that asks
+  // for no skin. The price, measured, is three controls whose type half pinned an
+  // older sentence (RF86, PS177, PS189); their other halves are unchanged.
+  refuseValuesOfTheWrongType(
+    visits.map((v) => ({ node: v.node, shape: v.shape, name: (tail) => place([...v.path, ...tail]) })),
+    RIG_TYPES,
+    where,
+  );
+  // After the key check, so a misspelled key is named as a misspelling before
+  // its value is judged, and before every reader below, so no range rule or
+  // derived number ever meets a value the file cannot carry (issue #881).
+  refuseNumbersTheFileCannotCarry(raw, where, place);
 
   if (typeof raw.name !== 'string' || raw.name.length === 0) {
     throw new CompileError(`${where}: a rig spec needs a "name" — a motion spec names it to pick this rig`);

package/src/types.ts

@@ -17,6 +17,7 @@
 import type { AtlasRegion } from './atlas.ts';
 import type { DeformTransform, DeformTransformReport } from './deformgen.ts';
 import type { TurnCeiling } from './depth.ts';
+import type { SpecTypeRow } from './keys.ts';
 import type { MeshKind } from './mesh.ts';
 import type { TrackDerive, TrackDeriveReport } from './trackgen.ts';
 
@@ -169,6 +170,47 @@ export interface FaceManifest {
   anchors?: Record<string, number[]>;
 }
 
+/**
+ * The type every field of the cut manifest holds, shape by shape — what
+ * `refuseValuesOfTheWrongType` refuses a manifest value against (issue #890).
+ * The three interfaces above name three rows; the inline object types they
+ * declare (`crop`, `axis`, `stroke`, `roi`, `mesh.bias`) are rows named
+ * `<interface>.<field>`, and the selftest derives every row's keys and checked
+ * types from the declarations here.
+ *
+ * ⚠️ A manifest has no key scan, and this table does not add one: a manifest is
+ * often also the record of the pipeline that made the art and carries fields
+ * rigc does not read. A key outside a row is left alone, exactly as before; a
+ * key inside one must hold its type. Measured before the walk existed, 62 of 84
+ * wrong-typed plants on the three fixture manifests built green —
+ * `crop.h: "256"` among them — and 4 threw a TypeError from `node:path`.
+ *
+ * Unchecked: `mesh.kind` and `mesh.hull` (`enum`) — the manifest mesh reader;
+ * `crop` and the other nested shapes, `parts` and `mesh` (`object`) — the
+ * readers that walk them.
+ */
+export const MANIFEST_TYPES = {
+  FaceManifest: {
+    schema: 'string', crop: 'object', base: 'string', state_machine: 'map of string[]', parts: 'object[]',
+    insertion: 'number[]', axis: 'object', stroke: 'object', roi: 'object', anchors: 'map of number[]',
+  },
+  'FaceManifest.crop': { x: 'number', y: 'number', w: 'number', h: 'number', resample: 'string' },
+  'FaceManifest.axis': { deg: 'number', unit: 'number[]' },
+  'FaceManifest.stroke': {
+    amplitude: 'number', extension: 'number', contact_depth: 'number | null', cap_containment_ceiling: 'number | null',
+  },
+  'FaceManifest.roi': { x: 'number', y: 'number', w: 'number', h: 'number' },
+  FaceManifestPart: {
+    slot: 'string', rig_slot: 'string', draw_order: 'number', image: 'string | null', offset: 'number[]', size: 'number[]',
+    state_key: 'string', states: 'map of string | null', polygon: 'number[][]', mesh: 'object',
+  },
+  FaceManifestMesh: {
+    kind: 'enum', hull: 'enum', center: 'number[]', inner: 'number', control_bone: 'string', control_bones: 'string[]',
+    rows: 'number', chain: 'string[]', bias: 'object',
+  },
+  'FaceManifestMesh.bias': { axis_deg: 'number', ramp: 'number[]', note: 'string' },
+} as const satisfies Record<string, SpecTypeRow>;
+
 // ---------------------------------------------------------------------------
 // Motion spec  (spec: "rigc-motion/1")
 // ---------------------------------------------------------------------------

package/src/validate.ts

@@ -82,6 +82,7 @@ import {
   type SpineGeneration,
 } from './generation.ts';
 import { colourTypeName, readPngHeader } from './png.ts';
+import { nonFiniteOfPosed } from './render.ts';
 import { BONE_INHERIT_KNOWN } from './rig.ts';
 import {
   CHANNELS_BY_KIND,
@@ -4400,6 +4401,26 @@ export function validate(input: ValidateInput): ValidateReport {
       }
       if (unresolved > 0) return;
 
+      // -- the whole world transform, at the setup pose and every stepped frame
+      //
+      // 🚨 Read through `nonFiniteOfPosed`, the scan `render` refuses on, and
+      // not a second opinion of it (issue #882). This loop read `worldX` and
+      // `worldY` alone until then, and a bone at `rotation: 1e309` — in its setup
+      // pose or as a `rotate` key — poses a finite position over a NaN `a`, `b`,
+      // `c` and `d` whenever it has no child offset from it: measured on every
+      // leaf bone of the three generated probes, 20 of 20 green through the whole
+      // gate, and `render` then refused the same file by the bone. So the gate
+      // said the skeleton was fine and the renderer said it was not, which is two
+      // definitions of one word. The scan reads the six terms of every bone, then
+      // the vertices of every region and mesh shown — because a bone can be
+      // finite over a vertex that is not (a `scaleX` chain whose product stays
+      // under the largest double while every corner of the child's region
+      // passes it) — and names the bone or the vertex, the term and the frame.
+      //
+      // ⚠️ The setup pose is its own surface and is read as such: every frame
+      // below is posed AFTER `state.apply`, so a bone the animation keys from
+      // t=0 never shows its setup value to the loop, and a runtime that shows
+      // the rig at rest does show it.
       for (const anim of data.animations) {
         const skeleton = new Skeleton(data);
         const state = new AnimationState(new AnimationStateData(data));
@@ -4407,18 +4428,27 @@ export function validate(input: ValidateInput): ValidateReport {
         skeleton.setupPose();
         skeleton.update(0);
         skeleton.updateWorldTransform(Physics.reset);
+        const atSetup = nonFiniteOfPosed('the setup pose', skeleton);
+        if (atSetup !== null) {
+          fail('A10_NO_NAN_AFTER_STEPPING', atSetup);
+          return;
+        }
         const step = Math.max(anim.duration, 1) / STEP_FRAMES;
         for (let i = 0; i < STEP_FRAMES; i++) {
           state.update(step);
           state.apply(skeleton);
           skeleton.update(step);
           skeleton.updateWorldTransform(Physics.update);
+          const found = nonFiniteOfPosed(
+            `animation ${JSON.stringify(anim.name)} frame ${i + 1} of ${STEP_FRAMES} (t=${((i + 1) * step).toFixed(4)}s)`,
+            skeleton,
+          );
+          if (found !== null) {
+            fail('A10_NO_NAN_AFTER_STEPPING', found);
+            return;
+          }
           for (const bone of skeleton.bones) {
             const pose = bone.appliedPose;
-            if (!Number.isFinite(pose.worldX) || !Number.isFinite(pose.worldY)) {
-              fail('A10_NO_NAN_AFTER_STEPPING', `${anim.name}: bone "${bone.data.name}" world is (${pose.worldX}, ${pose.worldY})`);
-              return;
-            }
             // The setup half of the clause above: a bone's own `inherit` goes
             // through the same lookup, and a miss there loads `undefined` into
             // the setup pose, which every frame copies. Only reachable on a