spine-rigc 0.2.1 → 0.3.0

package/src/rig.ts

@@ -395,18 +395,99 @@ export interface RigMeshAttachment {
 }
 
 /**
- * The four types the format holds and rigc's emitter does not cover yet. They
- * are in the type so a spec can *say* them and get a named
- * `NotImplementedError`; the alternative is the parser's own behaviour, which is
- * to return `null` for an unknown `type` and drop the attachment without a word
+ * The geometry every non-region attachment shares: a polygon, either pinned to
+ * one bone or weighted across several.
+ *
+ * ⭐ `vertexCount` is REQUIRED and cross-checked, and that is the whole design of
+ * these two types. A mesh gets its vertex count from `uvs.length`, so there is
+ * nothing to state; a bounding box and a clipping polygon have no uvs, and the
+ * parser reads `map.vertexCount << 1` — with the field absent that is
+ * `undefined << 1` = **0**, so `readVertices` takes the weighted branch,
+ * decodes coordinates as a weight run, and hands back an attachment with no
+ * vertices at all. Nothing throws. So the count is declared here and checked
+ * against whichever encoding the spec used.
+ *
+ * The two encodings are the mesh's, unchanged, and for the same reason:
+ * `weights` binds by NAME and is the default; `vertices` is either an unweighted
+ * `x, y` run (one pair per vertex) or Spine's index-encoded weighted run, and
+ * the second of those needs `boneIndexing: "raw"` said out loud because a bone
+ * inserted anywhere above shifts every index in silence (issue #45).
+ */
+export interface RigVertexGeometry {
+  /** Required. No parser default: absent reads as 0 and the polygon vanishes. */
+  vertexCount: number;
+  /**
+   * Unweighted `x, y` pairs (`vertices.length === vertexCount * 2`), or Spine's
+   * weighted run behind `boneIndexing: "raw"`. Mutually exclusive with `weights`.
+   */
+  vertices?: number[];
+  /** Weighted geometry bound by name — one entry per vertex. The default form. */
+  weights?: RigMeshBinding[][];
+  /** `"raw"` opts a `vertices` weighted run into the index encoding. */
+  boneIndexing?: 'name' | 'raw';
+  /** `rrggbbaa`. Editor affordance: the colour the box is drawn in. */
+  color?: string;
+}
+
+/**
+ * `type: "boundingbox"` (`SkeletonJson.ts:560-567`).
+ *
+ * **When you need one:** a polygon the game can hit-test against — a hurt box, a
+ * pick region, a trigger volume — that moves with the skeleton and draws
+ * nothing. It is the only attachment type whose entire purpose is outside the
+ * renderer, which is why it has no `path`, no size and no uvs.
+ */
+export interface RigBoundingBoxAttachment extends RigVertexGeometry {
+  type: 'boundingbox';
+}
+
+/**
+ * `type: "clipping"` (`SkeletonJson.ts:635-651`).
+ *
+ * **When you need one:** a mask. The polygon clips every slot drawn from the one
+ * carrying it up to and including `end`, so a window, a portal or a wipe is one
+ * attachment rather than a second set of art.
+ *
+ * ⚠️ `end` is resolved with `skeletonData.findSlot(end)`, which returns **null**
+ * on a miss and assigns that null without complaint (`:626-627`). The clip then
+ * never ends — it runs to the bottom of the draw order and takes every slot
+ * below it with it. rigc refuses a name the rig does not declare.
+ */
+export interface RigClippingAttachment extends RigVertexGeometry {
+  type: 'clipping';
+  /**
+   * The last slot this clip applies to, by name. Absent leaves `endSlot` null,
+   * which is the parser's own encoding for "clip everything after this one".
+   */
+  end?: string;
+  /** 4.3. Default false. */
+  convex?: boolean;
+  /** 4.3. Default false. */
+  inverse?: boolean;
+}
+
+/**
+ * The three types the format holds and rigc's emitter does not cover. They are
+ * in the type so a spec can *say* them and get a named `NotImplementedError`;
+ * the alternative is the parser's own behaviour, which is to return `null` for
+ * an unknown `type` and drop the attachment without a word
  * (`SkeletonJson.ts:653`).
+ *
+ * 🚧 None of the three appears anywhere in the benchmark corpus
+ * (SPEC_COVERAGE parts 3-1 and 4-2), so none is on the ladder's critical path —
+ * which is the reason they are deferred rather than an oversight.
  */
 export interface RigUnimplementedAttachment {
-  type: 'boundingbox' | 'point' | 'clipping' | 'path' | 'linkedmesh';
+  type: 'point' | 'path' | 'linkedmesh';
   [field: string]: unknown;
 }
 
-export type RigAttachment = RigRegionAttachment | RigMeshAttachment | RigUnimplementedAttachment;
+export type RigAttachment =
+  | RigRegionAttachment
+  | RigMeshAttachment
+  | RigBoundingBoxAttachment
+  | RigClippingAttachment
+  | RigUnimplementedAttachment;
 
 /** `slotName -> placeholderName -> attachment` (`SkeletonJson.ts:431-439`). */
 export type RigSkin = Record<string, Record<string, RigAttachment>>;
@@ -549,6 +630,43 @@ export type RigConstraint =
   | RigPhysicsConstraint
   | RigUnimplementedConstraint;
 
+// ---------------------------------------------------------------------------
+// events — `root.events` (SkeletonJson.ts:469-484), an OBJECT, not an array
+// ---------------------------------------------------------------------------
+
+/**
+ * One event **definition**: a name the skeleton owns, plus the payload a firing
+ * carries when the animation does not override it.
+ *
+ * ⭐ The declaration lives in the rig spec and the firings live in the motion
+ * spec, for the same reason slots live here and their colour keys live there:
+ * the name is structure — the runtime looks it up, the game listens for it —
+ * and *when* it fires is time. `skeletonData.findEvent` resolves an animation's
+ * key against this table and **throws** on a miss (`:1244`), so an animation
+ * that names an event nobody declared does not load at all. rigc refuses it at
+ * compile instead, where the message can name the file that has to change.
+ *
+ * ⚠️ `volume` and `balance` are read **only when `audio` is set** (`:478-481`).
+ * Declared without one they are dropped in silence, so rigc refuses that pairing
+ * rather than emitting two numbers the runtime will never look at.
+ */
+export interface RigEvent {
+  /** Default 0. The `int` payload every firing inherits unless it overrides it. */
+  int?: number;
+  /** Default 0. */
+  float?: number;
+  /** Default `""`. */
+  string?: string;
+  /**
+   * Audio path the editor recorded for this event. Nonessential to playback —
+   * no runtime here loads it — but it is what makes `volume`/`balance` legible.
+   */
+  audio?: string;
+  /** Only read when `audio` is set. */
+  volume?: number;
+  balance?: number;
+}
+
 // ---------------------------------------------------------------------------
 // invariants — what skeleton JSON cannot say about itself
 // ---------------------------------------------------------------------------
@@ -619,6 +737,13 @@ export interface RigSpec {
   /** At least `default`, which becomes `skeletonData.defaultSkin` (`:441`). */
   skins?: Record<string, RigSkin>;
   constraints?: RigConstraint[];
+  /**
+   * `eventName -> payload defaults`. Emitted as `root.events`, which is an
+   * OBJECT keyed by name and not an array. The motion spec's per-animation
+   * `events` timeline fires them; a firing whose name is not a key here is a
+   * compile error, because the parser throws on it at load.
+   */
+  events?: Record<string, RigEvent>;
   invariants?: RigInvariants;
 }
 
@@ -727,5 +852,43 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
     constraintNames.add(constraint.name);
   }
 
+  if (raw.events !== undefined) {
+    if (!isObj(raw.events)) {
+      throw new CompileError(
+        `${where}: "events" is an object keyed by event name (\`{ "footstep": {} }\`), not an array — the format's own shape`,
+      );
+    }
+    for (const [name, def] of Object.entries(raw.events)) {
+      if (name.length === 0) throw new CompileError(`${where}: an event has an empty name`);
+      if (!isObj(def)) {
+        throw new CompileError(`${where}: event "${name}" must be an object of payload defaults (use {} for none)`);
+      }
+      for (const field of ['int', 'float', 'volume', 'balance'] as const) {
+        const v = def[field];
+        if (v !== undefined && (typeof v !== 'number' || !Number.isFinite(v))) {
+          throw new CompileError(`${where}: event "${name}" has ${field} ${JSON.stringify(v)}, which is not a finite number`);
+        }
+      }
+      if (def.int !== undefined && !Number.isInteger(def.int)) {
+        throw new CompileError(`${where}: event "${name}" has int ${JSON.stringify(def.int)}; the payload is an integer`);
+      }
+      for (const field of ['string', 'audio'] as const) {
+        if (def[field] !== undefined && typeof def[field] !== 'string') {
+          throw new CompileError(`${where}: event "${name}" has ${field} ${JSON.stringify(def[field])}, which is not a string`);
+        }
+      }
+      // SkeletonJson.ts:478-481 reads these two ONLY inside `if (data.audioPath)`.
+      // Without an audio path they are dropped with no error, so a spec that
+      // wrote them down would carry a number no runtime ever reads.
+      for (const field of ['volume', 'balance'] as const) {
+        if (def[field] !== undefined && def.audio === undefined) {
+          throw new CompileError(
+            `${where}: event "${name}" declares ${field} but no "audio"; the parser reads ${field} only when an audio path is set, so it would be dropped in silence`,
+          );
+        }
+      }
+    }
+  }
+
   return spec;
 }

package/src/timelines.ts

@@ -87,11 +87,15 @@ const EVENT_CHANNELS: Record<string, number | null> = { events: null };
  * How far past an animation's declared `duration` a key time may land: one step
  * of the grid every key time is rounded onto.
  *
- * The compiler emits key times through `r6`, so 1e-6 s is the finest distinction
- * a key can make and half a step is the most a *correct* key can miss its target
- * by. A key the author put exactly ON a duration of 68/12 s emits as 5.666667 —
- * 3.3e-7 s late, and legal. Anything a whole step further was authored past the
- * end, not rounded onto it.
+ * The compiler quantises key times onto that grid with `keyTime`, which rounds
+ * DOWN (issue #99), so 1e-6 s is the finest distinction a key can make and a
+ * *correct* key now misses its target only on the early side: a key the author put
+ * exactly ON a duration of 68/12 s emits as 5.666666 rather than past it. What
+ * still needs the tolerance is the other side of the same rule — `validate` re-runs
+ * it on an emitted file read back through a **Float32Array**, whose steps are
+ * coarser than this one and round both ways, and on artifacts no rigc compile ever
+ * touched. Anything a whole step past a declared duration was authored there, not
+ * rounded onto it.
  *
  * ⚠️ `FRAME` (1/60 s) is the wrong tolerance for this, which is why the constant
  * is separate rather than reused: 1/60 s answers "is the DECLARED DURATION

package/src/types.ts

@@ -303,6 +303,33 @@ export interface MotionDrawOrderKey {
   offsets?: MotionDrawOrderOffset[];
 }
 
+/**
+ * One firing of a declared event, at one time.
+ *
+ * ⚠️ Like `drawOrder` and unlike a `track`, this timeline names **no target**:
+ * 4.3 writes it as `animations.<a>.events` beside `bones` and `slots`
+ * (SPEC_COVERAGE part 1-8), and there is one per animation. The `name` picks
+ * an entry out of the rig spec's `events` table; the optional payload fields
+ * override that entry's defaults for this firing only.
+ *
+ * A key with no `int`/`float`/`string` inherits the event's setup payload
+ * (`:1250-1252`) — which is what the editor writes, and why `{ "t": 0.5,
+ * "name": "footstep" }` is the common shape.
+ */
+export interface MotionEventKey {
+  /** Time in seconds. */
+  t: number;
+  /** An event the rig spec declares. A miss throws in the parser; rigc refuses it. */
+  name: string;
+  /** Payload overrides for this firing. Omit to inherit the event's defaults. */
+  int?: number;
+  float?: number;
+  string?: string;
+  /** Read only when the declared event carries an `audio` path — see `RigEvent`. */
+  volume?: number;
+  balance?: number;
+}
+
 export interface MotionAnimation {
   /** Declared, then verified against the compiled result (rule 4). */
   duration: number;
@@ -320,6 +347,11 @@ export interface MotionAnimation {
    * time. First needed at ladder rung 5.
    */
   drawOrder?: MotionDrawOrderKey[];
+  /**
+   * The event timeline. One per animation, names no target, and for the same
+   * reason `drawOrder` is not a `track`. First needed at the spineboy rung.
+   */
+  events?: MotionEventKey[];
 }
 
 /**
@@ -442,7 +474,37 @@ export interface SpineMeshAttachment {
   color?: string;
 }
 
-export type SpineAttachment = SpineRegionAttachment | SpineMeshAttachment;
+/**
+ * The two vertex-only attachments: a polygon and nothing else.
+ *
+ * `vertexCount` is not optional the way a mesh's is absent-by-design: the parser
+ * reads `map.vertexCount << 1`, so an omission is `0` and `readVertices` decodes
+ * the coordinate array as a weight run and stores nothing.
+ */
+export interface SpineBoundingBoxAttachment {
+  type: 'boundingbox';
+  vertexCount: number;
+  /** Unweighted x/y pairs, or the weighted run — same encoding as a mesh's. */
+  vertices: number[];
+  color?: string;
+}
+
+export interface SpineClippingAttachment {
+  type: 'clipping';
+  /** The last slot the clip applies to. Absent = to the bottom of the order. */
+  end?: string;
+  convex?: boolean;
+  inverse?: boolean;
+  vertexCount: number;
+  vertices: number[];
+  color?: string;
+}
+
+export type SpineAttachment =
+  | SpineRegionAttachment
+  | SpineMeshAttachment
+  | SpineBoundingBoxAttachment
+  | SpineClippingAttachment;
 
 export type SpineTimelineKey = Record<string, unknown>;
 
@@ -469,6 +531,11 @@ export interface SpineSkeletonJson {
   slots: SpineSlot[];
   constraints?: SpineConstraint[];
   skins: Array<{ name: string; attachments: Record<string, Record<string, SpineAttachment>> }>;
+  /**
+   * Event definitions, keyed by name (`SkeletonJson.ts:451-464`). An object, not
+   * an array — the one top-level collection in the format that is.
+   */
+  events?: Record<string, SpineEvent>;
   animations: Record<
     string,
     {
@@ -477,10 +544,22 @@ export interface SpineSkeletonJson {
       physics?: Record<string, Record<string, SpineTimelineKey[]>>;
       /** Whole-animation timeline: no target name, one array per animation. */
       drawOrder?: SpineTimelineKey[];
+      /** The other whole-animation timeline; same shape, same reason. */
+      events?: SpineTimelineKey[];
     }
   >;
 }
 
+/** One entry of the emitted `events` map: the payload a firing inherits. */
+export interface SpineEvent {
+  int?: number;
+  float?: number;
+  string?: string;
+  audio?: string;
+  volume?: number;
+  balance?: number;
+}
+
 // ---------------------------------------------------------------------------
 // Compiler result
 // ---------------------------------------------------------------------------

package/src/validate.ts

@@ -19,6 +19,7 @@ import {
   AnimationState,
   AnimationStateData,
   AtlasAttachmentLoader,
+  BoundingBoxAttachment,
   ClippingAttachment,
   MeshAttachment,
   Physics,
@@ -42,8 +43,9 @@ export interface Failure {
  *
  * ⭐ The distinction this draws is the difference between "wrong" and "not how we
  * do it here", and conflating the two is how a validator stops being usable on
- * anybody else's data. Nine of the 31 assertions are policy for one renderer
- * (`spine-html`) or for one project's canvas budget, and every one of them fires
+ * anybody else's data. Fourteen of the 34 assertions are policy — seven for one
+ * renderer (`spine-html`) and one project's canvas budget, seven for rigc's own
+ * formations — and every one of them fires
  * on real, correct, editor-produced Spine data — the official example projects
  * carry clipping attachments, unweighted meshes, 116-triangle meshes and packed
  * atlases, all of which are perfectly valid and none of which spine-html likes.
@@ -113,6 +115,8 @@ const ASSERTION_KIND: Record<string, 'validity' | 'renderer' | 'archetype'> = {
   A29_STROKE_WITHIN_CONTACT_DEPTH: 'archetype',
   A30_STROKE_WITHIN_CAP_CONTAINMENT: 'archetype',
   A31_DRAW_ORDER_OFFSETS_RESOLVE: 'validity',
+  A32_EVENT_KEYS_RESOLVE: 'validity',
+  A33_VERTEX_ATTACHMENT_GEOMETRY: 'validity',
 };
 
 export interface ValidateInput {
@@ -370,6 +374,81 @@ export function validate(input: ValidateInput): ValidateReport {
     if (!sawATimeline) return skip('A31_DRAW_ORDER_OFFSETS_RESOLVE', 'no animation carries a drawOrder timeline');
   });
 
+  // --- A32: every event key fires a declared event, in order ----------------
+  //
+  // The event timeline's three failure modes, and only the first is loud:
+  //
+  //   1. **An undeclared name.** `findEvent` returns null and `readAnimation`
+  //      throws `Event not found` (SkeletonJson.ts:1244). A00 would catch it, but
+  //      as a parser message about a name with no context; this one says which
+  //      animation, which key, and what the skeleton does declare.
+  //   2. **Times out of order.** `readAnimation` writes frame `i` from key `i` in
+  //      ARRAY order and never sorts, so a decreasing time builds an
+  //      `EventTimeline` whose frames run backwards. It loads clean, and the
+  //      firings behind the fold simply never come out. Equal times are fine —
+  //      two events on one frame is ordinary — so this is non-decreasing.
+  //   3. **`volume`/`balance` on a silent event.** `:1254-1257` reads them only
+  //      inside `if (event.data.audioPath)`, so on an event with no `audio` they
+  //      are two numbers in the file that no runtime will ever read.
+  //
+  // It runs on the raw JSON rather than on the loaded data because the loaded
+  // `Event` no longer remembers which fields the file wrote: an override that was
+  // dropped and an override that matched the default are the same object.
+  check('A32_EVENT_KEYS_RESOLVE', () => {
+    if (!raw) return skip('A32_EVENT_KEYS_RESOLVE', 'the skeleton JSON did not parse (A00 owns that failure)');
+    if (!isObj(raw.animations)) return skip('A32_EVENT_KEYS_RESOLVE', 'the skeleton declares no animations');
+    const declared = isObj(raw.events) ? (raw.events as Json) : {};
+    const known = Object.keys(declared);
+    let sawATimeline = false;
+    for (const [animName, anim] of Object.entries(raw.animations as Json)) {
+      if (!isObj(anim) || !Array.isArray(anim.events)) continue;
+      sawATimeline = true;
+      let previous = -Infinity;
+      (anim.events as unknown[]).forEach((key, k) => {
+        const at = `animation "${animName}" event key ${k}`;
+        if (!isObj(key) || typeof key.name !== 'string') {
+          fail('A32_EVENT_KEYS_RESOLVE', `${at}: an event key needs a string "name"`);
+          return;
+        }
+        const definition = declared[key.name];
+        if (definition === undefined) {
+          fail(
+            'A32_EVENT_KEYS_RESOLVE',
+            `${at}: fires "${key.name}", which the skeleton's events block does not declare` +
+              (known.length ? ` (declared: ${known.join(', ')})` : ' (that block is empty or absent)'),
+          );
+          return;
+        }
+        // `time` defaults to 0 when absent (`:1247`), which is what the editor
+        // writes for a firing on frame 0.
+        const time = key.time === undefined ? 0 : key.time;
+        if (typeof time !== 'number' || !Number.isFinite(time)) {
+          fail('A32_EVENT_KEYS_RESOLVE', `${at}: time is ${JSON.stringify(key.time)}, not a finite number`);
+          return;
+        }
+        if (time < previous) {
+          fail(
+            'A32_EVENT_KEYS_RESOLVE',
+            `${at}: "${key.name}" is at t=${time}, after a key at t=${previous} — the parser fills frames in ` +
+              'array order and never sorts them, so the earlier firing is unreachable',
+          );
+        }
+        previous = Math.max(previous, time);
+        const hasAudio = isObj(definition) && typeof definition.audio === 'string';
+        for (const field of ['volume', 'balance'] as const) {
+          if (key[field] !== undefined && !hasAudio) {
+            fail(
+              'A32_EVENT_KEYS_RESOLVE',
+              `${at}: "${key.name}" sets ${field}, but the event declares no audio path — the parser reads ` +
+                `${field} only for an event that has one, so it is dropped in silence`,
+            );
+          }
+        }
+      });
+    }
+    if (!sawATimeline) return skip('A32_EVENT_KEYS_RESOLVE', 'no animation carries an event timeline');
+  });
+
   // --- A: the round trip ----------------------------------------------------
   // The two loaded objects come back OUT of the assertion rather than being
   // assigned into it. Everything below reads them, and a `let` written inside a
@@ -563,6 +642,117 @@ export function validate(input: ValidateInput): ValidateReport {
       }
     });
 
+    // --- A33: bounding boxes and clipping polygons hold a real polygon -------
+    //
+    // These two types are the same shape — a polygon and nothing else — and they
+    // fail the same three ways, all three silent:
+    //
+    //   1. **A missing or wrong `vertexCount`.** The parser reads
+    //      `map.vertexCount << 1` and hands it to `readVertices` as the length to
+    //      expect (`:552`, `:632`). `undefined << 1` is 0, so an omission makes
+    //      the coordinate array read as a WEIGHTED run: it decodes numbers as
+    //      bone counts and weights, and the attachment ends up with no vertices
+    //      at all. Nothing throws, and neither type draws a pixel, so nothing
+    //      downstream notices either.
+    //   2. **A weighted run that does not decode to that many vertices.** Same
+    //      trap as a mesh's (A04), minus the uvs that would have caught it.
+    //   3. **A clipping `end` naming a slot that is not there.**
+    //      `skeletonData.findSlot` returns null on a miss and `:626-627` assigns
+    //      the null, so the clip does not end where it was told to — it runs to
+    //      the bottom of the draw order and takes every slot below it with it.
+    //      Checked on the raw JSON, because a null `endSlot` and an `end` that
+    //      was never written are the same loaded object.
+    check('A33_VERTEX_ATTACHMENT_GEOMETRY', () => {
+      const polygons: Array<{ what: string; att: BoundingBoxAttachment | ClippingAttachment }> = [];
+      for (const skin of data.skins) {
+        for (const entry of skin.getAttachments()) {
+          const att = entry.attachment;
+          if (att instanceof BoundingBoxAttachment) polygons.push({ what: `bounding box "${att.name}"`, att });
+          else if (att instanceof ClippingAttachment) polygons.push({ what: `clipping attachment "${att.name}"`, att });
+        }
+      }
+      const slotNames = new Set(data.slots.map((s) => s.name));
+      let endsChecked = 0;
+      if (raw && Array.isArray(raw.skins)) {
+        for (const skin of raw.skins as unknown[]) {
+          if (!isObj(skin) || !isObj(skin.attachments)) continue;
+          for (const [slotName, perSlot] of Object.entries(skin.attachments as Json)) {
+            if (!isObj(perSlot)) continue;
+            for (const [placeholder, att] of Object.entries(perSlot)) {
+              if (!isObj(att) || att.type !== 'clipping' || att.end === undefined) continue;
+              endsChecked++;
+              if (typeof att.end !== 'string' || !slotNames.has(att.end)) {
+                fail(
+                  'A33_VERTEX_ATTACHMENT_GEOMETRY',
+                  `clipping attachment "${placeholder}" on slot "${slotName}" ends at ${JSON.stringify(att.end)}, ` +
+                    'which is not a slot of this skeleton — the clip would run to the bottom of the draw order',
+                );
+              }
+            }
+          }
+        }
+      }
+      if (polygons.length === 0 && endsChecked === 0) {
+        return skip('A33_VERTEX_ATTACHMENT_GEOMETRY', 'the skeleton carries no bounding box and no clipping attachment');
+      }
+      for (const { what, att } of polygons) {
+        const length = att.worldVerticesLength;
+        if (!Number.isInteger(length) || length < 6 || length % 2 !== 0) {
+          fail(
+            'A33_VERTEX_ATTACHMENT_GEOMETRY',
+            `${what} loaded worldVerticesLength ${length}; a polygon is an even count of at least 6 (3 vertices). ` +
+              'A missing "vertexCount" reads as 0 and takes the polygon with it',
+          );
+          continue;
+        }
+        const vertexCount = length / 2;
+        if (!att.bones) {
+          if (att.vertices.length !== length) {
+            fail(
+              'A33_VERTEX_ATTACHMENT_GEOMETRY',
+              `${what} declares ${vertexCount} vertices but holds ${att.vertices.length} unweighted numbers ` +
+                `(expected ${length}); the parser reads that mismatch as a weighted run`,
+            );
+          }
+          continue;
+        }
+        // Weighted: `bones` is boneCount, (index × boneCount), repeated, and
+        // `vertices` holds x, y, weight per binding.
+        let decoded = 0;
+        let bindings = 0;
+        let ok = true;
+        for (let i = 0; i < att.bones.length; decoded++) {
+          const count = att.bones[i++];
+          if (!Number.isInteger(count) || count < 1 || i + count > att.bones.length) {
+            fail('A33_VERTEX_ATTACHMENT_GEOMETRY', `${what} vertex ${decoded} claims ${count} bone(s); the run is malformed`);
+            ok = false;
+            break;
+          }
+          for (let k = 0; k < count; k++, i++) {
+            const index = att.bones[i];
+            if (index < 0 || index >= data.bones.length) {
+              fail('A33_VERTEX_ATTACHMENT_GEOMETRY', `${what} vertex ${decoded} references bone index ${index}`);
+              ok = false;
+            }
+          }
+          bindings += count;
+        }
+        if (!ok) continue;
+        if (decoded !== vertexCount) {
+          fail(
+            'A33_VERTEX_ATTACHMENT_GEOMETRY',
+            `${what} declares ${vertexCount} vertices and its weighted run decodes to ${decoded}`,
+          );
+        }
+        if (att.vertices.length !== bindings * 3) {
+          fail(
+            'A33_VERTEX_ATTACHMENT_GEOMETRY',
+            `${what} has ${bindings} binding(s) and ${att.vertices.length} weight numbers (expected ${bindings * 3})`,
+          );
+        }
+      }
+    });
+
     // --- A11 / A13 / A14: renderer + canvas budgets ----
     check('A11_NO_CLIPPING_ATTACHMENTS', () => {
       if (clippingCount > 0) {