@flighthq/mesh 0.3.0 → 0.3.1-next.1041.35b950c

package/src/meshGeometryCompute.test.ts

@@ -1,5 +1,5 @@
 import { createAabb, createBoundingSphere } from '@flighthq/geometry/contract';
-import type { VertexAttributeLayout } from '@flighthq/types/contract';
+import type { MeshGeometry, VertexAttributeLayout } from '@flighthq/types/contract';
 
 import { createMeshGeometry, invalidateMeshGeometry } from './meshGeometry';
 import {
@@ -7,6 +7,7 @@ import {
   computeMeshGeometryBounds,
   computeMeshGeometryFlatNormals,
   computeMeshGeometryNormals,
+  computeMeshGeometryPositionGroups,
   computeMeshGeometryTangents,
   ensureMeshGeometryBounds,
   refreshMeshGeometryBounds,
@@ -41,6 +42,43 @@ function makeTriangle() {
   return createMeshGeometry({ indices: indices, layout: CANONICAL_LAYOUT, vertices: vertices });
 }
 
+function makeUvSeamFold() {
+  const vertices = new Float32Array(6 * 12);
+  const setVertex = (i: number, px: number, py: number, pz: number, u: number, v: number): void => {
+    const base = i * 12;
+    vertices[base] = px;
+    vertices[base + 1] = py;
+    vertices[base + 2] = pz;
+    vertices[base + 10] = u;
+    vertices[base + 11] = v;
+  };
+  // The first triangle has twice the area of the second. Vertices 0/3 and 1/4 are exact position
+  // duplicates with distinct UVs across their shared edge.
+  setVertex(0, 0, 0, 0, 0, 0);
+  setVertex(1, 2, 0, 0, 1, 0);
+  setVertex(2, 0, 2, 0, 0, 1);
+  setVertex(3, 0, 0, 0, 0.25, 0.25);
+  setVertex(4, 2, 0, 0, 0.75, 0.25);
+  setVertex(5, 0, 0, 1, 0.25, 0.75);
+  return createMeshGeometry({
+    indices: new Uint16Array([0, 1, 2, 3, 4, 5]),
+    layout: CANONICAL_LAYOUT,
+    vertices,
+  });
+}
+
+function reconstructBitangent(vertices: Readonly<Float32Array>, vertex: number): [number, number, number] {
+  const base = vertex * 12;
+  const nx = vertices[base + 3];
+  const ny = vertices[base + 4];
+  const nz = vertices[base + 5];
+  const tx = vertices[base + 6];
+  const ty = vertices[base + 7];
+  const tz = vertices[base + 8];
+  const sign = vertices[base + 9];
+  return [sign * (ny * tz - nz * ty), sign * (nz * tx - nx * tz), sign * (nx * ty - ny * tx)];
+}
+
 describe('computeMeshGeometryBoundingSphere', () => {
   it('writes the center and radius for a unit-side triangle', () => {
     const geometry = makeTriangle();
@@ -185,6 +223,57 @@ describe('computeMeshGeometryNormals', () => {
     computeMeshGeometryNormals(out, source);
     expect(out.vertices[5]).toBeCloseTo(1);
   });
+
+  it('bumps the output version after rewriting normals', () => {
+    const source = makeTriangle();
+    const out = makeTriangle();
+    const previousVersion = out.version;
+
+    computeMeshGeometryNormals(out, source);
+
+    expect(out.version).toBe(previousVersion + 1);
+  });
+
+  it('keeps duplicated positions independent when position groups are omitted', () => {
+    const geometry = makeUvSeamFold();
+
+    computeMeshGeometryNormals(geometry, geometry);
+
+    expect(Array.from(geometry.vertices.subarray(3, 6))).toEqual([0, 0, 1]);
+    expect(Array.from(geometry.vertices.subarray(3 * 12 + 3, 3 * 12 + 6))).toEqual([0, -1, 0]);
+  });
+
+  it('area-weights face normals inside exact position groups before normalization', () => {
+    const geometry = makeUvSeamFold();
+    const groups = computeMeshGeometryPositionGroups(geometry);
+
+    computeMeshGeometryNormals(geometry, geometry, groups);
+
+    const expectedY = -1 / Math.sqrt(5);
+    const expectedZ = 2 / Math.sqrt(5);
+    for (const vertex of [0, 1, 3, 4]) {
+      const base = vertex * 12 + 3;
+      expect(geometry.vertices[base]).toBeCloseTo(0);
+      expect(geometry.vertices[base + 1]).toBeCloseTo(expectedY);
+      expect(geometry.vertices[base + 2]).toBeCloseTo(expectedZ);
+    }
+  });
+});
+
+describe('computeMeshGeometryPositionGroups', () => {
+  it('returns the first exact-position vertex as each group representative', () => {
+    const geometry = makeUvSeamFold();
+
+    expect(Array.from(computeMeshGeometryPositionGroups(geometry))).toEqual([0, 1, 2, 0, 1, 5]);
+  });
+
+  it('does not group adjacent Float32 values', () => {
+    const geometry = makeUvSeamFold();
+    const bits = new Uint32Array(geometry.vertices.buffer);
+    bits[3 * 12] = 1;
+
+    expect(Array.from(computeMeshGeometryPositionGroups(geometry))).toEqual([0, 1, 2, 3, 1, 5]);
+  });
 });
 
 describe('computeMeshGeometryTangents', () => {
@@ -224,6 +313,38 @@ describe('computeMeshGeometryTangents', () => {
     expect(geometry.vertices[9]).toBe(-1);
   });
 
+  it('keeps the reconstructed bitangent continuous across a grouped mirrored-UV seam', () => {
+    const vertices = new Float32Array(6 * 12);
+    // The duplicate seam position (vertices 0/3) sees different face frames on each side. The second
+    // UV chart mirrors u: its tangent and handedness flip, while the shared bitangent must not.
+    setCanonicalVertex(vertices, 0, 0, 0, 0, 0);
+    setCanonicalVertex(vertices, 1, 1, 0, 1, 0);
+    setCanonicalVertex(vertices, 2, 0, 1, 0, 1);
+    setCanonicalVertex(vertices, 3, 0, 0, 0, 0);
+    setCanonicalVertex(vertices, 4, -1, 0, 0, 1);
+    setCanonicalVertex(vertices, 5, 0, -1, 1, 0);
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 3, 4, 5]),
+      layout: CANONICAL_LAYOUT,
+      vertices,
+    });
+    const groups = computeMeshGeometryPositionGroups(geometry);
+    computeMeshGeometryNormals(geometry, geometry, groups);
+
+    computeMeshGeometryTangents(geometry, geometry, groups);
+
+    expect(geometry.vertices[9]).toBe(1);
+    expect(geometry.vertices[3 * 12 + 9]).toBe(-1);
+    const firstBitangent = reconstructBitangent(geometry.vertices, 0);
+    const mirroredBitangent = reconstructBitangent(geometry.vertices, 3);
+    expect(firstBitangent[0]).toBeCloseTo(-1 / Math.sqrt(2));
+    expect(firstBitangent[1]).toBeCloseTo(1 / Math.sqrt(2));
+    expect(firstBitangent[2]).toBeCloseTo(0);
+    for (let component = 0; component < 3; component++) {
+      expect(mirroredBitangent[component]).toBeCloseTo(firstBitangent[component]);
+    }
+  });
+
   it('splits shared vertices at a mirrored-UV handedness boundary', () => {
     // Two CCW triangles share vertices 0/2. Their UV determinants have opposite signs, so a single
     // tangent.w cannot describe both triangles: the shared records must be duplicated and remapped.
@@ -237,10 +358,11 @@ describe('computeMeshGeometryTangents', () => {
       layout: CANONICAL_LAYOUT,
       vertices,
     });
-    computeMeshGeometryNormals(geometry, geometry);
+    const groups = computeMeshGeometryPositionGroups(geometry);
+    computeMeshGeometryNormals(geometry, geometry, groups);
     const previousVersion = geometry.version;
 
-    computeMeshGeometryTangents(geometry, geometry);
+    computeMeshGeometryTangents(geometry, geometry, groups);
 
     expect(geometry.vertices.length / 12).toBe(6);
     expect(geometry.version).toBe(previousVersion + 1);
@@ -258,70 +380,10 @@ describe('computeMeshGeometryTangents', () => {
     expect(indices[2]).toBe(2);
     expect(indices[3]).toBeGreaterThanOrEqual(4);
     expect(indices[4]).toBeGreaterThanOrEqual(4);
-  });
-
-  it('splits same-handed corners whose tangent directions cannot share a stable frame', () => {
-    // Both triangles are CCW and both UV determinants are positive, but their U axes point in
-    // opposite model-space directions at shared vertex 0. Handedness-only reconciliation leaves the
-    // shared tangent cancelled or dominated by one face; Flight must create a second complete record.
-    const vertices = new Float32Array(5 * 12);
-    setCanonicalVertex(vertices, 0, 0, 0, 0, 0);
-    setCanonicalVertex(vertices, 1, 1, 0, 1, 0);
-    setCanonicalVertex(vertices, 2, 0, 1, 0, 1);
-    setCanonicalVertex(vertices, 3, -1, 0, 1, 0);
-    setCanonicalVertex(vertices, 4, 0, -1, 0, 1);
-    const geometry = createMeshGeometry({
-      indices: new Uint16Array([0, 1, 2, 0, 3, 4]),
-      layout: CANONICAL_LAYOUT,
-      vertices,
-    });
-    computeMeshGeometryNormals(geometry, geometry);
-
-    computeMeshGeometryTangents(geometry, geometry);
-
-    expect(geometry.vertices.length / 12).toBe(6);
-    const indices = geometry.indices!;
-    expect(indices[0]).not.toBe(indices[3]);
-    expect(geometry.vertices[indices[0] * 12 + 6]).toBeGreaterThan(0.9);
-    expect(geometry.vertices[indices[3] * 12 + 6]).toBeLessThan(-0.9);
-    // This is a directional split within one handedness, not a mirror split.
-    expect(geometry.vertices[indices[0] * 12 + 9]).toBe(1);
-    expect(geometry.vertices[indices[3] * 12 + 9]).toBe(1);
-
-    // The reference MD5 demo historically repeated both authoring calls after import. Repeating them
-    // must neither grow topology again nor turn the Flight-created tangent split into a hard normal seam.
-    computeMeshGeometryNormals(geometry, geometry);
-    computeMeshGeometryTangents(geometry, geometry);
-    expect(geometry.vertices.length / 12).toBe(6);
-    expect(geometry.vertices[indices[0] * 12 + 3]).toBeCloseTo(geometry.vertices[indices[3] * 12 + 3]);
-    expect(geometry.vertices[indices[0] * 12 + 4]).toBeCloseTo(geometry.vertices[indices[3] * 12 + 4]);
-    expect(geometry.vertices[indices[0] * 12 + 5]).toBeCloseTo(geometry.vertices[indices[3] * 12 + 5]);
-  });
-
-  it('keeps smooth normals shared across a folded mirrored tangent seam', () => {
-    const vertices = new Float32Array(4 * 12);
-    setCanonicalVertex(vertices, 0, 0, 0, 0, 0);
-    setCanonicalVertex(vertices, 1, 1, 0, 1, 0);
-    setCanonicalVertex(vertices, 2, 0, 1, 0, 1);
-    setCanonicalVertex(vertices, 3, -1, 0, 1, 0);
-    vertices[3 * 12 + 2] = 1;
-    const geometry = createMeshGeometry({
-      indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
-      layout: CANONICAL_LAYOUT,
-      vertices,
-    });
-    computeMeshGeometryNormals(geometry, geometry);
-    const originalNormal = Array.from(geometry.vertices.subarray(3, 6));
-    computeMeshGeometryTangents(geometry, geometry);
-    const indices = geometry.indices!;
-    expect(indices[0]).not.toBe(indices[3]);
-
-    computeMeshGeometryNormals(geometry, geometry);
-
-    for (const vertex of [indices[0], indices[3]]) {
-      expect(geometry.vertices[vertex * 12 + 3]).toBeCloseTo(originalNormal[0]);
-      expect(geometry.vertices[vertex * 12 + 4]).toBeCloseTo(originalNormal[1]);
-      expect(geometry.vertices[vertex * 12 + 5]).toBeCloseTo(originalNormal[2]);
+    const firstBitangent = reconstructBitangent(geometry.vertices, indices[0]);
+    const mirroredBitangent = reconstructBitangent(geometry.vertices, indices[3]);
+    for (let component = 0; component < 3; component++) {
+      expect(mirroredBitangent[component]).toBeCloseTo(firstBitangent[component]);
     }
   });
 
@@ -374,6 +436,34 @@ describe('computeMeshGeometryTangents', () => {
   });
 });
 
+describe('ensureMeshGeometryBounds', () => {
+  it('computes on first query, then reuses the cache until the version moves', () => {
+    const geometry = makeTriangle();
+    expect(geometry.bounds).toBeNull();
+
+    const bounds = ensureMeshGeometryBounds(geometry);
+    expect(bounds?.max.x).toBe(1);
+
+    // A vertex edit WITHOUT a version bump must not be picked up — the version is the dirty signal,
+    // and honouring the cache is what makes the steady-state query an integer compare.
+    geometry.vertices[12] = 4;
+    expect(ensureMeshGeometryBounds(geometry)?.max.x).toBe(1);
+
+    // The public direct-write escape hatch marks the cache stale.
+    invalidateMeshGeometry(geometry);
+    expect(ensureMeshGeometryBounds(geometry)?.max.x).toBe(4);
+  });
+
+  it('trusts bounds supplied at construction without re-sweeping them', () => {
+    const geometry = makeTriangle();
+    refreshMeshGeometryBounds(geometry);
+    const bounds = geometry.bounds;
+
+    // Same AABB instance back, no recompute: the cache is valid for the current version.
+    expect(ensureMeshGeometryBounds(geometry)).toBe(bounds);
+  });
+});
+
 function setCanonicalVertex(vertices: Float32Array, vertex: number, x: number, y: number, u: number, v: number): void {
   const base = vertex * 12;
   vertices[base] = x;
@@ -407,34 +497,6 @@ function setSkinnedVertex(
   vertices[base + 19] = 0.4;
 }
 
-describe('ensureMeshGeometryBounds', () => {
-  it('computes on first query, then reuses the cache until the version moves', () => {
-    const geometry = makeTriangle();
-    expect(geometry.bounds).toBeNull();
-
-    const bounds = ensureMeshGeometryBounds(geometry);
-    expect(bounds?.max.x).toBe(1);
-
-    // A vertex edit WITHOUT a version bump must not be picked up — the version is the dirty signal,
-    // and honouring the cache is what makes the steady-state query an integer compare.
-    geometry.vertices[12] = 4;
-    expect(ensureMeshGeometryBounds(geometry)?.max.x).toBe(1);
-
-    // The public direct-write escape hatch marks the cache stale.
-    invalidateMeshGeometry(geometry);
-    expect(ensureMeshGeometryBounds(geometry)?.max.x).toBe(4);
-  });
-
-  it('trusts bounds supplied at construction without re-sweeping them', () => {
-    const geometry = makeTriangle();
-    refreshMeshGeometryBounds(geometry);
-    const bounds = geometry.bounds;
-
-    // Same AABB instance back, no recompute: the cache is valid for the current version.
-    expect(ensureMeshGeometryBounds(geometry)).toBe(bounds);
-  });
-});
-
 describe('refreshMeshGeometryBounds', () => {
   it('allocates once, then refreshes the same cached bounds after vertex edits', () => {
     const geometry = makeTriangle();
@@ -449,3 +511,92 @@ describe('refreshMeshGeometryBounds', () => {
     expect(bounds?.max.x).toBe(4);
   });
 });
+
+describe('triangle-strip topology', () => {
+  // A four-vertex strip [0, 1, 2, 3] is two triangles; the same surface as a list is
+  // [0, 1, 2, 2, 1, 3], including the winding flip the odd strip triangle carries. Every compute
+  // pass must produce the same attributes from either spelling.
+  //
+  // The fixture is deliberately IRREGULAR — the fourth corner is lifted out of the plane and its
+  // UV is skewed. A flat quad with axis-aligned UVs makes both triangles agree by accident: every
+  // tangent comes out (1, 0, 0, 1) whichever topology is used, so the tangent pass looks correct
+  // while ignoring topology entirely. The irregular corner is what makes the two disagree when the
+  // second triangle is dropped.
+  function createStripQuad(topology: 'triangle-list' | 'triangle-strip'): MeshGeometry {
+    const vertices = new Float32Array(4 * 12);
+    setCanonicalVertex(vertices, 0, 0, 0, 0, 0);
+    setCanonicalVertex(vertices, 1, 1, 0, 1, 0);
+    setCanonicalVertex(vertices, 2, 0, 1, 0, 1);
+    setCanonicalVertex(vertices, 3, 1, 1, 0.3, 0.9);
+    vertices[3 * 12 + 2] = 1; // lift the fourth corner out of the plane
+    const indices = topology === 'triangle-strip' ? [0, 1, 2, 3] : [0, 1, 2, 2, 1, 3];
+    return createMeshGeometry({
+      indices: new Uint16Array(indices),
+      layout: CANONICAL_LAYOUT,
+      topology,
+      vertices,
+    });
+  }
+
+  function expectStripMatchesList(
+    compute: (out: MeshGeometry, geometry: Readonly<MeshGeometry>) => void,
+    offset: number,
+    componentCount: number,
+  ): void {
+    const strip = createStripQuad('triangle-strip');
+    const list = createStripQuad('triangle-list');
+    compute(strip, strip);
+    compute(list, list);
+    for (let vertex = 0; vertex < 4; vertex++) {
+      for (let component = 0; component < componentCount; component++) {
+        expect(strip.vertices[vertex * 12 + offset + component]).toBeCloseTo(
+          list.vertices[vertex * 12 + offset + component],
+          5,
+        );
+      }
+    }
+  }
+
+  it('computeMeshGeometryNormals reads a strip as two triangles, not one', () => {
+    // Dropping the second triangle leaves vertex 3 at exactly (0, 0, 0) and vertices 1 and 2
+    // carrying only the first triangle's contribution — three of the four wrong, not just the one
+    // no earlier triangle referenced.
+    expectStripMatchesList(computeMeshGeometryNormals, 3, 3);
+  });
+
+  it('computeMeshGeometryFlatNormals reads a strip as two triangles, not one', () => {
+    expectStripMatchesList(computeMeshGeometryFlatNormals, 3, 3);
+  });
+
+  it('computeMeshGeometryTangents reads a strip as two triangles, not one', () => {
+    // A vertex that accumulates nothing falls back to a unit perpendicular, so the dropped
+    // triangle shows up here as a plausible-looking tangent rather than a zero — harder to spot by
+    // eye than the zero normal, which is why it is asserted against the list rather than a literal.
+    const strip = createStripQuad('triangle-strip');
+    const list = createStripQuad('triangle-list');
+    computeMeshGeometryNormals(strip, strip);
+    computeMeshGeometryNormals(list, list);
+    computeMeshGeometryTangents(strip, strip);
+    computeMeshGeometryTangents(list, list);
+    for (let vertex = 0; vertex < 4; vertex++) {
+      for (let component = 0; component < 4; component++) {
+        expect(strip.vertices[vertex * 12 + 6 + component]).toBeCloseTo(list.vertices[vertex * 12 + 6 + component], 5);
+      }
+    }
+  });
+
+  it('leaves no vertex of a strip without a normal', () => {
+    // The symptom that reaches a renderer: an unreferenced vertex keeps the zero normal it was
+    // allocated with, and lights as a black seam.
+    const strip = createStripQuad('triangle-strip');
+    computeMeshGeometryNormals(strip, strip);
+    for (let vertex = 0; vertex < 4; vertex++) {
+      const length = Math.hypot(
+        strip.vertices[vertex * 12 + 3],
+        strip.vertices[vertex * 12 + 4],
+        strip.vertices[vertex * 12 + 5],
+      );
+      expect(length).toBeCloseTo(1, 5);
+    }
+  });
+});

package/src/meshGeometryDeformationClone.test.ts

@@ -48,6 +48,8 @@ describe('cloneMeshGeometryForDeformation', () => {
       positions: new Float32Array([1, 2, 3]),
       skinnedNormals: new Float32Array(3),
       skinnedPositions: new Float32Array(3),
+      skinnedTangents: new Float32Array(0),
+      tangents: new Float32Array(0),
       weights: new Float32Array(4),
     });
 

package/src/meshGeometryLayout.test.ts

@@ -1,5 +1,4 @@
-import type { MeshGeometryRuntime, VertexAttributeLayout } from '@flighthq/types/contract';
-import { EntityRuntimeKey } from '@flighthq/types/contract';
+import type { VertexAttributeLayout } from '@flighthq/types/contract';
 
 import { createMeshGeometry } from './meshGeometry';
 import {
@@ -91,16 +90,6 @@ describe('convertMeshGeometryLayout', () => {
     expect(converted.vertices[1]).toBeCloseTo(2);
     expect(converted.vertices[2]).toBeCloseTo(3);
   });
-  it('preserves tangent-split smoothing identity across a layout conversion', () => {
-    const source = createMeshGeometry({ layout: CANONICAL_MESH_GEOMETRY_LAYOUT, vertices: new Float32Array(24) });
-    (source[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources = new Uint32Array([0, 0]);
-
-    const converted = convertMeshGeometryLayout(source, POSITION_ONLY_LAYOUT);
-
-    const convertedSources = (converted[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources;
-    expect(Array.from(convertedSources!)).toEqual([0, 0]);
-    expect(convertedSources).not.toBe((source[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources);
-  });
   it('strips to position + uv0 layout', () => {
     const source = makeCanonicalGeometry();
     const converted = convertMeshGeometryLayout(source, POSITION_UV0_LAYOUT);

package/src/meshGeometryOperations.test.ts

@@ -139,6 +139,29 @@ describe('mergeMeshGeometries', () => {
     const b = createMeshGeometry({ layout: POSITION_ONLY_LAYOUT, vertices: new Float32Array(9) });
     expect(mergeMeshGeometries([a, b])).toBeNull();
   });
+  it('returns null on topology mismatch', () => {
+    // The merged result carries ONE topology, so concatenating a line-list into a triangle-list
+    // would reinterpret pairs of line endpoints as face corners — triangles nobody authored, from
+    // a call that reported success. There is no correct single topology for that merge, so it is
+    // refused, the same way a layout mismatch is.
+    const faces = createQuadMeshGeometry();
+    const lines = createMeshGeometry({
+      layout: faces.layout,
+      topology: 'line-list',
+      vertices: new Float32Array(faces.vertices.length),
+    });
+    expect(mergeMeshGeometries([faces, lines])).toBeNull();
+    expect(mergeMeshGeometries([lines, faces])).toBeNull();
+  });
+  it('merges geometries that share a non-default topology', () => {
+    // The check is mismatch, not triangle-list-only: two line meshes still merge.
+    const layout = createQuadMeshGeometry().layout;
+    const a = createMeshGeometry({ layout, topology: 'line-list', vertices: new Float32Array(24) });
+    const b = createMeshGeometry({ layout, topology: 'line-list', vertices: new Float32Array(24) });
+    const merged = mergeMeshGeometries([a, b]);
+    expect(merged).not.toBeNull();
+    expect(merged!.topology).toBe('line-list');
+  });
   it('concatenates vertices from two geometries', () => {
     const a = createQuadMeshGeometry();
     const b = createQuadMeshGeometry();
@@ -207,4 +230,79 @@ describe('validateMeshGeometry', () => {
     const geo = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: verts });
     expect(validateMeshGeometry(geo)).toBe(false);
   });
+
+  // Position was the only channel checked, so a degenerate normal, tangent or UV passed straight
+  // through. This validator sits between every importer and the GPU, and a NaN normal reaches a shader
+  // exactly as a NaN position does — normalize() of it is undefined rather than merely misplaced.
+  // Canonical layout float offsets: position 0..2, normal 3..5, tangent 6..9, uv0 10..11.
+  it.each([
+    ['a normal', 3],
+    ['a tangent', 6],
+    ['a uv', 10],
+  ])('returns false for NaN in %s', (_channel, offset) => {
+    const verts = new Float32Array(12);
+    verts[offset] = NaN;
+
+    expect(validateMeshGeometry(createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: verts }))).toBe(false);
+  });
+
+  it('returns false for Infinity in a tangent', () => {
+    const verts = new Float32Array(12);
+    verts[7] = Infinity;
+
+    expect(validateMeshGeometry(createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: verts }))).toBe(false);
+  });
+
+  // A subset is a draw call's offset and count. A range past the end of the element stream is one the
+  // driver rejects, so approving it here means the validator passed something no backend can execute.
+  it('returns false for a subset whose draw range runs past the index buffer', () => {
+    const geo = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      vertices: new Float32Array(3 * 12),
+    });
+    geo.subsets = [{ indexCount: 99, indexOffset: 2 }];
+
+    expect(validateMeshGeometry(geo)).toBe(false);
+  });
+
+  // A triangle list ending mid-triangle has no drawable interpretation of its remainder.
+  it('returns false for an element count that cannot form whole triangles', () => {
+    const geo = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 0]),
+      layout: CANONICAL_LAYOUT,
+      vertices: new Float32Array(3 * 12),
+    });
+
+    expect(validateMeshGeometry(geo)).toBe(false);
+  });
+
+  it('accepts a line list with an even element count and rejects an odd one', () => {
+    const evenGeo = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      topology: 'line-list',
+      vertices: new Float32Array(3 * 12),
+    });
+    const oddGeo = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      topology: 'line-list',
+      vertices: new Float32Array(3 * 12),
+    });
+
+    expect(validateMeshGeometry(evenGeo)).toBe(true);
+    expect(validateMeshGeometry(oddGeo)).toBe(false);
+  });
+
+  // An empty range draws nothing, which is a legal state rather than a malformed one.
+  it('accepts an empty element stream', () => {
+    const geo = createMeshGeometry({
+      indices: new Uint16Array(0),
+      layout: CANONICAL_LAYOUT,
+      vertices: new Float32Array(3 * 12),
+    });
+
+    expect(validateMeshGeometry(geo)).toBe(true);
+  });
 });

package/src/meshGeometryTransforms.test.ts

@@ -1,4 +1,4 @@
-import { createMatrix4, setMatrix4Identity } from '@flighthq/geometry/contract';
+import { createMatrix4, setMatrix4, setMatrix4Identity } from '@flighthq/geometry/contract';
 import type { Aabb, VertexAttributeLayout } from '@flighthq/types/contract';
 
 import { createMeshGeometry } from './meshGeometry';
@@ -66,6 +66,108 @@ describe('centerMeshGeometry', () => {
   });
 });
 
+describe('mirror and non-uniform scale invariants', () => {
+  // ★ THE FIXTURE IS THE POINT. `makeVertex` above is axis-aligned — normal (1,0,0), tangent
+  // (0,1,0) — and under scale(2,1,1) the correct tangent transform and the inverse-transpose one
+  // produce the SAME vector, so it cannot tell them apart. That is why a tangent transformed by the
+  // wrong matrix survived here. These use a diagonal frame in the XY plane, where the two answers
+  // differ. Do not "simplify" this fixture back to an axis-aligned one.
+  function makeDiagonalFrameVertex() {
+    const r = Math.SQRT1_2;
+    const vertices = new Float32Array(12);
+    vertices[0] = 1;
+    vertices[3] = r;
+    vertices[4] = r; // normal  ( .707,  .707, 0)
+    vertices[6] = r;
+    vertices[7] = -r; // tangent ( .707, -.707, 0)
+    vertices[9] = 1; // handedness
+    return createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices });
+  }
+
+  function normalDotTangent(geometry: ReturnType<typeof makeDiagonalFrameVertex>) {
+    const v = geometry.vertices;
+    return v[3] * v[6] + v[4] * v[7] + v[5] * v[8];
+  }
+
+  it('keeps the tangent on the surface under a non-uniform scale', () => {
+    // A tangent is a true vector and follows the model matrix; a normal is a covector and follows
+    // the inverse-transpose. Transform both with the inverse-transpose and the tangent tilts off
+    // the surface — it stops being perpendicular to its own normal, which is what breaks the TBN
+    // frame every normal-mapped material reconstructs.
+    const geometry = makeDiagonalFrameVertex();
+    const matrix = createMatrix4();
+    setMatrix4(matrix, 2, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
+    transformMeshGeometry(geometry, matrix);
+    expect(normalDotTangent(geometry)).toBeCloseTo(0, 5);
+  });
+
+  it('keeps the tangent on the surface under scaleMeshGeometry too', () => {
+    const geometry = makeDiagonalFrameVertex();
+    scaleMeshGeometry(geometry, 2, 1, 1);
+    expect(normalDotTangent(geometry)).toBeCloseTo(0, 5);
+  });
+
+  it('reverses indexed triangle winding and flips handedness when the transform mirrors', () => {
+    // A baked mirror leaves no determinant behind for a renderer to detect, so the geometry would
+    // upload inside-out under an identity model matrix. The correction has to happen at bake time.
+    const vertices = new Float32Array(3 * 12);
+    for (let v = 0; v < 3; v++) vertices[v * 12 + 9] = 1; // handedness on every vertex
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      vertices,
+    });
+    scaleMeshGeometry(geometry, -1, 1, 1);
+    expect(Array.from(geometry.indices!)).toEqual([0, 2, 1]);
+    for (let v = 0; v < 3; v++) expect(geometry.vertices[v * 12 + 9]).toBe(-1);
+  });
+
+  it('reverses non-indexed triangle winding by swapping the records themselves', () => {
+    // With no index array the record ORDER is the winding, so the second and third records of each
+    // triple exchange places — and they must exchange whole, not just their positions.
+    const vertices = new Float32Array(3 * 12);
+    for (let v = 0; v < 3; v++) {
+      vertices[v * 12] = v; // position.x identifies the record
+      vertices[v * 12 + 10] = v; // uv0.u rides along to prove the whole record moved
+    }
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices });
+    scaleMeshGeometry(geometry, -1, 1, 1);
+    expect([geometry.vertices[0], geometry.vertices[12], geometry.vertices[24]]).toEqual([0, -2, -1]);
+    expect([geometry.vertices[10], geometry.vertices[22], geometry.vertices[34]]).toEqual([0, 2, 1]);
+  });
+
+  it('leaves winding and handedness alone when the transform does not mirror', () => {
+    const vertices = new Float32Array(3 * 12);
+    for (let v = 0; v < 3; v++) vertices[v * 12 + 9] = 1;
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      vertices,
+    });
+    scaleMeshGeometry(geometry, 2, 3, 4);
+    expect(Array.from(geometry.indices!)).toEqual([0, 1, 2]);
+    for (let v = 0; v < 3; v++) expect(geometry.vertices[v * 12 + 9]).toBe(1);
+  });
+
+  it('flips strip handedness but leaves strip indices untouched', () => {
+    // Handedness is per-vertex and topology-independent, so it is corrected here as everywhere.
+    // The winding is NOT: a strip shares each vertex between up to three triangles, so a per-triple
+    // swap does not describe it, and there is no established strip reversal in this repository to
+    // follow. This pins the current, deliberate gap rather than claiming strips are handled.
+    const vertices = new Float32Array(4 * 12);
+    for (let v = 0; v < 4; v++) vertices[v * 12 + 9] = 1;
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 3]),
+      layout: CANONICAL_LAYOUT,
+      topology: 'triangle-strip',
+      vertices,
+    });
+    scaleMeshGeometry(geometry, -1, 1, 1);
+    expect(Array.from(geometry.indices!)).toEqual([0, 1, 2, 3]);
+    for (let v = 0; v < 4; v++) expect(geometry.vertices[v * 12 + 9]).toBe(-1);
+  });
+});
+
 describe('scaleMeshGeometry', () => {
   it('scales positions by the given factors', () => {
     const geo = makeVertex(1, 2, 3);