spine-rigc 0.5.0 → 0.7.0

package/src/compile.ts

@@ -21,6 +21,7 @@ import { basename, dirname, relative, resolve } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { readPngInfo } from './png.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
+import { parseJsonWithPosition } from './json-position.ts';
 import {
   parseRigSpec,
   type RigAttachment,
@@ -51,10 +52,13 @@ import type {
   EasingHandles,
   FaceManifest,
   FaceManifestPart,
+  MotionDeformTrack,
   MotionDrawOrderKey,
   MotionEventKey,
+  MotionIkTrack,
   MotionSpec,
   MotionTrack,
+  MotionTransformTrack,
   RigInfo,
   SpineAttachment,
   SpineBone,
@@ -205,6 +209,78 @@ const PHYSICS_TRACKS: Record<string, { fields: string[]; identity: number[] }> =
   reset: { fields: [], identity: [] },
 };
 
+/**
+ * One numeric channel of a constraint timeline: the JSON field, the value the
+ * parser uses when a key omits it, and — for `mixY` alone — the field it takes
+ * that default FROM.
+ *
+ * Channel order is load-bearing twice over. `readCurve` indexes a curve array by
+ * channel (`curve[value << 2]`), so the order here is the order four-number
+ * groups concatenate in; and the parser reads the fields in this order, so
+ * emitting them in it keeps the file readable against an editor export.
+ */
+interface ConstraintChannel {
+  field: string;
+  dflt: number;
+  /** `mixY` defaults to the SAME key's `mixX`, not to 1 (`:988`). */
+  inheritsFrom?: string;
+}
+
+/** A stepped-by-nature boolean on a constraint key. Never a curve channel. */
+interface ConstraintFlag {
+  field: string;
+  dflt: boolean;
+}
+
+interface ConstraintTimelineShape {
+  channels: ConstraintChannel[];
+  flags: ConstraintFlag[];
+  /** Per-field bounds, where the runtime documents one. */
+  range: Record<string, [number, number]>;
+}
+
+/**
+ * The two constraint groups that are ONE unnamed timeline per constraint
+ * (`animations.<a>.ik.<name>`, `animations.<a>.transform.<name>`).
+ *
+ * ⚠️ Every field is optional in the file and every one has a per-key default, so
+ * omitting a field on one key of a track does not carry the previous key's value
+ * forward — it snaps to the default. `compileConstraintTrack` refuses a track
+ * whose keys disagree about which fields they name, because that is the shape
+ * that loads clean and plays something nobody wrote.
+ *
+ * The bounds: `IkConstraintPose.mix` is documented as a percentage 0-1 and
+ * `softness` as a distance, while every transform mix is documented **unbounded**
+ * — so only the IK pair carries a range, and refusing a transform mix above 1
+ * would refuse correct data (an over-mix is a real editor idiom).
+ */
+const CONSTRAINT_TIMELINES: Record<'ik' | 'transform', ConstraintTimelineShape> = {
+  ik: {
+    channels: [
+      { field: 'mix', dflt: 1 },
+      { field: 'softness', dflt: 0 },
+    ],
+    flags: [
+      { field: 'bendPositive', dflt: true },
+      { field: 'compress', dflt: false },
+      { field: 'stretch', dflt: false },
+    ],
+    range: { mix: [0, 1], softness: [0, Infinity] },
+  },
+  transform: {
+    channels: [
+      { field: 'mixRotate', dflt: 1 },
+      { field: 'mixX', dflt: 1 },
+      { field: 'mixY', dflt: 1, inheritsFrom: 'mixX' },
+      { field: 'mixScaleX', dflt: 1 },
+      { field: 'mixScaleY', dflt: 1 },
+      { field: 'mixShearY', dflt: 1 },
+    ],
+    flags: [],
+    range: {},
+  },
+};
+
 /** Physics constraint fields and their parser defaults (SkeletonJson.js:295-319). */
 const PHYSICS_COMPONENTS = ['x', 'y', 'rotate', 'scaleX', 'shearX'] as const;
 const PHYSICS_PARAMS: Array<[string, number]> = [
@@ -255,8 +331,17 @@ export function bezierForChannel(
 // ---------------------------------------------------------------------------
 
 function readJson<T>(path: string): T {
+  let text: string;
   try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
+    text = readFileSync(path, 'utf8');
+  } catch (err) {
+    throw new CompileError(`cannot read ${path}: ${(err as Error).message}`);
+  }
+  try {
+    // A parse failure gets a line/column appended to the runtime's own
+    // message — see `parseJsonWithPosition` for why `JSON.parse` alone
+    // cannot say where.
+    return parseJsonWithPosition(text) as T;
   } catch (err) {
     throw new CompileError(`cannot read ${path}: ${(err as Error).message}`);
   }
@@ -319,6 +404,36 @@ export interface CompileOptions {
   imagesDir?: string;
 }
 
+/**
+ * One part = one page. No packer, so no PMA trap, no rotation, no strip
+ * offsets. Region covers the page exactly => u2=v2=1.
+ *
+ * Two text-shape traps are load-bearing here:
+ *   * a region name is the RAW line, not a trimmed one -> no indentation;
+ *   * a blank line closes the page block -> none between header and regions.
+ *
+ * Exported (rather than inlined into `compile`) so `--copy-images` can call it a
+ * second time with `page` rewritten to the copies' filenames, after the copy
+ * itself has happened — see [`src/emit.ts`](emit.ts). Everything else about an
+ * image (`region`, `width`, `height`) is unchanged by that rewrite; only where the
+ * bytes live moved.
+ */
+export function buildAtlasText(images: CompiledImage[]): string {
+  const atlasLines: string[] = [];
+  images.forEach((img, i) => {
+    if (i > 0) atlasLines.push(''); // exactly one blank line BETWEEN pages
+    atlasLines.push(img.page);
+    atlasLines.push(`size: ${img.width}, ${img.height}`);
+    atlasLines.push('filter: Linear, Linear');
+    atlasLines.push('pma: false');
+    atlasLines.push(img.region);
+    atlasLines.push(`bounds: 0, 0, ${img.width}, ${img.height}`);
+    atlasLines.push(`offsets: 0, 0, ${img.width}, ${img.height}`);
+    atlasLines.push('rotate: 0');
+  });
+  return `${atlasLines.join('\n')}\n`;
+}
+
 export function compile(opts: CompileOptions): CompileResult {
   const rigPath = resolve(opts.rigPath);
   const motionPath = resolve(opts.motionPath);
@@ -330,17 +445,38 @@ export function compile(opts: CompileOptions): CompileResult {
   const motion = readJson<MotionSpec>(motionPath);
   const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath);
 
-  if (motion.spec !== 'rigc-motion/1') {
-    throw new CompileError(`unknown motion spec version: ${String(motion.spec)}`);
-  }
-  // The motion spec was authored against one formation. Pairing it with another
-  // rig would aim its keys at bones whose names happen to match and whose meaning
-  // does not — the class of wrongness that loads, plays and lies.
-  if (motion.archetype !== rig.name) {
-    throw new CompileError(
-      `motion spec names archetype "${motion.archetype}" but the rig spec at ${rigPath} is called "${rig.name}"`,
-    );
-  }
+  // The rig spec names its own path in every message `parseRigSpec` throws (its
+  // `where` argument, above). The motion spec gets no such treatment below —
+  // every "animation … bone … property" refusal is built from data alone — so a
+  // reader with two input files and one error has no way to tell which one is at
+  // fault. This wraps the motion-only regions (the version/archetype check right
+  // below, the physics table and the animation loop further down) and prefixes
+  // the motion path onto any `CompileError` that escapes them, unless the
+  // message already names it.
+  const withMotionSource = <T>(fn: () => T): T => {
+    try {
+      return fn();
+    } catch (err) {
+      if (err instanceof CompileError && !err.message.includes(motionPath)) {
+        throw new CompileError(`${motionPath}: ${err.message}`);
+      }
+      throw err;
+    }
+  };
+
+  withMotionSource(() => {
+    if (motion.spec !== 'rigc-motion/1') {
+      throw new CompileError(`unknown motion spec version: ${String(motion.spec)}`);
+    }
+    // The motion spec was authored against one formation. Pairing it with another
+    // rig would aim its keys at bones whose names happen to match and whose meaning
+    // does not — the class of wrongness that loads, plays and lies.
+    if (motion.archetype !== rig.name) {
+      throw new CompileError(
+        `motion spec names archetype "${motion.archetype}" but the rig spec at ${rigPath} is called "${rig.name}"`,
+      );
+    }
+  });
 
   // 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
@@ -546,25 +682,7 @@ export function compile(opts: CompileOptions): CompileResult {
   }
 
   // -- 2. atlas --------------------------------------------------------------
-  // One part = one page. No packer, so no PMA trap, no rotation, no strip
-  // offsets. Region covers the page exactly => u2=v2=1.
-  //
-  // Two text-shape traps are load-bearing here:
-  //   * a region name is the RAW line, not a trimmed one -> no indentation;
-  //   * a blank line closes the page block -> none between header and regions.
-  const atlasLines: string[] = [];
-  images.forEach((img, i) => {
-    if (i > 0) atlasLines.push(''); // exactly one blank line BETWEEN pages
-    atlasLines.push(img.page);
-    atlasLines.push(`size: ${img.width}, ${img.height}`);
-    atlasLines.push('filter: Linear, Linear');
-    atlasLines.push('pma: false');
-    atlasLines.push(img.region);
-    atlasLines.push(`bounds: 0, 0, ${img.width}, ${img.height}`);
-    atlasLines.push(`offsets: 0, 0, ${img.width}, ${img.height}`);
-    atlasLines.push('rotate: 0');
-  });
-  const atlasText = `${atlasLines.join('\n')}\n`;
+  const atlasText = buildAtlasText(images);
 
   // -- 3. bones --------------------------------------------------------------
   //
@@ -724,132 +842,248 @@ export function compile(opts: CompileOptions): CompileResult {
   const constraints: SpineConstraint[] = [];
   const physicsReport: CompileResult['physics'] = [];
   const constraintNames = new Set<string>();
+  // `ik` and `transform` timelines resolve their target by name AND by type —
+  // `findConstraint(name, IkConstraintData)` returns null for a transform
+  // constraint of the same name and the parser then throws. Keeping the type
+  // beside the name is what lets the refusal say which of the two it is.
+  const constraintTypes = new Map<string, string>();
   for (const spec of rig.constraints ?? []) {
     constraints.push(buildRigConstraint(spec as RigConstraintInput, boneNames));
     constraintNames.add(spec.name);
+    constraintTypes.set(spec.name, spec.type);
   }
-  for (const [name, spec] of Object.entries(motion.physics ?? {})) {
-    if (constraintNames.has(name)) {
-      throw new CompileError(`constraint "${name}" is declared in both the rig spec and the motion spec's physics table`);
-    }
-    constraintNames.add(name);
-    if (!boneNames.has(spec.bone)) {
-      throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
-    }
-    const entry: SpineConstraint = {
-      name,
-      type: 'physics',
-      bone: spec.bone,
-    };
-    const components: string[] = [];
-    for (const comp of PHYSICS_COMPONENTS) {
-      const v = spec[comp];
-      if (v === undefined || v === 0) continue;
-      entry[comp] = r6(v);
-      components.push(comp);
-    }
-    if (!components.length) {
-      // The parser is happy with this and the constraint does nothing at all.
-      // A23 catches it too; refusing here means it never reaches the gate.
-      throw new CompileError(
-        `physics constraint "${name}" drives no component — set at least one of ${PHYSICS_COMPONENTS.join('/')}`,
-      );
+  withMotionSource(() => {
+    for (const [name, spec] of Object.entries(motion.physics ?? {})) {
+      if (constraintNames.has(name)) {
+        throw new CompileError(`constraint "${name}" is declared in both the rig spec and the motion spec's physics table`);
+      }
+      constraintNames.add(name);
+      constraintTypes.set(name, 'physics');
+      if (!boneNames.has(spec.bone)) {
+        throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
+      }
+      const entry: SpineConstraint = {
+        name,
+        type: 'physics',
+        bone: spec.bone,
+      };
+      const components: string[] = [];
+      for (const comp of PHYSICS_COMPONENTS) {
+        const v = spec[comp];
+        if (v === undefined || v === 0) continue;
+        entry[comp] = r6(v);
+        components.push(comp);
+      }
+      if (!components.length) {
+        // The parser is happy with this and the constraint does nothing at all.
+        // A23 catches it too; refusing here means it never reaches the gate.
+        throw new CompileError(
+          `physics constraint "${name}" drives no component — set at least one of ${PHYSICS_COMPONENTS.join('/')}`,
+        );
+      }
+      for (const [param, dflt] of PHYSICS_PARAMS) {
+        const v = spec[param as keyof typeof spec] as number | undefined;
+        if (v === undefined || v === dflt) continue;
+        entry[param] = r6(v);
+      }
+      constraints.push(entry);
+      physicsReport.push({
+        name,
+        bone: spec.bone,
+        components,
+        mix: spec.mix ?? 1,
+        drivesMesh: meshBones.has(spec.bone),
+      });
     }
-    for (const [param, dflt] of PHYSICS_PARAMS) {
-      const v = spec[param as keyof typeof spec] as number | undefined;
-      if (v === undefined || v === dflt) continue;
-      entry[param] = r6(v);
-    }
-    constraints.push(entry);
-    physicsReport.push({
-      name,
-      bone: spec.bone,
-      components,
-      mix: spec.mix ?? 1,
-      drivesMesh: meshBones.has(spec.bone),
-    });
-  }
+  });
 
   // -- 5. animations ---------------------------------------------------------
   const animations: SpineSkeletonJson['animations'] = {};
   const declaredDurations: Record<string, number> = {};
   const slotNames = new Set(slots.map((s) => s.name));
 
-  for (const [animName, anim] of Object.entries(motion.animations)) {
-    declaredDurations[animName] = anim.duration;
-    const slotTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const boneTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const physicsTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const claimed = new Set<string>();
-    let compiledDuration = 0;
-
-    for (const track of anim.tracks) {
-      const isPhysicsTrack = track.property in PHYSICS_TRACKS;
-      const isBoneTrack = !isPhysicsTrack && track.property in BONE_TRACKS;
-      const targets = resolveTargets(track, motion, animName);
-      targets.forEach((target, index) => {
-        if (isPhysicsTrack) {
-          if (!constraintNames.has(target)) {
-            throw new CompileError(`animation "${animName}" keys unknown physics constraint "${target}"`);
+  withMotionSource(() => {
+    for (const [animName, anim] of Object.entries(motion.animations)) {
+      declaredDurations[animName] = anim.duration;
+      const slotTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const boneTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const physicsTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const claimed = new Set<string>();
+      let compiledDuration = 0;
+
+      for (const track of anim.tracks) {
+        const isPhysicsTrack = track.property in PHYSICS_TRACKS;
+        const isBoneTrack = !isPhysicsTrack && track.property in BONE_TRACKS;
+        const targets = resolveTargets(track, motion, animName);
+        targets.forEach((target, index) => {
+          if (isPhysicsTrack) {
+            if (!constraintNames.has(target)) {
+              throw new CompileError(`animation "${animName}" keys unknown physics constraint "${target}"`);
+            }
+          } else if (isBoneTrack) {
+            if (!boneNames.has(target)) {
+              throw new CompileError(`animation "${animName}" keys unknown bone "${target}"`);
+            }
+          } else if (!slotNames.has(target)) {
+            throw new CompileError(`animation "${animName}" targets unknown slot "${target}"`);
+          }
+          const claim = `${target}.${track.property}`;
+          if (claimed.has(claim)) {
+            throw new CompileError(
+              `animation "${animName}" has two tracks on ${claim}; merge them into one track`,
+            );
+          }
+          claimed.add(claim);
+
+          const shift = (track.lag ?? 0) + (track.stagger ?? 0) * index;
+          const keys = isPhysicsTrack
+            ? compileValueTrack(track, motion, animName, anim.duration, target, shift, PHYSICS_TRACKS, 'physics constraint')
+            : isBoneTrack
+              ? compileValueTrack(track, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
+              : compileTrack(track, motion, animName, anim.duration, target, shift, tableFor('default'));
+          for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
+          if (isPhysicsTrack) (physicsTimelines[target] ??= {})[track.property] = keys;
+          else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
+          else (slotTimelines[target] ??= {})[track.property] = keys;
+        });
+      }
+
+      // -- constraint timelines: one unnamed timeline per constraint ---------
+      //
+      // `ik` and `transform` sit beside `tracks` rather than in it because their
+      // keys carry named fields instead of one `v` — see `MotionAnimation.ik`.
+      // The target is resolved by name AND by type: `findConstraint(name,
+      // IkConstraintData)` misses a transform constraint of the same name and the
+      // parser throws in the consumer's process, so the mismatch is named here.
+      const constraintTimelines: Record<'ik' | 'transform', Record<string, SpineTimelineKey[]>> = {
+        ik: {},
+        transform: {},
+      };
+      for (const group of ['ik', 'transform'] as const) {
+        const tracks: Array<MotionIkTrack | MotionTransformTrack> = anim[group] ?? [];
+        if (!Array.isArray(tracks)) {
+          throw new CompileError(`animation "${animName}": "${group}" must be an array of { constraint, keys } entries`);
+        }
+        for (const track of tracks) {
+          const name = track.constraint;
+          if (typeof name !== 'string' || name.length === 0) {
+            throw new CompileError(`animation "${animName}": a ${group} timeline needs a "constraint" name`);
           }
-        } else if (isBoneTrack) {
-          if (!boneNames.has(target)) {
-            throw new CompileError(`animation "${animName}" keys unknown bone "${target}"`);
+          const type = constraintTypes.get(name);
+          if (type === undefined) {
+            const known = [...constraintTypes.entries()].filter(([, t]) => t === group).map(([n]) => n);
+            throw new CompileError(
+              `animation "${animName}" keys unknown ${group} constraint "${name}"; ` +
+                (known.length
+                  ? `the rig declares ${group} constraint(s): ${known.join(', ')}`
+                  : `the rig declares no ${group} constraint at all`),
+            );
           }
-        } else if (!slotNames.has(target)) {
-          throw new CompileError(`animation "${animName}" targets unknown slot "${target}"`);
+          if (type !== group) {
+            throw new CompileError(
+              `animation "${animName}" keys "${name}" as ${group === 'ik' ? 'an' : 'a'} ${group} constraint, but the rig declares it as a ` +
+                `"${type}" constraint — the parser looks a timeline's target up by name AND type, misses, and throws`,
+            );
+          }
+          if (constraintTimelines[group][name]) {
+            throw new CompileError(
+              `animation "${animName}" has two ${group} timelines on constraint "${name}"; ` +
+                'the group holds one timeline per constraint, so merge them into one',
+            );
+          }
+          const keys = compileConstraintTrack(group, track, motion, animName, anim.duration);
+          for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
+          constraintTimelines[group][name] = keys;
         }
-        const claim = `${target}.${track.property}`;
-        if (claimed.has(claim)) {
+      }
+
+      // -- deform timelines: keyed on a skin/slot/attachment triple ----------
+      // Four deep, because the format is: skin -> slot -> attachment -> timeline
+      // name -> keys. `deform` is one of two timeline names an attachment can
+      // carry (the other is `sequence`), which is why the level exists at all.
+      const deformTimelines: Record<string, Record<string, Record<string, Record<string, SpineTimelineKey[]>>>> = {};
+      const deformTracks: MotionDeformTrack[] = anim.deform ?? [];
+      if (!Array.isArray(deformTracks)) {
+        throw new CompileError(
+          `animation "${animName}": "deform" must be an array of { slot, attachment, keys } entries`,
+        );
+      }
+      for (const track of deformTracks) {
+        const skinName = track.skin ?? 'default';
+        const at = `animation "${animName}" deform ${skinName}/${String(track.slot)}/${String(track.attachment)}`;
+        const table = skinTables.get(skinName);
+        if (!table) {
           throw new CompileError(
-            `animation "${animName}" has two tracks on ${claim}; merge them into one track`,
+            `${at}: this rig emits no skin called "${skinName}" (it emits: ${[...skinTables.keys()].join(', ')})`,
           );
         }
-        claimed.add(claim);
-
-        const shift = (track.lag ?? 0) + (track.stagger ?? 0) * index;
-        const keys = isPhysicsTrack
-          ? compileValueTrack(track, motion, animName, anim.duration, target, shift, PHYSICS_TRACKS, 'physics constraint')
-          : isBoneTrack
-            ? compileValueTrack(track, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
-            : compileTrack(track, motion, animName, anim.duration, target, shift, tableFor('default'));
+        const perSlot = table[track.slot];
+        if (!perSlot) {
+          throw new CompileError(
+            `${at}: skin "${skinName}" gives slot "${String(track.slot)}" no attachments` +
+              (slotNames.has(track.slot) ? '' : ', and this rig does not declare that slot at all'),
+          );
+        }
+        const attachment = perSlot[track.attachment];
+        if (!attachment) {
+          throw new CompileError(
+            `${at}: slot "${track.slot}" in skin "${skinName}" has no attachment "${String(track.attachment)}" ` +
+              `(it has: ${Object.keys(perSlot).join(', ')})`,
+          );
+        }
+        if (deformTimelines[skinName]?.[track.slot]?.[track.attachment]) {
+          throw new CompileError(`${at}: two deform timelines on one attachment; merge them into one`);
+        }
+        const keys = compileDeformTrack(
+          track,
+          motion,
+          animName,
+          anim.duration,
+          deformGeometryOf(attachment, at),
+        );
         for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
-        if (isPhysicsTrack) (physicsTimelines[target] ??= {})[track.property] = keys;
-        else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
-        else (slotTimelines[target] ??= {})[track.property] = keys;
-      });
-    }
+        ((deformTimelines[skinName] ??= {})[track.slot] ??= {})[track.attachment] = { deform: keys };
+      }
 
-    const drawOrder = anim.drawOrder ? compileDrawOrder(anim.drawOrder, animName, anim.duration, slots) : null;
-    if (drawOrder) for (const key of drawOrder) compiledDuration = Math.max(compiledDuration, key.time as number);
-
-    const eventKeys = anim.events ? compileEvents(anim.events, animName, anim.duration, rig.events ?? {}) : null;
-    // An event timeline counts towards the animation's length the same as any
-    // other: `readAnimation` takes the duration from the longest timeline it
-    // built, and `EventTimeline.getDuration()` is its last frame like the rest.
-    if (eventKeys) for (const key of eventKeys) compiledDuration = Math.max(compiledDuration, key.time as number);
-
-    // Rule 4: the declared duration is verified, because skeleton JSON does not
-    // carry one — the loader takes the max key time.
-    //
-    // This arm is about the DECLARED DURATION being wrong, so it compares one
-    // number per animation and tolerates a frame of it. The other arm —
-    // `checkKeyTime`, above, per key — is about a key landing past the end, and
-    // a frame is 16,667 times too coarse to see one. Both are needed: this one
-    // catches an animation that stops a second early, and only that one catches
-    // a key on a track whose neighbour already sits on the declared duration.
-    if (Math.abs(compiledDuration - anim.duration) > FRAME) {
-      throw new CompileError(
-        `animation "${animName}" declares duration ${anim.duration}s but its last key is at ${compiledDuration}s`,
-      );
+      const drawOrder = anim.drawOrder ? compileDrawOrder(anim.drawOrder, animName, anim.duration, slots) : null;
+      if (drawOrder) for (const key of drawOrder) compiledDuration = Math.max(compiledDuration, key.time as number);
+
+      const eventKeys = anim.events ? compileEvents(anim.events, animName, anim.duration, rig.events ?? {}) : null;
+      // An event timeline counts towards the animation's length the same as any
+      // other: `readAnimation` takes the duration from the longest timeline it
+      // built, and `EventTimeline.getDuration()` is its last frame like the rest.
+      if (eventKeys) for (const key of eventKeys) compiledDuration = Math.max(compiledDuration, key.time as number);
+
+      // Rule 4: the declared duration is verified, because skeleton JSON does not
+      // carry one — the loader takes the max key time.
+      //
+      // This arm is about the DECLARED DURATION being wrong, so it compares one
+      // number per animation and tolerates a frame of it. The other arm —
+      // `checkKeyTime`, above, per key — is about a key landing past the end, and
+      // a frame is 16,667 times too coarse to see one. Both are needed: this one
+      // catches an animation that stops a second early, and only that one catches
+      // a key on a track whose neighbour already sits on the declared duration.
+      if (Math.abs(compiledDuration - anim.duration) > FRAME) {
+        throw new CompileError(
+          `animation "${animName}" declares duration ${anim.duration}s but its last key is at ${compiledDuration}s`,
+        );
+      }
+      // Group order is `readAnimation`'s own reading order, so an emitted file
+      // diffs cleanly against an editor export. Each line is conditional, which
+      // is what keeps a spec that uses none of the new groups byte-identical.
+      animations[animName] = {};
+      if (Object.keys(slotTimelines).length) animations[animName].slots = slotTimelines;
+      if (Object.keys(boneTimelines).length) animations[animName].bones = boneTimelines;
+      if (Object.keys(constraintTimelines.ik).length) animations[animName].ik = constraintTimelines.ik;
+      if (Object.keys(constraintTimelines.transform).length) {
+        animations[animName].transform = constraintTimelines.transform;
+      }
+      if (Object.keys(physicsTimelines).length) animations[animName].physics = physicsTimelines;
+      if (Object.keys(deformTimelines).length) animations[animName].attachments = deformTimelines;
+      if (drawOrder) animations[animName].drawOrder = drawOrder;
+      if (eventKeys) animations[animName].events = eventKeys;
     }
-    animations[animName] = {};
-    if (Object.keys(slotTimelines).length) animations[animName].slots = slotTimelines;
-    if (Object.keys(boneTimelines).length) animations[animName].bones = boneTimelines;
-    if (Object.keys(physicsTimelines).length) animations[animName].physics = physicsTimelines;
-    if (drawOrder) animations[animName].drawOrder = drawOrder;
-    if (eventKeys) animations[animName].events = eventKeys;
-  }
+  });
 
   // -- 6. assemble -----------------------------------------------------------
   const header: SpineSkeletonJson['skeleton'] = {
@@ -2063,6 +2297,431 @@ function compileEvents(
   return out;
 }
 
+/**
+ * An IK or transform constraint keyed over time — `animations.<a>.<group>.<name>`.
+ *
+ * One function for both because the two differ only in their field table: the
+ * group is one unnamed timeline per constraint, every field is optional with a
+ * per-key default, and the curve concatenates four numbers per channel in field
+ * order. `CONSTRAINT_TIMELINES` holds what differs.
+ *
+ * 🚨 The refusal that is not obvious is the **uniform field set**. In this format
+ * a key does not inherit anything from the key before it: `getValue(keyMap,
+ * "softness", 0)` is read fresh per key, so a track written as
+ *
+ * ```
+ * { "t": 0, "mix": 1, "softness": 20 },  { "t": 1, "mix": 0 }
+ * ```
+ *
+ * does not hold softness at 20 and fade the mix out — it snaps softness to 0 at
+ * t=1 and interpolates from 20 down to 0 on the way, which is a thing the author
+ * did not write and cannot see. It loads, it plays, and it is wrong. So every key
+ * of a track has to name the same fields; stating the default explicitly is the
+ * way to opt in.
+ *
+ * ⚠️ The values a curve is built between are the **effective** ones — the
+ * author's number where there is one, the parser's default where there is not.
+ * That is reading the format, not inventing a value: it is exactly what the
+ * runtime will interpolate, and a bezier built against anything else would
+ * describe a curve the player does not play.
+ */
+function compileConstraintTrack(
+  group: 'ik' | 'transform',
+  track: MotionIkTrack | MotionTransformTrack,
+  motion: MotionSpec,
+  animName: string,
+  duration: number,
+): SpineTimelineKey[] {
+  const shape = CONSTRAINT_TIMELINES[group];
+  const article = group === 'ik' ? 'an' : 'a';
+  const where = `animation "${animName}" ${group} constraint "${track.constraint}"`;
+  const keys = track.keys;
+  if (!Array.isArray(keys) || keys.length === 0) throw new CompileError(`${where}: no keys`);
+
+  const read = (key: MotionIkTrack['keys'][number] | MotionTransformTrack['keys'][number], field: string): unknown =>
+    (key as unknown as Record<string, unknown>)[field];
+  const named = (key: MotionIkTrack['keys'][number] | MotionTransformTrack['keys'][number]): string[] =>
+    [...shape.channels, ...shape.flags].map((c) => c.field).filter((field) => read(key, field) !== undefined);
+
+  // The uniform-field-set rule, checked against key 0 so the message can name the
+  // key that differs rather than "some key".
+  const first = named(keys[0]);
+  const firstSet = new Set(first);
+  keys.forEach((key, i) => {
+    if (i === 0) return;
+    const here = named(key);
+    for (const field of here) {
+      if (firstSet.has(field)) continue;
+      throw new CompileError(
+        `${where}: key ${i} (t=${key.t}) names "${field}" and key 0 does not. Every key of ${article} ${group} timeline ` +
+          'is read with its own default, so a field stated on some keys and not others snaps to the default on ' +
+          'the rest — state it on every key or on none.',
+      );
+    }
+    for (const field of first) {
+      if (here.includes(field)) continue;
+      throw new CompileError(
+        `${where}: key 0 names "${field}" and key ${i} (t=${key.t}) does not. Every key of ${article} ${group} timeline ` +
+          `is read with its own default, so "${field}" would snap to ` +
+          `${JSON.stringify(defaultOf(shape, field))} at t=${key.t} — state it on every key or on none.`,
+      );
+    }
+  });
+
+  /** The value the runtime will see for `field` on this key: authored, or default. */
+  const effective = (key: MotionIkTrack['keys'][number] | MotionTransformTrack['keys'][number], channel: ConstraintChannel): number => {
+    const v = read(key, channel.field);
+    if (v !== undefined) return v as number;
+    if (channel.inheritsFrom === undefined) return channel.dflt;
+    const inherited = read(key, channel.inheritsFrom);
+    return inherited === undefined ? channel.dflt : (inherited as number);
+  };
+
+  const out: SpineTimelineKey[] = [];
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const next = keys[i + 1];
+    if (!Number.isFinite(key.t)) throw new CompileError(`${where}: key ${i} has a non-finite time ${String(key.t)}`);
+    const time = keyTime(key.t);
+    if (i > 0 && time <= (out[i - 1].time as number)) {
+      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`);
+    }
+    checkKeyTime(where, time, key.t, duration);
+
+    const entry: SpineTimelineKey = { time };
+    for (const channel of shape.channels) {
+      const v = read(key, channel.field);
+      if (v === undefined) continue;
+      if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new CompileError(`${where} (t=${key.t}): ${channel.field} is ${JSON.stringify(v)}, not a finite number`);
+      }
+      const bounds = shape.range[channel.field];
+      if (bounds && (v < bounds[0] || v > bounds[1])) {
+        throw new CompileError(
+          `${where} (t=${key.t}): ${channel.field} is ${v}, outside ${bounds[0]}..${
+            bounds[1] === Infinity ? '∞' : bounds[1]
+          } — the runtime documents it as ${channel.field === 'mix' ? 'a percentage 0-1' : 'a distance'}`,
+        );
+      }
+      entry[channel.field] = r6(v);
+    }
+    for (const flag of shape.flags) {
+      const v = read(key, flag.field);
+      if (v === undefined) continue;
+      if (typeof v !== 'boolean') {
+        throw new CompileError(`${where} (t=${key.t}): ${flag.field} is ${JSON.stringify(v)}, not true or false`);
+      }
+      entry[flag.field] = v;
+    }
+
+    if (key.ease !== undefined && key.curve !== undefined) {
+      throw new CompileError(`${where}: a key carries both a named easing and a raw curve; pick one`);
+    }
+    if (key.curve !== undefined) {
+      if (!next) throw new CompileError(`${where}: last key carries a curve but has nothing to ease to`);
+      entry.curve = rawCurve(key.curve, shape.channels.length, where, String(key.t));
+    } else if (key.ease !== undefined && next) {
+      if (key.ease === 'stepped') {
+        entry.curve = 'stepped';
+      } else {
+        const handles = motion.easings?.[key.ease];
+        if (!handles) throw new CompileError(`${where}: unknown easing "${key.ease}"`);
+        const t2 = keyTime(next.t);
+        const curve: number[] = [];
+        for (const channel of shape.channels) {
+          curve.push(...bezierForChannel(handles, time, t2, effective(key, channel), effective(next, channel)));
+        }
+        entry.curve = curve;
+      }
+    } else if (key.ease !== undefined && !next) {
+      throw new CompileError(`${where}: last key carries an easing but has nothing to ease to`);
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+/** The parser default for one field of a constraint timeline, for a message. */
+function defaultOf(shape: ConstraintTimelineShape, field: string): number | boolean {
+  const channel = shape.channels.find((c) => c.field === field);
+  if (channel) return channel.dflt;
+  return shape.flags.find((f) => f.field === field)?.dflt ?? 0;
+}
+
+/**
+ * What a deform key is editing: the array the parser builds for one attachment.
+ *
+ * The two encodings are the reason this is derived rather than assumed, and they
+ * are the same split `readVertices` makes when it decides whether a `vertices`
+ * array is coordinates or a weight run:
+ *
+ *   unweighted — `deformLength = vertices.length`, one `x, y` pair per vertex;
+ *   weighted   — `deformLength = vertices.length / 3 * 2`, one pair per bone
+ *                INFLUENCE, because the loaded `vertices` is `x, y, weight` per
+ *                influence.
+ *
+ * Same shape, two meanings, and picking the wrong one writes a run that silently
+ * lands on the wrong vertices.
+ */
+interface DeformGeometry {
+  weighted: boolean;
+  /** How long the array the key edits is. */
+  deformLength: number;
+  vertexCount: number;
+  /** Bone influences per vertex, in vertex order. Null on an unweighted attachment. */
+  boneCounts: number[] | null;
+}
+
+/**
+ * Measure one emitted attachment's deform array.
+ *
+ * A region attachment is refused rather than measured: it has no `vertices` at
+ * all, so `attachment.vertices.length` throws inside the parser — one of the very
+ * few places this format fails loudly, and it fails in the consumer's process.
+ */
+function deformGeometryOf(att: SpineAttachment, where: string): DeformGeometry {
+  const type = (att as { type?: string }).type ?? 'region';
+  let worldVerticesLength: number;
+  if (type === 'mesh') {
+    worldVerticesLength = (att as SpineMeshAttachment).uvs.length;
+  } else if (type === 'boundingbox' || type === 'clipping') {
+    worldVerticesLength = (att as SpineBoundingBoxAttachment).vertexCount * 2;
+  } else {
+    throw new CompileError(
+      `${where}: a deform timeline keys the vertices of an attachment, and this one is a "${type}" — ` +
+        'it has no vertex array to deform. Deformable types: mesh, boundingbox, clipping.',
+    );
+  }
+  const vertices = (att as SpineMeshAttachment).vertices ?? [];
+  const weighted = vertices.length !== worldVerticesLength;
+  if (!weighted) {
+    return { weighted, deformLength: worldVerticesLength, vertexCount: worldVerticesLength / 2, boneCounts: null };
+  }
+  // Walk the weight run for the per-vertex influence counts. The run's own shape
+  // is already assured by the attachment builders and by A33/A04; this only
+  // counts, and a malformed run stops rather than producing a plausible number.
+  const boneCounts: number[] = [];
+  for (let i = 0; i < vertices.length; ) {
+    const n = vertices[i++];
+    if (!Number.isInteger(n) || n < 1) {
+      throw new CompileError(`${where}: the attachment's weighted vertex run has a bone count of ${String(n)} at index ${i - 1}`);
+    }
+    i += n * 4;
+    if (i > vertices.length) {
+      throw new CompileError(`${where}: the attachment's weighted vertex run is truncated at vertex ${boneCounts.length}`);
+    }
+    boneCounts.push(n);
+  }
+  const influences = vertices.length / 3;
+  return { weighted, deformLength: influences * 2, vertexCount: boneCounts.length, boneCounts };
+}
+
+/**
+ * One attachment's geometry keyed over time —
+ * `animations.<a>.attachments.<skin>.<slot>.<attachment>.deform`.
+ *
+ * ⭐ Every refusal below is a silent failure of the parser's own deform branch,
+ * and the first is the one that matters most:
+ *
+ *   1. **A run that does not fit.** The parser copies with
+ *      `Utils.arrayCopy(vertices, 0, deform, start, vertices.length)` into a
+ *      `Float32Array` sized from the attachment. Writing past the end of a typed
+ *      array is a **no-op in JavaScript** — no throw, no warning — so a run one
+ *      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
+ *      offset — a NaN in the deform array propagates into world vertices.
+ *
+ * `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
+ * the array is indexed in influences. On an **unweighted** attachment the two
+ * coincide, so the translation is exact. On a **weighted** one it is exact only
+ * where each vertex the run covers has exactly ONE bone on it; with two bones a
+ * vertex occupies two pairs and "move vertex 3 by (dx, dy)" is not a statement
+ * the array can hold — the world offset would be
+ * `Σ weightᵦ · Mᵦ · (dx, dy)`, which equals `(dx, dy)` only if every influencing
+ * bone happens to share one world matrix. So that case is refused by name and
+ * `offset` stays available for an author who really is writing bind-space
+ * offsets per influence.
+ */
+function compileDeformTrack(
+  track: MotionDeformTrack,
+  motion: MotionSpec,
+  animName: string,
+  duration: number,
+  geometry: DeformGeometry,
+): SpineTimelineKey[] {
+  const skin = track.skin ?? 'default';
+  const where = `animation "${animName}" deform ${skin}/${track.slot}/${track.attachment}`;
+  const keys = track.keys;
+  if (!Array.isArray(keys) || keys.length === 0) throw new CompileError(`${where}: no keys`);
+
+  const out: SpineTimelineKey[] = [];
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (!Number.isFinite(key.t)) throw new CompileError(`${where}: key ${i} has a non-finite time ${String(key.t)}`);
+    const time = keyTime(key.t);
+    if (i > 0 && time <= (out[i - 1].time as number)) {
+      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`);
+    }
+    checkKeyTime(where, time, key.t, duration);
+    if (key.offset !== undefined && key.fromVertex !== undefined) {
+      throw new CompileError(
+        `${where} (t=${key.t}): a key gives its start as "offset" (an index into the deform array) or as ` +
+          '"fromVertex" (a vertex index rigc translates), never both',
+      );
+    }
+    const run = key.vertices ?? null;
+    if (run === null) {
+      // The parser's own encoding for "no edit": with no `vertices` the deform is
+      // the setup pose. `offset`/`fromVertex` would be pointing into nothing, and
+      // two spellings of one key must not emit two different files.
+      if (key.offset !== undefined || key.fromVertex !== undefined) {
+        throw new CompileError(
+          `${where} (t=${key.t}): the key has no "vertices", which is the format's way of saying "back to the ` +
+            'setup pose" — so there is nothing for a start index to point at. Drop the offset, or give it a run.',
+        );
+      }
+      out.push(deformKeyCurve({ time }, key, keys, i, motion, where));
+      continue;
+    }
+    if (!Array.isArray(run) || run.length === 0) {
+      throw new CompileError(
+        `${where} (t=${key.t}): "vertices" is ${JSON.stringify(key.vertices)}; give an array of x, y offsets, ` +
+          '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`,
+      );
+    }
+    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)}`);
+      }
+    }
+    const start = deformStart(key, run.length, geometry, where);
+    if (start + run.length > geometry.deformLength) {
+      throw new CompileError(
+        `${where} (t=${key.t}): the run starts at deform index ${start} and is ${run.length} long, which ends at ` +
+          `${start + run.length}; this attachment's deform array is ${geometry.deformLength} long ` +
+          `(${geometry.weighted ? `${geometry.deformLength / 2} bone influences` : `${geometry.vertexCount} vertices`}). ` +
+          'The parser copies into a Float32Array, so everything past the end is dropped without a word.',
+      );
+    }
+    const entry: SpineTimelineKey = { time };
+    // `offset` defaults to 0 in the parser and the editor omits it there, so an
+    // authored 0, an authored `fromVertex: 0` and an absent start all emit the
+    // same bytes — one meaning, one file.
+    if (start !== 0) entry.offset = start;
+    entry.vertices = run.map(r6);
+    out.push(deformKeyCurve(entry, key, keys, i, motion, where));
+  }
+  return out;
+}
+
+/**
+ * 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.
+ */
+function deformStart(
+  key: MotionDeformTrack['keys'][number],
+  runLength: number,
+  geometry: DeformGeometry,
+  where: string,
+): number {
+  if (key.offset !== undefined) {
+    if (!Number.isInteger(key.offset) || key.offset < 0) {
+      throw new CompileError(
+        `${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\".",
+      );
+    }
+    return key.offset;
+  }
+  if (key.fromVertex === undefined) return 0;
+  const from = key.fromVertex;
+  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;
+  if (from + covered > geometry.vertexCount) {
+    throw new CompileError(
+      `${where} (t=${key.t}): fromVertex ${from} plus ${covered} vertex offset(s) runs to vertex ${from + covered}, ` +
+        `and the attachment has ${geometry.vertexCount}`,
+    );
+  }
+  if (!geometry.weighted) return from * 2;
+  const counts = geometry.boneCounts!;
+  for (let v = from; v < from + covered; v++) {
+    if (counts[v] === 1) continue;
+    throw new CompileError(
+      `${where} (t=${key.t}): "fromVertex" counts VERTICES, and this attachment is weighted — its deform array ` +
+        `holds one x, y pair per bone INFLUENCE, and vertex ${v} has ${counts[v]} of them. One offset per vertex ` +
+        'is not a thing that array can hold: the world offset of a multi-bone vertex is the weighted sum of a ' +
+        'per-bone offset in each bone\'s own bind space, so rigc will not guess one for you. Either key the ' +
+        'control bone instead, or write the bind-space pairs yourself and start the run with "offset" ' +
+        `(vertex ${from} starts at deform index ${2 * counts.slice(0, from).reduce((a, b) => a + b, 0)}).`,
+    );
+  }
+  let start = 0;
+  for (let v = 0; v < from; v++) start += counts[v];
+  return start * 2;
+}
+
+/**
+ * A deform key's curve.
+ *
+ * One channel, and it is not any value in `vertices`: `readCurve(curve, timeline,
+ * bezier, frame, 0, time, time2, 0, 1, 1)` builds the cubic between **0 and 1**,
+ * the fraction of the way from this key's geometry to the next one's. So a named
+ * easing here is the same shape it would be anywhere, applied to the blend rather
+ * than to a coordinate, and a raw curve is four numbers whose value axis is 0..1.
+ */
+function deformKeyCurve(
+  entry: SpineTimelineKey,
+  key: MotionDeformTrack['keys'][number],
+  keys: MotionDeformTrack['keys'],
+  index: number,
+  motion: MotionSpec,
+  where: string,
+): SpineTimelineKey {
+  const hasNext = index + 1 < keys.length;
+  if (key.ease !== undefined && key.curve !== undefined) {
+    throw new CompileError(`${where}: a key carries both a named easing and a raw curve; pick one`);
+  }
+  if (key.curve !== undefined) {
+    if (!hasNext) throw new CompileError(`${where}: last key carries a curve but has nothing to ease to`);
+    entry.curve = rawCurve(key.curve, 1, where, String(key.t));
+    return entry;
+  }
+  if (key.ease === undefined) return entry;
+  if (!hasNext) throw new CompileError(`${where}: last key carries an easing but has nothing to ease to`);
+  if (key.ease === 'stepped') {
+    entry.curve = 'stepped';
+    return entry;
+  }
+  const handles = motion.easings?.[key.ease];
+  if (!handles) throw new CompileError(`${where}: unknown easing "${key.ease}"`);
+  entry.curve = bezierForChannel(handles, entry.time as number, keyTime(keys[index + 1].t), 0, 1);
+  return entry;
+}
+
 function resolveTargets(track: MotionTrack, motion: MotionSpec, animName: string): string[] {
   const named = [track.slot, track.group, track.bone, track.physics].filter((v) => v !== undefined);
   if (named.length > 1) {