spine-rigc 0.22.2 → 0.24.0

package/src/render.ts

@@ -92,6 +92,7 @@ import {
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { Plate, readPlate, type RGBA } from '../tools/plate.ts';
+import { pageFootprint } from './atlas.ts';
 
 /** Opaque, and light: both of rung 3's parts are dark slate, so is every ground. */
 export const BACKGROUND: RGBA = [232, 232, 232, 255];
@@ -184,6 +185,19 @@ export interface FramesSidecar {
   example?: string;
   rung?: string;
   skeleton?: string;
+  /**
+   * The skin these frames were posed under, when one was asked for (issue #571).
+   *
+   * ⭐ **Absent is not `"default"`.** A render with no skin sets none — every
+   * slot resolves through `SkeletonData.defaultSkin` alone — and a frame set
+   * written before this field existed says nothing either, so the two are the
+   * same fact on disk and the field is omitted for both. That is what keeps
+   * every frame set in this repository byte-identical across this change, and it
+   * is why `check` can refuse a mismatch it can SEE (`skin` present and
+   * different, or present where the run asked for none) and can only NOTE the
+   * one it cannot (`skin` absent while the run asked for one).
+   */
+  skin?: string;
   /** The colour the frames were cleared to, straight RGBA 0..255. */
   background: RGBA;
   viewport: {
@@ -281,6 +295,71 @@ export interface PoseOptions {
    * one instrument that does (`bonedist.ts`) needs it on every frame.
    */
   bones?: boolean;
+  /**
+   * Pose under this skin, by the name the skeleton declares for it.
+   *
+   * ⭐ Absent means **no skin is set at all**, which is spine-core's own initial
+   * state (`Skeleton.skin` is null) and resolves every slot through
+   * `SkeletonData.defaultSkin` alone. That is not the same claim as "the default
+   * skin was chosen": it is the absence of a choice, and the two are spelled
+   * differently everywhere this travels — the frames sidecar omits the field
+   * rather than writing `"default"` into it (issue #571).
+   *
+   * ⚠️ Read by the SAMPLERS, never by `piecesOf`, which is handed a skeleton
+   * somebody else already posed; handing it one is refused by name rather than
+   * ignored, because a skin quietly dropped here is exactly the silence this
+   * whole flag exists to remove.
+   */
+  skin?: string;
+}
+
+/**
+ * A fresh skeleton with `skin` applied, or refused by name.
+ *
+ * ## Why the skin goes on before `setupPose`, and why nothing else is needed
+ *
+ * `Skeleton.setSkin` (spine-core 4.3.13 `Skeleton.js:279-311`) attaches the new
+ * skin's art into each slot's pose and calls `updateCache`, which is what turns
+ * on a `skinRequired` bone or constraint the skin names. Every sampler below
+ * then calls `skeleton.setupPose()`, and `setupPose` → `setupPoseSlots`
+ * (`Skeleton.js:231-249`) re-resolves each slot's setup attachment through
+ * `Slot.setupPose` → `Skeleton.getAttachment`, which checks `this.skin` first
+ * and `SkeletonData.defaultSkin` second (`Skeleton.js:335-346`). So the setup
+ * pose of a skinned skeleton is already the skin's, and the extra
+ * `setSlotsToSetupPose()` a 4.1-era recipe prescribes has no 4.3 spelling to
+ * call: the method is named `setupPoseSlots` here, and `setupPose()` runs it.
+ *
+ * `setSkin(string)` exists too, but its by-name half throws
+ * `Skin not found: <name>` (`Skeleton.js:286-291`) — a message that names the
+ * miss and not the alternatives. Everything in a rig resolves by name and a miss
+ * is refused **by name, with the names that would have worked**, so the lookup
+ * happens here and the runtime is handed a `Skin` it cannot fail on.
+ */
+function skeletonUnderSkin(data: SkeletonData, skin: string | undefined): Skeleton {
+  const skeleton = new Skeleton(data);
+  if (skin === undefined) return skeleton;
+  const found = data.findSkin(skin);
+  if (!found) {
+    throw new Error(
+      `no skin ${JSON.stringify(skin)} in this skeleton; it declares [${
+        data.skins.map((s) => s.name).join(', ') || 'none'
+      }]`,
+    );
+  }
+  skeleton.setSkin(found);
+  return skeleton;
+}
+
+/**
+ * The same options with the skin taken off — what the samplers hand `piecesOf`.
+ *
+ * Spelled once, so the one function that must not see a `skin` cannot come to
+ * see one because a second call site forgot.
+ */
+function piecesOptions(opts: PoseOptions | undefined): PoseOptions | undefined {
+  if (opts === undefined || opts.skin === undefined) return opts;
+  const { skin: _applied, ...rest } = opts;
+  return rest;
 }
 
 /**
@@ -460,7 +539,8 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
       `no animation "${name}" in this skeleton; it has [${data.animations.map((a) => a.name).join(', ') || 'none'}]`,
     );
   }
-  const skeleton = new Skeleton(data);
+  const skeleton = skeletonUnderSkin(data, opts?.skin);
+  const pieceOpts = piecesOptions(opts);
   const state = new AnimationState(new AnimationStateData(data));
   // Not looping: the last frame sits at the animation's duration, and a looping
   // entry would wrap it back onto the first pose.
@@ -484,7 +564,7 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
     frames.push({
       index: i,
       time: i * step,
-      pieces: piecesOf(skeleton, opts),
+      pieces: piecesOf(skeleton, pieceOpts),
       ...(opts?.bones ? { bones: boneSnapshots(skeleton) } : {}),
     });
   }
@@ -500,7 +580,7 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
  * whole content is the setup pose.
  */
 export function sampleSetupPose(data: SkeletonData, opts?: PoseOptions): Frame[] {
-  const skeleton = new Skeleton(data);
+  const skeleton = skeletonUnderSkin(data, opts?.skin);
   skeleton.setupPose();
   skeleton.update(0);
   skeleton.updateWorldTransform(Physics.reset);
@@ -508,7 +588,7 @@ export function sampleSetupPose(data: SkeletonData, opts?: PoseOptions): Frame[]
     {
       index: 0,
       time: 0,
-      pieces: piecesOf(skeleton, opts),
+      pieces: piecesOf(skeleton, piecesOptions(opts)),
       ...(opts?.bones ? { bones: boneSnapshots(skeleton) } : {}),
     },
   ];
@@ -519,10 +599,10 @@ export function sampleSetupPose(data: SkeletonData, opts?: PoseOptions): Frame[]
  * filed under. A skeleton with no animation at all contributes its setup pose
  * under `SETUP_POSE_DIR`.
  */
-export function sampleAll(data: SkeletonData, fps: number): Map<string, Frame[]> {
+export function sampleAll(data: SkeletonData, fps: number, opts?: PoseOptions): Map<string, Frame[]> {
   const out = new Map<string, Frame[]>();
-  if (data.animations.length === 0) out.set(SETUP_POSE_DIR, sampleSetupPose(data));
-  else for (const animation of data.animations) out.set(animation.name, sampleAnimation(data, animation.name, fps));
+  if (data.animations.length === 0) out.set(SETUP_POSE_DIR, sampleSetupPose(data, opts));
+  else for (const animation of data.animations) out.set(animation.name, sampleAnimation(data, animation.name, fps, opts));
   return out;
 }
 
@@ -537,6 +617,17 @@ export function sampleAll(data: SkeletonData, fps: number): Map<string, Frame[]>
  * of them draws a pixel.
  */
 export function piecesOf(skeleton: Skeleton, opts?: PoseOptions): Piece[] {
+  // A skin is chosen before a skeleton is posed, and this one is already posed —
+  // so there is nothing honest to do with the name except say so. Silently
+  // ignoring it is the shape of defect #571 itself: a skin asked for, no skin
+  // applied, and a picture that looks like an answer.
+  if (opts?.skin !== undefined) {
+    throw new Error(
+      `piecesOf was asked for skin ${JSON.stringify(opts.skin)}, and it reads a skeleton that is already posed. ` +
+        'Ask a sampler for it — sampleSetupPose/sampleAnimation/sampleAll take { skin } — or call ' +
+        'skeleton.setSkin(...) and skeleton.setupPose() before this.',
+    );
+  }
   const pieces: Piece[] = [];
   for (const slot of skeleton.drawOrder.appliedPose) {
     const pose = slot.appliedPose;
@@ -718,19 +809,20 @@ export function atlasScales(atlasText: string): number[] {
  * (The same gap is why `RegionAttachment.computeUVs` draws a 270-packed region
  * wrong, which is what `--atlas` was measuring on rung 7 — issue #199.)
  * `region.u/v` are always `x/pageWidth, y/pageHeight` and are used as they are; the
- * size is the region's own, transposed for a quarter turn, which is what the atlas
- * format means by `bounds` on a rotated region.
+ * size is `pageFootprint`'s, which is the region's own transposed for a quarter
+ * turn — what the atlas format means by `bounds` on a rotated region. That
+ * derivation was written out here, and in three other places that wanted the same
+ * rectangle; two of them had it wrong at 270 (issue #579), so it is one function
+ * now and this is one of its callers.
  */
 function windowOf(region: TextureAtlasRegion): UvWindow {
-  const turned = region.degrees === 90 || region.degrees === 270;
-  const rectWidth = turned ? region.height : region.width;
-  const rectHeight = turned ? region.width : region.height;
+  const rect = pageFootprint(region);
   const page = region.page;
   return {
     u0: region.x / page.width,
     v0: region.y / page.height,
-    u1: (region.x + rectWidth) / page.width,
-    v1: (region.y + rectHeight) / page.height,
+    u1: (region.x + rect.width) / page.width,
+    v1: (region.y + rect.height) / page.height,
   };
 }
 
@@ -970,11 +1062,15 @@ export function trimmedUnionBounds(
  * Measuring the box densely and once makes the framing a property of the SHOT,
  * so every rate of one skeleton lands on the same pixels.
  */
-export function framingViewport(data: SkeletonData, maxSide: number): Viewport | null {
+export function framingViewport(data: SkeletonData, maxSide: number, opts?: PoseOptions): Viewport | null {
+  // The skin belongs here as much as in the frames: the union box is over the
+  // attachments that POSE, and two skins fill a slot with art of different sizes
+  // in different places. Framing one skin's shot with another skin's box would
+  // put the difference between two skins into every measurement taken in it.
   const sets =
     data.animations.length === 0
-      ? [sampleSetupPose(data)]
-      : data.animations.map((a) => sampleAnimation(data, a.name, FRAMING_FPS));
+      ? [sampleSetupPose(data, opts)]
+      : data.animations.map((a) => sampleAnimation(data, a.name, FRAMING_FPS, opts));
   const box = unionBounds(sets);
   if (!Number.isFinite(box.minX)) return null;
   const pad = Math.max(box.maxX - box.minX, box.maxY - box.minY) * PAD;

package/src/rig.ts

@@ -80,6 +80,25 @@ export const RIG_SPEC_VERSION = 'rigc-rig/1';
  * `A19_OVERLAY_PNGS_HAVE_ALPHA` measure against, and a guessed stage is a gate
  * that measures against a number nobody wrote down.
  *
+ * ⭐ **`width: null, height: null` is the third state: this skeleton declares no
+ * stage** (issue #578). Omitting them is silence and stays a refusal by name;
+ * stating them `null` is a claim, and the emitted header then carries none of
+ * `x`/`y`/`width`/`height` — which is what an editor export of a skeleton whose
+ * stage was never set looks like, and what a transcriber of one has to be able
+ * to write down. `null` is this spec's spelling for a stated absence everywhere
+ * else it has one (`RigSlot.attachment` = "show nothing", the cut manifest's
+ * `image` = "this cut does not carry the part"), so it is the spelling here too
+ * and no new key is introduced: the pair already exists, and only a third value
+ * of it is new.
+ *
+ * Two shapes are refused rather than interpreted, both in `parseRigSpec`:
+ * stating one of the pair `null` and the other a number (a stage with one
+ * extent is not a stage, and guessing which half was meant is inventing), and
+ * stating `x` or `y` alongside the absence (an origin for a box that is not
+ * there). ⚠️ A stated absence also beats a cut manifest's `crop`, for the reason
+ * a stated `width` already does: the rig spec is where a claim about the
+ * skeleton is made, and the manifest is a record of what the art measured.
+ *
  * `spine` is not here: rigc emits its own version label and `A16` re-checks it.
  * `hash` is not here either — it is the editor's change-detection token and
  * inventing one would be claiming an export this file did not come from.
@@ -87,8 +106,10 @@ export const RIG_SPEC_VERSION = 'rigc-rig/1';
 export interface RigSkeletonHeader {
   x?: number;
   y?: number;
-  width?: number;
-  height?: number;
+  /** A number, or `null` with `height` for "this skeleton declares no stage". */
+  width?: number | null;
+  /** A number, or `null` with `width` for "this skeleton declares no stage". */
+  height?: number | null;
   /** Nonessential; `SkeletonData.fps` stays 30 when absent. */
   fps?: number;
   /** 4.2+; the runtime's physics/scale reference. Parser default 100. */
@@ -107,6 +128,18 @@ export interface RigSkeletonHeader {
   images?: string;
 }
 
+/**
+ * Does this header state that the skeleton has no stage?
+ *
+ * One reading of the spelling, exported so that the compiler, the emitter and
+ * anything that grows a third opinion later read it the same way. `parseRigSpec`
+ * has already refused the half-stated shapes by the time this is asked, so the
+ * two `null`s travel together.
+ */
+export function declaresNoStage(header: RigSkeletonHeader | undefined): boolean {
+  return header !== undefined && header.width === null && header.height === null;
+}
+
 // ---------------------------------------------------------------------------
 // bones — `root.bones[]` (SkeletonJson.ts:90-118)
 // ---------------------------------------------------------------------------
@@ -223,12 +256,22 @@ export const RIG_SLOT_BLEND: readonly RigSlotBlend[] = ['normal', 'additive', 'm
  * One slot. **The array order IS the draw order** — there is no separate setup
  * draw-order field anywhere in the format.
  *
- * The rig's slot list is the CANONICAL table, which is a slightly stronger claim
- * than "the slots this cut emits". A cut whose manifest carries no part for a
- * slot does not emit it, and the emitted array is then a *subsequence* of this
- * one; that is what `A26_SLOT_DRAW_ORDER` checks. Declaring a slot no cut fills
- * is therefore legitimate — it fixes where that slot will sit when a cut does
- * fill it.
+ * The rig's slot list is the CANONICAL table and **every slot in it is emitted**,
+ * in this order, whether or not anything fills it. A slot no skin and no manifest
+ * part fills is emitted with no setup attachment — the shape an editor export
+ * carries for a slot that shows nothing (the slot reader above takes `attachment`
+ * with a `null` default) — so the emitted array and this one are the same array.
+ * `A26_SLOT_DRAW_ORDER` checks both halves of that: nothing out of order, and
+ * nothing missing. Declaring a slot no cut fills is therefore legitimate, and it
+ * fixes where that slot sits whether or not this cut has art for it.
+ *
+ * ⚠️ Until issue #575 such a slot was **dropped**, and the gate licensed it: the
+ * emitted array was allowed to be any *subsequence* of this one. What that
+ * bought was the format's own silence. Nothing said which slot had gone, and
+ * every slot below it moved up one index — the index a `drawOrder` key's offsets
+ * are counted against, and the one an index-keyed consumer splits on. Two
+ * production exports declaring 53 and 61 slots built green at 51 and 57 and read
+ * 0.962 and 0.934 under `diff` against the file they were transcribed from.
  */
 export interface RigSlot {
   name: string;
@@ -241,6 +284,12 @@ export interface RigSlot {
    * comes from: `motion.setup` owns it, because which of the two overlay
    * mechanisms a slot uses (attachment + alpha 0, or attachment swapping) is a
    * decision about time. Declaring it in both is a compile error.
+   *
+   * Required for a slot something fills — the compiler will not guess which of
+   * the slot's attachments the setup pose shows — and **optional for a slot
+   * nothing fills**, where it can only be `null` and saying so changes no
+   * emitted byte. Naming an attachment on a slot nothing fills is refused: the
+   * name resolves to nothing, which is the shape of a half-finished wiring-up.
    */
   attachment?: string | null;
   /** `rrggbbaa`. Default opaque white. */
@@ -1520,6 +1569,15 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
         const type = att.type === undefined ? 'region' : String(att.type);
         const shape = ATTACHMENT_SHAPE[type];
         if (shape === undefined) continue;
+        // A mesh carrying `source` is a LINKED mesh — `type: "mesh"` and
+        // `type: "linkedmesh"` share one parser branch and the `source` key is
+        // what decides (`:568-569`, `:582`; SPEC_COVERAGE part 1-6). It has no
+        // key set here because `RigUnimplementedAttachment` deliberately has
+        // none, and checking it against a MESH's keys named the wrong fault:
+        // *2 keys this compiler does not read: "source", "skin" … fix the
+        // spelling or remove it*, where removing `source` is what unmakes the
+        // linked mesh. `buildRigAttachment` refuses it as the construct it is.
+        if (type === 'mesh' && att.source !== undefined) continue;
         at(att, shape, `${who} (${type})`);
         for (const [i, vertex] of (Array.isArray(att.weights) ? att.weights : []).entries()) {
           for (const [j, binding] of (Array.isArray(vertex) ? vertex : []).entries()) {
@@ -1573,6 +1631,32 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
 
   const spec = raw as unknown as RigSpec;
 
+  // The stage, stated or stated absent. Half a statement is refused here rather
+  // than resolved in `compile`, because which half was meant is not derivable
+  // and a compiler that picks one is inventing a number (issue #578).
+  const header = spec.skeleton;
+  if (header !== undefined) {
+    const noWidth = header.width === null;
+    const noHeight = header.height === null;
+    if (noWidth !== noHeight) {
+      const stated = noWidth ? 'height' : 'width';
+      const absent = noWidth ? 'width' : 'height';
+      throw new CompileError(
+        `${where}: "skeleton" states ${absent}: null and a ${stated} of ` +
+          `${JSON.stringify(noWidth ? header.height : header.width)}. A stage has both extents or neither: ` +
+          'write both as null for "this skeleton declares no stage", or give both a number',
+      );
+    }
+    if (noWidth && noHeight && (header.x !== undefined || header.y !== undefined)) {
+      const origin = [header.x !== undefined ? 'x' : null, header.y !== undefined ? 'y' : null].filter((k) => k !== null);
+      throw new CompileError(
+        `${where}: "skeleton" declares no stage (width: null, height: null) and still states ${origin.join(' and ')}. ` +
+          `${origin.length === 1 ? 'That is an origin' : 'Those are an origin'} for a box that is not there: ` +
+          'drop them, or state a width and a height',
+      );
+    }
+  }
+
   const seen = new Set<string>();
   for (const bone of spec.bones) {
     if (!isObj(bone) || typeof bone.name !== 'string' || bone.name.length === 0) {

package/src/timelines.ts

@@ -9,6 +9,11 @@
  * have had to restate it — and a second copy of a catalogue is a second copy
  * that goes stale silently.
  *
+ * `PHYSICS_POSE_RULES` at the bottom is here for that reason and no other: the
+ * compiler refuses an out-of-range physics value a spec states, `A23` names one
+ * in a file rigc did not write, and the two have to be the same criterion rather
+ * than two readings of one (issue #610).
+ *
  * Pure JSON reading. No spine-core, no filesystem. The line numbers cited are
  * into `SkeletonJson.ts` on branch 4.3; the field-by-field survey is in
  * `docs/SPEC_COVERAGE.md` part 1-8.
@@ -255,3 +260,161 @@ export function walkTimelines(
   }
 }
 
+
+/**
+ * A physics constraint's pose, as the four fields `A23` judges.
+ *
+ * Structural rather than spine-core's `PhysicsConstraintPose`, because this
+ * module links no runtime (see the header) — the runtime's class satisfies it,
+ * and so does the probe `validate.ts` hands the runtime's own timeline `set` to
+ * fill.
+ */
+export interface PhysicsJudgedPose {
+  mix: number;
+  massInverse: number;
+  strength: number;
+  damping: number;
+}
+
+/**
+ * One physics property `A23` has an opinion about, stated once for the two
+ * layers that hold it.
+ *
+ * ⚠️ **The keyed number and the pose field are not always the same number.**
+ * `mass` is the one: `PhysicsConstraintMassTimeline.set` is
+ * `pose.massInverse = 1 / value` (`Animation.js:2132-2145`) and the parser does
+ * the same to a constraint's own `mass` (`SkeletonJson.js:309`), so a key states
+ * a mass and the integrator reads its reciprocal. `toPose` IS that transform, and
+ * every predicate here is written against the pose field rather than against the
+ * keyed number — which is what makes "the compiler and the assertion apply the
+ * same criterion" a property of the code and not a claim about it.
+ */
+export interface PhysicsPoseRule {
+  /** The timeline name in skeleton JSON, and the motion spec's `property`. */
+  timeline: string;
+  /** The pose field the integrator reads. */
+  field: keyof PhysicsJudgedPose;
+  /** The pose field, from the number a key or the rig's tuning table states. */
+  toPose: (value: number) => number;
+  /** True when the integrator can use that pose field. */
+  poseOk: (poseValue: number) => boolean;
+  /**
+   * The same question asked of a KEY, where it differs — `null` means it does
+   * not. Only `mix` has one, and the runtime is the reason: `update` opens with
+   * `if (mix === 0) return;` (`PhysicsConstraint.js:109-111`) and
+   * `PhysicsConstraintPose` documents the field as "a percentage (0+)", so a
+   * mix of exactly 0 is a state the runtime has a branch for. A setup pose at 0
+   * is a constraint that does nothing unless an animation rescues it; a KEY at 0
+   * is an animation muting it for a stretch, which is what a mix timeline is for
+   * — measured, not assumed: the editor's own `sack-pro` example keys mix to 0 on
+   * 24 of its 36 mix keys, and applying the setup rule to keys would refuse all
+   * 24 (issue #610).
+   */
+  keyOk: ((poseValue: number) => boolean) | null;
+  /** The bound in words, for a message: what the value has to be. */
+  states: string;
+  /** The bound a KEY is held to, where `keyOk` widens it. */
+  statesKeyed: string;
+  /** What the runtime does outside the bound, with the lines that say so. */
+  why: string;
+}
+
+/**
+ * Every physics property with a bound the runtime supports, and **only** those.
+ *
+ * 🚫 `inertia`, `wind` and `gravity` are absent on purpose. The runtime
+ * documents no range for any of them and the integrator diverges on none:
+ * `inertia` scales how much bone movement is converted (`PhysicsConstraint.js:137,143`)
+ * so 0 is an inert frame and nothing worse, and `wind`/`gravity` are forces along
+ * the skeleton's own vectors (`:151-153, :214-215`) where a negative number is the
+ * other direction — the corpus keys `wind` at −27.4 through −12.6 on all 48 of its
+ * wind keys. Inventing a bound for them would refuse correct data, which is the
+ * failure this repository has already paid for twice (issues #44, #262).
+ *
+ * 🚫 There is no UPPER bound on `mix` either, for the same reason and a stronger
+ * one: `PhysicsConstraintPose` documents it as "a percentage (0+)", and a keyed
+ * mix of 1.5 changes nothing inside the integration at all — it multiplies the
+ * finished offset onto the bone (`:172,174,251,256,287`), so it is an over-mix and
+ * an over-mix is a real idiom (the same argument `CONSTRAINT_TIMELINES` makes for
+ * a transform mix).
+ */
+export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
+  {
+    timeline: 'mix',
+    field: 'mix',
+    toPose: (v) => v,
+    poseOk: (v) => v > 0,
+    keyOk: (v) => v >= 0,
+    states: '> 0',
+    statesKeyed: '>= 0',
+    why: 'the runtime documents it as a percentage (0+) and `update` returns immediately at 0 (`PhysicsConstraint.js:109-111`)',
+  },
+  {
+    timeline: 'mass',
+    field: 'massInverse',
+    toPose: (v) => 1 / v,
+    poseOk: (v) => Number.isFinite(v) && v > 0,
+    keyOk: null,
+    states: '> 0',
+    statesKeyed: '> 0',
+    why:
+      'the pose holds 1/mass, so 0 is an infinite massInverse and `m = t * massInverse` ' +
+      '(`PhysicsConstraint.js:149,211`) takes every velocity to NaN, while a negative mass ' +
+      'injects energy instead of resisting it',
+  },
+  {
+    timeline: 'strength',
+    field: 'strength',
+    toPose: (v) => v,
+    poseOk: (v) => v > 0,
+    keyOk: null,
+    states: '> 0',
+    statesKeyed: '> 0',
+    why:
+      'it is the restoring force — `velocity += (a - offset * strength) * m` ' +
+      '(`PhysicsConstraint.js:150,156,212,220`) — so at 0 nothing pulls the offset back and it drifts',
+  },
+  {
+    timeline: 'damping',
+    field: 'damping',
+    toPose: (v) => v,
+    poseOk: (v) => v > 0 && v < 1,
+    keyOk: null,
+    states: 'inside (0, 1)',
+    statesKeyed: 'inside (0, 1)',
+    why:
+      'the per-step decay is `damping ** (60 * step)` and every velocity is multiplied by it ' +
+      '(`PhysicsConstraint.js:148,158,163,210,222,227`), so 1 never decays, above 1 diverges, and ' +
+      'at or below 0 the velocity is killed outright or raised to a fractional power',
+  },
+];
+
+/** The rule for one timeline name, or `undefined` where the runtime bounds nothing. */
+export function physicsRuleFor(timeline: string): PhysicsPoseRule | undefined {
+  return PHYSICS_POSE_RULES.find((rule) => rule.timeline === timeline);
+}
+
+/**
+ * Whether the number a KEY states is one the runtime can use, judged on the pose
+ * field it becomes rather than on itself.
+ *
+ * `null` when it is. The string is the tail of a message and names the bound and
+ * the reason, never just "invalid".
+ */
+export function physicsKeyRefusal(rule: PhysicsPoseRule, value: number, posedBy?: number): string | null {
+  // ⚠️ `posedBy` exists so the VALIDATOR can hand over the number the runtime's
+  // own `PhysicsConstraint*Timeline.set` wrote, rather than rigc's reading of
+  // what that call does. The compiler cannot: it links no runtime, by the rule in
+  // CLAUDE.md, so it passes nothing and `toPose` answers. Those are two paths to
+  // one number and a selftest control measures that they agree — without it this
+  // parameter would be exactly the silent second opinion this table exists to
+  // remove.
+  const posed = posedBy ?? rule.toPose(value);
+  const ok = rule.keyOk ?? rule.poseOk;
+  if (ok(posed)) return null;
+  // The pose field only when it is a different number from the keyed one, which
+  // is derived rather than declared: it is exactly `mass`, and only where the
+  // reciprocal has moved.
+  const shown = posed === value ? '' : ` (${rule.field} ${posed})`;
+  return `${value}${shown}; must be ${rule.statesKeyed} — ${rule.why}`;
+}

package/src/types.ts

@@ -197,6 +197,8 @@ export interface MotionKey {
    *   scale      -> [x, y] as multipliers (1 = setup)
    *   rotate     -> [degrees]
    *   mix        -> [0..1] physics authority
+   *   inertia / strength / damping / mass / wind / gravity
+   *              -> [value]; the physics constraint's own setting, over time
    *   reset      -> null; the key is the event
    *
    * ⭐ On a track that names a `group`, this may instead be a **map keyed by
@@ -259,8 +261,39 @@ export type BoneProperty =
   | 'sheary'
   | 'rotate';
 
-/** Physics timelines the compiler emits. `reset` carries no value at all. */
-export type PhysicsProperty = 'mix' | 'reset';
+/**
+ * Physics timelines the compiler emits — all eight `SkeletonJson`'s physics
+ * branch reads, in the order it reads them (`SkeletonJson.js:1063-1094`).
+ *
+ * Six of them are one number that overrides the constraint's own setting for
+ * the length of an animation: `[inertia]`, `[strength]`, `[damping]`, `[mass]`,
+ * `[wind]`, `[gravity]`. `mix` is the constraint's authority and `reset`
+ * carries no value at all.
+ *
+ * ⚠️ A key that omits its value reads **0** on all six, and 1 on `mix` — the
+ * per-key default, which is NOT the constraint default (`inertia` 0.5,
+ * `strength` 100, `damping` 0.85, `mass` 1). rigc never omits a channel, so the
+ * distinction only bites a reader comparing an emitted file with an editor
+ * export; `PHYSICS_TRACKS` in `compile.ts` carries the argument.
+ *
+ * 🔒 **Four of them have a compile-time range** (issue #610): `mass` and
+ * `strength` must be `> 0`, `damping` strictly inside `(0, 1)`, and `mix` `0` or
+ * more. The bounds are `PHYSICS_POSE_RULES` in `src/timelines.ts` and they are
+ * the runtime's, not a policy — `inertia`, `wind`, `gravity` and the top of
+ * `mix` are bounded nowhere, because the runtime documents nothing for the first
+ * three and documents `mix` as "a percentage (0+)". The same four rows are what
+ * `A23_PHYSICS_CONSTRAINT_EFFECTIVE` judges a setup pose and a foreign file's
+ * timeline keys with, which is why they are not stated here as numbers.
+ */
+export type PhysicsProperty =
+  | 'inertia'
+  | 'strength'
+  | 'damping'
+  | 'mass'
+  | 'wind'
+  | 'gravity'
+  | 'mix'
+  | 'reset';
 
 /**
  * Path constraint timelines. `mix` is three values in one key —
@@ -515,13 +548,30 @@ export interface MotionTransformTrack {
 export interface MotionDeformKey {
   /** Time in seconds. */
   t: number;
-  /** Where the run starts in the attachment's own deform array. Default 0. */
+  /**
+   * Where the run starts in the attachment's own deform array. Default 0.
+   *
+   * Any index the array holds, **odd ones included** (issue #576): the parser
+   * copies at this index and does no pair arithmetic, so an odd start is what an
+   * editor writes when it trims the leading numbers off a delta run.
+   */
   offset?: number;
   /** The same start, given as a vertex index. Never together with `offset`. */
   fromVertex?: number;
   /**
-   * The run: `x, y` offsets, two numbers per array slot. Absent or `null` is the
-   * parser's own encoding for "back to the setup pose" — the key with no edit.
+   * The run: consecutive numbers written into the deform array from `offset` on,
+   * `x, y` per array slot. Absent or `null` is the parser's own encoding for
+   * "back to the setup pose" — the key with no edit.
+   *
+   * ⚠️ **An ODD count is legal and means something** (issue #576). Both readers
+   * copy the run verbatim — `Utils.arrayCopy(vertices, 0, deform, offset,
+   * vertices.length)` in `SkeletonJson`, a `for (let v = start; v < end; v++)`
+   * fill in `SkeletonBinary` — so a run of three numbers moves one vertex in x
+   * and y and the next in x alone, leaving that y at its setup value. Padding a
+   * `0` to even it out is a different animation whenever that setup y is
+   * non-zero, which is why the even-length rule that stood here could not be kept
+   * as a convenience: it left one production export with no spelling in this
+   * spec at all.
    */
   vertices?: number[] | null;
   /**
@@ -926,10 +976,25 @@ export type SpineConstraint = { name: string; type: string } & Record<string, un
 export interface SpineSkeletonJson {
   skeleton: {
     spine: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
+    /**
+     * The setup-pose bounding box. All four together or none of them: a rig spec
+     * that declares no stage (`skeleton.width`/`height` stated `null` — see
+     * `RigSkeletonHeader`) emits a header without any of them, which is what an
+     * export of a skeleton whose stage was never set carries (issue #578).
+     *
+     * ⚠️ Optional here because the *runtime* leaves them `undefined` when they
+     * are absent, not 0. `SkeletonData` declares `x = 0 … height = 0`
+     * (`SkeletonData.js:55-61`), and `SkeletonJson` then overwrites all four
+     * unconditionally — `skeletonData.x = skeletonMap.x` (`SkeletonJson.js:70-73`,
+     * no `getValue` default) — so an absent field lands as `undefined` on a
+     * `SkeletonData` whose own `.d.ts` types it `number`. Anything reading these
+     * back off a parsed skeleton guards for it; `validate.ts`'s `data.width || 0`
+     * is why A14 and A19 were already right about a stage-less file.
+     */
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
     fps?: number;
     referenceScale?: number;
     images?: string;