@flighthq/skeleton2d-formats 0.3.0-edge.1458.0c01b63

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/spineBinaryParse.test.ts

@@ -0,0 +1,418 @@
+import { easeCubicBezier } from '@flighthq/easing/contract';
+import { collectImportDiagnostics } from '@flighthq/importdiagnostics/contract';
+import { applyAnimationClipToSkeleton2D, cloneSkeleton2D } from '@flighthq/skeleton2d/contract';
+import type { RegionAttachment2D } from '@flighthq/types/contract';
+import { RegionAttachment2DKind, TransformMode2D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { parseSpineSkeletonBinary } from './spineBinaryParse';
+
+describe('parseSpineSkeletonBinary', () => {
+  it('parses the header, bones, and slots of a 4.x file', () => {
+    const result = parseSpineSkeletonBinary(buildSpineBinary())!;
+    expect(result).not.toBeNull();
+    const bones = result.skeleton.bones;
+    expect(bones.length).toBe(2);
+    expect(bones[0]).toMatchObject({ name: 'root', parentIndex: -1, rotation: 0, x: 0, y: 0 });
+    // Bone 0 writes NO parent index — the reader must not consume one for it, or every later field shifts.
+    expect(bones[1]).toMatchObject({
+      length: 26.25,
+      name: 'hip',
+      parentIndex: 0,
+      rotation: 19.5,
+      scaleX: 2,
+      scaleY: 0.5,
+      shearX: 1.5,
+      shearY: -1.5,
+      x: 1.25,
+      y: 247.5,
+    });
+    const slots = result.skeleton.slots!;
+    expect(slots.length).toBe(1);
+    expect(slots[0]).toMatchObject({ boneIndex: 1, color: 0x80c0ffff, name: 'body' });
+  });
+
+  it('builds a named clip of RELATIVE bone deltas, like the .json parser', () => {
+    const result = parseSpineSkeletonBinary(buildSpineBinary())!;
+    expect(result.animations.length).toBe(1);
+    expect(result.animations[0].name).toBe('walk');
+    // Setup rotation is 19.5 on the hip; the timeline's +90 delta composes onto it rather than replacing it.
+    const setup = result.skeleton;
+    const pose = cloneSkeleton2D(setup);
+    applyAnimationClipToSkeleton2D(result.animations[0].clip, setup, pose, 1);
+    expect(pose.bones[1].rotation).toBeCloseTo(109.5, 4);
+    expect(setup.bones[1].rotation).toBeCloseTo(19.5, 4); // setup left intact
+  });
+
+  it('widens a PER-AXIS timeline, leaving the untouched axis at its setup value', () => {
+    // Ordinal 2 is translateX: one value per keyframe, driving only x. y must receive the identity delta,
+    // not garbage — a two-component path cannot express "x only" any other way.
+    const result = parseSpineSkeletonBinary(buildSpineBinary({ boneTimelineType: 2 }))!;
+    const setup = result.skeleton;
+    const pose = cloneSkeleton2D(setup);
+    applyAnimationClipToSkeleton2D(result.animations[0].clip, setup, pose, 1);
+    expect(pose.bones[1].x).toBeCloseTo(1.25 + 90, 4); // setup x + delta
+    expect(pose.bones[1].y).toBeCloseTo(247.5, 4); // setup y, untouched
+  });
+
+  it('drives BOTH components from a combined translate timeline', () => {
+    const result = parseSpineSkeletonBinary(buildSpineBinary({ boneTimelineType: 1 }))!;
+    const setup = result.skeleton;
+    const pose = cloneSkeleton2D(setup);
+    applyAnimationClipToSkeleton2D(result.animations[0].clip, setup, pose, 1);
+    expect(pose.bones[1].x).toBeCloseTo(1.25 + 90, 4);
+    expect(pose.bones[1].y).toBeCloseTo(247.5 + 90, 4);
+  });
+
+  it('rebases a BEZIER segment onto per-interval easing, in absolute time/value units', () => {
+    const result = parseSpineSkeletonBinary(buildSpineBinary({ bezier: true }))!;
+    const track = result.animations[0].clip.channels[0].track;
+    expect(track.segmentEasings).not.toBeNull();
+    const setup = result.skeleton;
+    const pose = cloneSkeleton2D(setup);
+    applyAnimationClipToSkeleton2D(result.animations[0].clip, setup, pose, 0.5);
+    // curve [0.42, 0, 1, 90] over a 0..1s / 0..90deg segment is the CSS ease-in shape.
+    expect(pose.bones[1].rotation).toBeCloseTo(19.5 + 90 * easeCubicBezier(0.42, 0, 1, 1)(0.5), 3);
+  });
+
+  it('leaves a LINEAR timeline with no segment easings', () => {
+    const track = parseSpineSkeletonBinary(buildSpineBinary())!.animations[0].clip.channels[0].track;
+    expect(track.segmentEasings).toBeNull();
+  });
+
+  it('resolves a slot to the setup attachment the SKIN defines, which is read after the slot', () => {
+    // The slot names its attachment before the skin exists in the stream, so this is the ordering the parser
+    // has to defer: name captured during slots, resolved once the skin is parsed.
+    const region = parseSpineSkeletonBinary(buildSpineBinary())!.skeleton.slots![0].attachment as RegionAttachment2D;
+    expect(region).not.toBeNull();
+    expect(region.kind).toBe(RegionAttachment2DKind);
+    expect(region).toMatchObject({ height: 32, name: 'body-attachment', rotation: 12.5, width: 64, x: 3.5, y: 4.5 });
+  });
+
+  it('parses a RIGID mesh attachment: uvs, triangles, and bone-local positions', () => {
+    const skin = parseSpineSkeletonBinary(buildSpineBinary())!;
+    // The mesh is the second attachment on the slot; it is not the setup one, so reach it via the region's
+    // sibling — the parse must still have consumed it correctly for the file to end cleanly.
+    const crumbs = collectImportDiagnostics((sink) => parseSpineSkeletonBinary(buildSpineBinary(), sink));
+    expect(crumbs.find((c) => c.kind === 'spine.binary-tail-unparsed')!.detail).toMatchObject({ bytes: 0 });
+    expect(skin.skeleton.slots!.length).toBe(1);
+  });
+
+  it('decodes a WEIGHTED mesh into Skin2D influences without re-packing', () => {
+    // Spine's binary influence stream is already [boneIndex, x, y, weight] per influence, which is exactly
+    // Skin2D's layout — so a wrong stride here would surface as a clean end-of-file failure.
+    const crumbs = collectImportDiagnostics((sink) =>
+      parseSpineSkeletonBinary(buildSpineBinary({ weightedMesh: true }), sink),
+    );
+    expect(crumbs.find((c) => c.kind === 'spine.binary-tail-unparsed')!.detail).toMatchObject({ bytes: 0 });
+    expect(crumbs.map((c) => c.kind)).not.toContain('spine.binary-truncated');
+  });
+
+  it('CONSUMES IK constraint records it does not model, so the skin after them still parses', () => {
+    // Constraints cannot be skipped — they carry no length — so mis-walking one desynchronizes the skin.
+    // A resolved attachment on the far side is therefore the proof that the walk was byte-exact.
+    const result = parseSpineSkeletonBinary(buildSpineBinary({ ikConstraints: 2 }))!;
+    expect(result.skeleton.slots![0].attachment).not.toBeNull();
+    const kinds = collectImportDiagnostics((sink) =>
+      parseSpineSkeletonBinary(buildSpineBinary({ ikConstraints: 2 }), sink),
+    ).map((c) => c.kind);
+    expect(kinds).toContain('spine.ik-constraint-unsupported');
+  });
+
+  it('REJECTS a version whose record layout this importer does not describe', () => {
+    const crumbs = collectImportDiagnostics((sink) =>
+      expect(parseSpineSkeletonBinary(buildSpineBinary({ version: '3.8.99' }), sink)).toBeNull(),
+    );
+    const crumb = crumbs.find((c) => c.kind === 'spine.binary-version-unsupported')!;
+    expect(crumb.detail).toMatchObject({ version: '3.8.99' });
+  });
+
+  it('REJECTS an unreadable header rather than decoding garbage', () => {
+    const kinds = collectImportDiagnostics((sink) =>
+      expect(parseSpineSkeletonBinary(Uint8Array.from([1, 2, 3]), sink)).toBeNull(),
+    ).map((c) => c.kind);
+    expect(kinds).toContain('spine.binary-header-unreadable');
+  });
+
+  it('reports how many bytes of the file it did not parse', () => {
+    const bytes = buildSpineBinary();
+    const crumbs = collectImportDiagnostics((sink) => parseSpineSkeletonBinary(bytes, sink));
+    const tail = crumbs.find((c) => c.kind === 'spine.binary-tail-unparsed')!;
+    // The fixture ends exactly where this landing stops parsing, so nothing is left over — the crumb still
+    // fires to record that the importer STOPPED rather than finished, which is the honest signal while the
+    // event and animation sections are still unmodeled.
+    expect(tail.detail).toMatchObject({ bytes: 0 });
+  });
+
+  it('RECOVERS from a truncated file, keeping whatever records were complete', () => {
+    const full = buildSpineBinary();
+    const truncated = full.subarray(0, full.byteLength - 6);
+    const crumbs = collectImportDiagnostics((sink) => parseSpineSkeletonBinary(truncated, sink));
+    expect(crumbs.map((c) => c.kind)).toContain('spine.binary-truncated');
+    // It still returns a skeleton rather than null or a throw: the bones completed before the cut.
+    const result = parseSpineSkeletonBinary(truncated)!;
+    expect(result.skeleton.bones.length).toBe(2);
+  });
+
+  it('maps the transform-mode ORDINAL positionally, falling back to Normal when out of range', () => {
+    const modes = [
+      TransformMode2D.Normal,
+      TransformMode2D.OnlyTranslation,
+      TransformMode2D.NoRotationOrReflection,
+      TransformMode2D.NoScale,
+      TransformMode2D.NoScaleOrReflection,
+    ];
+    for (let ordinal = 0; ordinal < modes.length; ordinal++) {
+      const bones = parseSpineSkeletonBinary(buildSpineBinary({ transformMode: ordinal }))!.skeleton.bones;
+      expect(bones[1].transformMode).toEqual(modes[ordinal]);
+    }
+    // An ordinal from a future version with more modes must not yield an undefined inherit rule.
+    const beyond = parseSpineSkeletonBinary(buildSpineBinary({ transformMode: 99 }))!.skeleton.bones;
+    expect(beyond[1].transformMode).toEqual(TransformMode2D.Normal);
+  });
+
+  it('honors the nonessential flag, which changes the bone record width', () => {
+    // With nonessential set, each bone carries a trailing editor color. Reading the flag but not the color
+    // would desynchronize every following record, so the slot below is the canary.
+    const result = parseSpineSkeletonBinary(buildSpineBinary({ nonessential: true }))!;
+    expect(result.skeleton.bones.length).toBe(2);
+    expect(result.skeleton.slots![0]).toMatchObject({ boneIndex: 1, name: 'body' });
+  });
+
+  it('Skip-crumbs a slot dark color, which Slot2D cannot represent', () => {
+    const kinds = collectImportDiagnostics((sink) =>
+      parseSpineSkeletonBinary(buildSpineBinary({ darkColor: 0x102030 }), sink),
+    ).map((c) => c.kind);
+    expect(kinds).toContain('spine.slot-dark-color-unsupported');
+    const plain = collectImportDiagnostics((sink) => parseSpineSkeletonBinary(buildSpineBinary(), sink)).map(
+      (c) => c.kind,
+    );
+    expect(plain).not.toContain('spine.slot-dark-color-unsupported');
+  });
+});
+
+// Builds a minimal but structurally faithful Spine 4.x `.skel`: hash, version, bounds, the nonessential
+// flag, a string table, two bones, and one slot. The byte layout it writes is the layout verified
+// byte-for-byte against a real 4.1.17 export (see the package status) — the encoder REPRODUCES a confirmed
+// wire format rather than defining it, which is what keeps these tests a real check and not a round-trip
+// against the importer's own assumptions. Real Spine assets are license-restricted and never committed, so
+// the committed fixture is authored here.
+function buildSpineBinary(
+  options: {
+    version?: string;
+    nonessential?: boolean;
+    transformMode?: number;
+    darkColor?: number;
+    ikConstraints?: number;
+    weightedMesh?: boolean;
+    animations?: boolean;
+    boneTimelineType?: number;
+    bezier?: boolean;
+  } = {},
+): Uint8Array {
+  const version = options.version ?? '4.1.17';
+  const nonessential = options.nonessential ?? false;
+  const out: number[] = [];
+  for (let i = 0; i < 8; i++) out.push(0); // export hash
+  writeString(out, version);
+  for (let i = 0; i < 4; i++) writeFloat(out, 0); // x, y, width, height
+  out.push(nonessential ? 1 : 0);
+  if (nonessential) {
+    writeFloat(out, 30);
+    writeString(out, './images/');
+    writeString(out, '');
+  }
+  writeVarint(out, 2); // string table
+  writeString(out, 'body-attachment');
+  writeString(out, 'body-mesh');
+
+  writeVarint(out, 2); // bones
+  writeBone(out, { name: 'root', parentIndex: null, nonessential });
+  writeBone(out, {
+    length: 26.25,
+    name: 'hip',
+    nonessential,
+    parentIndex: 0,
+    rotation: 19.5,
+    scaleX: 2,
+    scaleY: 0.5,
+    shearX: 1.5,
+    shearY: -1.5,
+    transformMode: options.transformMode ?? 0,
+    x: 1.25,
+    y: 247.5,
+  });
+
+  writeVarint(out, 1); // slots
+  writeString(out, 'body');
+  writeVarint(out, 1); // bone index
+  writeInt(out, 0x80c0ffff);
+  writeInt(out, options.darkColor ?? -1);
+  writeVarint(out, 1); // setup attachment -> string table entry 1, 'body-attachment'
+  writeVarint(out, 0); // blend mode: normal
+
+  // Constraint sections. Flight models no solvers, but the records sit between the slots and the skins, so
+  // the counts are always written even when empty.
+  writeVarint(out, options.ikConstraints ?? 0);
+  for (let i = 0; i < (options.ikConstraints ?? 0); i++) writeIkConstraint(out, 'ik' + i);
+  writeVarint(out, 0); // transform constraints
+  writeVarint(out, 0); // path constraints
+
+  // Default skin: one slot entry carrying a region and a mesh.
+  writeVarint(out, 1); // slot entries
+  writeVarint(out, 0); // slot index
+  writeVarint(out, 2); // attachments on it
+  writeVarint(out, 1); // key -> 'body-attachment'
+  writeVarint(out, 0); // name: absent, so the key is used
+  out.push(0); // type: region
+  writeVarint(out, 0); // atlas path
+  writeFloat(out, 12.5); // rotation
+  writeFloat(out, 3.5); // x
+  writeFloat(out, 4.5); // y
+  writeFloat(out, 1); // scaleX
+  writeFloat(out, 1); // scaleY
+  writeFloat(out, 64); // width
+  writeFloat(out, 32); // height
+  writeInt(out, 0xffffffff); // color
+  out.push(0); // sequence: absent
+  writeVarint(out, 2); // key -> 'body-mesh'
+  writeVarint(out, 0);
+  out.push(2); // type: mesh
+  writeVarint(out, 0); // atlas path
+  writeInt(out, 0xffffffff); // color
+  writeVarint(out, 3); // vertex count
+  for (const uv of [0, 0, 1, 0, 1, 1]) writeFloat(out, uv);
+  writeVarint(out, 3); // triangle index count
+  for (const t of [0, 1, 2]) writeShort(out, t);
+  out.push(options.weightedMesh ? 1 : 0);
+  if (options.weightedMesh) {
+    for (let v = 0; v < 3; v++) {
+      writeVarint(out, 1); // one influence
+      writeVarint(out, 1); // bone index
+      writeFloat(out, v);
+      writeFloat(out, v * 2);
+      writeFloat(out, 1); // weight
+    }
+  } else {
+    for (const xy of [0, 0, 10, 0, 10, 10]) writeFloat(out, xy);
+  }
+  writeVarint(out, 0); // hull length
+  out.push(0); // sequence: absent
+
+  writeVarint(out, 0); // alternate skins
+  writeVarint(out, 0); // event definitions
+
+  // Animations. One clip driving the hip bone, so the bone-timeline path is exercised end to end.
+  writeVarint(out, options.animations === false ? 0 : 1);
+  if (options.animations !== false) {
+    writeString(out, 'walk');
+    writeVarint(out, 1); // total timeline count
+    writeVarint(out, 0); // slot timelines
+    writeVarint(out, 1); // bone timelines
+    writeVarint(out, 1); // bone index
+    writeVarint(out, 1); // timelines on it
+    out.push(options.boneTimelineType ?? 0); // 0 = rotate
+    writeVarint(out, 2); // frame count
+    writeVarint(out, options.bezier ? 1 : 0); // bezier count
+    const values = options.boneTimelineType === 1 ? 2 : 1;
+    writeFloat(out, 0); // time
+    for (let v = 0; v < values; v++) writeFloat(out, 0);
+    writeFloat(out, 1); // next time
+    for (let v = 0; v < values; v++) writeFloat(out, 90);
+    if (options.bezier) {
+      out.push(2); // CURVE_BEZIER
+      for (let v = 0; v < values; v++) {
+        writeFloat(out, 0.42); // cx1 in absolute time units
+        writeFloat(out, 0); // cy1 in absolute value units
+        writeFloat(out, 1); // cx2
+        writeFloat(out, 90); // cy2
+      }
+    } else {
+      out.push(0); // CURVE_LINEAR
+    }
+    writeVarint(out, 0); // ik timelines
+    writeVarint(out, 0); // transform timelines
+    writeVarint(out, 0); // path timelines
+    writeVarint(out, 0); // deform timelines
+    writeVarint(out, 0); // draw order frames
+    writeVarint(out, 0); // event frames
+  }
+  return Uint8Array.from(out);
+}
+
+// An IK constraint record, written only so the parser has something real to walk past.
+function writeIkConstraint(out: number[], name: string): void {
+  writeString(out, name);
+  writeVarint(out, 0); // order
+  out.push(0); // skinRequired
+  writeVarint(out, 1); // bone count
+  writeVarint(out, 0); // bone
+  writeVarint(out, 0); // target
+  writeFloat(out, 1); // mix
+  writeFloat(out, 0); // softness
+  out.push(1, 0, 0, 0); // bendDirection, compress, stretch, uniform
+}
+
+function writeShort(out: number[], value: number): void {
+  out.push((value >> 8) & 0xff, value & 0xff);
+}
+
+function writeBone(
+  out: number[],
+  bone: {
+    name: string;
+    parentIndex: number | null;
+    nonessential: boolean;
+    rotation?: number;
+    x?: number;
+    y?: number;
+    scaleX?: number;
+    scaleY?: number;
+    shearX?: number;
+    shearY?: number;
+    length?: number;
+    transformMode?: number;
+  },
+): void {
+  writeString(out, bone.name);
+  if (bone.parentIndex !== null) writeVarint(out, bone.parentIndex);
+  writeFloat(out, bone.rotation ?? 0);
+  writeFloat(out, bone.x ?? 0);
+  writeFloat(out, bone.y ?? 0);
+  writeFloat(out, bone.scaleX ?? 1);
+  writeFloat(out, bone.scaleY ?? 1);
+  writeFloat(out, bone.shearX ?? 0);
+  writeFloat(out, bone.shearY ?? 0);
+  writeFloat(out, bone.length ?? 0);
+  writeVarint(out, bone.transformMode ?? 0);
+  out.push(0); // skinRequired
+  if (bone.nonessential) writeInt(out, 0xff00ffff);
+}
+
+function writeFloat(out: number[], value: number): void {
+  const view = new DataView(new ArrayBuffer(4));
+  view.setFloat32(0, value, false);
+  for (let i = 0; i < 4; i++) out.push(view.getUint8(i));
+}
+
+function writeInt(out: number[], value: number): void {
+  const view = new DataView(new ArrayBuffer(4));
+  view.setInt32(0, value, false);
+  for (let i = 0; i < 4; i++) out.push(view.getUint8(i));
+}
+
+// Spine's string encoding: a varint of `byteCount + 1` (0 would mean "absent"), then the UTF-8 bytes.
+function writeString(out: number[], value: string): void {
+  const bytes = new TextEncoder().encode(value);
+  writeVarint(out, bytes.length + 1);
+  for (const byte of bytes) out.push(byte);
+}
+
+function writeVarint(out: number[], value: number): void {
+  let remaining = value >>> 0;
+  while (remaining > 0x7f) {
+    out.push((remaining & 0x7f) | 0x80);
+    remaining >>>= 7;
+  }
+  out.push(remaining);
+}

package/src/spineBinaryReader.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createSpineBinaryReader,
+  hasSpineBinaryBytes,
+  isSpineBinaryReaderOverrun,
+  readSpineBinaryBoolean,
+  readSpineBinaryByte,
+  readSpineBinaryFloat,
+  readSpineBinaryInt,
+  readSpineBinarySignedVarint,
+  readSpineBinaryString,
+  readSpineBinaryUnsignedShort,
+  readSpineBinaryVarint,
+  skipSpineBinaryBytes,
+} from './spineBinaryReader';
+
+describe('createSpineBinaryReader', () => {
+  it('starts at the beginning and is not overrun', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([1, 2, 3]));
+    expect(reader.offset).toBe(0);
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(false);
+  });
+
+  it('reads only the window of a subarray, not the whole backing buffer', () => {
+    // A caller who slices one file out of a larger buffer must not be able to read its neighbours.
+    const backing = Uint8Array.from([0xaa, 0xbb, 0x07, 0xcc]);
+    const reader = createSpineBinaryReader(backing.subarray(2, 3));
+    expect(reader.view.byteLength).toBe(1);
+    expect(readSpineBinaryByte(reader)).toBe(0x07);
+    // The neighbouring 0xcc is outside the window, so the next read overruns rather than leaking it.
+    expect(readSpineBinaryByte(reader)).toBe(0);
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(true);
+  });
+});
+
+describe('hasSpineBinaryBytes', () => {
+  it('reports the bytes remaining and stays false once overrun', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([1, 2]));
+    expect(hasSpineBinaryBytes(reader, 2)).toBe(true);
+    expect(hasSpineBinaryBytes(reader, 3)).toBe(false);
+    readSpineBinaryByte(reader);
+    expect(hasSpineBinaryBytes(reader, 1)).toBe(true);
+    expect(hasSpineBinaryBytes(reader, 2)).toBe(false);
+    readSpineBinaryFloat(reader); // overruns
+    expect(hasSpineBinaryBytes(reader, 0)).toBe(false);
+  });
+});
+
+describe('isSpineBinaryReaderOverrun', () => {
+  it('treats a cursor resting exactly at the end as a clean end-of-stream', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([1]));
+    readSpineBinaryByte(reader);
+    expect(reader.offset).toBe(1);
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(false);
+  });
+
+  it('is STICKY — one short read short-circuits every later read', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0x41]));
+    expect(readSpineBinaryFloat(reader)).toBe(0); // needs 4, has 1
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(true);
+    // The unread 0x41 is NOT handed out afterwards: the mark short-circuits everything downstream.
+    expect(readSpineBinaryByte(reader)).toBe(0);
+    expect(readSpineBinaryString(reader)).toBeNull();
+    expect(readSpineBinaryBoolean(reader)).toBe(false);
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(true);
+  });
+
+  it('does not consume the bytes a short read could not satisfy', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([1, 2, 3]));
+    readSpineBinaryFloat(reader); // needs 4, has 3
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(true);
+    expect(reader.offset).toBeGreaterThan(reader.view.byteLength);
+  });
+});
+
+describe('readSpineBinaryBoolean', () => {
+  it('reads one byte, zero false and any nonzero true', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0, 1, 0xff]));
+    expect(readSpineBinaryBoolean(reader)).toBe(false);
+    expect(readSpineBinaryBoolean(reader)).toBe(true);
+    expect(readSpineBinaryBoolean(reader)).toBe(true);
+  });
+});
+
+describe('readSpineBinaryByte', () => {
+  it('reads unsigned bytes in order', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0x00, 0x7f, 0x80, 0xff]));
+    expect(readSpineBinaryByte(reader)).toBe(0x00);
+    expect(readSpineBinaryByte(reader)).toBe(0x7f);
+    expect(readSpineBinaryByte(reader)).toBe(0x80);
+    expect(readSpineBinaryByte(reader)).toBe(0xff);
+  });
+});
+
+describe('readSpineBinaryFloat', () => {
+  it('reads BIG-endian 32-bit floats', () => {
+    // 1.0 is 0x3f800000 and −2.5 is 0xc0200000; byte-swapped input would read as garbage, which is the
+    // point of asserting the byte order explicitly.
+    const reader = createSpineBinaryReader(Uint8Array.from([0x3f, 0x80, 0x00, 0x00, 0xc0, 0x20, 0x00, 0x00]));
+    expect(readSpineBinaryFloat(reader)).toBe(1);
+    expect(readSpineBinaryFloat(reader)).toBe(-2.5);
+  });
+});
+
+describe('readSpineBinaryInt', () => {
+  it('reads BIG-endian signed 32-bit integers', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0x00, 0x00, 0x01, 0x00, 0xff, 0xff, 0xff, 0xff]));
+    expect(readSpineBinaryInt(reader)).toBe(256);
+    expect(readSpineBinaryInt(reader)).toBe(-1);
+  });
+});
+
+describe('readSpineBinarySignedVarint', () => {
+  it('undoes the zigzag fold so small negatives cost one byte', () => {
+    // Raw varints 0,1,2,3,4 fold back to 0,−1,1,−2,2.
+    const reader = createSpineBinaryReader(Uint8Array.from([0, 1, 2, 3, 4]));
+    expect(readSpineBinarySignedVarint(reader)).toBe(0);
+    expect(readSpineBinarySignedVarint(reader)).toBe(-1);
+    expect(readSpineBinarySignedVarint(reader)).toBe(1);
+    expect(readSpineBinarySignedVarint(reader)).toBe(-2);
+    expect(readSpineBinarySignedVarint(reader)).toBe(2);
+  });
+
+  it('folds the widest five-byte pattern to the most negative int32', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0xff, 0xff, 0xff, 0xff, 0x0f]));
+    expect(readSpineBinarySignedVarint(reader)).toBe(-2147483648);
+  });
+});
+
+describe('readSpineBinaryString', () => {
+  it('distinguishes an ABSENT string from an empty one by the 0/1 length prefix', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0x00, 0x01]));
+    expect(readSpineBinaryString(reader)).toBeNull(); // 0 = no string at all
+    expect(readSpineBinaryString(reader)).toBe(''); // 1 = present but empty
+  });
+
+  it('reads `count − 1` bytes of UTF-8, including multi-byte code points', () => {
+    // 'abc' is 3 bytes so the prefix is 4; 'é' is the two bytes c3 a9 so its prefix is 3.
+    const reader = createSpineBinaryReader(Uint8Array.from([0x04, 0x61, 0x62, 0x63, 0x03, 0xc3, 0xa9]));
+    expect(readSpineBinaryString(reader)).toBe('abc');
+    expect(readSpineBinaryString(reader)).toBe('é');
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(false);
+  });
+
+  it('reads a string out of a subarray window without leaking past it', () => {
+    const backing = Uint8Array.from([0xaa, 0x03, 0x68, 0x69, 0xbb]);
+    const reader = createSpineBinaryReader(backing.subarray(1, 4));
+    expect(readSpineBinaryString(reader)).toBe('hi');
+  });
+
+  it('returns the null sentinel when the declared length runs past the end', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0x09, 0x61, 0x62]));
+    expect(readSpineBinaryString(reader)).toBeNull();
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(true);
+  });
+});
+
+describe('readSpineBinaryUnsignedShort', () => {
+  it('reads BIG-endian unsigned 16-bit values', () => {
+    // 0xffff read unsigned is 65535, not -1 — the point of asserting this isn't the signed reading.
+    const reader = createSpineBinaryReader(Uint8Array.from([0x01, 0x00, 0xff, 0xff]));
+    expect(readSpineBinaryUnsignedShort(reader)).toBe(256);
+    expect(readSpineBinaryUnsignedShort(reader)).toBe(65535);
+  });
+});
+
+describe('readSpineBinaryVarint', () => {
+  it('reads the 7-bits-per-byte encoding across every byte-count boundary', () => {
+    const reader = createSpineBinaryReader(
+      Uint8Array.from([
+        0x00, // 0
+        0x7f, // 127 — the largest one-byte value
+        0x80,
+        0x01, // 128 — the smallest two-byte value
+        0xff,
+        0x7f, // 16383 — the largest two-byte value
+        0x80,
+        0x80,
+        0x01, // 16384
+      ]),
+    );
+    expect(readSpineBinaryVarint(reader)).toBe(0);
+    expect(readSpineBinaryVarint(reader)).toBe(127);
+    expect(readSpineBinaryVarint(reader)).toBe(128);
+    expect(readSpineBinaryVarint(reader)).toBe(16383);
+    expect(readSpineBinaryVarint(reader)).toBe(16384);
+  });
+
+  it('returns the widest five-byte pattern UNSIGNED rather than as a negative int32', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0xff, 0xff, 0xff, 0xff, 0x0f]));
+    expect(readSpineBinaryVarint(reader)).toBe(4294967295);
+  });
+
+  it('stops at the buffer end instead of reading past it when a continuation byte is missing', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([0x80])); // says "more follows", but nothing does
+    expect(readSpineBinaryVarint(reader)).toBe(0);
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(true);
+  });
+});
+
+describe('skipSpineBinaryBytes', () => {
+  it('advances past unmodelled fields', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([1, 2, 3, 4]));
+    skipSpineBinaryBytes(reader, 3);
+    expect(readSpineBinaryByte(reader)).toBe(4);
+  });
+
+  it('marks overrun rather than skipping past the end', () => {
+    const reader = createSpineBinaryReader(Uint8Array.from([1, 2]));
+    skipSpineBinaryBytes(reader, 5);
+    expect(isSpineBinaryReaderOverrun(reader)).toBe(true);
+  });
+});