@flighthq/skeleton2d-formats 0.3.0-next.1021.f5f1ee0

package/src/dragonBonesParse.test.ts

@@ -0,0 +1,313 @@
+import { collectImportDiagnostics } from '@flighthq/importdiagnostics/contract';
+import type { ImportDiagnostic, MeshAttachment2D, RegionAttachment2D } from '@flighthq/types/contract';
+import { MeshAttachment2DKind, RegionAttachment2DKind, TransformMode2D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { parseDragonBonesSkeleton } from './dragonBonesParse';
+
+// Hand-authored minimal DragonBones JSON (per the real-asset rule: committed fixtures are hand-written,
+// never transcribed from a rig). Bones are listed CHILD-FIRST to exercise the topological sort.
+const DB_TWO_BONES = JSON.stringify({
+  frameRate: 24,
+  name: 'demo',
+  version: '5.5',
+  armature: [
+    {
+      name: 'armatureA',
+      bone: [
+        { name: 'arm', parent: 'root', length: 50, transform: { x: 10, y: 20, skX: 45, skY: 30, scX: 2, scY: 3 } },
+        { name: 'root' },
+      ],
+    },
+  ],
+});
+
+describe('parseDragonBonesSkeleton', () => {
+  it('parses the first armature, topologically sorts bones, and maps the skX/skY transform', () => {
+    const result = parseDragonBonesSkeleton(DB_TWO_BONES);
+    expect(result).not.toBeNull();
+    const bones = result!.skeleton.bones;
+    expect(bones.length).toBe(2);
+    // Topological sort puts the parent (listed second) before its child.
+    expect(bones[0].name).toBe('root');
+    expect(bones[0].parentIndex).toBe(-1);
+    const arm = bones[1];
+    expect(arm.name).toBe('arm');
+    expect(arm.parentIndex).toBe(0); // 'root' resolved to index 0
+    expect(arm.length).toBe(50);
+    expect(arm.x).toBe(10);
+    expect(arm.y).toBe(20);
+    // rotation = skY = 30, shearX = 0, shearY = skX − skY = 15; scale from scX/scY.
+    expect(arm.rotation).toBe(30);
+    expect(arm.shearX).toBe(0);
+    expect(arm.shearY).toBe(15);
+    expect(arm.scaleX).toBe(2);
+    expect(arm.scaleY).toBe(3);
+    expect(result!.animations).toEqual([]);
+  });
+
+  it('maps the newer rotate/skew transform form identically to skX/skY', () => {
+    const doc = { armature: [{ bone: [{ name: 'b', transform: { rotate: 30, skew: 15 } }] }] };
+    const bone = parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.bones[0];
+    expect(bone.rotation).toBe(30);
+    expect(bone.shearY).toBe(15);
+  });
+
+  it('applies DragonBones defaults for an omitted transform', () => {
+    const doc = { armature: [{ bone: [{ name: 'b' }] }] };
+    const bone = parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.bones[0];
+    expect(bone).toMatchObject({
+      x: 0,
+      y: 0,
+      rotation: 0,
+      shearX: 0,
+      shearY: 0,
+      scaleX: 1,
+      scaleY: 1,
+      length: 0,
+      parentIndex: -1,
+      transformMode: TransformMode2D.Normal,
+    });
+  });
+
+  it('maps the DragonBones inheritance booleans onto TransformMode2D', () => {
+    const doc = {
+      armature: [
+        {
+          bone: [
+            { name: 'normal' },
+            { name: 'onlyT', inheritRotation: false, inheritScale: false },
+            { name: 'noScale', inheritScale: false },
+            { name: 'noScaleRefl', inheritScale: false, inheritReflection: false },
+            { name: 'noRot', inheritRotation: false, inheritReflection: false },
+          ],
+        },
+      ],
+    };
+    const bones = parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.bones;
+    const mode = (name: string) => bones.find((b) => b.name === name)!.transformMode;
+    expect(mode('normal')).toBe(TransformMode2D.Normal);
+    expect(mode('onlyT')).toBe(TransformMode2D.OnlyTranslation);
+    expect(mode('noScale')).toBe(TransformMode2D.NoScale);
+    expect(mode('noScaleRefl')).toBe(TransformMode2D.NoScaleOrReflection);
+    expect(mode('noRot')).toBe(TransformMode2D.NoRotationOrReflection);
+  });
+
+  it('Skip-crumbs an inheritance combo the five-value enum cannot express', () => {
+    // inheritRotation false + inheritReflection true (scale kept): "strip rotation, keep reflection" has no
+    // TransformMode2D — NoRotationOrReflection would also strip the reflection.
+    const doc = { armature: [{ bone: [{ name: 'b', inheritRotation: false }] }] };
+    const kinds = collectImportDiagnostics((sink) => parseDragonBonesSkeleton(JSON.stringify(doc), sink)).map(
+      (c) => c.kind,
+    );
+    expect(kinds).toContain('dragonbones.inherit-mode-unmapped');
+  });
+
+  it('parses slots with resolved bone index, image display, and ColorTransform tint', () => {
+    const doc = {
+      armature: [
+        {
+          bone: [{ name: 'root' }, { name: 'armBone', parent: 'root' }],
+          slot: [{ name: 'arm', parent: 'armBone', displayIndex: 0, color: { rM: 50, gM: 75, bM: 100, aM: 100 } }],
+          skin: [
+            {
+              name: 'default',
+              slot: [{ name: 'arm', display: [{ name: 'armImage', transform: { x: 1, y: 2, skX: 30, skY: 30 } }] }],
+            },
+          ],
+        },
+      ],
+    };
+    const slots = parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.slots!;
+    expect(slots.length).toBe(1);
+    expect(slots[0].name).toBe('arm');
+    expect(slots[0].boneIndex).toBe(1); // 'armBone' resolved to its topo-sorted output index
+    // ColorTransform multiply 50/75/100/100 % → RR GG BB AA bytes 0x80 0xbf 0xff 0xff.
+    expect(slots[0].color).toBe(0x80bfffff);
+    const region = slots[0].attachment as RegionAttachment2D;
+    expect(region.kind).toBe(RegionAttachment2DKind);
+    expect(region).toMatchObject({ x: 1, y: 2, rotation: 30, scaleX: 1, scaleY: 1 });
+  });
+
+  it('parses an unweighted mesh display into a MeshAttachment2D (positions direct, skin null)', () => {
+    const doc = {
+      armature: [
+        {
+          bone: [{ name: 'root' }],
+          slot: [{ name: 's', parent: 'root' }],
+          skin: [
+            {
+              name: 'default',
+              slot: [
+                {
+                  name: 's',
+                  display: [
+                    {
+                      type: 'mesh',
+                      name: 'm',
+                      uvs: [0, 0, 1, 0, 1, 1],
+                      triangles: [0, 1, 2],
+                      vertices: [0, 0, 10, 0, 10, 10],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    const mesh = parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.slots![0].attachment as MeshAttachment2D;
+    expect(mesh.kind).toBe(MeshAttachment2DKind);
+    expect(mesh.skin).toBeNull();
+    expect(mesh.vertexCount).toBe(3);
+    expect(Array.from(mesh.vertices!)).toEqual([0, 0, 10, 0, 10, 10]);
+    expect(Array.from(mesh.triangles)).toEqual([0, 1, 2]);
+  });
+
+  // Wraps a single weighted mesh display in a full DragonBones doc. Bones are listed CHILD-FIRST so the
+  // topo-sort reorders (output [root=0, child=1]); the weights reference bones by armature FILE-ORDER index.
+  function weightedMeshDoc(mesh: Record<string, unknown>): string {
+    return JSON.stringify({
+      armature: [
+        {
+          bone: [{ name: 'child', parent: 'root' }, { name: 'root' }],
+          slot: [{ name: 's', parent: 'root' }],
+          skin: [{ name: 'default', slot: [{ name: 's', display: [{ type: 'mesh', name: 'm', ...mesh }] }] }],
+        },
+      ],
+    });
+  }
+
+  it('converts a WEIGHTED mesh to Skin2D offsets, remapping bone indices through the topo-sort (formula parity)', () => {
+    // slotPose identity; the used bone is armature raw index 0 ('child'), which the topo-sort places at
+    // OUTPUT index 1. Its bind matrix is translate(10,0), so the inverse maps vertex (12,5) → bind-local (2,5).
+    const mesh = parseDragonBonesSkeleton(
+      weightedMeshDoc({
+        uvs: [0, 0],
+        triangles: [],
+        vertices: [12, 5],
+        slotPose: [1, 0, 0, 1, 0, 0],
+        bonePose: [0, 1, 0, 0, 1, 10, 0], // rawBoneIndex 0, bind = translate(10,0)
+        weights: [1, 0, 1], // vertex 0: one influence, rawBoneIndex 0, weight 1
+      }),
+    )!.skeleton.slots![0].attachment as MeshAttachment2D;
+    expect(mesh.vertices).toBeNull();
+    expect(Array.from(mesh.skin!.influenceCounts)).toEqual([1]);
+    // [outputBoneIndex, offsetX, offsetY, weight]: raw bone 0 ('child') → OUTPUT 1; offset (2,5).
+    expect(Array.from(mesh.skin!.influences)).toEqual([1, 2, 5, 1]);
+  });
+
+  it('applies the inverse bind ROTATION when converting a weighted mesh (formula parity)', () => {
+    // Bind matrix = a 90° rotation ([a,b,c,d]=[0,1,-1,0]); its inverse rotates the vertex (1,0) to (0,-1).
+    const mesh = parseDragonBonesSkeleton(
+      weightedMeshDoc({
+        uvs: [0, 0],
+        triangles: [],
+        vertices: [1, 0],
+        slotPose: [1, 0, 0, 1, 0, 0],
+        bonePose: [1, 0, 1, -1, 0, 0, 0], // rawBoneIndex 1 ('root' → output 0), bind = 90° rotation
+        weights: [1, 1, 1], // vertex 0: one influence, rawBoneIndex 1, weight 1
+      }),
+    )!.skeleton.slots![0].attachment as MeshAttachment2D;
+    const influences = Array.from(mesh.skin!.influences);
+    expect(influences[0]).toBe(0); // raw bone 1 ('root') → OUTPUT 0
+    expect(influences[1]).toBeCloseTo(0, 5); // offsetX
+    expect(influences[2]).toBeCloseTo(-1, 5); // offsetY
+    expect(influences[3]).toBe(1); // weight
+  });
+
+  it('recovers (Recover crumb) a weighted mesh whose stream is truncated, without reading past the end', () => {
+    const kinds = collectImportDiagnostics((sink) =>
+      parseDragonBonesSkeleton(
+        weightedMeshDoc({
+          uvs: [0, 0],
+          triangles: [],
+          vertices: [0, 0],
+          slotPose: [1, 0, 0, 1, 0, 0],
+          bonePose: [1, 1, 0, 0, 1, 0, 0],
+          weights: [2, 1, 1], // declares 2 influences but only supplies one before the stream ends
+        }),
+        sink,
+      ),
+    ).map((c) => c.kind);
+    expect(kinds).toContain('dragonbones.weighted-mesh-recovered');
+  });
+
+  it('holds an unmodeled display at its displayIndex slot (null, not dropped) so indices stay aligned', () => {
+    // A boundingBox display at index 0 must NOT drop, or the image at index 1 would shift to 0 and
+    // displayIndex 1 would then address the wrong display (read-integrity axis 12 on the display array).
+    const doc = {
+      armature: [
+        {
+          bone: [{ name: 'root' }],
+          slot: [{ name: 's', parent: 'root', displayIndex: 1 }],
+          skin: [
+            {
+              name: 'default',
+              slot: [
+                {
+                  name: 's',
+                  display: [
+                    { type: 'boundingBox', name: 'bb' },
+                    { name: 'img', transform: { x: 9 } },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    const crumbs: ImportDiagnostic[] = collectImportDiagnostics((sink) =>
+      parseDragonBonesSkeleton(JSON.stringify(doc), sink),
+    );
+    expect(crumbs.map((c) => c.kind)).toContain('dragonbones.boundingBox-display-unsupported');
+    // displayIndex 1 still resolves to the image, not shifted down by the dropped mesh.
+    const region = parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.slots![0].attachment as RegionAttachment2D;
+    expect(region.kind).toBe(RegionAttachment2DKind);
+    expect(region.x).toBe(9);
+  });
+
+  it('Skip-crumbs additional armatures, alternate skins, and the unmodeled animation section', () => {
+    const doc = {
+      armature: [
+        {
+          bone: [{ name: 'root' }],
+          slot: [{ name: 's', parent: 'root' }],
+          skin: [
+            { name: 'default', slot: [] },
+            { name: 'costume2', slot: [] },
+          ],
+          animation: [{ name: 'idle', duration: 1 }],
+        },
+        { bone: [{ name: 'other' }] },
+      ],
+    };
+    const crumbs: ImportDiagnostic[] = collectImportDiagnostics((sink) =>
+      parseDragonBonesSkeleton(JSON.stringify(doc), sink),
+    );
+    const kinds = crumbs.map((c) => c.kind);
+    expect(kinds).toContain('dragonbones.multi-armature-unsupported');
+    expect(kinds).toContain('dragonbones.alternate-skin-unsupported');
+    expect(kinds).toContain('dragonbones.animation-unsupported');
+    // Only the first armature is parsed.
+    expect(parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.bones[0].name).toBe('root');
+  });
+
+  it('emits a bone with an unresolved parent as a root and Skip-crumbs it', () => {
+    const doc = { armature: [{ bone: [{ name: 'orphan', parent: 'ghost' }] }] };
+    const kinds = collectImportDiagnostics((sink) => parseDragonBonesSkeleton(JSON.stringify(doc), sink)).map(
+      (c) => c.kind,
+    );
+    expect(kinds).toContain('dragonbones.unresolved-bone-parent');
+    expect(parseDragonBonesSkeleton(JSON.stringify(doc))!.skeleton.bones[0].parentIndex).toBe(-1);
+  });
+
+  it('returns null for malformed JSON and for a non-DragonBones document (no armature)', () => {
+    expect(parseDragonBonesSkeleton('{ not json')).toBeNull();
+    expect(parseDragonBonesSkeleton('42')).toBeNull();
+    expect(parseDragonBonesSkeleton(JSON.stringify({ bones: [] }))).toBeNull(); // a Spine-shaped doc
+    expect(parseDragonBonesSkeleton(JSON.stringify({ armature: [] }))).toBeNull(); // empty armature list
+  });
+});

package/src/skeletonDetect.test.ts

@@ -0,0 +1,50 @@
+import type { ImportDiagnostic, Skeleton2DImport } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { parseSkeleton2D, registerSkeleton2DFormat } from './skeletonDetect';
+
+describe('parseSkeleton2D', () => {
+  it('auto-detects a Spine JSON document and parses it', () => {
+    const doc = JSON.stringify({ skeleton: { spine: '4.1' }, bones: [{ name: 'root' }] });
+    const result = parseSkeleton2D(doc);
+    expect(result).not.toBeNull();
+    expect(result!.skeleton.bones.length).toBe(1);
+    expect(result!.skeleton.bones[0].name).toBe('root');
+  });
+
+  it('threads the diagnostics sink through to the detected parser', () => {
+    const crumbs: ImportDiagnostic[] = [];
+    const doc = JSON.stringify({
+      bones: [{ name: 'root' }],
+      slots: [{ name: 's', bone: 'root', attachment: 'c' }],
+      skins: [{ name: 'default', attachments: { s: { c: { type: 'point' } } } }],
+    });
+    parseSkeleton2D(doc, crumbs);
+    expect(crumbs.map((c) => c.kind)).toContain('spine.point-attachment-unsupported');
+  });
+
+  it('auto-detects a DragonBones JSON document (armature container) and parses it', () => {
+    const doc = JSON.stringify({ version: '5.5', armature: [{ bone: [{ name: 'root' }] }] });
+    const result = parseSkeleton2D(doc);
+    expect(result).not.toBeNull();
+    expect(result!.skeleton.bones[0].name).toBe('root');
+  });
+
+  it('returns null when no registered format recognizes the text', () => {
+    expect(parseSkeleton2D('not a skeleton')).toBeNull();
+    expect(parseSkeleton2D('<xml/>')).toBeNull();
+    expect(parseSkeleton2D('{ "unrelated": true }')).toBeNull();
+  });
+});
+
+describe('registerSkeleton2DFormat', () => {
+  it('registers a custom (vendor-prefixed) format that parseSkeleton2D then dispatches to', () => {
+    const sentinel = { animations: [], skeleton: { bones: [], slots: null } } as unknown as Skeleton2DImport;
+    registerSkeleton2DFormat(
+      'acme.Rig',
+      (text) => text.startsWith('ACME'),
+      () => sentinel,
+    );
+    expect(parseSkeleton2D('ACME rig v1')).toBe(sentinel);
+  });
+});

package/src/spineParse.test.ts

@@ -0,0 +1,292 @@
+import { collectImportDiagnostics } from '@flighthq/importdiagnostics/contract';
+import { applyAnimationClipToSkeleton2D, cloneSkeleton2D } from '@flighthq/skeleton2d/contract';
+import type { ImportDiagnostic, MeshAttachment2D, RegionAttachment2D } from '@flighthq/types/contract';
+import { MeshAttachment2DKind, RegionAttachment2DKind, TransformMode2D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { parseSpineSkeleton } from './spineParse';
+
+// Hand-authored minimal Spine skeleton JSON (per the real-asset rule: committed fixtures are hand-written,
+// never transcribed from a licensed rig). Two bones: a root, and a child that sets every transform field.
+const SPINE_TWO_BONES = JSON.stringify({
+  skeleton: { spine: '4.1', hash: 'x' },
+  bones: [
+    { name: 'root' },
+    {
+      name: 'arm',
+      parent: 'root',
+      length: 50,
+      x: 10,
+      y: 20,
+      rotation: 45,
+      scaleX: 2,
+      scaleY: 3,
+      shearX: 5,
+      shearY: 6,
+      transform: 'onlyTranslation',
+    },
+  ],
+});
+
+describe('parseSpineSkeleton', () => {
+  it('parses the bone hierarchy: names, parent resolution, TRS, and transform mode', () => {
+    const result = parseSpineSkeleton(SPINE_TWO_BONES);
+    expect(result).not.toBeNull();
+    const bones = result!.skeleton.bones;
+    expect(bones.length).toBe(2);
+    expect(bones[0].name).toBe('root');
+    expect(bones[0].parentIndex).toBe(-1);
+    expect(bones[0].transformMode).toBe(TransformMode2D.Normal);
+
+    const arm = bones[1];
+    expect(arm.name).toBe('arm');
+    expect(arm.parentIndex).toBe(0); // 'root' resolved to index 0
+    expect(arm.length).toBe(50);
+    expect(arm.x).toBe(10);
+    expect(arm.y).toBe(20);
+    expect(arm.rotation).toBe(45);
+    expect(arm.scaleX).toBe(2);
+    expect(arm.scaleY).toBe(3);
+    expect(arm.shearX).toBe(5);
+    expect(arm.shearY).toBe(6);
+    expect(arm.transformMode).toBe(TransformMode2D.OnlyTranslation);
+  });
+
+  it('applies Spine defaults for omitted bone fields', () => {
+    const bones = parseSpineSkeleton(JSON.stringify({ bones: [{ name: 'b' }] }))!.skeleton.bones;
+    expect(bones[0]).toMatchObject({
+      x: 0,
+      y: 0,
+      rotation: 0,
+      scaleX: 1,
+      scaleY: 1,
+      shearX: 0,
+      shearY: 0,
+      length: 0,
+      parentIndex: -1,
+      transformMode: TransformMode2D.Normal,
+    });
+  });
+
+  it('maps every Spine transform-mode string', () => {
+    const doc = {
+      bones: [
+        { name: 'a', transform: 'noRotationOrReflection' },
+        { name: 'b', transform: 'noScale' },
+        { name: 'c', transform: 'noScaleOrReflection' },
+        { name: 'd', transform: 'bogus' },
+      ],
+    };
+    const bones = parseSpineSkeleton(JSON.stringify(doc))!.skeleton.bones;
+    expect(bones[0].transformMode).toBe(TransformMode2D.NoRotationOrReflection);
+    expect(bones[1].transformMode).toBe(TransformMode2D.NoScale);
+    expect(bones[2].transformMode).toBe(TransformMode2D.NoScaleOrReflection);
+    expect(bones[3].transformMode).toBe(TransformMode2D.Normal); // unknown → default
+  });
+
+  it('returns null for malformed JSON and for a non-object document', () => {
+    expect(parseSpineSkeleton('{ not json')).toBeNull();
+    expect(parseSpineSkeleton('42')).toBeNull();
+    expect(parseSpineSkeleton('null')).toBeNull();
+  });
+
+  it('best-efforts an empty skeleton when bones are missing', () => {
+    const result = parseSpineSkeleton(JSON.stringify({ skeleton: { spine: '4.1' } }));
+    expect(result).not.toBeNull();
+    expect(result!.skeleton.bones.length).toBe(0);
+    expect(result!.animations).toEqual([]);
+  });
+
+  it('parses slots with resolved bone index, draw-order, region attachment, and color', () => {
+    const doc = {
+      bones: [{ name: 'root' }, { name: 'armBone', parent: 'root' }],
+      slots: [{ name: 'arm', bone: 'armBone', attachment: 'armImage', color: '80c0ffff' }],
+      skins: [
+        {
+          name: 'default',
+          attachments: { arm: { armImage: { type: 'region', x: 1, y: 2, rotation: 30, width: 40, height: 20 } } },
+        },
+      ],
+    };
+    const slots = parseSpineSkeleton(JSON.stringify(doc))!.skeleton.slots!;
+    expect(slots.length).toBe(1);
+    expect(slots[0].name).toBe('arm');
+    expect(slots[0].boneIndex).toBe(1); // 'armBone' resolved
+    expect(slots[0].color).toBe(0x80c0ffff);
+    const region = slots[0].attachment as RegionAttachment2D;
+    expect(region.kind).toBe(RegionAttachment2DKind);
+    expect(region).toMatchObject({ x: 1, y: 2, rotation: 30, width: 40, height: 20, scaleX: 1, scaleY: 1 });
+  });
+
+  it('parses an unweighted mesh attachment (positions local to the bone, skin null)', () => {
+    const doc = {
+      bones: [{ name: 'root' }],
+      slots: [{ name: 's', bone: 'root', attachment: 'm' }],
+      skins: [
+        {
+          name: 'default',
+          attachments: {
+            s: { m: { type: 'mesh', uvs: [0, 0, 1, 0, 1, 1], triangles: [0, 1, 2], vertices: [0, 0, 10, 0, 10, 10] } },
+          },
+        },
+      ],
+    };
+    const mesh = parseSpineSkeleton(JSON.stringify(doc))!.skeleton.slots![0].attachment as MeshAttachment2D;
+    expect(mesh.kind).toBe(MeshAttachment2DKind);
+    expect(mesh.skin).toBeNull();
+    expect(mesh.vertexCount).toBe(3);
+    expect(Array.from(mesh.vertices!)).toEqual([0, 0, 10, 0, 10, 10]);
+    expect(Array.from(mesh.triangles)).toEqual([0, 1, 2]);
+  });
+
+  it('parses a weighted mesh attachment into a Skin2D influence stream', () => {
+    // 1 vertex, 2 influences: bone 0 offset (1,2) w0.25, bone 1 offset (3,4) w0.75. uvs give vertexCount=1.
+    const doc = {
+      bones: [{ name: 'a' }, { name: 'b' }],
+      slots: [{ name: 's', bone: 'a', attachment: 'm' }],
+      skins: [
+        {
+          name: 'default',
+          attachments: {
+            s: { m: { type: 'mesh', uvs: [0, 0], triangles: [], vertices: [2, 0, 1, 2, 0.25, 1, 3, 4, 0.75] } },
+          },
+        },
+      ],
+    };
+    const mesh = parseSpineSkeleton(JSON.stringify(doc))!.skeleton.slots![0].attachment as MeshAttachment2D;
+    expect(mesh.vertices).toBeNull();
+    expect(mesh.skin).not.toBeNull();
+    expect(Array.from(mesh.skin!.influenceCounts)).toEqual([2]);
+    expect(Array.from(mesh.skin!.influences)).toEqual([0, 1, 2, 0.25, 1, 3, 4, 0.75]);
+  });
+
+  it('recovers a malformed bone as an aligned placeholder so file-order indices stay valid (read-integrity axis 12)', () => {
+    // The bone array is positionally referenced by weighted-mesh influences, so a malformed entry must hold
+    // its slot rather than drop — else every later bone shifts and those indices point at the wrong bone.
+    const doc = { bones: [{ name: 'a' }, null, { name: 'c' }] };
+    const crumbs: ImportDiagnostic[] = collectImportDiagnostics((sink) =>
+      parseSpineSkeleton(JSON.stringify(doc), sink),
+    );
+    const bones = parseSpineSkeleton(JSON.stringify(doc))!.skeleton.bones;
+    expect(bones.length).toBe(3); // placeholder holds index 1
+    expect(bones[0].name).toBe('a');
+    expect(bones[1].name).toBeNull(); // inert placeholder
+    expect(bones[2].name).toBe('c'); // still at index 2 — NOT shifted down to 1
+    expect(crumbs.map((c) => c.kind)).toContain('spine.malformed-bone-recovered');
+  });
+
+  it('bounds a weighted-vertex stream against its actual length instead of reading past it (read-integrity axis 13)', () => {
+    // vertexCount = 1 (from uvs); the stream declares boneCount 5 but supplies only one (boneIndex,x,y,weight)
+    // quad. The declared count is clamped to what the stream actually holds — no undefined→NaN, no runaway loop.
+    const doc = {
+      bones: [{ name: 'a' }],
+      slots: [{ name: 's', bone: 'a', attachment: 'm' }],
+      skins: [
+        {
+          name: 'default',
+          attachments: { s: { m: { type: 'mesh', uvs: [0, 0], triangles: [], vertices: [5, 0, 1, 2, 0.25] } } },
+        },
+      ],
+    };
+    const crumbs: ImportDiagnostic[] = collectImportDiagnostics((sink) =>
+      parseSpineSkeleton(JSON.stringify(doc), sink),
+    );
+    const mesh = parseSpineSkeleton(JSON.stringify(doc))!.skeleton.slots![0].attachment as MeshAttachment2D;
+    expect(Array.from(mesh.skin!.influenceCounts)).toEqual([1]); // clamped 5 → 1
+    expect(Array.from(mesh.skin!.influences)).toEqual([0, 1, 2, 0.25]); // exactly the one available quad
+    expect(crumbs.map((c) => c.kind)).toContain('spine.weighted-vertices-truncated');
+  });
+
+  it('Skip-crumbs an unmodeled attachment type and an alternate skin', () => {
+    const doc = {
+      bones: [{ name: 'root' }],
+      slots: [{ name: 's', bone: 'root', attachment: 'clip' }],
+      skins: [
+        { name: 'default', attachments: { s: { clip: { type: 'clipping', end: 's', vertexCount: 4, vertices: [] } } } },
+        { name: 'costume2', attachments: {} },
+      ],
+    };
+    const crumbs: ImportDiagnostic[] = collectImportDiagnostics((sink) =>
+      parseSpineSkeleton(JSON.stringify(doc), sink),
+    );
+    expect(crumbs.map((c) => c.kind)).toContain('spine.clipping-attachment-unsupported');
+    expect(crumbs.map((c) => c.kind)).toContain('spine.alternate-skin-unsupported');
+    // The clipping attachment was dropped (not shown on the slot).
+    expect(parseSpineSkeleton(JSON.stringify(doc))!.skeleton.slots![0].attachment).toBeNull();
+  });
+
+  it('builds a named animation clip of RELATIVE deltas that compose onto the setup pose', () => {
+    const doc = {
+      bones: [{ name: 'b', rotation: 10, x: 5, scaleX: 2 }],
+      animations: {
+        walk: {
+          bones: {
+            b: {
+              rotate: [
+                { time: 0, value: 0 },
+                { time: 1, value: 90 },
+              ],
+              translate: [
+                { time: 0, x: 0, y: 0 },
+                { time: 1, x: 20, y: 0 },
+              ],
+              scale: [
+                { time: 0, x: 1, y: 1 },
+                { time: 1, x: 3, y: 1 },
+              ],
+            },
+          },
+        },
+      },
+    };
+    const result = parseSpineSkeleton(JSON.stringify(doc))!;
+    expect(result.animations.length).toBe(1);
+    expect(result.animations[0].name).toBe('walk');
+    // Compose the clip onto a pose clone at t=1. The end result is identical to the old setup-baked
+    // encoding — rotation 10+90, x 5+20, scaleX 2*3 — confirming the relative-delta switch is numerically
+    // neutral on the original rig; the win is portability/blending, not different numbers.
+    const setup = result.skeleton;
+    const pose = cloneSkeleton2D(setup);
+    applyAnimationClipToSkeleton2D(result.animations[0].clip, setup, pose, 1);
+    expect(pose.bones[0].rotation).toBeCloseTo(100, 5);
+    expect(pose.bones[0].x).toBeCloseTo(25, 5);
+    expect(pose.bones[0].scaleX).toBeCloseTo(6, 5); // multiplier: setup 2 × 3
+    expect(setup.bones[0].rotation).toBe(10); // the parsed setup pose is left intact
+  });
+
+  it('uses Step interpolation when every keyframe of a timeline is stepped', () => {
+    const doc = {
+      bones: [{ name: 'b' }],
+      animations: {
+        a: {
+          bones: {
+            b: {
+              rotate: [
+                { time: 0, value: 0, curve: 'stepped' },
+                { time: 1, value: 90, curve: 'stepped' },
+              ],
+            },
+          },
+        },
+      },
+    };
+    const result = parseSpineSkeleton(JSON.stringify(doc))!;
+    const pose = cloneSkeleton2D(result.skeleton);
+    applyAnimationClipToSkeleton2D(result.animations[0].clip, result.skeleton, pose, 0.9);
+    expect(pose.bones[0].rotation).toBeCloseTo(0, 5); // stepped holds the t=0 keyframe (delta 0) until t=1
+  });
+
+  it('Skip-crumbs constraint, event, and slot animation timelines', () => {
+    const doc = {
+      bones: [{ name: 'b' }],
+      animations: {
+        a: { bones: {}, ik: { c1: [] }, transform: { t1: [] }, events: [{ time: 0, name: 'e' }], slots: { s: {} } },
+      },
+    };
+    const kinds = collectImportDiagnostics((sink) => parseSpineSkeleton(JSON.stringify(doc), sink)).map((c) => c.kind);
+    expect(kinds).toContain('spine.ik-timeline-unsupported');
+    expect(kinds).toContain('spine.transform-timeline-unsupported');
+    expect(kinds).toContain('spine.event-timeline-unsupported');
+    expect(kinds).toContain('spine.slot-timeline-unsupported');
+  });
+});