spine-rigc 0.22.2 → 0.24.0

package/src/compile.ts

@@ -41,6 +41,7 @@ import { parseJsonWithPosition } from './json-position.ts';
 import { nearMisses } from './keys.ts';
 import { parseMotionSpec } from './motion.ts';
 import {
+  declaresNoStage,
   parseRigSpec,
   RIG_FROM_PROPERTIES,
   RIG_PATH_POSITION_MODES,
@@ -84,13 +85,14 @@ import {
 import { Plate, readPlate } from '../tools/plate.ts';
 import {
   extractRegion,
+  pageFootprint,
   parseAtlasText,
   rewritePageNames,
   writeAtlasText,
   type AtlasRegion,
   type ParsedAtlas,
 } from './atlas.ts';
-import { KEY_TIME_EPSILON } from './timelines.ts';
+import { KEY_TIME_EPSILON, physicsKeyRefusal, physicsRuleFor, type PhysicsPoseRule } from './timelines.ts';
 import { evaluateDeformTransform } from './deformgen.ts';
 import { evaluateTrackDerive, TRACK_DERIVE_PROJECTIONS, type TrackDeriveMember } from './trackgen.ts';
 import {
@@ -731,6 +733,28 @@ function rgbaHex(v: number[]): string {
   return v.map(channelHex).join('');
 }
 
+/**
+ * One timeline a `MotionValueTrack` can name: the JSON fields a key carries, the
+ * per-key default the parser uses for each, and — where the runtime has one — the
+ * bound each field is held to.
+ *
+ * ⚠️ `bounds` is parallel to `fields`, not keyed by name, because a shape's
+ * channels are positional everywhere else in this file (a curve array indexes by
+ * channel) and a second addressing scheme for one table is how the two go out of
+ * step. `null` in a slot is "the runtime bounds this field nowhere", which is the
+ * value for every field of every shape but four of `PHYSICS_TRACKS`'.
+ *
+ * This is the `compileValueTrack` equivalent of `ConstraintTimelineShape.range`,
+ * and the reason it took a change rather than a table entry is that the
+ * ik/transform pair never shared this type: they carry named fields per key and
+ * go through `compileConstraintTrack`, where `range` already lived (issue #610).
+ */
+interface ValueTrackShape {
+  fields: string[];
+  identity: number[];
+  bounds?: Array<PhysicsPoseRule | null>;
+}
+
 /**
  * Bone timeline shapes: which JSON fields a key carries, and their defaults.
  *
@@ -738,7 +762,7 @@ function rgbaHex(v: number[]): string {
  * setup value, and `scale` defaults to 1 while `translate` defaults to 0. Emit
  * `x: 0` on a scale key and the bone collapses to nothing, silently.
  */
-const BONE_TRACKS: Record<string, { fields: string[]; identity: number[] }> = {
+const BONE_TRACKS: Record<string, ValueTrackShape> = {
   translate: { fields: ['x', 'y'], identity: [0, 0] },
   translatex: { fields: ['value'], identity: [0] },
   translatey: { fields: ['value'], identity: [0] },
@@ -752,13 +776,45 @@ const BONE_TRACKS: Record<string, { fields: string[]; identity: number[] }> = {
 };
 
 /**
- * Physics timelines. `mix` is the constraint's authority; `reset` is an event
- * with no value — one key at the entry frame stops the constraint from flying
- * in from whatever pose the previous animation left — solved in DATA rather
- * than in caller glue.
+ * Physics timelines — the eight `SkeletonJson`'s physics branch reads
+ * (`SkeletonJson.js:1063-1094`), in the order it reads them. `mix` is the
+ * constraint's authority; `reset` is an event with no value — one key at the
+ * entry frame stops the constraint from flying in from whatever pose the
+ * previous animation left — solved in DATA rather than in caller glue.
+ *
+ * 🚨 **`identity` here is the PER-KEY default, and for six of the eight it is
+ * not the constraint's own default.** The parser sets `defaultValue = 0` at
+ * `:1062` and only `mix` reassigns it (`:1090`), so an `inertia` key that omits
+ * `value` reads **0** — not the 0.5 that `:306` gives a constraint that states
+ * no `inertia`. Two different tables of defaults sit forty lines apart in one
+ * file (`PHYSICS_PARAMS` above holds the other one), and reading the setup
+ * column into this one would emit a `damping` timeline whose omitted keys mean
+ * 0.85 to the author and 0 to the runtime. Nothing here depends on the number,
+ * because `compileValueTrack` writes every field explicitly — it is recorded
+ * because a reader checking rigc against the parser will trip over it.
+ *
+ * ⚠️ `mass` is the one whose keyed value is not what the runtime stores:
+ * `PhysicsConstraintMassTimeline.set` is `pose.massInverse = 1 / value`
+ * (`Animation.js:2132-2145`, "The timeline values are not inverted"), so the
+ * key states a mass and the pose holds its reciprocal. A `mass` key of 0 is an
+ * infinite `massInverse`, and `bounds` below is what refuses it here.
+ *
+ * ⭐ **`bounds` is not a second opinion about the same numbers.** Each entry is
+ * a `PHYSICS_POSE_RULES` row — the one table `A23` judges a setup pose with —
+ * and the rule is applied to the POSE FIELD the key becomes rather than to the
+ * key, so `mass` is judged as `1 / value` on both sides of the tool. Four of the
+ * seven have a rule and three deliberately do not: the runtime bounds `inertia`,
+ * `wind` and `gravity` nowhere, and inventing one would refuse correct data
+ * (issue #610 — the corpus keys `wind` negative on all 48 of its wind keys).
  */
-const PHYSICS_TRACKS: Record<string, { fields: string[]; identity: number[] }> = {
-  mix: { fields: ['value'], identity: [1] },
+const PHYSICS_TRACKS: Record<string, ValueTrackShape> = {
+  inertia: { fields: ['value'], identity: [0], bounds: [physicsRuleFor('inertia') ?? null] },
+  strength: { fields: ['value'], identity: [0], bounds: [physicsRuleFor('strength') ?? null] },
+  damping: { fields: ['value'], identity: [0], bounds: [physicsRuleFor('damping') ?? null] },
+  mass: { fields: ['value'], identity: [0], bounds: [physicsRuleFor('mass') ?? null] },
+  wind: { fields: ['value'], identity: [0], bounds: [physicsRuleFor('wind') ?? null] },
+  gravity: { fields: ['value'], identity: [0], bounds: [physicsRuleFor('gravity') ?? null] },
+  mix: { fields: ['value'], identity: [1], bounds: [physicsRuleFor('mix') ?? null] },
   reset: { fields: [], identity: [] },
 };
 
@@ -776,7 +832,7 @@ const PHYSICS_TRACKS: Record<string, { fields: string[]; identity: number[] }> =
  * out — `compileValueTrack` never omits a field, which is what keeps "the author
  * wrote mixY" and "mixY happened to equal mixX" from emitting the same file.
  */
-const PATH_TRACKS: Record<string, { fields: string[]; identity: number[] }> = {
+const PATH_TRACKS: Record<string, ValueTrackShape> = {
   position: { fields: ['value'], identity: [0] },
   spacing: { fields: ['value'], identity: [0] },
   mix: { fields: ['mixRotate', 'mixX', 'mixY'], identity: [1, 1, 1] },
@@ -792,7 +848,7 @@ const PATH_TRACKS: Record<string, { fields: string[]; identity: number[] }> = {
  * a copy of a neighbour, and a reader checking rigc against the parser will trip
  * over it.
  */
-const SLIDER_TRACKS: Record<string, { fields: string[]; identity: number[] }> = {
+const SLIDER_TRACKS: Record<string, ValueTrackShape> = {
   time: { fields: ['value'], identity: [1] },
   mix: { fields: ['value'], identity: [1] },
 };
@@ -1150,8 +1206,38 @@ function skeletonImagesPath(
   if (declared !== undefined) return declared;
   if (partDirs.size !== 1) return undefined;
   const [partsDir] = partDirs;
-  const rel = relative(outDir, partsDir).split('\\').join('/');
-  if (rel === '') return self;
+  const spelled = relativeImagesPath(outDir, partsDir);
+  // `./` is the one spelling the editor collapses to nothing (see above), so
+  // "the parts are in this very directory" is said the way the editor keeps.
+  // That substitution is the ONLY thing this path does that a rig spec's own
+  // `images` does not, which is why the rest of the spelling is one function.
+  return spelled === './' ? self : spelled;
+}
+
+/**
+ * An images directory spelled as a path from the directory of the file that
+ * names it — the one convention this repository has for saying where the parts
+ * are, in one function rather than in each of its callers (issue #595).
+ *
+ * Three rules, and each is load-bearing: POSIX separators, so two checkouts of
+ * one tree emit one file and `A18` holds; a trailing `/`, as the format page's
+ * own example (`"./images/"`) spells it; and `./` on a descendant, so the value
+ * reads as a relative path rather than as a bare name.
+ *
+ * ⚠️ `./` for "the very directory the file is in" is returned rather than
+ * decided here, because who reads the field differs. `skeletonImagesPath`
+ * replaces it — the editor was measured collapsing a literal `./` to no path at
+ * all (issue #370) — while a rig spec's own `images` is read by rigc, which
+ * resolves `./` against the spec's own directory and finds the parts.
+ *
+ * Both callers pass two ABSOLUTE directories, and `relative` reads neither of
+ * them off disk — which is what lets `cli.ts` spell a rig spec's `images` for
+ * `ingest` here, rather than `src/ingest.ts` growing a notion of an output
+ * directory it otherwise has none of.
+ */
+export function relativeImagesPath(from: string, to: string): string {
+  const rel = relative(from, to).split('\\').join('/');
+  if (rel === '') return './';
   return rel.startsWith('..') ? `${rel}/` : `./${rel}/`;
 }
 
@@ -1321,9 +1407,9 @@ function resolveFromAtlas(
       `region "${region}" sits on page "${found.page.name}" of ${atlas.path}, which is not on disk at ${absPath}`,
     );
   }
-  const turned = found.region.degrees === 90 || found.region.degrees === 270;
-  const rectW = turned ? found.region.height : found.region.width;
-  const rectH = turned ? found.region.width : found.region.height;
+  // The rectangle ON THE PAGE, which at a quarter turn is not the one `bounds:`
+  // states — `pageFootprint` owns that derivation for every reader of it.
+  const { width: rectW, height: rectH } = pageFootprint(found.region);
   if (
     found.region.x < 0 ||
     found.region.y < 0 ||
@@ -1363,6 +1449,13 @@ function resolveFromAtlas(
  * own, only a rectangle of somebody's page. `extractRegion` lifts the drawing
  * back out, so the generator sees the same grid either way and its output does
  * not depend on how the art was delivered.
+ *
+ * ⭐ *Either way* was not true for a pack that turns a region until issue #570:
+ * `extractRegion` refused a `rotate: 90`, so how the art was delivered decided
+ * whether a measurement could be taken at all — on a foreign pack, where turning
+ * is the norm rather than the exception. It now transcribes the runtime's own
+ * mapping for all four rotations, which is what makes the sentence above a
+ * description rather than an aspiration.
  */
 function partPlate(img: CompiledImage): Plate {
   const page = readPlate(img.absPath);
@@ -1433,15 +1526,34 @@ export function compile(opts: CompileOptions): CompileResult {
   // The stage. The rig may state it outright (a foreign skeleton has no crop);
   // otherwise the manifest's crop is it. With neither there is nothing to
   // measure a full-frame mesh against, so the compile stops rather than guess.
-  const stageWidth = rig.skeleton?.width ?? manifest?.crop.w;
-  const stageHeight = rig.skeleton?.height ?? manifest?.crop.h;
-  if (stageWidth === undefined || stageHeight === undefined) {
+  //
+  // ⭐ The third state is the rig saying there is no stage at all — `width` and
+  // `height` stated `null` (issue #578). That is a claim rather than a silence,
+  // so it beats the manifest's crop the way a stated number already does, and
+  // the header below emits none of the four fields. Omitting them is still the
+  // refusal underneath: a transcriber who has no stage to copy can now say so,
+  // and one who simply has not looked still cannot.
+  const noStage = declaresNoStage(rig.skeleton);
+  const stageWidth = noStage ? undefined : (rig.skeleton?.width ?? manifest?.crop.w);
+  const stageHeight = noStage ? undefined : (rig.skeleton?.height ?? manifest?.crop.h);
+  if (!noStage && (stageWidth === undefined || stageHeight === undefined)) {
     throw new CompileError(
-      'no stage size: give the rig spec a `skeleton.width`/`skeleton.height`, or compile against a cut manifest whose `crop` states them',
+      'no stage size: give the rig spec a `skeleton.width`/`skeleton.height`, or compile against a cut manifest whose `crop` states them, ' +
+        'or state `"width": null, "height": null` for a skeleton that declares no stage',
     );
   }
-  /** Crop height, for the y-down -> y-up flip. Only manifest data uses it. */
-  const cropH = manifest?.crop.h ?? stageHeight;
+  /**
+   * Crop height, for the y-down -> y-up flip. Only manifest data uses it, and
+   * `cropPointOf` refuses every bone that asks for manifest data when there is
+   * no manifest — so the two states that can be read here both have one, or a
+   * stage.
+   *
+   * ⚠️ `NaN` for the third, unreachable state (no manifest and a rig that
+   * declares no stage) rather than 0. A plausible number is the failure this
+   * compiler exists to refuse; if the guard above it ever moved, a NaN
+   * coordinate is a named failure and an origin-flipped bone is not.
+   */
+  const cropH = manifest?.crop.h ?? stageHeight ?? Number.NaN;
   const imagesDir = opts.imagesDir !== undefined ? resolve(opts.imagesDir) : resolve(dirname(rigPath), rig.images ?? '.');
 
   // -- 1. gather images ------------------------------------------------------
@@ -1806,16 +1918,29 @@ export function compile(opts: CompileOptions): CompileResult {
   for (const rigSlot of rig.slots) {
     const part = partBySlot.get(rigSlot.name);
     const names = slotAttachments.get(rigSlot.name) ?? rigAttachmentNames.get(rigSlot.name) ?? [];
-    if (!names.length) continue;
+    // 🔑 A slot nothing fills is EMITTED, empty — it is not dropped (issue #575).
+    // A `continue` stood here instead, and what it bought was the format's own
+    // silence: the emitted array came back a slot short with no line saying
+    // which, and every slot after it moved down one. That index is what a
+    // `drawOrder` key's offsets are counted against and what an index-keyed
+    // consumer splits on, so the drop is not a smaller file, it is a different
+    // rig. Two production exports declaring 53 and 61 slots built green at 51
+    // and 57 and read 0.962 / 0.934 against the file they were transcribed from.
+    //
+    // The shape emitted here is the editor's own: `SkeletonJson`'s slot reader
+    // takes `attachment` with a `null` default, so a slot with no `attachment`
+    // key is a slot that shows nothing — 34 of the 52 slots in the official
+    // `spineboy-pro` export omit the key.
+    const empty = names.length === 0;
 
     const setup = motion.setup?.[rigSlot.name];
     // ⚠️ The entry's SHAPE is `parseMotionSpec`'s now (issue #307), and it had to
-    // move: this loop walks the RIG's slots and `continue`s past one with no
-    // attachments a few lines above, so the #293 shapes — `"lid_l": null` and,
-    // far worse, `"lid_l": "plate"`, which reads `.attachment` off a string as
-    // `undefined` and hides the slot in silence — stayed GREEN for exactly the
-    // slots a reader is most likely to be halfway through wiring up. Everything
-    // from here down is the half that needs the rig in front of it.
+    // move: this loop used to `continue` past a slot with no attachments before
+    // reaching here, so the #293 shapes — `"lid_l": null` and, far worse,
+    // `"lid_l": "plate"`, which reads `.attachment` off a string as `undefined`
+    // and hides the slot in silence — stayed GREEN for exactly the slots a
+    // reader is most likely to be halfway through wiring up. Everything from
+    // here down is the half that needs the rig in front of it.
     if (setup !== undefined && rigSlot.attachment !== undefined) {
       throw new CompileError(
         `slot "${rigSlot.name}" has a setup attachment in the rig spec AND in the motion spec; the setup pose has one author`,
@@ -1824,6 +1949,11 @@ export function compile(opts: CompileOptions): CompileResult {
     let setupAttachment: string | null;
     if (setup !== undefined) setupAttachment = setup.attachment ?? null;
     else if (rigSlot.attachment !== undefined) setupAttachment = rigSlot.attachment;
+    // Nothing fills the slot, so there is nothing to choose between and nothing
+    // to guess: the setup pose of an empty slot is "show nothing", which is the
+    // one value the format can express for it. The refusal below stays exactly
+    // where it was for a slot that HAS attachments and states no setup pose.
+    else if (empty) setupAttachment = null;
     else {
       throw new CompileError(
         `no setup pose for slot "${rigSlot.name}": give the motion spec a \`setup\` entry or the rig slot an \`attachment\` — the compiler will not guess one`,
@@ -1831,7 +1961,11 @@ export function compile(opts: CompileOptions): CompileResult {
     }
     if (setupAttachment !== null && !names.includes(setupAttachment)) {
       throw new CompileError(
-        `setup attachment "${setupAttachment}" for slot "${rigSlot.name}" is not one of [${names.join(', ')}]`,
+        empty
+          ? `the setup pose shows attachment "${setupAttachment}" on slot "${rigSlot.name}", which no skin and no ` +
+            'manifest part fills — the slot is emitted empty, so there is no such attachment to show. Give the ' +
+            'slot an attachment, or state the setup pose as null'
+          : `setup attachment "${setupAttachment}" for slot "${rigSlot.name}" is not one of [${names.join(', ')}]`,
       );
     }
     if (setup?.color && rigSlot.color !== undefined) {
@@ -1844,6 +1978,11 @@ export function compile(opts: CompileOptions): CompileResult {
     if (rigSlot.dark !== undefined) slot.dark = rigSlot.dark;
     if (rigSlot.blend !== undefined) slot.blend = rigSlot.blend;
     slots.push(slot);
+    // ...and nothing below this line has anything to build. An empty entry in a
+    // skin's attachment table would be rigc writing a key the editor does not,
+    // so the skins array is left exactly as it was before #575 for every slot
+    // that IS filled, and gains nothing for one that is not.
+    if (empty) continue;
 
     if (part) {
       const perSlot: Record<string, SpineAttachment> = {};
@@ -2288,13 +2427,19 @@ export function compile(opts: CompileOptions): CompileResult {
   });
 
   // -- 6. assemble -----------------------------------------------------------
-  const header: SpineSkeletonJson['skeleton'] = {
-    spine: SPINE_VERSION,
-    x: rig.skeleton?.x ?? 0,
-    y: rig.skeleton?.y ?? 0,
-    width: stageWidth,
-    height: stageHeight,
-  };
+  //
+  // The stage is four fields or none of them. `x`/`y` are the origin of the box
+  // `width`/`height` give an extent to, so a header carrying an origin for a box
+  // it does not declare would be a shape no export has — and the key ORDER here
+  // is the editor's own, which is what keeps a staged build byte-identical to
+  // what it emitted before the stage could be declared absent (issue #578).
+  const header: SpineSkeletonJson['skeleton'] = { spine: SPINE_VERSION };
+  if (stageWidth !== undefined && stageHeight !== undefined) {
+    header.x = rig.skeleton?.x ?? 0;
+    header.y = rig.skeleton?.y ?? 0;
+    header.width = stageWidth;
+    header.height = stageHeight;
+  }
   if (rig.skeleton?.fps !== undefined) header.fps = rig.skeleton.fps;
   if (rig.skeleton?.referenceScale !== undefined) header.referenceScale = rig.skeleton.referenceScale;
   const imagesPath = skeletonImagesPath(rig.skeleton?.images, opts, outDir, partDirs);
@@ -2796,6 +2941,39 @@ interface AttachmentContext {
   slotNames: Set<string>;
 }
 
+/**
+ * The seven `type` values `readAttachment` has a branch for (`:540-651`), and
+ * the five rigc emits.
+ *
+ * ⚠️ The lists are separate because the refusals are separate. A `point` is a
+ * name the format HAS and rigc has not built; `sequence` is not a type at all —
+ * it is a key on a region or a mesh (SPEC_COVERAGE part 1-6) — and telling an
+ * author that it "is in the Spine 4.3 format and rigc does not emit it yet"
+ * promises work that will never be done, on a spelling that is simply wrong.
+ * One message said exactly that about every string it did not recognise.
+ */
+const SPINE_ATTACHMENT_TYPES = ['region', 'mesh', 'linkedmesh', 'boundingbox', 'path', 'point', 'clipping'] as const;
+const EMITTED_ATTACHMENT_TYPES = ['region', 'mesh', 'boundingbox', 'clipping', 'path'] as const;
+
+/**
+ * What each deferred type is and what it would carry — `docs/SPEC_COVERAGE.md`
+ * part 1-6's two rows, restated where the refusal can print them.
+ *
+ * ⭐ The construct, not just its name. "attachment type X is in the Spine 4.3
+ * format and rigc does not emit it yet" tells an author who already knows what a
+ * linked mesh is that rigc will not do it, and tells an author who does not know
+ * nothing at all — and the second is the reader this repository writes for.
+ */
+const DEFERRED_ATTACHMENTS: Record<string, string> = {
+  linkedmesh:
+    'a mesh that takes its geometry from another mesh instead of stating any — a region/mesh head, then ' +
+    '"source" (the attachment it links to, and the key that MAKES it linked), "slot" and "skin" naming where ' +
+    'that source lives, and "timelines" (default true) for whether it follows the source\'s deform keys',
+  point:
+    'a position and an angle with no geometry at all — "x", "y", "rotation" and "color", posed by its bone and ' +
+    'drawn by nothing; what reads it is game code asking where a muzzle or a hand is',
+};
+
 /**
  * Build one attachment a rig spec authored, as opposed to one a manifest part
  * produced.
@@ -2804,6 +2982,18 @@ interface AttachmentContext {
  * attachment type it does not know is to return null and drop it
  * (`SkeletonJson.ts:653`), so passing an unimplemented type through would produce
  * a skeleton missing an attachment nobody was told about.
+ *
+ * 🚨 **`?? 'region'` is not the parser's default, and that gap was the one real
+ * fall-through here** (issue #577). `getValue(map, "type", "region")` returns the
+ * default only when the key is **missing** (`SkeletonJson.ts:527`, `getValue` at
+ * `:1390`), so `"type": null` is a type the parser HAS and matches no case: the
+ * switch falls off the end, `readAttachment` returns null, and the attachment
+ * disappears. `att.type ?? 'region'` read that same map as a region and compiled
+ * one, which is the compiler inventing a value the spec did not state. Measured
+ * before the repair: `{"type": null, "image": "marker.png"}` compiled and gated
+ * green; `{"type": null}` was refused as *a region needs width and height*, which
+ * is the message the card for this issue quoted and the reason it read as a
+ * `linkedmesh` fault. `"type": "linkedmesh"` itself was always refused by name.
  */
 function buildRigAttachment(
   att: RigAttachment,
@@ -2811,18 +3001,55 @@ function buildRigAttachment(
   where: string,
   ctx: AttachmentContext,
 ): SpineAttachment {
-  const type = att.type ?? 'region';
+  const stated = (att as { type?: unknown }).type;
+  if (stated !== undefined && typeof stated !== 'string') {
+    throw new CompileError(
+      `${where}: "type" is ${JSON.stringify(stated) ?? String(stated)}, which is not a name. An attachment's type ` +
+        `is one of ${SPINE_ATTACHMENT_TYPES.join(', ')}, or the key is absent and reads as "region". ` +
+        'PRESENT-and-null is not absent: `getValue(map, "type", "region")` takes the default only when the key is ' +
+        'missing (`SkeletonJson.ts:527`), so this map matches no case, `readAttachment` returns null (`:653`), and ' +
+        'the attachment is dropped from the skeleton without a word. Remove the key, or name a type.',
+    );
+  }
+  const type = stated ?? 'region';
+  // A linked mesh in the format's OTHER spelling. `type: "mesh"` and `type:
+  // "linkedmesh"` share one branch and the `source` key is what decides between
+  // them (`:568-569`, `:582`; SPEC_COVERAGE part 1-6) — so a mesh carrying
+  // `source` is a linked mesh whatever its `type` says, and refusing it as "two
+  // keys this compiler does not read: source, skin" sent the author to delete
+  // the one key that made it linked.
+  if (type === 'mesh' && (att as { source?: unknown }).source !== undefined) {
+    throw new NotImplementedError(deferredAttachmentRefusal('linkedmesh', where, ' (a mesh carrying "source" is one)'));
+  }
   if (type === 'region') return buildRigRegion(att as RigRegionAttachment, placeholder, where, ctx);
   if (type === 'mesh') return buildRigMesh(att as RigMeshAttachment, placeholder, where, ctx);
   if (type === 'boundingbox') return buildRigBoundingBox(att as RigBoundingBoxAttachment, where, ctx);
   if (type === 'clipping') return buildRigClipping(att as RigClippingAttachment, where, ctx);
   if (type === 'path') return buildRigPath(att as RigPathAttachment, where, ctx);
-  throw new NotImplementedError(
-    `${where}: attachment type "${String(type)}" is in the Spine 4.3 format and rigc does not emit it yet. ` +
-      'Implemented: region, mesh, boundingbox, clipping, path. ' +
-      'point and linkedmesh are deliberately deferred: neither appears anywhere in the benchmark ' +
-      'corpus (docs/SPEC_COVERAGE.md parts 3-1 and 4-2), so neither is on the ladder\'s critical path. ' +
-      'docs/SPEC_COVERAGE.md part 1-6 lists what each type would have to carry.',
+  if (DEFERRED_ATTACHMENTS[type] !== undefined) throw new NotImplementedError(deferredAttachmentRefusal(type, where, ''));
+  const near = nearMisses(type, SPINE_ATTACHMENT_TYPES);
+  throw new CompileError(
+    `${where}: attachment type "${type}" is not one of the ${SPINE_ATTACHMENT_TYPES.length} the Spine 4.3 format ` +
+      `defines (${SPINE_ATTACHMENT_TYPES.join(', ')}). ` +
+      (near.length ? `Did you mean ${near.map((n) => JSON.stringify(n)).join(' or ')}? ` : '') +
+      'The parser matches no case for it, `readAttachment` returns null (`SkeletonJson.ts:653`), and the ' +
+      'attachment is dropped from the skeleton without a word.' +
+      // The one near-miss worth naming outright, because it is a real word in
+      // this format standing one level up from where it was written.
+      (type === 'sequence'
+        ? ' "sequence" is a KEY on a region or a mesh rather than a type of its own (docs/SPEC_COVERAGE.md part 1-6).'
+        : ''),
+  );
+}
+
+/** The refusal for a type the format has and rigc has not built. */
+function deferredAttachmentRefusal(type: string, where: string, how: string): string {
+  return (
+    `${where}: this attachment is a "${type}"${how} — ${DEFERRED_ATTACHMENTS[type]}. ` +
+    `rigc does not emit it yet, deliberately: it emits ${EMITTED_ATTACHMENT_TYPES.join(', ')}, and neither a ` +
+    'point nor a linked mesh appears anywhere in the benchmark corpus (docs/SPEC_COVERAGE.md parts 3-1 and 4-2), ' +
+    'so neither is on the ladder\'s critical path. docs/SPEC_COVERAGE.md part 1-6 is the row this sentence reads ' +
+    'from, and it is what an implementation would have to carry.'
   );
 }
 
@@ -3191,6 +3418,45 @@ function atlasedImage(image: string, where: string, ctx: AttachmentContext): Com
   );
 }
 
+/**
+ * The atlas region this attachment resolves its art from — **one rule for every
+ * attachment kind that has art**, which is region and mesh (the parser's own two
+ * `getValue(map, "path", name)` sites, `:541` and `:570`).
+ *
+ * `path` defaults to the attachment's NAME, not to the placeholder, so a
+ * placeholder called anything other than its PNG's basename resolves a region no
+ * atlas has. Stating it is therefore not decoration: without it the loader
+ * throws `Region not found in atlas`, which `A00_ROUNDTRIP_PARSE` reports in the
+ * parser's own words.
+ *
+ * 🚨 The tree answered this in three different ways until issue #577, and
+ * `docs/AUTHORING.md` §3.4 documented only one of them — *"rigc sets it for you
+ * when the PNG basename differs from the placeholder"*. A region derived it, the
+ * `contour` and `grid` generators derived it (one of them with a comment reading
+ * "Same rule a region attachment follows"), and an authored mesh and the
+ * `ring`/`ribbon` generators wrote `path` only when the spec stated one.
+ * Measured on the probe rig: a region with `image: hair_short.png` under
+ * placeholder `hair` gated green with `"path": "hair_short"`; the same image on
+ * an authored mesh emitted no `path` and failed `A00_ROUNDTRIP_PARSE: threw:
+ * Region not found in atlas: hair (attachment: hair)`. The asymmetry had already
+ * been paid for by hand — `selftest.ts`'s own `TIMELINE_RIG` restates
+ * `path: "block"` and `path: "marker"` on two authored meshes for no other
+ * reason.
+ *
+ * ⭐ Deriving is the reading that was already written down, in the doc and in
+ * two of the five emit sites. The alternative — document the asymmetry and
+ * refuse a mesh whose basename differs without a `path` — was rejected because
+ * it makes a hand-kept exception out of a rule the format applies to both kinds
+ * through one line of parser, and it would have had to contradict §3.4 rather
+ * than satisfy it.
+ */
+function attachmentPath(att: { path?: string; image?: string }, placeholder: string): string | undefined {
+  if (att.path !== undefined) return att.path;
+  if (att.image === undefined) return undefined;
+  const region = basename(att.image, '.png');
+  return region === placeholder ? undefined : region;
+}
+
 function buildRigRegion(
   att: RigRegionAttachment,
   placeholder: string,
@@ -3237,9 +3503,8 @@ function buildRigRegion(
     );
   }
   const out: SpineRegionAttachment = { width: r6(width), height: r6(height) };
-  const region = att.image === undefined ? undefined : basename(att.image, '.png');
-  if (att.path !== undefined) out.path = att.path;
-  else if (region !== undefined && region !== placeholder) out.path = region;
+  const path = attachmentPath(att, placeholder);
+  if (path !== undefined) out.path = path;
   if (att.x !== undefined) out.x = r6(att.x);
   if (att.y !== undefined) out.y = r6(att.y);
   if (att.rotation !== undefined) out.rotation = r6(att.rotation);
@@ -3300,6 +3565,16 @@ function encodeNamedWeights(weights: RigMeshBinding[][], where: string, ctx: Att
  * a part with no art at all (0 of 0 pixels is not a percentage). Neither is an
  * error here — a mesh with no image is ordinary data, and an all-transparent part
  * is somebody else's assertion to make.
+ *
+ * 🚨 The asymmetry was a promise this function could not keep, and nothing here
+ * said so (issue #570). `partPlate` three frames down called `extractRegion`,
+ * which refused a region a foreign pack had turned — so an authored mesh naming
+ * an `image` under `--atlas-in` ENDED the build, by a refusal raised inside a
+ * measurement, on 36 of 42 atlases of the pack the card was filed from. The
+ * repair was to make the refusal unnecessary rather than to catch it: reading a
+ * turned region is a transcription of `MeshAttachment.computeUVs` and is now
+ * 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 {
   if (att.image === undefined || att.uvs === undefined || att.triangles === undefined) return null;
@@ -3466,7 +3741,8 @@ function buildRigMesh(
     width: r6(width),
     height: r6(height),
   };
-  if (att.path !== undefined) out.path = att.path;
+  const path = attachmentPath(att, placeholder);
+  if (path !== undefined) out.path = path;
   if (att.color !== undefined) out.color = att.color;
   // Register it as `authored`: geometry rigc did not build and whose topology it
   // therefore gets to assume nothing about. The generator-topology assertions
@@ -3557,7 +3833,8 @@ function buildGeneratedMesh(
     width: r6(w),
     height: r6(h),
   };
-  if (att.path !== undefined) out.path = att.path;
+  const path = attachmentPath(att, placeholder);
+  if (path !== undefined) out.path = path;
   if (att.color !== undefined) out.color = att.color;
   return out;
 }
@@ -4035,8 +4312,8 @@ function buildGridAttachment(
     width: r6(w),
     height: r6(h),
   };
-  if (att.path !== undefined) out.path = att.path;
-  else if (img.region !== placeholder) out.path = img.region;
+  const path = attachmentPath(att, placeholder);
+  if (path !== undefined) out.path = path;
   if (att.color !== undefined) out.color = att.color;
   return out;
 }
@@ -4174,9 +4451,11 @@ function buildContourAttachment(
   };
   // Same rule a region attachment follows: the atlas region is the PNG's
   // basename, so a placeholder named anything else needs `path` written down or
-  // the loader resolves nothing.
-  if (att.path !== undefined) out.path = att.path;
-  else if (img.region !== placeholder) out.path = img.region;
+  // the loader resolves nothing. Stated once in `attachmentPath` since #577 —
+  // this comment used to be the rule's only statement, beside four emit sites
+  // that disagreed with it.
+  const path = attachmentPath(att, placeholder);
+  if (path !== undefined) out.path = path;
   if (att.color !== undefined) out.color = att.color;
   return out;
 }
@@ -4990,7 +5269,7 @@ function compileValueTrack(
   duration: number,
   target: string,
   shift: number,
-  shapes: Record<string, { fields: string[]; identity: number[] }>,
+  shapes: Record<string, ValueTrackShape>,
   kind: string,
 ): SpineTimelineKey[] {
   const shape = shapes[track.property];
@@ -5022,6 +5301,23 @@ function compileValueTrack(
     shape.fields.forEach((field, c) => {
       const v = key.v as number[];
       if (!Number.isFinite(v[c])) throw new CompileError(`${where}: non-finite value ${String(v[c])}`);
+      // The bound, where the runtime has one. Refused here rather than left to
+      // `A23` because this is a spec somebody wrote and the key is the thing to
+      // change — the same division `compileConstraintTrack`'s `range` makes for
+      // an ik mix, and the same criterion `A23` applies to a file rigc did not
+      // write (issue #610). Note the value is judged BEFORE `r6`: a number
+      // rounding onto a bound would be refused for the rounding rather than for
+      // what the author wrote.
+      const bound = shape.bounds?.[c];
+      if (bound) {
+        const refusal = physicsKeyRefusal(bound, v[c]);
+        // `where` already ends in the property, so the JSON field is named only
+        // on a shape that has more than one of them — otherwise the message
+        // reads "… mass: value is 0", which says the property twice and the
+        // second time under the wrong name.
+        const at = shape.fields.length > 1 ? `${field} at t=${key.t}` : `key at t=${key.t}`;
+        if (refusal !== null) throw new CompileError(`${where} ${at} is ${refusal}`);
+      }
       entry[field] = r6(v[c]);
     });
     if (key.ease !== undefined && key.curve !== undefined) {
@@ -5647,12 +5943,15 @@ function deformGeometryOf(
  *      pair too long, or aimed at the wrong attachment, loses its tail and
  *      deforms part of the mesh correctly. That is the worst possible failure
  *      shape: it looks almost right.
- *   2. **An odd `offset`, or an odd run length.** The array is `x, y` pairs; an
- *      odd index puts every x of the run on a y and vice versa. It loads.
- *   3. **`fromVertex` where a vertex is not one pair.** See below.
- *   4. **A key that carries both a run and no room for one**, or a non-finite
+ *   2. **`fromVertex` where a vertex is not one pair.** See below.
+ *   3. **A key that carries both a run and no room for one**, or a non-finite
  *      offset — a NaN in the deform array propagates into world vertices.
  *
+ * ⛔ What is **not** refused, and was until issue #576: an odd `offset` or an odd
+ * run length. Both are raw copies at raw indices in both readers, both are what a
+ * trimmed editor delta looks like, and neither has a second spelling — see the
+ * clause in the loop below and the one in `deformStart`.
+ *
  * `fromVertex` is rigc's own field and the reason it exists is issue #89's
  * observation: a deform key is the only key in the format whose meaning depends
  * on the attachment it is attached to, and an author reasons in vertices while
@@ -5811,11 +6110,31 @@ function compileDeformTrack(
           'or omit it entirely for "back to the setup pose"',
       );
     }
-    if (run.length % 2 !== 0) {
-      throw new CompileError(
-        `${where} (t=${key.t}): "vertices" holds ${run.length} numbers; the deform array is x, y PAIRS, so a run has an even length`,
-      );
-    }
+    // ⛔ No parity clause here, and its absence is the rule (issue #576).
+    //
+    // A run is copied, not decoded. `SkeletonJson`'s deform branch does
+    // `Utils.arrayCopy(verticesValue, 0, deform, start, verticesValue.length)`
+    // with `start` the key's own `offset`, and `SkeletonBinary` reads a count and
+    // a start and fills `for (let v = start; v < end; v++) deform[v] = ...`.
+    // Neither has any pair arithmetic to be misaligned against, so an ODD run is
+    // legal, deterministic data: it writes the x and y of one vertex and the x of
+    // the next, and that next y stays at its setup value.
+    //
+    // 🔒 The reason this cannot be "refused in THIS spec anyway" is that there is
+    // no other spelling of it. Padding a `0` to make the run even is a different
+    // animation wherever the setup y it lands on is non-zero, so a spec that
+    // refuses an odd run is a spec no transcription of such a file can be written
+    // in — and one is in this repository's own example corpus (`spineboy-pro`,
+    // `hoverboard` / `hoverboard-board`: `offset: 1` and 147 numbers into a
+    // 148-long array, the whole delta minus the leading zero the editor trimmed).
+    //
+    // What replaces it is the bound the runtime really has, below: the run has to
+    // FIT. That one is the quiet defect — a copy past the end of a `Float32Array`
+    // is a no-op in JavaScript — and it is unaffected by where a run starts or
+    // how long it is. `A35_DEFORM_KEYS_FIT_THE_ATTACHMENT` measures the same
+    // bound on the emitted file and has had no parity clause since issue #262;
+    // until this was removed the two halves of rigc disagreed about what the
+    // format holds, and the half that refused was the authoring half.
     for (const n of run) {
       if (typeof n !== 'number' || !Number.isFinite(n)) {
         throw new CompileError(`${where} (t=${key.t}): "vertices" holds a non-finite value ${JSON.stringify(n)}`);
@@ -5884,10 +6203,10 @@ function expandDeformToInfluences(displacements: number[], geometry: DeformGeome
 /**
  * Where in the deform array this key's run begins.
  *
- * `offset` is that index outright. `fromVertex` is a vertex index, and turning
- * one into the other is exact only where a vertex occupies exactly one pair —
- * which is every vertex of an unweighted attachment and only the single-bone
- * vertices of a weighted one.
+ * `offset` is that index outright — any index the array holds, odd ones included
+ * (issue #576). `fromVertex` is a vertex index, and turning one into the other is
+ * exact only where a vertex occupies exactly one pair — which is every vertex of
+ * an unweighted attachment and only the single-bone vertices of a weighted one.
  */
 function deformStart(
   key: MotionDeformTrack['keys'][number],
@@ -5901,12 +6220,16 @@ function deformStart(
         `${where} (t=${key.t}): offset is ${JSON.stringify(key.offset)}; it is an index into the deform array, so a whole number ≥ 0`,
       );
     }
-    if (key.offset % 2 !== 0) {
-      throw new CompileError(
-        `${where} (t=${key.t}): offset ${key.offset} is odd. The deform array is x, y pairs, so an odd start puts ` +
-          "every x of this run on a y — it loads, and the mesh tears. Use an even index, or say which vertex you meant with \"fromVertex\".",
-      );
-    }
+    // ⛔ An odd `offset` is not refused either, and it went the same way as the
+    // run's own length (issue #576). The refusal that stood here read an odd
+    // start as a `fromVertex` typed into the wrong field — a real mistake, but
+    // this caught exactly the half of it whose index happens to be odd:
+    // `offset: 4` meant as vertex 4 is the same mistake, lands on vertex 2, and
+    // was always accepted. What it did refuse was every faithful transcription of
+    // a trimmed editor run, one of which ships in `examples/` — `spineboy-pro`'s
+    // `hoverboard-board` starts at 1. A rule that filters one parity of a
+    // confusion it cannot see, at the price of a construct the format holds, is
+    // the wrong instrument; `A35` dropped the same clause in issue #262.
     return key.offset;
   }
   if (key.fromVertex === undefined) return 0;
@@ -5914,7 +6237,12 @@ function deformStart(
   if (!Number.isInteger(from) || from < 0) {
     throw new CompileError(`${where} (t=${key.t}): fromVertex is ${JSON.stringify(from)}; it is a vertex index, so a whole number ≥ 0`);
   }
-  const covered = runLength / 2;
+  // ⌈⌉ rather than ÷, because an odd run REACHES a last vertex without covering
+  // it: its final number is that vertex's x and the y beside it stays at setup
+  // (issue #576). The bound below is about which vertices the run reaches, so the
+  // half-reached one counts — and on a weighted attachment its influence count is
+  // checked with the rest.
+  const covered = Math.ceil(runLength / 2);
   if (from + covered > geometry.vertexCount) {
     throw new CompileError(
       `${where} (t=${key.t}): fromVertex ${from} plus ${covered} vertex offset(s) runs to vertex ${from + covered}, ` +