@flighthq/scene3d-wgpu 0.2.1-next.840.857425c

package/src/drawWgpuScene3D.test.ts

@@ -0,0 +1,247 @@
+import { createCamera3D, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createVector3 } from '@flighthq/geometry';
+import { createAmbientLight, createDirectionalLight } from '@flighthq/lighting';
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import { CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT, createBoxMeshGeometry, createMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild, invalidateNodeLocalTransform } from '@flighthq/node';
+import { createParticleEmitter3D, reserveParticleEmitter3D } from '@flighthq/particleemitter';
+import { createMesh, createNode3D, Node3DKind } from '@flighthq/scene3d';
+import type { Camera3D, ParticleEmitter3D, Scene3DLightsLike, Skeleton3D } from '@flighthq/types';
+
+import { drawWgpuScene3D, isWgpuMeshGpuSkinned } from './drawWgpuScene3D';
+import { registerStandardPbrWgpuMaterial } from './registerStandardPbrWgpuMaterial';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+import { registerWgpuGpuSkinning } from './wgpuSkinPalette';
+
+function makeCamera(): Camera3D {
+  const camera = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' },
+  });
+  setCamera3DViewMatrix4FromLookAt(camera, { x: 0, y: 0, z: 5 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+  return camera;
+}
+
+const LIGHTS: Scene3DLightsLike = {
+  ambient: createAmbientLight({ color: 0xffffffff, intensity: 0.2 }),
+  directional: createDirectionalLight({ color: 0xffffffff, direction: createVector3(0, -1, -1), intensity: 1 }),
+};
+
+describe('drawWgpuScene3D', () => {
+  it('draws each visible mesh subset with its registered material renderer', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    addNodeChild(scene, mesh);
+
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(fake.calls.some((c) => c.name === 'setPipeline')).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(true);
+  });
+
+  it('skips a subset whose material has no registered renderer (no fallback)', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    // No registerStandardPbrWgpuMaterial: nothing resolves.
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    addNodeChild(scene, mesh);
+
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(false);
+  });
+
+  it('binds once for a run of subsets sharing a material', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const material = createStandardPbrMaterial();
+    const meshA = createMesh(createBoxMeshGeometry(), [material]);
+    const meshB = createMesh(createBoxMeshGeometry(), [material]);
+    addNodeChild(scene, meshA);
+    addNodeChild(scene, meshB);
+
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+
+    // Same material across both meshes: pipeline bound once, drawn twice.
+    expect(fake.calls.filter((c) => c.name === 'setPipeline').length).toBe(1);
+    expect(fake.calls.filter((c) => c.name === 'drawIndexed').length).toBe(2);
+  });
+
+  it('does not draw a disabled mesh', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    mesh.enabled = false;
+    addNodeChild(scene, mesh);
+
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(false);
+  });
+
+  it('partitions opaque and blended subsets into distinct pipeline runs', () => {
+    const { state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+    const scene = createNode3D(Node3DKind);
+    const blendedMaterial = createStandardPbrMaterial();
+    blendedMaterial.alphaMode = 'blend';
+    const blended = createMesh(createBoxMeshGeometry(), [blendedMaterial]);
+    const opaque = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    addNodeChild(scene, blended);
+    addNodeChild(scene, opaque);
+
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+
+    const runtime = getWgpuScene3DRuntime(state);
+    expect(runtime.opaqueDrawList.map((entry) => entry.mesh)).toEqual([opaque]);
+    expect(runtime.blendedDrawList.map((entry) => entry.mesh)).toEqual([blended]);
+    expect(Array.from(runtime.pipelineCache.keys()).some((key) => key.endsWith('|opaque|rigid'))).toBe(true);
+    expect(Array.from(runtime.pipelineCache.keys()).some((key) => key.endsWith('|blend|rigid'))).toBe(true);
+  });
+
+  it('routes resolved node alpha through the blended pass and draw proxy', () => {
+    const { state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    mesh.alpha = 0.5;
+    addNodeChild(scene, mesh);
+
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+
+    const runtime = getWgpuScene3DRuntime(state);
+    expect(runtime.opaqueDrawList).toHaveLength(0);
+    expect(runtime.blendedDrawList[0]!.alpha).toBeCloseTo(0.5);
+    expect(Array.from(runtime.pipelineCache.keys()).some((key) => key.endsWith('|blend|rigid'))).toBe(true);
+  });
+
+  it('sorts blended subsets back-to-front by projected depth', () => {
+    const { state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+    const scene = createNode3D(Node3DKind);
+    const material = createStandardPbrMaterial();
+    material.alphaMode = 'blend';
+    const far = createMesh(createBoxMeshGeometry(), [material]);
+    const near = createMesh(createBoxMeshGeometry(), [material]);
+    far.position.z = -3;
+    near.position.z = -1;
+    invalidateNodeLocalTransform(far);
+    invalidateNodeLocalTransform(near);
+    addNodeChild(scene, near);
+    addNodeChild(scene, far);
+
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(getWgpuScene3DRuntime(state).blendedDrawList.map((entry) => entry.mesh)).toEqual([far, near]);
+  });
+
+  it('sorts blended subsets back-to-front with an orthographic camera', () => {
+    const { state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+    const scene = createNode3D(Node3DKind);
+    const material = createStandardPbrMaterial();
+    material.alphaMode = 'blend';
+    const far = createMesh(createBoxMeshGeometry(), [material]);
+    const near = createMesh(createBoxMeshGeometry(), [material]);
+    far.position.z = -3;
+    near.position.z = -1;
+    invalidateNodeLocalTransform(far);
+    invalidateNodeLocalTransform(near);
+    addNodeChild(scene, near);
+    addNodeChild(scene, far);
+    const camera = createCamera3D({
+      far: 100,
+      near: 0.1,
+      projection: { halfHeight: 1, halfWidth: 1, kind: 'orthographic' },
+    });
+    setCamera3DViewMatrix4FromLookAt(camera, { x: 0, y: 0, z: 5 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+    drawWgpuScene3D(state, scene, camera, LIGHTS);
+    expect(getWgpuScene3DRuntime(state).blendedDrawList.map((entry) => entry.mesh)).toEqual([far, near]);
+  });
+
+  it('reuses opaque and blended draw records across frames', () => {
+    const { state } = makeWgpuScene3DState();
+    registerStandardPbrWgpuMaterial(state);
+    const scene = createNode3D(Node3DKind);
+    const opaque = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    const material = createStandardPbrMaterial();
+    material.alphaMode = 'blend';
+    const blended = createMesh(createBoxMeshGeometry(), [material]);
+    addNodeChild(scene, opaque);
+    addNodeChild(scene, blended);
+    const camera = makeCamera();
+
+    drawWgpuScene3D(state, scene, camera, LIGHTS);
+    const runtime = getWgpuScene3DRuntime(state);
+    const opaqueEntry = runtime.opaqueDrawList[0];
+    const blendedEntry = runtime.blendedDrawList[0];
+    drawWgpuScene3D(state, scene, camera, LIGHTS);
+
+    expect(runtime.opaqueDrawList[0]).toBe(opaqueEntry);
+    expect(runtime.blendedDrawList[0]).toBe(blendedEntry);
+    expect(runtime.opaquePool).toHaveLength(0);
+    expect(runtime.blendedPool).toHaveLength(0);
+  });
+
+  it('draws a scene ParticleEmitter3D as a final pass without a manual emitter call', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeParticleEmitter2D(3));
+    // No mesh and no manual drawWgpuScene3DParticleEmitter3Ds — drawWgpuScene3D must render the emitter itself
+    // (a 6-index instanced quad draw), mirroring drawGlScene3D's automatic emitter pass.
+    drawWgpuScene3D(state, scene, makeCamera(), LIGHTS);
+    const draw = fake.calls.find((c) => c.name === 'drawIndexed');
+    expect(draw).toBeDefined();
+    expect(draw!.args[0]).toBe(6);
+    expect(draw!.args[1]).toBe(3);
+  });
+});
+
+describe('isWgpuMeshGpuSkinned', () => {
+  it('selects GPU skinning only for a skin plus joints0 and weights0 geometry', () => {
+    const { state } = makeWgpuScene3DState();
+    registerWgpuGpuSkinning(state);
+    const rigid = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    expect(isWgpuMeshGpuSkinned(state, rigid)).toBe(false);
+
+    const skinned = createMesh(
+      createMeshGeometry({
+        indices: new Uint16Array([0, 0, 0]),
+        layout: CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT,
+        vertices: new Float32Array(20),
+      }),
+      [createStandardPbrMaterial()],
+    );
+    skinned.skin = { skeleton: { jointMatrices: new Float32Array(16) } as Skeleton3D };
+    expect(isWgpuMeshGpuSkinned(state, skinned)).toBe(true);
+  });
+});
+
+function makeParticleEmitter2D(count: number): ParticleEmitter3D {
+  const emitter = createParticleEmitter3D();
+  reserveParticleEmitter3D(emitter, count);
+  const data = emitter.data;
+  data.particleCount = count;
+  for (let i = 0; i < count; i++) {
+    const tt = i * 4;
+    data.transforms[tt] = i;
+    data.transforms[tt + 1] = i;
+    data.transforms[tt + 2] = 0;
+    data.transforms[tt + 3] = 1;
+    data.positionsZ[i] = 0;
+    data.alphas[i] = 1;
+    const ct = i * 3;
+    data.colors[ct] = 1;
+    data.colors[ct + 1] = 1;
+    data.colors[ct + 2] = 1;
+    data.ids[i] = 0;
+  }
+  return emitter;
+}

package/src/emissiveWgpuMeshMaterialRenderer.test.ts

@@ -0,0 +1,64 @@
+import { createCamera3D } from '@flighthq/camera';
+import { createMatrix3, createMatrix4 } from '@flighthq/geometry';
+import { createEmissiveMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import type { Camera3D, Scene3DLightBlock, Scene3DRenderProxy } from '@flighthq/types';
+import { EmissiveMaterialKind } from '@flighthq/types';
+
+import { emissiveWgpuMeshMaterialRenderer, registerEmissiveWgpuMaterial } from './emissiveWgpuMeshMaterialRenderer';
+import { getWgpuMeshMaterialRenderer } from './wgpuMeshMaterialRegistry';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+function makeCamera(): Camera3D {
+  return createCamera3D({ far: 100, near: 0.1, projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' } });
+}
+
+const NO_LIGHTS: Scene3DLightBlock = {
+  ambientCount: 0,
+  data: new Float32Array(12),
+  directionalCount: 0,
+  hemisphereCount: 0,
+  pointCount: 0,
+  spotCount: 0,
+  version: 1,
+};
+
+function makeProxy(): Scene3DRenderProxy {
+  const geometry = createBoxMeshGeometry();
+  return {
+    material: createEmissiveMaterial(),
+    normalMatrix: createMatrix3(),
+    subset: geometry.subsets[0],
+    worldMatrix: createMatrix4(),
+  };
+}
+
+describe('emissiveWgpuMeshMaterialRenderer', () => {
+  it('bind uploads the emissive color and issues frame + material binds', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    emissiveWgpuMeshMaterialRenderer.bind(
+      state,
+      createEmissiveMaterial({ emissiveStrength: 3 }),
+      NO_LIGHTS,
+      makeCamera(),
+    );
+    expect(fake.calls.some((c) => c.name === 'setPipeline')).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'writeBuffer')).toBe(true);
+  });
+
+  it('draw issues an indexed draw over the subset after bind', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const proxy = makeProxy();
+    emissiveWgpuMeshMaterialRenderer.bind(state, proxy.material, NO_LIGHTS, makeCamera());
+    emissiveWgpuMeshMaterialRenderer.draw(state, proxy, createBoxMeshGeometry());
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(true);
+  });
+});
+
+describe('registerEmissiveWgpuMaterial', () => {
+  it('installs the renderer for EmissiveMaterialKind', () => {
+    const { state } = makeWgpuScene3DState();
+    registerEmissiveWgpuMaterial(state);
+    expect(getWgpuMeshMaterialRenderer(state, EmissiveMaterialKind)).toBe(emissiveWgpuMeshMaterialRenderer);
+  });
+});

package/src/enableWgpuScene3DCustomShaderGuards.test.ts

@@ -0,0 +1,73 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log';
+import { createCustomShaderMaterial } from '@flighthq/materials';
+
+import {
+  areWgpuScene3DCustomShaderGuardsEnabled,
+  enableWgpuScene3DCustomShaderGuards,
+  runWgpuCustomShaderGuards,
+} from './enableWgpuScene3DCustomShaderGuards';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+describe('areWgpuScene3DCustomShaderGuardsEnabled', () => {
+  it('reports installation state', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(areWgpuScene3DCustomShaderGuardsEnabled(state)).toBe(false);
+    enableWgpuScene3DCustomShaderGuards(state);
+    expect(areWgpuScene3DCustomShaderGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableWgpuScene3DCustomShaderGuards', () => {
+  it('is idempotent', () => {
+    const { state } = makeWgpuScene3DState();
+    enableWgpuScene3DCustomShaderGuards(state);
+    enableWgpuScene3DCustomShaderGuards(state);
+    expect(areWgpuScene3DCustomShaderGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('runWgpuCustomShaderGuards', () => {
+  it('warns on bad vector lengths, capacity overflow, and missing reserved bindings', () => {
+    const { state } = makeWgpuScene3DState();
+    enableWgpuScene3DCustomShaderGuards(state);
+    const uniforms: Record<string, number[]> = {};
+    for (let i = 0; i < 33; i++) uniforms[`value${i}`] = [i];
+    uniforms['invalid'] = [1, 2, 3, 4, 5];
+    const material = createCustomShaderMaterial({
+      shaderKey: 'guard-contract-test',
+      textures: { a: {} as never },
+      uniforms,
+    });
+    const sink = createMemoryLogSink(16);
+    addLogSink(sink.sink);
+    try {
+      runWgpuCustomShaderGuards(
+        state,
+        material.shaderKey,
+        '@group(0) @binding(0) var<uniform> frame: vec4f;',
+        material,
+      );
+      const messages = getMemoryLogSinkEntries(sink).map((entry) =>
+        String((entry.data as Record<string, unknown>).message),
+      );
+      expect(messages.some((message) => message.includes('1–4 components'))).toBe(true);
+      expect(messages.some((message) => message.includes('32-vec4'))).toBe(true);
+      expect(messages.some((message) => message.includes('@group(1) @binding(0)'))).toBe(true);
+      expect(messages.some((message) => message.includes('@group(3) @binding(1)'))).toBe(true);
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+
+  it('does nothing until enabled', () => {
+    const { state } = makeWgpuScene3DState();
+    const sink = createMemoryLogSink(2);
+    addLogSink(sink.sink);
+    try {
+      runWgpuCustomShaderGuards(state, 'disabled-guard-test', '', createCustomShaderMaterial());
+      expect(getMemoryLogSinkEntries(sink)).toHaveLength(0);
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+});

package/src/enableWgpuScene3DForwardLightSelectionGuards.test.ts

@@ -0,0 +1,39 @@
+import { createPointLight } from '@flighthq/lighting';
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log';
+
+import {
+  areWgpuScene3DForwardLightSelectionGuardsEnabled,
+  enableWgpuScene3DForwardLightSelectionGuards,
+} from './enableWgpuScene3DForwardLightSelectionGuards';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+describe('areWgpuScene3DForwardLightSelectionGuardsEnabled', () => {
+  it('reports false before installation and true afterward', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(areWgpuScene3DForwardLightSelectionGuardsEnabled(state)).toBe(false);
+    enableWgpuScene3DForwardLightSelectionGuards(state);
+    expect(areWgpuScene3DForwardLightSelectionGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableWgpuScene3DForwardLightSelectionGuards', () => {
+  it('installs the opt-in warning with actionable selection guidance', () => {
+    const { state } = makeWgpuScene3DState();
+    enableWgpuScene3DForwardLightSelectionGuards(state);
+    const sink = createMemoryLogSink(4);
+    addLogSink(sink.sink);
+    try {
+      getWgpuScene3DRuntime(state).forwardLightSelectionGuard!({
+        ambient: null,
+        directional: null,
+        point: Array.from({ length: 5 }, () => createPointLight()),
+      });
+      const entries = getMemoryLogSinkEntries(sink);
+      expect(entries).toHaveLength(1);
+      expect(String((entries[0].data as Record<string, unknown>).message)).toContain('prepareWgpuScene3DForwardLights');
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+});

package/src/explainWgpuScene3DForwardLightSelection.test.ts

@@ -0,0 +1,15 @@
+import { createPointLight } from '@flighthq/lighting';
+
+import { explainWgpuScene3DForwardLightSelection } from './explainWgpuScene3DForwardLightSelection';
+
+describe('explainWgpuScene3DForwardLightSelection', () => {
+  it('distinguishes within-budget, required, and prepared selection', () => {
+    const within = { ambient: null, directional: null, point: [createPointLight()] };
+    expect(explainWgpuScene3DForwardLightSelection(within).reason).toBe('within-budget');
+    const excess = { ambient: null, directional: null, point: Array.from({ length: 5 }, () => createPointLight()) };
+    expect(explainWgpuScene3DForwardLightSelection(excess).reason).toBe('selection-required');
+    expect(explainWgpuScene3DForwardLightSelection(excess, { meshCount: 0, meshLightBlocks: [] }).reason).toBe(
+      'selection-prepared',
+    );
+  });
+});

package/src/iridescencePbrWgpuMeshMaterialRenderer.test.ts

@@ -0,0 +1,90 @@
+import { createCamera3D } from '@flighthq/camera';
+import { createMatrix3, createMatrix4 } from '@flighthq/geometry';
+import { createIridescencePbrMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import type { Camera3D, Matrix3, Matrix4, Scene3DLightBlock, Scene3DRenderProxy } from '@flighthq/types';
+import { IridescencePbrMaterialKind } from '@flighthq/types';
+
+import {
+  iridescencePbrWgpuMeshMaterialRenderer,
+  registerIridescencePbrWgpuMaterial,
+} from './iridescencePbrWgpuMeshMaterialRenderer';
+import { getWgpuMeshMaterialRenderer } from './wgpuMeshMaterialRegistry';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+function makeCamera(): Camera3D {
+  return createCamera3D({ far: 100, near: 0.1, projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' } });
+}
+
+function makeLights(): Scene3DLightBlock {
+  const data = new Float32Array(12);
+  data[1] = -1;
+  data[4] = 1;
+  data[5] = 1;
+  data[6] = 1;
+  data[8] = 0.1;
+  data[9] = 0.1;
+  data[10] = 0.1;
+  return { ambientCount: 1, data, directionalCount: 1, hemisphereCount: 0, pointCount: 0, spotCount: 0, version: 1 };
+}
+
+function makeProxy(): Scene3DRenderProxy {
+  const geometry = createBoxMeshGeometry();
+  return {
+    material: createIridescencePbrMaterial({ iridescence: 1 }),
+    normalMatrix: createMatrix3() as Matrix3,
+    subset: geometry.subsets[0],
+    worldMatrix: createMatrix4() as Matrix4,
+  };
+}
+
+describe('iridescencePbrWgpuMeshMaterialRenderer', () => {
+  it('bind selects a pipeline and binds frame + material groups + uploads uniforms', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    iridescencePbrWgpuMeshMaterialRenderer.bind(
+      state,
+      createIridescencePbrMaterial({ iridescence: 1 }),
+      makeLights(),
+      makeCamera(),
+    );
+
+    expect(fake.calls.some((c) => c.name === 'createRenderPipeline')).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'setPipeline')).toBe(true);
+    expect(fake.calls.filter((c) => c.name === 'setBindGroup').length).toBeGreaterThanOrEqual(2);
+    expect(fake.calls.some((c) => c.name === 'writeBuffer')).toBe(true);
+  });
+
+  it('bind compiles the IRIDESCENCE extension variant', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    iridescencePbrWgpuMeshMaterialRenderer.bind(state, createIridescencePbrMaterial(), makeLights(), makeCamera());
+    const moduleCall = fake.calls.find((c) => c.name === 'createShaderModule');
+    const code = (moduleCall!.args[0] as { code: string }).code;
+    expect(code).toContain('const IRIDESCENCE : bool = true;');
+  });
+
+  it('draw uploads geometry and issues an indexed draw over the subset range', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const proxy = makeProxy();
+    iridescencePbrWgpuMeshMaterialRenderer.bind(state, proxy.material, makeLights(), makeCamera());
+    iridescencePbrWgpuMeshMaterialRenderer.draw(state, proxy, createBoxMeshGeometry());
+
+    const drawCall = fake.calls.find((c) => c.name === 'drawIndexed');
+    expect(drawCall).toBeDefined();
+    expect(drawCall!.args[0]).toBe(proxy.subset.indexCount);
+    expect(drawCall!.args[2]).toBe(proxy.subset.indexOffset);
+  });
+
+  it('draw is a no-op when bind has not selected a pipeline', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    iridescencePbrWgpuMeshMaterialRenderer.draw(state, makeProxy(), createBoxMeshGeometry());
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(false);
+  });
+});
+
+describe('registerIridescencePbrWgpuMaterial', () => {
+  it('installs the renderer for IridescencePbrMaterialKind', () => {
+    const { state } = makeWgpuScene3DState();
+    registerIridescencePbrWgpuMaterial(state);
+    expect(getWgpuMeshMaterialRenderer(state, IridescencePbrMaterialKind)).toBe(iridescencePbrWgpuMeshMaterialRenderer);
+  });
+});

package/src/lambertWgpuMeshMaterialRenderer.test.ts

@@ -0,0 +1,77 @@
+import { createCamera3D } from '@flighthq/camera';
+import { createMatrix3, createMatrix4 } from '@flighthq/geometry';
+import { createLambertMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import type { Camera3D, Matrix3, Matrix4, Scene3DLightBlock, Scene3DRenderProxy } from '@flighthq/types';
+import { LambertMaterialKind } from '@flighthq/types';
+
+import { lambertWgpuMeshMaterialRenderer, registerLambertWgpuMaterial } from './lambertWgpuMeshMaterialRenderer';
+import { getWgpuMeshMaterialRenderer } from './wgpuMeshMaterialRegistry';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+function makeCamera(): Camera3D {
+  return createCamera3D({ far: 100, near: 0.1, projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' } });
+}
+
+function makeLights(): Scene3DLightBlock {
+  const data = new Float32Array(12);
+  data[0] = 0;
+  data[1] = -1;
+  data[2] = 0;
+  data[4] = 1;
+  data[5] = 1;
+  data[6] = 1;
+  data[8] = 0.1;
+  data[9] = 0.1;
+  data[10] = 0.1;
+  return { ambientCount: 1, data, directionalCount: 1, hemisphereCount: 0, pointCount: 0, spotCount: 0, version: 1 };
+}
+
+function makeProxy(): Scene3DRenderProxy {
+  const geometry = createBoxMeshGeometry();
+  return {
+    material: createLambertMaterial(),
+    normalMatrix: createMatrix3() as Matrix3,
+    subset: geometry.subsets[0],
+    worldMatrix: createMatrix4() as Matrix4,
+  };
+}
+
+describe('lambertWgpuMeshMaterialRenderer', () => {
+  it('bind selects a pipeline and binds frame + material groups + uploads uniforms', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    lambertWgpuMeshMaterialRenderer.bind(state, createLambertMaterial(), makeLights(), makeCamera());
+
+    expect(fake.calls.some((c) => c.name === 'createRenderPipeline')).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'setPipeline')).toBe(true);
+    expect(fake.calls.filter((c) => c.name === 'setBindGroup').length).toBeGreaterThanOrEqual(2);
+    expect(fake.calls.some((c) => c.name === 'writeBuffer')).toBe(true);
+  });
+
+  it('draw uploads geometry and issues an indexed draw over the subset range', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const proxy = makeProxy();
+    const geometry = createBoxMeshGeometry();
+    lambertWgpuMeshMaterialRenderer.bind(state, proxy.material, makeLights(), makeCamera());
+    lambertWgpuMeshMaterialRenderer.draw(state, proxy, geometry);
+
+    const drawCall = fake.calls.find((c) => c.name === 'drawIndexed');
+    expect(drawCall).toBeDefined();
+    expect(drawCall!.args[0]).toBe(proxy.subset.indexCount);
+    expect(drawCall!.args[2]).toBe(proxy.subset.indexOffset);
+  });
+
+  it('draw is a no-op when bind has not selected a pipeline', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    lambertWgpuMeshMaterialRenderer.draw(state, makeProxy(), createBoxMeshGeometry());
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(false);
+  });
+});
+
+describe('registerLambertWgpuMaterial', () => {
+  it('installs the renderer for LambertMaterialKind', () => {
+    const { state } = makeWgpuScene3DState();
+    registerLambertWgpuMaterial(state);
+    expect(getWgpuMeshMaterialRenderer(state, LambertMaterialKind)).toBe(lambertWgpuMeshMaterialRenderer);
+  });
+});

package/src/matcapWgpuMeshMaterialRenderer.test.ts

@@ -0,0 +1,69 @@
+import { createCamera3D } from '@flighthq/camera';
+import { createMatrix3, createMatrix4 } from '@flighthq/geometry';
+import { createMatcapMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import type { Camera3D, Scene3DLightBlock, Scene3DRenderProxy } from '@flighthq/types';
+import { MatcapMaterialKind } from '@flighthq/types';
+
+import { matcapWgpuMeshMaterialRenderer, registerMatcapWgpuMaterial } from './matcapWgpuMeshMaterialRenderer';
+import { getWgpuMeshMaterialRenderer } from './wgpuMeshMaterialRegistry';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+function makeCamera(): Camera3D {
+  return createCamera3D({ far: 100, near: 0.1, projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' } });
+}
+
+const NO_LIGHTS: Scene3DLightBlock = {
+  ambientCount: 0,
+  data: new Float32Array(12),
+  directionalCount: 0,
+  hemisphereCount: 0,
+  pointCount: 0,
+  spotCount: 0,
+  version: 1,
+};
+
+function makeProxy(): Scene3DRenderProxy {
+  const geometry = createBoxMeshGeometry();
+  return {
+    material: createMatcapMaterial(),
+    normalMatrix: createMatrix3(),
+    subset: geometry.subsets[0],
+    worldMatrix: createMatrix4(),
+  };
+}
+
+describe('matcapWgpuMeshMaterialRenderer', () => {
+  it('bind selects a pipeline and binds the frame + material groups', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    matcapWgpuMeshMaterialRenderer.bind(state, createMatcapMaterial(), NO_LIGHTS, makeCamera());
+    expect(fake.calls.some((c) => c.name === 'createRenderPipeline')).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'setPipeline')).toBe(true);
+    expect(fake.calls.filter((c) => c.name === 'setBindGroup').length).toBeGreaterThanOrEqual(2);
+    expect(fake.calls.some((c) => c.name === 'writeBuffer')).toBe(true);
+  });
+
+  it('draw issues an indexed draw over the subset after bind', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const proxy = makeProxy();
+    matcapWgpuMeshMaterialRenderer.bind(state, proxy.material, NO_LIGHTS, makeCamera());
+    matcapWgpuMeshMaterialRenderer.draw(state, proxy, createBoxMeshGeometry());
+    const drawCall = fake.calls.find((c) => c.name === 'drawIndexed');
+    expect(drawCall).toBeDefined();
+    expect(drawCall!.args[0]).toBe(proxy.subset.indexCount);
+  });
+
+  it('draw is a no-op when bind has not selected a pipeline', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    matcapWgpuMeshMaterialRenderer.draw(state, makeProxy(), createBoxMeshGeometry());
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(false);
+  });
+});
+
+describe('registerMatcapWgpuMaterial', () => {
+  it('installs the renderer for MatcapMaterialKind', () => {
+    const { state } = makeWgpuScene3DState();
+    registerMatcapWgpuMaterial(state);
+    expect(getWgpuMeshMaterialRenderer(state, MatcapMaterialKind)).toBe(matcapWgpuMeshMaterialRenderer);
+  });
+});