@flighthq/mesh 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/mesh",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.1.0",
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Mesh geometry: vertex layouts, primitive builders, and normals/tangents/bounds",
+  "sideEffects": false
+}

package/src/meshGeometry.test.ts

@@ -0,0 +1,155 @@
+import type { MeshGeometryRuntime, VertexAttributeLayout } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import {
+  cloneMeshGeometry,
+  createMeshGeometry,
+  destroyMeshGeometryGlData,
+  destroyMeshGeometryWgpuData,
+  getMeshGeometryIndexCount,
+  getMeshGeometryVertexCount,
+} from './meshGeometry';
+
+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,
+};
+
+function makeVertices(count: number): Float32Array<ArrayBuffer> {
+  return new Float32Array(count * 12);
+}
+
+describe('cloneMeshGeometry', () => {
+  it('deep-copies vertices and indices independently', () => {
+    const vertices = makeVertices(3);
+    vertices[0] = 7;
+    const indices = new Uint16Array([0, 1, 2]);
+    const source = createMeshGeometry({ indices: indices, layout: CANONICAL_LAYOUT, vertices: vertices });
+
+    const clone = cloneMeshGeometry(source);
+    expect(clone).not.toBe(source);
+    expect(clone.vertices).not.toBe(source.vertices);
+    expect(clone.vertices[0]).toBe(7);
+    expect(clone.indices).not.toBe(source.indices);
+
+    clone.vertices[0] = 99;
+    expect(source.vertices[0]).toBe(7);
+  });
+
+  it('resets the upload version and carries a fresh runtime', () => {
+    const source = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(1) });
+    source.version = 5;
+    const clone = cloneMeshGeometry(source);
+    expect(clone.version).toBe(0);
+    expect(clone[EntityRuntimeKey]).not.toBe(source[EntityRuntimeKey]);
+  });
+
+  it('clones bounds when present without sharing the AABB instance', () => {
+    const source = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(1) });
+    source.bounds = { max: { x: 1, y: 1, z: 1 }, min: { x: -1, y: -1, z: -1 } } as NonNullable<typeof source.bounds>;
+    const clone = cloneMeshGeometry(source);
+    expect(clone.bounds).not.toBe(source.bounds);
+    expect(clone.bounds!.min.x).toBe(-1);
+    expect(clone.bounds!.max.z).toBe(1);
+  });
+});
+
+describe('createMeshGeometry', () => {
+  it('defaults topology to triangle-list and a single full subset', () => {
+    const indices = new Uint16Array([0, 1, 2]);
+    const geometry = createMeshGeometry({ indices: indices, layout: CANONICAL_LAYOUT, vertices: makeVertices(3) });
+    expect(geometry.topology).toBe('triangle-list');
+    expect(geometry.subsets).toHaveLength(1);
+    expect(geometry.subsets[0]).toEqual({ indexCount: 3, indexOffset: 0 });
+  });
+
+  it('keeps Uint16 indices below the 65k ceiling', () => {
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      vertices: makeVertices(3),
+    });
+    expect(geometry.indices).toBeInstanceOf(Uint16Array);
+  });
+
+  it('auto-promotes indices to Uint32 past 65535 vertices', () => {
+    const vertexCount = 70000;
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      vertices: makeVertices(vertexCount),
+    });
+    expect(geometry.indices).toBeInstanceOf(Uint32Array);
+    expect(getMeshGeometryVertexCount(geometry)).toBe(vertexCount);
+  });
+
+  it('keeps already-Uint32 indices as Uint32', () => {
+    const geometry = createMeshGeometry({
+      indices: new Uint32Array([0, 1, 2]),
+      layout: CANONICAL_LAYOUT,
+      vertices: makeVertices(3),
+    });
+    expect(geometry.indices).toBeInstanceOf(Uint32Array);
+  });
+
+  it('allows non-indexed geometry with a vertex-count subset', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(6) });
+    expect(geometry.indices).toBeNull();
+    expect(geometry.subsets[0].indexCount).toBe(6);
+  });
+
+  it('initializes null GPU upload slots on the runtime', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(1) });
+    const runtime = geometry[EntityRuntimeKey] as MeshGeometryRuntime;
+    expect(runtime.webglData).toBeNull();
+    expect(runtime.webgpuData).toBeNull();
+  });
+});
+
+describe('destroyMeshGeometryGlData', () => {
+  it('clears the webgl upload slot', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(1) });
+    const runtime = geometry[EntityRuntimeKey] as MeshGeometryRuntime;
+    runtime.webglData = {} as MeshGeometryRuntime['webglData'];
+    destroyMeshGeometryGlData(geometry);
+    expect(runtime.webglData).toBeNull();
+  });
+});
+
+describe('destroyMeshGeometryWgpuData', () => {
+  it('clears the webgpu upload slot', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(1) });
+    const runtime = geometry[EntityRuntimeKey] as MeshGeometryRuntime;
+    runtime.webgpuData = {} as MeshGeometryRuntime['webgpuData'];
+    destroyMeshGeometryWgpuData(geometry);
+    expect(runtime.webgpuData).toBeNull();
+  });
+});
+
+describe('getMeshGeometryIndexCount', () => {
+  it('returns the index length', () => {
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+      layout: CANONICAL_LAYOUT,
+      vertices: makeVertices(4),
+    });
+    expect(getMeshGeometryIndexCount(geometry)).toBe(6);
+  });
+
+  it('returns 0 for non-indexed geometry', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(3) });
+    expect(getMeshGeometryIndexCount(geometry)).toBe(0);
+  });
+});
+
+describe('getMeshGeometryVertexCount', () => {
+  it('derives the vertex count from stride', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(5) });
+    expect(getMeshGeometryVertexCount(geometry)).toBe(5);
+  });
+});

package/src/meshGeometryAttributes.test.ts

@@ -0,0 +1,195 @@
+import type { VertexAttributeLayout } from '@flighthq/types';
+
+import { createMeshGeometry } from './meshGeometry';
+import {
+  getMeshGeometryVertexNormal,
+  getMeshGeometryVertexPosition,
+  getMeshGeometryVertexTangent,
+  getMeshGeometryVertexUv0,
+  getVertexAttribute,
+  getVertexAttributeFloatOffset,
+  setMeshGeometryVertexNormal,
+  setMeshGeometryVertexPosition,
+  setMeshGeometryVertexTangent,
+  setMeshGeometryVertexUv0,
+} from './meshGeometryAttributes';
+
+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 vertex with known values: pos=(1,2,3) normal=(0,1,0) tangent=(1,0,0,1) uv=(0.5,0.75).
+function makeOneVertex() {
+  const vertices = new Float32Array(12);
+  vertices[0] = 1;
+  vertices[1] = 2;
+  vertices[2] = 3; // position
+  vertices[3] = 0;
+  vertices[4] = 1;
+  vertices[5] = 0; // normal
+  vertices[6] = 1;
+  vertices[7] = 0;
+  vertices[8] = 0;
+  vertices[9] = 1; // tangent
+  vertices[10] = 0.5;
+  vertices[11] = 0.75; // uv0
+  return createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices });
+}
+
+describe('getMeshGeometryVertexNormal', () => {
+  it('reads the normal of the given vertex', () => {
+    const geo = makeOneVertex();
+    const out = { x: 0, y: 0, z: 0 };
+    expect(getMeshGeometryVertexNormal(out, geo, 0)).toBe(true);
+    expect(out.x).toBe(0);
+    expect(out.y).toBe(1);
+    expect(out.z).toBe(0);
+  });
+  it('returns false for out-of-range index', () => {
+    const out = { x: 0, y: 0, z: 0 };
+    expect(getMeshGeometryVertexNormal(out, makeOneVertex(), 1)).toBe(false);
+  });
+  it('returns false when layout has no normal', () => {
+    const layout: VertexAttributeLayout = {
+      attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+      stride: 12,
+    };
+    const geo = createMeshGeometry({ layout, vertices: new Float32Array(3) });
+    const out = { x: 0, y: 0, z: 0 };
+    expect(getMeshGeometryVertexNormal(out, geo, 0)).toBe(false);
+  });
+});
+
+describe('getMeshGeometryVertexPosition', () => {
+  it('reads the position of the given vertex', () => {
+    const geo = makeOneVertex();
+    const out = { x: 0, y: 0, z: 0 };
+    expect(getMeshGeometryVertexPosition(out, geo, 0)).toBe(true);
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(2);
+    expect(out.z).toBe(3);
+  });
+  it('returns false for out-of-range index', () => {
+    const out = { x: 0, y: 0, z: 0 };
+    expect(getMeshGeometryVertexPosition(out, makeOneVertex(), -1)).toBe(false);
+  });
+});
+
+describe('getMeshGeometryVertexTangent', () => {
+  it('reads the tangent including w', () => {
+    const geo = makeOneVertex();
+    const out = { w: 0, x: 0, y: 0, z: 0 };
+    expect(getMeshGeometryVertexTangent(out, geo, 0)).toBe(true);
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(0);
+    expect(out.z).toBe(0);
+    expect(out.w).toBe(1);
+  });
+});
+
+describe('getMeshGeometryVertexUv0', () => {
+  it('reads the uv0 coordinates', () => {
+    const geo = makeOneVertex();
+    const out = { x: 0, y: 0 };
+    expect(getMeshGeometryVertexUv0(out, geo, 0)).toBe(true);
+    expect(out.x).toBeCloseTo(0.5);
+    expect(out.y).toBeCloseTo(0.75);
+  });
+});
+
+describe('getVertexAttribute', () => {
+  it('returns the attribute for a present semantic', () => {
+    const attr = getVertexAttribute(CANONICAL_LAYOUT, 'normal');
+    expect(attr).not.toBeNull();
+    expect(attr!.byteOffset).toBe(12);
+    expect(attr!.format).toBe('float32x3');
+  });
+  it('returns null for an absent semantic', () => {
+    expect(getVertexAttribute(CANONICAL_LAYOUT, 'color0')).toBeNull();
+  });
+});
+
+describe('getVertexAttributeFloatOffset', () => {
+  it('returns the float offset for a float32 semantic', () => {
+    expect(getVertexAttributeFloatOffset(CANONICAL_LAYOUT, 'position')).toBe(0);
+    expect(getVertexAttributeFloatOffset(CANONICAL_LAYOUT, 'normal')).toBe(3);
+    expect(getVertexAttributeFloatOffset(CANONICAL_LAYOUT, 'tangent')).toBe(6);
+    expect(getVertexAttributeFloatOffset(CANONICAL_LAYOUT, 'uv0')).toBe(10);
+  });
+  it('returns -1 for an absent semantic', () => {
+    expect(getVertexAttributeFloatOffset(CANONICAL_LAYOUT, 'color0')).toBe(-1);
+  });
+  it('returns -1 for a non-float32 attribute', () => {
+    const layout: VertexAttributeLayout = {
+      attributes: [{ byteOffset: 0, format: 'uint8x4', semantic: 'color0' }],
+      stride: 4,
+    };
+    expect(getVertexAttributeFloatOffset(layout, 'color0')).toBe(-1);
+  });
+});
+
+describe('setMeshGeometryVertexNormal', () => {
+  it('writes the normal and bumps version', () => {
+    const geo = makeOneVertex();
+    const v0 = geo.version;
+    expect(setMeshGeometryVertexNormal(geo, 0, 0, 0, 1)).toBe(true);
+    expect(geo.vertices[3]).toBe(0);
+    expect(geo.vertices[4]).toBe(0);
+    expect(geo.vertices[5]).toBe(1);
+    expect(geo.version).toBe(v0 + 1);
+  });
+  it('returns false for out-of-range index', () => {
+    const geo = makeOneVertex();
+    expect(setMeshGeometryVertexNormal(geo, 5, 0, 0, 1)).toBe(false);
+  });
+});
+
+describe('setMeshGeometryVertexPosition', () => {
+  it('writes the position and bumps version', () => {
+    const geo = makeOneVertex();
+    const v0 = geo.version;
+    expect(setMeshGeometryVertexPosition(geo, 0, 10, 20, 30)).toBe(true);
+    expect(geo.vertices[0]).toBe(10);
+    expect(geo.vertices[1]).toBe(20);
+    expect(geo.vertices[2]).toBe(30);
+    expect(geo.version).toBe(v0 + 1);
+  });
+});
+
+describe('setMeshGeometryVertexTangent', () => {
+  it('writes the tangent including w and bumps version', () => {
+    const geo = makeOneVertex();
+    const v0 = geo.version;
+    expect(setMeshGeometryVertexTangent(geo, 0, 0, 1, 0, -1)).toBe(true);
+    expect(geo.vertices[6]).toBe(0);
+    expect(geo.vertices[7]).toBe(1);
+    expect(geo.vertices[8]).toBe(0);
+    expect(geo.vertices[9]).toBe(-1);
+    expect(geo.version).toBe(v0 + 1);
+  });
+});
+
+describe('setMeshGeometryVertexUv0', () => {
+  it('writes the uv0 and bumps version', () => {
+    const geo = makeOneVertex();
+    const v0 = geo.version;
+    expect(setMeshGeometryVertexUv0(geo, 0, 0.1, 0.9)).toBe(true);
+    expect(geo.vertices[10]).toBeCloseTo(0.1);
+    expect(geo.vertices[11]).toBeCloseTo(0.9);
+    expect(geo.version).toBe(v0 + 1);
+  });
+  it('returns false for absent semantic', () => {
+    const layout: VertexAttributeLayout = {
+      attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+      stride: 12,
+    };
+    const geo = createMeshGeometry({ layout, vertices: new Float32Array(3) });
+    expect(setMeshGeometryVertexUv0(geo, 0, 0.5, 0.5)).toBe(false);
+  });
+});

package/src/meshGeometryBuilders.test.ts

@@ -0,0 +1,220 @@
+import type { MeshGeometry } from '@flighthq/types';
+
+import { getMeshGeometryIndexCount, getMeshGeometryVertexCount } from './meshGeometry';
+import {
+  createBoxMeshGeometry,
+  createCapsuleMeshGeometry,
+  createCircleMeshGeometry,
+  createConeMeshGeometry,
+  createCylinderMeshGeometry,
+  createDodecahedronMeshGeometry,
+  createIcosahedronMeshGeometry,
+  createIcosphereMeshGeometry,
+  createOctahedronMeshGeometry,
+  createPlaneMeshGeometry,
+  createPolyhedronMeshGeometry,
+  createQuadMeshGeometry,
+  createRingMeshGeometry,
+  createSphereMeshGeometry,
+  createTetrahedronMeshGeometry,
+  createTorusKnotMeshGeometry,
+  createTorusMeshGeometry,
+} from './meshGeometryBuilders';
+
+function expectUnitNormals(geometry: Readonly<MeshGeometry>): void {
+  const count = getMeshGeometryVertexCount(geometry);
+  const stride = 12;
+  for (let i = 0; i < count; i++) {
+    const b = i * stride + 3;
+    const len = Math.hypot(geometry.vertices[b], geometry.vertices[b + 1], geometry.vertices[b + 2]);
+    expect(len).toBeCloseTo(1, 4);
+  }
+}
+
+function expectUnitTangents(geometry: Readonly<MeshGeometry>): void {
+  const count = getMeshGeometryVertexCount(geometry);
+  const stride = 12;
+  for (let i = 0; i < count; i++) {
+    const b = i * stride + 6;
+    const len = Math.hypot(geometry.vertices[b], geometry.vertices[b + 1], geometry.vertices[b + 2]);
+    expect(len).toBeCloseTo(1, 4);
+    expect(Math.abs(geometry.vertices[b + 3])).toBe(1);
+  }
+}
+
+describe('createBoxMeshGeometry', () => {
+  it('builds 24 vertices, 36 indices, and bounds at the half-extents', () => {
+    const geometry = createBoxMeshGeometry(2, 4, 6);
+    expect(getMeshGeometryVertexCount(geometry)).toBe(24);
+    expect(getMeshGeometryIndexCount(geometry)).toBe(36);
+    expect(geometry.bounds!.min.x).toBeCloseTo(-1);
+    expect(geometry.bounds!.max.y).toBeCloseTo(2);
+    expect(geometry.bounds!.max.z).toBeCloseTo(3);
+    expectUnitNormals(geometry);
+    expectUnitTangents(geometry);
+  });
+});
+
+describe('createCapsuleMeshGeometry', () => {
+  it('builds a capsule that spans -(height/2+radius)..(height/2+radius) on Y', () => {
+    const geometry = createCapsuleMeshGeometry(0.5, 1, 8, 4);
+    expect(getMeshGeometryVertexCount(geometry)).toBeGreaterThan(0);
+    expect(geometry.bounds!.min.y).toBeCloseTo(-1, 1);
+    expect(geometry.bounds!.max.y).toBeCloseTo(1, 1);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createCircleMeshGeometry', () => {
+  it('builds a filled disc with segments triangles', () => {
+    const geometry = createCircleMeshGeometry(0.5, 16);
+    // 1 center + 17 rim (segments+1) = 18 vertices; 16 triangles = 48 indices.
+    expect(getMeshGeometryIndexCount(geometry)).toBe(48);
+    expect(geometry.bounds!.max.x).toBeCloseTo(0.5, 2);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createConeMeshGeometry', () => {
+  it('builds a capped cone with an apex at +Y', () => {
+    const geometry = createConeMeshGeometry(0.5, 2, 16);
+    expect(getMeshGeometryVertexCount(geometry)).toBeGreaterThan(0);
+    expect(geometry.bounds!.max.y).toBeCloseTo(1);
+    expect(geometry.bounds!.min.y).toBeCloseTo(-1);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createCylinderMeshGeometry', () => {
+  it('builds a capped cylinder bounded by its radius and height', () => {
+    const geometry = createCylinderMeshGeometry(0.5, 0.5, 2, 16);
+    expect(geometry.bounds!.max.y).toBeCloseTo(1);
+    expect(geometry.bounds!.max.x).toBeCloseTo(0.5, 2);
+    expectUnitNormals(geometry);
+    expectUnitTangents(geometry);
+  });
+});
+
+describe('createDodecahedronMeshGeometry', () => {
+  it('produces a non-empty geometry with positive vertex count', () => {
+    const geometry = createDodecahedronMeshGeometry(0.5);
+    expect(getMeshGeometryVertexCount(geometry)).toBeGreaterThan(0);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createIcosahedronMeshGeometry', () => {
+  it('builds 20 triangles at detail=0', () => {
+    const geometry = createIcosahedronMeshGeometry(0.5);
+    // 20 faces × 3 independent verts = 60 vertices.
+    expect(getMeshGeometryVertexCount(geometry)).toBe(60);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createIcosphereMeshGeometry', () => {
+  it('builds a sphere with evenly distributed vertices', () => {
+    const geometry = createIcosphereMeshGeometry(1, 1);
+    // Each icosahedron face is subdivided into 4, giving 20×4 = 80 faces × 3 = 240 verts.
+    expect(getMeshGeometryVertexCount(geometry)).toBe(240);
+    const count = getMeshGeometryVertexCount(geometry);
+    // All vertices should lie on the unit sphere.
+    for (let i = 0; i < count; i++) {
+      const b = i * 12;
+      const r = Math.hypot(geometry.vertices[b], geometry.vertices[b + 1], geometry.vertices[b + 2]);
+      expect(r).toBeCloseTo(1, 3);
+    }
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createOctahedronMeshGeometry', () => {
+  it('builds 8 triangles at detail=0', () => {
+    const geometry = createOctahedronMeshGeometry(0.5);
+    // 8 faces × 3 verts = 24 vertices.
+    expect(getMeshGeometryVertexCount(geometry)).toBe(24);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createPlaneMeshGeometry', () => {
+  it('builds a subdivided plane in the XZ plane with +Y normals', () => {
+    const geometry = createPlaneMeshGeometry(2, 2, 2, 2);
+    expect(getMeshGeometryVertexCount(geometry)).toBe(9);
+    expect(getMeshGeometryIndexCount(geometry)).toBe(24);
+    expect(geometry.vertices[4]).toBeCloseTo(1);
+    expect(geometry.bounds!.min.x).toBeCloseTo(-1);
+    expect(geometry.bounds!.max.z).toBeCloseTo(1);
+  });
+});
+
+describe('createPolyhedronMeshGeometry', () => {
+  it('accepts custom vertex/face data', () => {
+    const verts: ReadonlyArray<readonly [number, number, number]> = [
+      [0, 1, 0],
+      [-1, -1, 0],
+      [1, -1, 0],
+    ];
+    const faces: ReadonlyArray<readonly [number, number, number]> = [[0, 1, 2]];
+    const geometry = createPolyhedronMeshGeometry(verts, faces, 1, 0);
+    expect(getMeshGeometryVertexCount(geometry)).toBe(3);
+  });
+});
+
+describe('createQuadMeshGeometry', () => {
+  it('builds a unit quad in the XY plane with +Z normals', () => {
+    const geometry = createQuadMeshGeometry();
+    expect(getMeshGeometryVertexCount(geometry)).toBe(4);
+    expect(getMeshGeometryIndexCount(geometry)).toBe(6);
+    expect(geometry.vertices[5]).toBeCloseTo(1);
+    expectUnitTangents(geometry);
+  });
+});
+
+describe('createRingMeshGeometry', () => {
+  it('builds a ring bounded by outerRadius', () => {
+    const geometry = createRingMeshGeometry(0.25, 0.5, 16);
+    expect(getMeshGeometryVertexCount(geometry)).toBeGreaterThan(0);
+    expect(geometry.bounds!.max.x).toBeCloseTo(0.5, 2);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createSphereMeshGeometry', () => {
+  it('builds a sphere whose vertices lie on the radius', () => {
+    const geometry = createSphereMeshGeometry(1, 16, 8);
+    const count = getMeshGeometryVertexCount(geometry);
+    for (let i = 0; i < count; i++) {
+      const b = i * 12;
+      const r = Math.hypot(geometry.vertices[b], geometry.vertices[b + 1], geometry.vertices[b + 2]);
+      expect(r).toBeCloseTo(1, 4);
+    }
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createTetrahedronMeshGeometry', () => {
+  it('builds 4 triangles at detail=0', () => {
+    const geometry = createTetrahedronMeshGeometry(0.5);
+    // 4 faces × 3 verts = 12 vertices.
+    expect(getMeshGeometryVertexCount(geometry)).toBe(12);
+    expectUnitNormals(geometry);
+  });
+});
+
+describe('createTorusKnotMeshGeometry', () => {
+  it('produces a non-empty geometry', () => {
+    const geometry = createTorusKnotMeshGeometry(0.5, 0.15, 32, 8);
+    expect(getMeshGeometryVertexCount(geometry)).toBeGreaterThan(0);
+    expect(getMeshGeometryIndexCount(geometry)).toBeGreaterThan(0);
+  });
+});
+
+describe('createTorusMeshGeometry', () => {
+  it('builds a torus bounded by radius + tube', () => {
+    const geometry = createTorusMeshGeometry(0.5, 0.2, 12, 24);
+    expect(geometry.bounds!.max.x).toBeCloseTo(0.7, 2);
+    expect(geometry.bounds!.max.z).toBeCloseTo(0.2, 2);
+    expectUnitNormals(geometry);
+  });
+});