@flighthq/mesh 0.1.0

package/src/meshGeometryCompute.test.ts

@@ -0,0 +1,218 @@
+import { createAabb, createBoundingSphere } from '@flighthq/geometry';
+import type { VertexAttributeLayout } from '@flighthq/types';
+
+import { createMeshGeometry } from './meshGeometry';
+import {
+  computeMeshGeometryBoundingSphere,
+  computeMeshGeometryBounds,
+  computeMeshGeometryFlatNormals,
+  computeMeshGeometryNormals,
+  computeMeshGeometryTangents,
+} from './meshGeometryCompute';
+
+const CANONICAL_LAYOUT: VertexAttributeLayout = {
+  attributes: [
+    { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+    { byteOffset: 12, format: 'float32x3', semantic: 'normal' },
+    { byteOffset: 24, format: 'float32x4', semantic: 'tangent' },
+    { byteOffset: 40, format: 'float32x2', semantic: 'uv0' },
+  ],
+  stride: 48,
+};
+
+// One CCW triangle in the XY plane (normal +Z) with a u-along-X, v-along-Y UV mapping.
+function makeTriangle() {
+  const vertices = new Float32Array(3 * 12);
+  const setVertex = (i: number, px: number, py: number, u: number, v: number): void => {
+    const b = i * 12;
+    vertices[b] = px;
+    vertices[b + 1] = py;
+    vertices[b + 2] = 0;
+    vertices[b + 10] = u;
+    vertices[b + 11] = v;
+  };
+  setVertex(0, 0, 0, 0, 0);
+  setVertex(1, 1, 0, 1, 0);
+  setVertex(2, 0, 1, 0, 1);
+  const indices = new Uint16Array([0, 1, 2]);
+  return createMeshGeometry({ indices: indices, layout: CANONICAL_LAYOUT, vertices: vertices });
+}
+
+describe('computeMeshGeometryBoundingSphere', () => {
+  it('writes the center and radius for a unit-side triangle', () => {
+    const geometry = makeTriangle();
+    const out = createBoundingSphere();
+    computeMeshGeometryBoundingSphere(out, geometry);
+    // AABB of the triangle: min=(0,0,0) max=(1,1,0) → center=(0.5,0.5,0).
+    expect(out.center.x).toBeCloseTo(0.5);
+    expect(out.center.y).toBeCloseTo(0.5);
+    expect(out.center.z).toBeCloseTo(0);
+    expect(out.radius).toBeGreaterThan(0);
+  });
+
+  it('radius encloses all vertices', () => {
+    const geometry = makeTriangle();
+    const out = createBoundingSphere();
+    computeMeshGeometryBoundingSphere(out, geometry);
+    const cx = out.center.x,
+      cy = out.center.y,
+      cz = out.center.z;
+    const r = out.radius;
+    const verts = geometry.vertices;
+    for (let i = 0; i < 3; i++) {
+      const dx = verts[i * 12] - cx;
+      const dy = verts[i * 12 + 1] - cy;
+      const dz = verts[i * 12 + 2] - cz;
+      expect(Math.sqrt(dx * dx + dy * dy + dz * dz)).toBeLessThanOrEqual(r + 1e-6);
+    }
+  });
+
+  it('yields empty sphere (radius -1) for an empty vertex stream', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: new Float32Array(0) });
+    const out = createBoundingSphere();
+    computeMeshGeometryBoundingSphere(out, geometry);
+    expect(out.radius).toBe(-1);
+    expect(out.center.x).toBe(0);
+    expect(out.center.y).toBe(0);
+    expect(out.center.z).toBe(0);
+  });
+});
+
+describe('computeMeshGeometryBounds', () => {
+  it('writes the tight AABB of all positions', () => {
+    const geometry = makeTriangle();
+    const out = createAabb();
+    computeMeshGeometryBounds(out, geometry);
+    expect(out.min.x).toBe(0);
+    expect(out.min.y).toBe(0);
+    expect(out.max.x).toBe(1);
+    expect(out.max.y).toBe(1);
+    expect(out.max.z).toBe(0);
+  });
+
+  it('is safe when out aliases geometry bounds', () => {
+    const geometry = makeTriangle();
+    geometry.bounds = createAabb();
+    computeMeshGeometryBounds(geometry.bounds, geometry);
+    expect(geometry.bounds.max.x).toBe(1);
+    expect(geometry.bounds.min.y).toBe(0);
+  });
+
+  it('yields an empty box for an empty vertex stream', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: new Float32Array(0) });
+    const out = createAabb(1, 2, 3, 4, 5, 6);
+    computeMeshGeometryBounds(out, geometry);
+    expect(out.min.x).toBe(Number.POSITIVE_INFINITY);
+    expect(out.max.x).toBe(Number.NEGATIVE_INFINITY);
+  });
+});
+
+describe('computeMeshGeometryFlatNormals', () => {
+  it('writes the face normal to all three vertices of a CCW triangle (indexed)', () => {
+    const geometry = makeTriangle();
+    computeMeshGeometryFlatNormals(geometry, geometry);
+    // All three vertices should have the face normal +Z.
+    for (let i = 0; i < 3; i++) {
+      expect(geometry.vertices[i * 12 + 3]).toBeCloseTo(0);
+      expect(geometry.vertices[i * 12 + 4]).toBeCloseTo(0);
+      expect(geometry.vertices[i * 12 + 5]).toBeCloseTo(1);
+    }
+  });
+
+  it('writes the face normal to all three vertices of a CCW triangle (non-indexed)', () => {
+    const vertices = new Float32Array(3 * 12);
+    const setVertex = (i: number, px: number, py: number): void => {
+      const b = i * 12;
+      vertices[b] = px;
+      vertices[b + 1] = py;
+      vertices[b + 2] = 0;
+    };
+    setVertex(0, 0, 0);
+    setVertex(1, 1, 0);
+    setVertex(2, 0, 1);
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: vertices });
+    computeMeshGeometryFlatNormals(geometry, geometry);
+    for (let i = 0; i < 3; i++) {
+      expect(geometry.vertices[i * 12 + 3]).toBeCloseTo(0);
+      expect(geometry.vertices[i * 12 + 4]).toBeCloseTo(0);
+      expect(geometry.vertices[i * 12 + 5]).toBeCloseTo(1);
+    }
+  });
+
+  it('is safe when out aliases geometry (alias-safe)', () => {
+    const geometry = makeTriangle();
+    const prevVersion = geometry.version;
+    computeMeshGeometryFlatNormals(geometry, geometry);
+    expect(geometry.version).toBe(prevVersion + 1);
+    expect(geometry.vertices[5]).toBeCloseTo(1);
+  });
+
+  it('bumps version', () => {
+    const geometry = makeTriangle();
+    const prevVersion = geometry.version;
+    computeMeshGeometryFlatNormals(geometry, geometry);
+    expect(geometry.version).toBe(prevVersion + 1);
+  });
+
+  it('produces unit-length normals', () => {
+    const geometry = makeTriangle();
+    computeMeshGeometryFlatNormals(geometry, geometry);
+    for (let i = 0; i < 3; i++) {
+      const nx = geometry.vertices[i * 12 + 3];
+      const ny = geometry.vertices[i * 12 + 4];
+      const nz = geometry.vertices[i * 12 + 5];
+      expect(Math.sqrt(nx * nx + ny * ny + nz * nz)).toBeCloseTo(1);
+    }
+  });
+});
+
+describe('computeMeshGeometryNormals', () => {
+  it('writes the unit face normal in-place for a CCW triangle', () => {
+    const geometry = makeTriangle();
+    computeMeshGeometryNormals(geometry, geometry);
+    // Face normal of a CCW XY triangle is +Z.
+    expect(geometry.vertices[3]).toBeCloseTo(0);
+    expect(geometry.vertices[4]).toBeCloseTo(0);
+    expect(geometry.vertices[5]).toBeCloseTo(1);
+  });
+
+  it('writes into a distinct out geometry', () => {
+    const source = makeTriangle();
+    const out = makeTriangle();
+    computeMeshGeometryNormals(out, source);
+    expect(out.vertices[5]).toBeCloseTo(1);
+  });
+});
+
+describe('computeMeshGeometryTangents', () => {
+  it('writes a unit tangent aligned with +X for the canonical UV mapping', () => {
+    const geometry = makeTriangle();
+    computeMeshGeometryNormals(geometry, geometry);
+    computeMeshGeometryTangents(geometry, geometry);
+    // u increases along +X, so tangent.xyz ~ (1,0,0).
+    expect(geometry.vertices[6]).toBeCloseTo(1);
+    expect(geometry.vertices[7]).toBeCloseTo(0);
+    expect(geometry.vertices[8]).toBeCloseTo(0);
+    // Right-handed mapping => positive handedness.
+    expect(geometry.vertices[9]).toBe(1);
+  });
+
+  it('writes into a distinct out geometry', () => {
+    const source = makeTriangle();
+    computeMeshGeometryNormals(source, source);
+    const out = makeTriangle();
+    computeMeshGeometryNormals(out, out);
+    computeMeshGeometryTangents(out, source);
+    expect(out.vertices[6]).toBeCloseTo(1);
+    expect(out.vertices[9]).toBe(1);
+  });
+
+  it('produces negative handedness when the v axis is flipped', () => {
+    const geometry = makeTriangle();
+    // Flip v on vertex 2 so the UV winding reverses relative to geometry.
+    geometry.vertices[2 * 12 + 11] = -1;
+    computeMeshGeometryNormals(geometry, geometry);
+    computeMeshGeometryTangents(geometry, geometry);
+    expect(geometry.vertices[9]).toBe(-1);
+  });
+});

package/src/meshGeometryIndex.test.ts

@@ -0,0 +1,84 @@
+import type { VertexAttributeLayout } from '@flighthq/types';
+
+import { createMeshGeometry } from './meshGeometry';
+import { computeMeshGeometryWireframeIndices, expandMeshGeometryIndices } from './meshGeometryIndex';
+
+const CANONICAL_LAYOUT: VertexAttributeLayout = {
+  attributes: [
+    { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+    { byteOffset: 12, format: 'float32x3', semantic: 'normal' },
+    { byteOffset: 24, format: 'float32x4', semantic: 'tangent' },
+    { byteOffset: 40, format: 'float32x2', semantic: 'uv0' },
+  ],
+  stride: 48,
+};
+
+// A quad: 4 vertices, 2 triangles sharing the (1, 2) edge, position packed into slot 0.
+function makeQuad() {
+  const vertices = new Float32Array(4 * 12);
+  const setPosition = (i: number, x: number, y: number): void => {
+    vertices[i * 12] = x;
+    vertices[i * 12 + 1] = y;
+  };
+  setPosition(0, 0, 0);
+  setPosition(1, 1, 0);
+  setPosition(2, 0, 1);
+  setPosition(3, 1, 1);
+  const indices = new Uint16Array([0, 1, 2, 2, 1, 3]);
+  return createMeshGeometry({ indices: indices, layout: CANONICAL_LAYOUT, vertices: vertices });
+}
+
+describe('computeMeshGeometryWireframeIndices', () => {
+  it('expands each triangle into three edge line segments', () => {
+    const geometry = makeQuad();
+    const lines = computeMeshGeometryWireframeIndices(geometry);
+    // 2 triangles * 3 edges * 2 indices.
+    expect(lines.length).toBe(12);
+    expect(Array.from(lines.slice(0, 6))).toEqual([0, 1, 1, 2, 2, 0]);
+  });
+
+  it('mirrors the source index width (Uint16 stays Uint16)', () => {
+    const geometry = makeQuad();
+    const lines = computeMeshGeometryWireframeIndices(geometry);
+    expect(lines).toBeInstanceOf(Uint16Array);
+  });
+
+  it('returns an empty buffer for non-triangle topology', () => {
+    const vertices = new Float32Array(2 * 12);
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1]),
+      layout: CANONICAL_LAYOUT,
+      topology: 'line-list',
+      vertices: vertices,
+    });
+    const lines = computeMeshGeometryWireframeIndices(geometry);
+    expect(lines.length).toBe(0);
+  });
+});
+
+describe('expandMeshGeometryIndices', () => {
+  it('un-welds shared vertices into per-index copies', () => {
+    const geometry = makeQuad();
+    const expanded = expandMeshGeometryIndices(geometry);
+    expect(expanded.indices).toBeNull();
+    // 6 indices -> 6 standalone vertices.
+    expect(expanded.vertices.length).toBe(6 * 12);
+    // Index 2 (position 0,1) appears at flat positions 2 and 3.
+    expect(expanded.vertices[2 * 12]).toBe(0);
+    expect(expanded.vertices[2 * 12 + 1]).toBe(1);
+    expect(expanded.vertices[3 * 12]).toBe(0);
+    expect(expanded.vertices[3 * 12 + 1]).toBe(1);
+  });
+
+  it('deep-copies non-indexed geometry as-is', () => {
+    const vertices = new Float32Array(3 * 12);
+    vertices[0] = 7;
+    const geometry = createMeshGeometry({ indices: null, layout: CANONICAL_LAYOUT, vertices: vertices });
+    const expanded = expandMeshGeometryIndices(geometry);
+    expect(expanded.indices).toBeNull();
+    expect(expanded.vertices.length).toBe(3 * 12);
+    expect(expanded.vertices[0]).toBe(7);
+    // Distinct backing array.
+    expect(expanded.vertices).not.toBe(geometry.vertices);
+  });
+});

package/src/meshGeometryLayout.test.ts

@@ -0,0 +1,132 @@
+import type { VertexAttributeLayout } from '@flighthq/types';
+
+import { createMeshGeometry } from './meshGeometry';
+import { CANONICAL_MESH_GEOMETRY_LAYOUT, convertMeshGeometryLayout } from './meshGeometryLayout';
+
+// Minimal position-only layout: 3 floats / 12 bytes.
+const POSITION_ONLY_LAYOUT: VertexAttributeLayout = {
+  attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+  stride: 12,
+};
+
+// position + uv0 layout: 5 floats / 20 bytes.
+const POSITION_UV0_LAYOUT: VertexAttributeLayout = {
+  attributes: [
+    { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+    { byteOffset: 12, format: 'float32x2', semantic: 'uv0' },
+  ],
+  stride: 20,
+};
+
+function makeCanonicalGeometry() {
+  const vertices = new Float32Array(12); // one vertex, canonical layout
+  // position = (1, 2, 3), normal = (0, 1, 0), tangent = (1, 0, 0, 1), uv0 = (0.5, 0.25)
+  vertices[0] = 1;
+  vertices[1] = 2;
+  vertices[2] = 3;
+  vertices[3] = 0;
+  vertices[4] = 1;
+  vertices[5] = 0;
+  vertices[6] = 1;
+  vertices[7] = 0;
+  vertices[8] = 0;
+  vertices[9] = 1;
+  vertices[10] = 0.5;
+  vertices[11] = 0.25;
+  return createMeshGeometry({ layout: CANONICAL_MESH_GEOMETRY_LAYOUT, vertices: vertices });
+}
+
+describe('CANONICAL_MESH_GEOMETRY_LAYOUT', () => {
+  it('has stride 48', () => {
+    expect(CANONICAL_MESH_GEOMETRY_LAYOUT.stride).toBe(48);
+  });
+  it('has four attributes: position, normal, tangent, uv0', () => {
+    const semantics = CANONICAL_MESH_GEOMETRY_LAYOUT.attributes.map((a) => a.semantic);
+    expect(semantics).toContain('position');
+    expect(semantics).toContain('normal');
+    expect(semantics).toContain('tangent');
+    expect(semantics).toContain('uv0');
+  });
+  it('position attribute is at byteOffset 0 with format float32x3', () => {
+    const pos = CANONICAL_MESH_GEOMETRY_LAYOUT.attributes.find((a) => a.semantic === 'position');
+    expect(pos?.byteOffset).toBe(0);
+    expect(pos?.format).toBe('float32x3');
+  });
+});
+
+describe('convertMeshGeometryLayout', () => {
+  it('strips to position-only layout', () => {
+    const source = makeCanonicalGeometry();
+    const converted = convertMeshGeometryLayout(source, POSITION_ONLY_LAYOUT);
+    expect(converted.layout.stride).toBe(12);
+    expect(converted.vertices.length).toBe(3);
+    expect(converted.vertices[0]).toBeCloseTo(1);
+    expect(converted.vertices[1]).toBeCloseTo(2);
+    expect(converted.vertices[2]).toBeCloseTo(3);
+  });
+  it('strips to position + uv0 layout', () => {
+    const source = makeCanonicalGeometry();
+    const converted = convertMeshGeometryLayout(source, POSITION_UV0_LAYOUT);
+    expect(converted.layout.stride).toBe(20);
+    expect(converted.vertices.length).toBe(5);
+    expect(converted.vertices[0]).toBeCloseTo(1);
+    expect(converted.vertices[1]).toBeCloseTo(2);
+    expect(converted.vertices[2]).toBeCloseTo(3);
+    expect(converted.vertices[3]).toBeCloseTo(0.5);
+    expect(converted.vertices[4]).toBeCloseTo(0.25);
+  });
+  it('zero-fills attributes absent in the source', () => {
+    // Source has position only; target requests position + normal.
+    const posOnlySource = createMeshGeometry({
+      layout: POSITION_ONLY_LAYOUT,
+      vertices: new Float32Array([1, 2, 3]),
+    });
+    const targetLayout: VertexAttributeLayout = {
+      attributes: [
+        { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+        { byteOffset: 12, format: 'float32x3', semantic: 'normal' },
+      ],
+      stride: 24,
+    };
+    const converted = convertMeshGeometryLayout(posOnlySource, targetLayout);
+    expect(converted.vertices[0]).toBeCloseTo(1);
+    expect(converted.vertices[1]).toBeCloseTo(2);
+    expect(converted.vertices[2]).toBeCloseTo(3);
+    // Normal was not in source → zero-filled.
+    expect(converted.vertices[3]).toBe(0);
+    expect(converted.vertices[4]).toBe(0);
+    expect(converted.vertices[5]).toBe(0);
+  });
+  it('preserves vertex count', () => {
+    const vertices = new Float32Array(3 * 12); // 3 canonical vertices
+    vertices[0] = 1;
+    vertices[12] = 2;
+    vertices[24] = 3;
+    const source = createMeshGeometry({ layout: CANONICAL_MESH_GEOMETRY_LAYOUT, vertices: vertices });
+    const converted = convertMeshGeometryLayout(source, POSITION_ONLY_LAYOUT);
+    expect(converted.vertices.length).toBe(9); // 3 vertices × 3 floats
+    expect(converted.vertices[0]).toBeCloseTo(1);
+    expect(converted.vertices[3]).toBeCloseTo(2);
+    expect(converted.vertices[6]).toBeCloseTo(3);
+  });
+  it('preserves index buffer and topology', () => {
+    const vertices = new Float32Array(3 * 12);
+    const indices = new Uint16Array([0, 1, 2]);
+    const source = createMeshGeometry({
+      indices: indices,
+      layout: CANONICAL_MESH_GEOMETRY_LAYOUT,
+      topology: 'triangle-list',
+      vertices: vertices,
+    });
+    const converted = convertMeshGeometryLayout(source, POSITION_ONLY_LAYOUT);
+    expect(converted.topology).toBe('triangle-list');
+    expect(converted.indices).not.toBeNull();
+    expect(converted.indices?.length).toBe(3);
+  });
+  it('does not modify the source geometry', () => {
+    const source = makeCanonicalGeometry();
+    const originalData = Array.from(source.vertices);
+    convertMeshGeometryLayout(source, POSITION_ONLY_LAYOUT);
+    expect(Array.from(source.vertices)).toEqual(originalData);
+  });
+});

package/src/meshGeometryOperations.test.ts

@@ -0,0 +1,154 @@
+import type { VertexAttributeLayout } from '@flighthq/types';
+
+import { createMeshGeometry, getMeshGeometryIndexCount, getMeshGeometryVertexCount } from './meshGeometry';
+import { createBoxMeshGeometry, createQuadMeshGeometry } from './meshGeometryBuilders';
+import {
+  createMeshGeometryFromAttributes,
+  getMeshGeometryTriangleCount,
+  mergeMeshGeometries,
+  validateMeshGeometry,
+} from './meshGeometryOperations';
+
+const CANONICAL_LAYOUT: VertexAttributeLayout = {
+  attributes: [
+    { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+    { byteOffset: 12, format: 'float32x3', semantic: 'normal' },
+    { byteOffset: 24, format: 'float32x4', semantic: 'tangent' },
+    { byteOffset: 40, format: 'float32x2', semantic: 'uv0' },
+  ],
+  stride: 48,
+};
+
+const POSITION_ONLY_LAYOUT: VertexAttributeLayout = {
+  attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+  stride: 12,
+};
+
+describe('createMeshGeometryFromAttributes', () => {
+  it('builds a triangle from positions only, computing normals', () => {
+    const positions = [0, 0, 0, 1, 0, 0, 0, 1, 0];
+    const indices = [0, 1, 2];
+    const geo = createMeshGeometryFromAttributes({ indices, positions });
+    expect(getMeshGeometryVertexCount(geo)).toBe(3);
+    expect(getMeshGeometryIndexCount(geo)).toBe(3);
+    // Normal should be +Z for this CCW XY triangle.
+    expect(geo.vertices[5]).toBeCloseTo(1, 3);
+  });
+  it('uses supplied normals without recomputing', () => {
+    const positions = [0, 0, 0, 1, 0, 0, 0, 1, 0];
+    const normals = [0, 0, -1, 0, 0, -1, 0, 0, -1]; // explicit -Z normals
+    const indices = [0, 1, 2];
+    const geo = createMeshGeometryFromAttributes({ indices, normals, positions });
+    expect(geo.vertices[5]).toBeCloseTo(-1, 3); // supplied -Z preserved
+  });
+  it('computes bounds', () => {
+    const positions = [0, 0, 0, 2, 0, 0, 0, 2, 0];
+    const geo = createMeshGeometryFromAttributes({ positions });
+    expect(geo.bounds!.max.x).toBeCloseTo(2);
+    expect(geo.bounds!.max.y).toBeCloseTo(2);
+  });
+});
+
+describe('getMeshGeometryTriangleCount', () => {
+  it('returns index/3 for triangle-list', () => {
+    const geo = createBoxMeshGeometry();
+    expect(getMeshGeometryTriangleCount(geo)).toBe(getMeshGeometryIndexCount(geo) / 3);
+  });
+  it('returns 0 for point-list', () => {
+    const geo = createMeshGeometry({
+      layout: CANONICAL_LAYOUT,
+      topology: 'point-list',
+      vertices: new Float32Array(12),
+    });
+    expect(getMeshGeometryTriangleCount(geo)).toBe(0);
+  });
+  it('returns indexCount - 2 for triangle-strip', () => {
+    const verts = new Float32Array(4 * 12);
+    const geo = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 3]),
+      layout: CANONICAL_LAYOUT,
+      topology: 'triangle-strip',
+      vertices: verts,
+    });
+    expect(getMeshGeometryTriangleCount(geo)).toBe(2); // 4 - 2
+  });
+});
+
+describe('mergeMeshGeometries', () => {
+  it('returns null for empty array', () => {
+    expect(mergeMeshGeometries([])).toBeNull();
+  });
+  it('returns null on layout mismatch', () => {
+    const a = createQuadMeshGeometry();
+    const b = createMeshGeometry({ layout: POSITION_ONLY_LAYOUT, vertices: new Float32Array(9) });
+    expect(mergeMeshGeometries([a, b])).toBeNull();
+  });
+  it('concatenates vertices from two geometries', () => {
+    const a = createQuadMeshGeometry();
+    const b = createQuadMeshGeometry();
+    const merged = mergeMeshGeometries([a, b]);
+    expect(merged).not.toBeNull();
+    expect(getMeshGeometryVertexCount(merged!)).toBe(getMeshGeometryVertexCount(a) + getMeshGeometryVertexCount(b));
+  });
+  it('offsets indices correctly', () => {
+    const a = createQuadMeshGeometry(); // 4 verts, indices 0..3
+    const b = createQuadMeshGeometry();
+    const merged = mergeMeshGeometries([a, b]);
+    const aVertCount = getMeshGeometryVertexCount(a);
+    // All indices from `b` should be >= aVertCount in the merged geometry.
+    const bIndexStart = a.indices ? a.indices.length : getMeshGeometryVertexCount(a);
+    const bIndexCount = b.indices ? b.indices.length : getMeshGeometryVertexCount(b);
+    for (let i = bIndexStart; i < bIndexStart + bIndexCount; i++) {
+      expect(merged!.indices![i]).toBeGreaterThanOrEqual(aVertCount);
+    }
+  });
+  it('recomputes bounds', () => {
+    const a = createQuadMeshGeometry();
+    const merged = mergeMeshGeometries([a, a]);
+    expect(merged!.bounds).not.toBeNull();
+  });
+  it('carries per-source subsets', () => {
+    const a = createQuadMeshGeometry();
+    const b = createQuadMeshGeometry();
+    const merged = mergeMeshGeometries([a, b]);
+    expect(merged!.subsets.length).toBe(2);
+    expect(merged!.subsets[0].indexOffset).toBe(0);
+    expect(merged!.subsets[1].indexOffset).toBe(a.indices ? a.indices.length : getMeshGeometryVertexCount(a));
+  });
+});
+
+describe('validateMeshGeometry', () => {
+  it('returns true for a valid geometry', () => {
+    expect(validateMeshGeometry(createBoxMeshGeometry())).toBe(true);
+  });
+  it('returns false when indices reference out-of-range vertices', () => {
+    const geo = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 99]),
+      layout: CANONICAL_LAYOUT,
+      vertices: new Float32Array(3 * 12),
+    });
+    expect(validateMeshGeometry(geo)).toBe(false);
+  });
+  it('returns false when vertex stream is not stride-aligned', () => {
+    const geo = createMeshGeometry({
+      layout: CANONICAL_LAYOUT,
+      // 13 floats is not a multiple of 12 (the stride in floats).
+      vertices: new Float32Array(13),
+    });
+    // Override to force non-aligned stream.
+    geo.vertices = new Float32Array(13);
+    expect(validateMeshGeometry(geo)).toBe(false);
+  });
+  it('returns false when positions contain NaN', () => {
+    const verts = new Float32Array(12);
+    verts[0] = NaN;
+    const geo = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: verts });
+    expect(validateMeshGeometry(geo)).toBe(false);
+  });
+  it('returns false when positions contain Infinity', () => {
+    const verts = new Float32Array(12);
+    verts[2] = Infinity;
+    const geo = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: verts });
+    expect(validateMeshGeometry(geo)).toBe(false);
+  });
+});

package/src/meshGeometrySubset.test.ts

@@ -0,0 +1,75 @@
+import type { VertexAttributeLayout } from '@flighthq/types';
+
+import { createMeshGeometry } from './meshGeometry';
+import {
+  addMeshGeometrySubset,
+  getMeshGeometrySubsetTriangleCount,
+  setMeshGeometrySubsets,
+} from './meshGeometrySubset';
+
+const CANONICAL_LAYOUT: VertexAttributeLayout = {
+  attributes: [
+    { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+    { byteOffset: 12, format: 'float32x3', semantic: 'normal' },
+    { byteOffset: 24, format: 'float32x4', semantic: 'tangent' },
+    { byteOffset: 40, format: 'float32x2', semantic: 'uv0' },
+  ],
+  stride: 48,
+};
+
+// A two-triangle quad so the default subset spans 6 indices.
+function makeQuad() {
+  const vertices = new Float32Array(4 * 12);
+  const indices = new Uint16Array([0, 1, 2, 2, 1, 3]);
+  return createMeshGeometry({ indices: indices, layout: CANONICAL_LAYOUT, vertices: vertices });
+}
+
+describe('addMeshGeometrySubset', () => {
+  it('appends a subset, replacing the array reference', () => {
+    const geometry = makeQuad();
+    const previous = geometry.subsets;
+    addMeshGeometrySubset(geometry, { indexCount: 3, indexOffset: 3 });
+    expect(geometry.subsets.length).toBe(2);
+    expect(geometry.subsets[1].indexOffset).toBe(3);
+    expect(geometry.subsets).not.toBe(previous);
+  });
+});
+
+describe('getMeshGeometrySubsetTriangleCount', () => {
+  it('divides the index count by three for triangle-list topology', () => {
+    const geometry = makeQuad();
+    expect(getMeshGeometrySubsetTriangleCount(geometry, 0)).toBe(2);
+  });
+
+  it('returns the sentinel 0 for an out-of-range subset', () => {
+    const geometry = makeQuad();
+    expect(getMeshGeometrySubsetTriangleCount(geometry, 5)).toBe(0);
+    expect(getMeshGeometrySubsetTriangleCount(geometry, -1)).toBe(0);
+  });
+
+  it('counts strip triangles as indexCount - 2', () => {
+    const vertices = new Float32Array(4 * 12);
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 3]),
+      layout: CANONICAL_LAYOUT,
+      topology: 'triangle-strip',
+      vertices: vertices,
+    });
+    expect(getMeshGeometrySubsetTriangleCount(geometry, 0)).toBe(2);
+  });
+});
+
+describe('setMeshGeometrySubsets', () => {
+  it('replaces the entire subset list with a fresh copy', () => {
+    const geometry = makeQuad();
+    const input = [
+      { indexCount: 3, indexOffset: 0 },
+      { indexCount: 3, indexOffset: 3 },
+    ];
+    setMeshGeometrySubsets(geometry, input);
+    expect(geometry.subsets.length).toBe(2);
+    // Copied, not aliased to the input objects.
+    expect(geometry.subsets[0]).not.toBe(input[0]);
+    expect(geometry.subsets[1].indexOffset).toBe(3);
+  });
+});