spine-rigc 0.25.6 → 0.26.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 {
+  constraintAt,
   declaresNoStage,
   parseRigSpec,
   RIG_FROM_PROPERTIES,
@@ -55,6 +56,7 @@ import {
   type RigBoundingBoxAttachment,
   type RigClippingAttachment,
   type RigEvent,
+  type RigLinkedMeshAttachment,
   type RigMeshAttachment,
   type RigMeshBinding,
   type RigPathAttachment,
@@ -131,6 +133,7 @@ import type {
   SpineClippingAttachment,
   SpineConstraint,
   SpineEvent,
+  SpineLinkedMeshAttachment,
   SpineMeshAttachment,
   SpinePathAttachment,
   SpineRegionAttachment,
@@ -735,6 +738,26 @@ function rgbaHex(v: number[]): string {
   return v.map(channelHex).join('');
 }
 
+/**
+ * A two-colour key's seven channels, as the pair of hex strings the format
+ * carries: `light` is `rrggbbaa`, `dark` is `rrggbb`.
+ *
+ * ⚠️ **Seven and not eight**, and the asymmetry is the format's rather than a
+ * simplification here. `RGBA2Timeline.setFrame(frame, time, r, g, b, a, r2, g2,
+ * b2)` stores three dark channels and no fourth, and `SkeletonJson`'s `rgba2`
+ * branch reads `Color.fromString(keyMap.dark)` into a colour whose alpha it then
+ * never passes on. `Color.setFromString` does fill one — `a = hex.length !== 8 ?
+ * 1 : …` — so a `dark` written with eight digits loads without complaint and the
+ * eighth pair is dropped one line later. Emitting six is emitting what is read.
+ *
+ * The channel ORDER is the format's too, and it is what a curve array indexes
+ * by: `readCurve(…, 0..3, light r/g/b/a)` then `readCurve(…, 4..6, dark r/g/b)`.
+ */
+function rgba2Hex(v: number[]): { light: string; dark: string } {
+  if (v.length !== 7) throw new CompileError(`rgba2 value needs 7 channels, got ${v.length}`);
+  return { light: v.slice(0, 4).map(channelHex).join(''), dark: v.slice(4, 7).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
@@ -893,12 +916,21 @@ const SLIDER_TRACKS: Record<string, ValueTrackShape> = {
  * the branch below that writes its keys — so an entry added here without a
  * branch to write it is an entry emitted in some other timeline's shape, which
  * is the defect this table closed rather than a new affordance. The format has
- * four more (`rgb`, `alpha`, `rgba2`, `rgb2`); rigc emits none of them, and
- * `A12_NO_DARK_COLOR` refuses the last two outright.
+ * three more (`rgb`, `alpha`, `rgb2`) and rigc emits none of them.
+ *
+ * 🎨 `rgba2` joined in issue #690, and what it adds is the half of the two-colour
+ * tint that moves: a slot's `dark` has been an emitted setup field all along
+ * (`RigSlot.dark`, step 4 below), with no way to key it. 🚫 Both halves are still
+ * refused by `A12_NO_DARK_COLOR`, and that is not a contradiction — A12 is filed
+ * `renderer` in `ASSERTION_KIND`, so it states what ONE renderer ignores rather
+ * than what is wrong. The `spine` profile `build` runs reports it `PROF` and
+ * never applies it; `--profile spine-html` is where it fires. Emitting a
+ * construct one consumer drops is exactly what a profile is for.
  */
-export const SLOT_TRACKS: Record<string, 'attachment' | 'rgba'> = {
+export const SLOT_TRACKS: Record<string, 'attachment' | 'rgba' | 'rgba2'> = {
   attachment: 'attachment',
   rgba: 'rgba',
+  rgba2: 'rgba2',
 };
 
 /**
@@ -1988,6 +2020,8 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     }
     return table;
   };
+  /** Linked meshes to resolve once every skin exists — see `resolveLinkedMeshes`. */
+  const pendingLinks: PendingLink[] = [];
   tableFor('default'); // rigc always emits a default skin, even when it is empty
   // ...and every skin the rig declares, for the same reason: a skin can now carry
   // `bones`/constraint lists with no attachments at all, and a skin that only
@@ -2158,6 +2192,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           imagesDir,
           depths: attachmentDepths,
           slotNames: new Set(rig.slots.map((s) => s.name)),
+          links: pendingLinks,
         });
         // The name is put on AFTER the builder rather than inside it: five
         // builders write five shapes, the rule is one rule, and a rule that has
@@ -2172,6 +2207,10 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
       tableFor(skinName)[rigSlot.name] = perSlot;
     }
   }
+  // Every skin is built, so every `source` can now be looked up — and until this
+  // line a linked mesh is the one construct in a rig spec whose name has not been
+  // resolved yet.
+  resolveLinkedMeshes(pendingLinks, skinTables);
   // 📐 The implicit budget of 0 is a statement about rigc's own GENERATORS:
   // geometry rigc built is geometry rigc will not ship unmeasured, and
   // `A13_MESH_BUDGET` has nothing to measure a generated mesh against until the
@@ -2215,12 +2254,22 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   const deformTransforms: CompileResult['deformTransforms'] = [];
   /** Group-track keys whose per-member values were stated or derived (issue #295). */
   const trackDerivations: CompileResult['trackDerivations'] = [];
-  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>();
+  // constraint of the same name and the parser then throws. So the table this
+  // compiler resolves against is keyed by BOTH (issue #692): a name alone is not
+  // a constraint in this format, and a rig may declare `leg` once per kind.
+  /** `<kind> constraint "<name>"` -> declared. The key is the format's namespace. */
+  const constraintDeclared = new Set<string>();
+  /** name -> the kinds that declare it, for the refusal that has to say which. */
+  const constraintKinds = new Map<string, string[]>();
+  /** kind -> the names it declares, for the "the rig declares: …" half of one. */
+  const constraintNamesOfKind = new Map<string, string[]>();
+  const declareConstraint = (name: string, type: string): void => {
+    constraintDeclared.add(constraintAt(type, name));
+    constraintKinds.set(name, [...(constraintKinds.get(name) ?? []), type]);
+    constraintNamesOfKind.set(type, [...(constraintNamesOfKind.get(type) ?? []), name]);
+  };
   /**
    * ik constraint -> the booleans it declares that the timeline format would
    * otherwise take away from it. Issue #273.
@@ -2262,8 +2311,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // wrote in it and the union above is a claim about a correct one.
   for (const spec of (rig.constraints ?? []) as unknown as RigConstraintInput[]) {
     constraints.push(buildRigConstraint(spec, constraintCtx));
-    constraintNames.add(spec.name);
-    constraintTypes.set(spec.name, spec.type);
+    declareConstraint(spec.name, spec.type);
     if (spec.type === 'ik') {
       const carried: Record<string, boolean> = {};
       for (const flag of CONSTRAINT_TIMELINES.ik.flags) {
@@ -2275,11 +2323,16 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   }
   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`);
+      // Per kind, like everything else about a constraint name: a rig-declared
+      // `ik` and a tuned `physics` constraint of one name are two objects, and
+      // two PHYSICS constraints of one name are the pair no timeline can tell
+      // apart.
+      if (constraintDeclared.has(constraintAt('physics', name))) {
+        throw new CompileError(
+          `physics constraint "${name}" is declared in both the rig spec and the motion spec's physics table`,
+        );
       }
-      constraintNames.add(name);
-      constraintTypes.set(name, 'physics');
+      declareConstraint(name, 'physics');
       if (!boneNames.has(spec.bone)) {
         throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
       }
@@ -2353,6 +2406,12 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   const animations: SpineSkeletonJson['animations'] = {};
   const declaredDurations: Record<string, number> = {};
   const slotNames = new Set(slots.map((s) => s.name));
+  // Which slots an `rgba2` timeline may be keyed on: the ones the EMITTED file
+  // gives a `dark`, for the same reason `attachmentIndex` is built off the
+  // emitted skins — what the runtime does with a timeline depends on the file,
+  // not on the spec that produced it. A slot whose `dark` never reached the
+  // artifact is a slot the runtime allocates no dark colour for (issue #690).
+  const darkSlots = new Set(slots.filter((s) => s.dark !== undefined).map((s) => s.name));
 
   withMotionSource(() => {
     checkMotionGroups(motion);
@@ -2382,22 +2441,24 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           const resolved = perMember.get(target)!;
           if (family !== null) {
             const label = CONSTRAINT_TRACK_FAMILIES[family].label;
-            if (!constraintNames.has(target)) {
-              const known = [...constraintTypes.entries()].filter(([, t]) => t === family).map(([n]) => n);
-              throw new CompileError(
-                `animation "${animName}" keys unknown ${label} "${target}"` +
-                  (known.length ? ` (the rig declares: ${known.join(', ')})` : `, and the rig declares no ${family} constraint at all`),
-              );
-            }
             // Resolved by name AND by type in the parser
             // (`findConstraint(name, PathConstraintData)`), which returns null on
             // a type mismatch and makes `readAnimation` throw in the consumer's
-            // process. Named here instead, where the motion file can be named too.
-            const declared = constraintTypes.get(target);
-            if (declared !== family) {
+            // process. Named here instead, where the motion file can be named too
+            // — and looked up the same way, so a rig that declares `leg` under two
+            // kinds sends each track to its own constraint.
+            if (!constraintDeclared.has(constraintAt(family, target))) {
+              const kinds = constraintKinds.get(target) ?? [];
+              if (kinds.length > 0) {
+                throw new CompileError(
+                  `animation "${animName}" keys "${target}" as a ${label}, but the rig declares it as a "${kinds.join('"/"')}" ` +
+                    'constraint — a timeline group resolves its target by name AND type, misses, and the loader throws',
+                );
+              }
+              const known = constraintNamesOfKind.get(family) ?? [];
               throw new CompileError(
-                `animation "${animName}" keys "${target}" as a ${label}, but the rig declares it as a "${declared}" ` +
-                  'constraint — a timeline group resolves its target by name AND type, misses, and the loader throws',
+                `animation "${animName}" keys unknown ${label} "${target}"` +
+                  (known.length ? ` (the rig declares: ${known.join(', ')})` : `, and the rig declares no ${family} constraint at all`),
               );
             }
           } else if (isBoneTrack) {
@@ -2407,10 +2468,14 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           } else if (!slotNames.has(target)) {
             throw new CompileError(`animation "${animName}" targets unknown slot "${target}"`);
           }
-          const claim = `${target}.${track.property}`;
+          // A timeline is a kind, a name and a property — `physics.leg.mix` and
+          // `path.leg.mix` are two timelines on two constraints, so the claim
+          // carries the family the target was resolved in (issue #692). The
+          // sentence still names the pair the author wrote.
+          const claim = `${family ?? (isBoneTrack ? 'bone' : 'slot')} ${target}.${track.property}`;
           if (claimed.has(claim)) {
             throw new CompileError(
-              `animation "${animName}" has two tracks on ${claim}; merge them into one track`,
+              `animation "${animName}" has two tracks on ${target}.${track.property}; merge them into one track`,
             );
           }
           claimed.add(claim);
@@ -2430,7 +2495,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
                 )
               : isBoneTrack
                 ? compileValueTrack(resolved, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
-                : compileTrack(resolved, motion, animName, anim.duration, target, shift, attachmentIndex);
+                : compileTrack(resolved, motion, animName, anim.duration, target, shift, attachmentIndex, darkSlots);
           for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
           if (family !== null) (familyTimelines[family][target] ??= {})[track.property] = keys;
           else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
@@ -2456,9 +2521,15 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         const tracks: Array<MotionIkTrack | MotionTransformTrack> = anim[group] ?? [];
         for (const track of tracks) {
           const name = track.constraint;
-          const type = constraintTypes.get(name);
-          if (type === undefined) {
-            const known = [...constraintTypes.entries()].filter(([, t]) => t === group).map(([n]) => n);
+          if (!constraintDeclared.has(constraintAt(group, name))) {
+            const kinds = constraintKinds.get(name) ?? [];
+            if (kinds.length > 0) {
+              throw new CompileError(
+                `animation "${animName}" keys "${name}" as ${group === 'ik' ? 'an' : 'a'} ${group} constraint, but the rig declares it as a ` +
+                  `"${kinds.join('"/"')}" constraint — the parser looks a timeline's target up by name AND type, misses, and throws`,
+              );
+            }
+            const known = constraintNamesOfKind.get(group) ?? [];
             throw new CompileError(
               `animation "${animName}" keys unknown ${group} constraint "${name}"; ` +
                 (known.length
@@ -2466,12 +2537,6 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
                   : `the rig declares no ${group} constraint at all`),
             );
           }
-          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}"; ` +
@@ -2484,7 +2549,10 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
             motion,
             animName,
             anim.duration,
-            ikRigFlags.get(name) ?? {},
+            // The ik table, asked only by the ik group: `leg` may also be a
+            // transform constraint, and a transform key set carries no flag for
+            // the rig's booleans to be stamped onto (issue #692).
+            group === 'ik' ? (ikRigFlags.get(name) ?? {}) : {},
           );
           for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
           constraintTimelines[group][name] = keys;
@@ -3055,8 +3123,14 @@ function nameSkinAttachment(att: SpineAttachment, name: string, placeholder: str
   // Key order is the parser's reading order — `name`, then `path`, then the rest
   // as the builder wrote it — for the same reason every other emitted object
   // follows it: the file is read by people and diffed against references.
-  if (kind !== 'region' && kind !== 'mesh') return { name, ...att };
-  const { path, ...rest } = att as SpineRegionAttachment | SpineMeshAttachment;
+  //
+  // ⚠️ The three kinds here are the three the parser gives a texture `path` to,
+  // and `linkedmesh` is one of them (`SkeletonJson.ts:541`, `:570` — the mesh
+  // branch is shared). Leaving it out would write a `name` and no `path`, and
+  // `path` defaults to `name`, so a contested link would resolve the region
+  // "<skin>/<placeholder>", which no atlas holds.
+  if (kind !== 'region' && kind !== 'mesh' && kind !== 'linkedmesh') return { name, ...att };
+  const { path, ...rest } = att as SpineRegionAttachment | SpineMeshAttachment | SpineLinkedMeshAttachment;
   return { name, path: path ?? placeholder, ...rest } as SpineAttachment;
 }
 
@@ -3093,11 +3167,37 @@ interface AttachmentContext {
   depths: Map<string, number[]>;
   /** Every slot the rig declares — a clipping attachment's `end` resolves here. */
   slotNames: Set<string>;
+  /**
+   * Linked meshes whose `source` is still unresolved — `resolveLinkedMeshes`
+   * empties it once every skin has been built.
+   *
+   * ⭐ Deferred for the reason spine-core defers its own (`this.linkedMeshes`,
+   * `SkeletonJson.js:56` filled at `:581` and drained at `:427-449`): a link may
+   * name a source in a skin or a slot this loop has not reached yet, so resolving
+   * it in place would refuse a correct rig on nothing but declaration order.
+   */
+  links: PendingLink[];
+}
+
+/** One linked mesh, with everything a refusal has to name once the skins exist. */
+interface PendingLink {
+  where: string;
+  /** What it asked for, the parser's defaults already applied. */
+  skin: string;
+  slot: string;
+  source: string;
+  /**
+   * Whether the author wrote `skin`/`slot` or is taking the parser's default —
+   * which is the half of the refusal that says where a name came from, and the
+   * one an author who wrote neither key needs most.
+   */
+  skinStated: boolean;
+  slotStated: boolean;
 }
 
 /**
  * The seven `type` values `readAttachment` has a branch for (`:540-651`), and
- * the five rigc emits.
+ * the six 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 —
@@ -3107,22 +3207,24 @@ interface AttachmentContext {
  * 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;
+const EMITTED_ATTACHMENT_TYPES = ['region', 'mesh', 'linkedmesh', '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.
+ * part 1-6's row, restated where the refusal can print it.
  *
  * ⭐ 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
+ * point 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.
+ *
+ * ⚠️ `linkedmesh` was the other entry until issue #691 emitted it. The sentence
+ * below no longer says *"neither a point nor a linked mesh appears anywhere in
+ * the benchmark corpus"*, because half of that is now a statement about a type
+ * rigc writes, and a refusal that argues from a construct it has since built is
+ * a refusal nobody can act on.
  */
 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',
@@ -3171,9 +3273,10 @@ function buildRigAttachment(
   // 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)'));
+  // the one key that made it linked. Both spellings reach one builder for the
+  // same reason they reach one parser branch.
+  if (type === 'linkedmesh' || (type === 'mesh' && (att as { source?: unknown }).source !== undefined)) {
+    return buildRigLinkedMesh(att as RigLinkedMeshAttachment, placeholder, where, ctx);
   }
   if (type === 'region') return buildRigRegion(att as RigRegionAttachment, placeholder, where, ctx);
   if (type === 'mesh') return buildRigMesh(att as RigMeshAttachment, placeholder, where, ctx);
@@ -3200,9 +3303,9 @@ function buildRigAttachment(
 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 ' +
+    `rigc does not emit it yet, deliberately: it emits ${EMITTED_ATTACHMENT_TYPES.join(', ')}, and a point ` +
+    'appears nowhere in the benchmark corpus (docs/SPEC_COVERAGE.md parts 3-1 and 4-2), so it is not 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.'
   );
 }
@@ -3917,6 +4020,178 @@ function buildRigMesh(
   return out;
 }
 
+/**
+ * A mesh that borrows another mesh's geometry. `type: "linkedmesh"`, or
+ * `type: "mesh"` carrying `source` — one parser branch, one builder.
+ *
+ * 🚨 **Everything this refuses, the parser reads in silence**, which is the whole
+ * reason the refusals exist. Measured on forged skeletons through spine-core
+ * 4.3.13:
+ *
+ *   - Geometry beside `source`: the branch returns at `:586`, BEFORE
+ *     `readVertices`. A link declaring 5 uvs, 3 triangles, `hull: 5` and
+ *     `edges: [0, 2]` beside a 4-vertex source loaded with the source's 8-long
+ *     `worldVerticesLength`, 6 triangles, `hullLength` 8 and 10 edges. Nothing
+ *     the author wrote was read and nothing said so.
+ *   - A chain — a link whose source is itself a link — resolves in the order
+ *     `linkedMeshes` was FILLED, which is the order the skins' JSON keys are
+ *     iterated in. Source-first, the chained link loaded the full geometry; with
+ *     the two keys swapped in the same file it loaded `worldVerticesLength` 0,
+ *     0 triangles, 0 bones and a 0x0 size, silently. A construct whose meaning
+ *     depends on key order is a construct rigc will not write.
+ *   - A link to itself is that chain at length one, and loads the same nothing.
+ *
+ * What is NOT refused here is `source` naming something in a skin or a slot this
+ * builder has not reached yet: that is `resolveLinkedMeshes`' job, and doing it
+ * here would refuse a correct rig on declaration order — the very thing the
+ * chain measurement above condemns.
+ */
+function buildRigLinkedMesh(
+  att: RigLinkedMeshAttachment,
+  placeholder: string,
+  where: string,
+  ctx: AttachmentContext,
+): SpineLinkedMeshAttachment {
+  // The mesh keys the parser does not reach on this branch. Named one by one,
+  // because "remove what does not belong" is not an instruction an author can
+  // act on and the remedy for each of these is the same single sentence.
+  const geometry = (['uvs', 'triangles', 'vertices', 'weights', 'boneIndexing', 'hull', 'edges', 'generator'] as const)
+    .filter((key) => att[key] !== undefined);
+  if (geometry.length > 0) {
+    throw new CompileError(
+      `${where}: a linked mesh states ${geometry.map((k) => JSON.stringify(k)).join(', ')}, and a linked mesh has ` +
+        'no geometry of its own — it draws the geometry of the attachment "source" names. The parser returns from ' +
+        'the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`), so these keys are read by nothing ' +
+        "at all: a link declaring 5 uvs beside a 4-vertex source loads the SOURCE's 4 vertices and says nothing. " +
+        `Remove ${geometry.length === 1 ? 'it' : 'them'}, or remove "source" and author this as a mesh of its own.`,
+    );
+  }
+  const source = att.source;
+  if (typeof source !== 'string' || source.length === 0) {
+    throw new CompileError(
+      `${where}: a linked mesh needs "source" — the PLACEHOLDER of the mesh whose geometry it draws (the key that ` +
+        `attachment is filed under in its skin, not its "name"), and this one states ${JSON.stringify(source) ?? String(source)}. ` +
+        '"source" is what MAKES a mesh linked: `getValue(map, "source", null)` is falsy-tested ' +
+        '(`SkeletonJson.ts:582`), so an absent or empty one is read as an ordinary mesh, whose `uvs` this ' +
+        'attachment does not have — the parser dereferences `map.uvs.length` and throws.',
+    );
+  }
+  if (att.slot !== undefined && !ctx.slotNames.has(att.slot)) {
+    throw new CompileError(
+      `${where}: "slot" is ${JSON.stringify(att.slot)}, which the rig does not declare as a slot. It names where ` +
+        'the source lives and is resolved through `skeletonData.findSlot` (`SkeletonJson.ts:575`), which throws ' +
+        `\`Source mesh slot not found\` on a miss. The rig's slots are ${[...ctx.slotNames].sort().map((s) => JSON.stringify(s)).join(', ')}. ` +
+        "Leave it out and the source is looked for in this attachment's own slot, which is the parser's default.",
+    );
+  }
+  ctx.links.push({
+    where,
+    skin: att.skin ?? 'default',
+    slot: att.slot ?? ctx.slotName,
+    source,
+    skinStated: att.skin !== undefined,
+    slotStated: att.slot !== undefined,
+  });
+  // The art side is a mesh's, unchanged: a link draws its OWN region, which is
+  // the reason the type exists — one triangulation, one outfit's pixels each.
+  const img = att.image === undefined ? undefined : atlasedImage(att.image, where, ctx);
+  const width = att.width ?? img?.width;
+  const height = att.height ?? img?.height;
+  if (width === undefined || height === undefined) {
+    throw new CompileError(
+      `${where}: a linked mesh needs width and height — give them, or give an "image" and rigc will measure the PNG`,
+    );
+  }
+  const out: SpineLinkedMeshAttachment = { type: 'linkedmesh', source, width: r6(width), height: r6(height) };
+  const path = attachmentPath(att, placeholder);
+  if (path !== undefined) out.path = path;
+  // Only where they differ from the parser's own defaults. Writing `timelines:
+  // true`, or a `skin` of "default", would be a byte the editor's own export
+  // does not carry.
+  if (att.slot !== undefined && att.slot !== ctx.slotName) out.slot = att.slot;
+  if (att.skin !== undefined && att.skin !== 'default') out.skin = att.skin;
+  if (att.timelines === false) out.timelines = false;
+  if (att.color !== undefined) out.color = att.color;
+  // 🚫 NOT registered in `ctx.meshes`, and that is a decision rather than an
+  // omission. `meshKinds` is keyed by SLOT and the commonest linked mesh shares
+  // its source's slot from another skin, so an entry here would overwrite the
+  // source's own `ring`/`ribbon`/`contour` kind and silence `A21_MESH_RIM_PINNED`
+  // on the mesh rigc actually built — a gate turned off by a feature, which is
+  // the failure mode issue #44 is about, pointed the other way. The validator
+  // tells a link apart from the ARTIFACT instead — off the file's own `source`
+  // keys, joined to the loaded attachment by (skin, slot, placeholder) — which
+  // is the archetype rule's own words: an assertion reads the rig, never a name.
+  return out;
+}
+
+/**
+ * Resolve every `source` against the skins that were built, and refuse a miss by
+ * name.
+ *
+ * Three of the four refusals are one per throw the runtime would have made
+ * (`SkeletonJson.js:427-436`) — `Skin not found`, `Source mesh slot not found`,
+ * `Source mesh not found`. Those are thrown `Error`s, so left to the round trip
+ * they arrive as `A00_ROUNDTRIP_PARSE`'s report of the runtime's sentence, which
+ * names neither the attachment that asked nor the skin and slot it searched. The
+ * fourth has no runtime throw behind it at all: a source that is not a mesh is
+ * read field by field off whatever was found, and `undefined` is not an error.
+ */
+function resolveLinkedMeshes(
+  links: readonly PendingLink[],
+  tables: Map<string, Record<string, Record<string, SpineAttachment>>>,
+): void {
+  const skinNames = [...tables.keys()];
+  for (const link of links) {
+    // ⚠️ Only a STATED `skin` can miss here, and it is worth saying why rather
+    // than leaving the other half to look like a branch nothing reaches: rigc
+    // always emits a `default` skin, empty if it has to (`tableFor('default')`),
+    // so the parser's own default always resolves to a table. An omitted `skin`
+    // therefore fails one line down, at the source, and the sentence there is
+    // what names the trap.
+    const table = tables.get(link.skin);
+    if (table === undefined) {
+      throw new CompileError(
+        `${link.where}: "skin" is ${JSON.stringify(link.skin)}, and the rig declares no such skin. The rig's skins ` +
+          `are ${skinNames.map((s) => JSON.stringify(s)).join(', ')}. ` +
+          "Left to the round trip this is the runtime's `Skin not found`, which names neither this attachment nor " +
+          'where it was looking.',
+      );
+    }
+    const slot = table[link.slot];
+    const held = slot === undefined ? [] : Object.keys(slot).sort();
+    const found = slot?.[link.source];
+    if (found === undefined) {
+      throw new CompileError(
+        `${link.where}: "source" is ${JSON.stringify(link.source)}, and skin ${JSON.stringify(link.skin)}` +
+          `${link.skinStated ? '' : ' (the default skin, because no "skin" was stated — never the skin this attachment is written in)'}` +
+          ` slot ${JSON.stringify(link.slot)}${link.slotStated ? '' : ' (this attachment\'s own slot, because no "slot" was stated)'} ` +
+          `holds ${held.length === 0 ? 'no attachment at all' : `${held.length}: ${held.map((k) => JSON.stringify(k)).join(', ')}`}. ` +
+          '"source" is the PLACEHOLDER the source is filed under — `skin.getAttachment(slotIndex, source)` ' +
+          "(`SkeletonJson.ts:433`), whose table is keyed by the JSON key, not by the attachment's `name`. " +
+          "Left to the round trip this is the runtime's `Source mesh not found`.",
+      );
+    }
+    const type = (found as { type?: string }).type ?? 'region';
+    if (type === 'linkedmesh') {
+      throw new CompileError(
+        `${link.where}: "source" is ${JSON.stringify(link.source)}, which is itself a linked mesh, and a chain of ` +
+          'them is refused. Measured through spine-core: the runtime resolves links in the order they were read, ' +
+          "so a link whose source is a link loads the source's geometry when the source comes first in the file " +
+          'and loads NOTHING — `worldVerticesLength` 0, 0 triangles, a 0x0 size — when the two are swapped, in ' +
+          'silence either way. Point "source" at the mesh itself.',
+      );
+    }
+    if (type !== 'mesh') {
+      throw new CompileError(
+        `${link.where}: "source" is ${JSON.stringify(link.source)}, which is a ${JSON.stringify(type)} attachment ` +
+          "and not a mesh. A linked mesh takes another MESH's `uvs`, `triangles`, `vertices`, `hull` and `edges` " +
+          '(`MeshAttachment.setSourceMesh`); the runtime casts whatever it finds and reads those fields off it, ' +
+          'which on any other type is `undefined` and no error.',
+      );
+    }
+  }
+}
+
 /**
  * Invoke a `src/mesh.ts` builder from rig-spec data.
  *
@@ -6050,22 +6325,40 @@ function deformGeometryOf(
   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 if (type === 'path') {
-    // The one type that HAS a vertex array and is still refused here. Deforming
-    // a path is a real idiom — an animated track — but it also invalidates the
-    // measured `lengths` that a `constantSpeed: false` traversal reads, so it is
-    // a feature with a rule attached rather than one line of plumbing.
-    throw new NotImplementedError(
-      `${where}: a path attachment does have a vertex array, and rigc does not key it yet — a deformed path ` +
-        'changes the arc lengths its `lengths` array records, which only `constantSpeed: false` reads. ' +
-        'Move the curve by posing the bones its vertices are bound to.',
-    );
+  } else if (type === 'boundingbox' || type === 'clipping' || type === 'path') {
+    // ⭐ A `path` reaches this line as of issue #696, and it is the SAME line the
+    // other two vertex-and-no-triangles types take: the array the parser sizes
+    // is `vertexCount * 2`, the two encodings below are the mesh's own, and a
+    // path's vertices are its control points.
+    //
+    // ⚠️ What stood here was a `NotImplementedError` — *a path attachment does
+    // have a vertex array, and rigc does not key it yet* — whose stated reason
+    // was that a deformed path invalidates the `lengths` the attachment carries.
+    // The reason is measured and it does not belong to rigc:
+    //
+    //   - `lengths` is a field of the ATTACHMENT. The format has nowhere to put
+    //     a per-key length, so no export of any tool carries a re-measured one;
+    //     the editor's own is the setup measurement, which is what
+    //     `pathCurveLengths` reproduces digit for digit.
+    //   - `PathConstraint.computeWorldPositions` reads that field only under
+    //     `constantSpeed: false` (`PathConstraint.js:205`). Under the parser's
+    //     default, `true`, it re-measures the curve from the posed world
+    //     vertices every frame — and those come through
+    //     `VertexAttachment.computeWorldVertices`, which uses
+    //     `slot.appliedPose.deform` when the array is non-empty
+    //     (`attachments/Attachment.js:97-115`). So the constraint follows the
+    //     DEFORMED spline, and the stale field is not read at all.
+    //
+    // ⇒ refusing it was refusing correct data for behaviour the format has and
+    // every runtime shares — the shape issues #44 and #262 already cost this
+    // file twice. `docs/AUTHORING.md` §4.11 states the `constantSpeed: false`
+    // reading instead, which is the honest home for it: a fact about the format
+    // the author is choosing, not a fault rigc can measure.
+    worldVerticesLength = (att as SpineBoundingBoxAttachment | SpinePathAttachment).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.',
+        'it has no vertex array to deform. Deformable types: mesh, boundingbox, clipping, path.',
     );
   }
   const vertices = (att as SpineMeshAttachment).vertices ?? [];
@@ -6910,6 +7203,7 @@ function compileTrack(
   target: string,
   shift: number,
   attachments: SlotAttachmentIndex,
+  darkSlots: ReadonlySet<string>,
 ): SpineTimelineKey[] {
   const where = `animation "${animName}" slot "${target}" ${track.property}`;
   // Before any key is shaped, and before the empty-track refusal: a property
@@ -6922,6 +7216,25 @@ function compileTrack(
         `(it has: ${Object.keys(SLOT_TRACKS).join(', ')})`,
     );
   }
+  // 🚨 Raised here, with the target and before the keys, for the same reason as
+  // the refusal above: the fault is in the pairing of timeline and slot, not in
+  // any key. A two-colour timeline poses `SlotPose.darkColor`, and the runtime
+  // creates that object only for a slot whose setup pose HAS one — `Slot`'s
+  // constructor reads `if (data.setupPose.darkColor != null)` before allocating
+  // it. Measured on the emitted file with the refusal removed: `SkeletonJson`
+  // loads it in silence, `SlotData.setupPose.darkColor` is `null`, and the first
+  // `state.apply` throws `TypeError: null is not an object (evaluating 'dark.r =
+  // …')` inside `RGBA2Timeline.apply1`. That is a crash in the consumer's
+  // process, from a file every parser accepts — the exact silence this compiler
+  // exists to convert into a name (issue #690).
+  if (shape === 'rgba2' && !darkSlots.has(target)) {
+    throw new CompileError(
+      `${where}: slot "${target}" declares no setup "dark", and an "rgba2" timeline poses a slot's dark colour — ` +
+        'the runtime allocates one only for a slot whose setup pose has it, so applying this animation throws ' +
+        `instead of tinting. Give slot "${target}" a \`dark\` in the rig spec (the colour it holds at rest), or ` +
+        'key "rgba" if only the light colour moves',
+    );
+  }
   if (!track.keys.length) throw new CompileError(`${where}: no keys`);
 
   const out: SpineTimelineKey[] = [];
@@ -6960,16 +7273,28 @@ function compileTrack(
       continue;
     }
 
-    // rgba — the other shape `SLOT_TRACKS` names, and now the only way to reach
-    // this branch: a property the table does not carry was refused above.
-    if (!Array.isArray(key.v)) throw new CompileError(`${where}: rgba key value must be [r,g,b,a]`);
-    const entry: SpineTimelineKey = { time, color: rgbaHex(key.v) };
+    // rgba / rgba2 — the two colour shapes `SLOT_TRACKS` names, and between them
+    // the only ways left to reach here: `attachment` returned above and a
+    // property the table does not carry was refused before any key was shaped.
+    //
+    // ⚠️ The two differ in three places and nowhere else, so they are read out of
+    // `shape` rather than forked into two loops: how many channels a `v` carries,
+    // which FIELDS the emitted key spells them as (`color`, or `light` + `dark`),
+    // and therefore how long a raw curve array is. Everything else — the
+    // ease/curve exclusivity, the stepped case, the hold test, the last-key
+    // refusals — is one rule, and a second copy of it is a second thing to keep
+    // in step.
+    const spelling = shape === 'rgba2' ? '[lr,lg,lb,la,dr,dg,db]' : '[r,g,b,a]';
+    const channels = shape === 'rgba2' ? 7 : 4;
+    const colourOf = (v: number[]): Record<string, string> => (shape === 'rgba2' ? rgba2Hex(v) : { color: rgbaHex(v) });
+    if (!Array.isArray(key.v)) throw new CompileError(`${where}: ${shape} key value must be ${spelling}`);
+    const entry: SpineTimelineKey = { time, ...colourOf(key.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, 4, where, String(key.t));
+      entry.curve = rawCurve(key.curve, channels, where, String(key.t));
       out.push(entry);
       continue;
     }
@@ -6980,14 +7305,18 @@ function compileTrack(
         const handles = motion.easings?.[key.ease];
         if (!handles) throw new CompileError(`${where}: unknown easing "${key.ease}"`);
         if (!Array.isArray(next.v)) {
-          throw new CompileError(`${where}: rgba key value must be [r,g,b,a]`);
+          throw new CompileError(`${where}: ${shape} key value must be ${spelling}`);
         }
         const t2 = keyTime(next.t + shift);
-        // 4 numbers per channel, r g b a — 16 in total. Short arrays become NaN
+        // 4 numbers per channel, in the format's own channel order — 16 for
+        // `rgba` (r g b a), 28 for `rgba2` (light r g b a, then dark r g b, which
+        // is the order `readCurve` indexes them in). Short arrays become NaN
         // curves with no error. The hold test reads the emitted hex rather than
         // the authored floats: two colours that quantise to one byte are one
-        // colour in the file.
-        entry.curve = easingCurve(handles, time, t2, key.v, next.v, rgbaHex(key.v) === rgbaHex(next.v));
+        // colour in the file, and for `rgba2` that has to be true of BOTH — a key
+        // whose light holds while its dark moves is not a hold.
+        const held = JSON.stringify(colourOf(key.v)) === JSON.stringify(colourOf(next.v));
+        entry.curve = easingCurve(handles, time, t2, key.v, next.v, held);
       }
     } else if (key.ease && !next) {
       throw new CompileError(`${where}: last key carries an easing but has nothing to ease to`);