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

package/src/wgpuClassicPrelude.test.ts

@@ -0,0 +1,176 @@
+import { createTexture } from '@flighthq/texture';
+import type { ImageResource, WgpuClassicDefineKey, WgpuClassicLightingModel } from '@flighthq/types';
+
+import {
+  bindWgpuClassicSurface,
+  buildWgpuClassicDefineKey,
+  compileWgpuClassicPipeline,
+  ensureWgpuClassicPipeline,
+  getWgpuClassicModuleSourceForKey,
+  getWgpuClassicSharedSamplerModuleSourceForKey,
+} from './wgpuClassicPrelude';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState, makeWgpuSkinningAdapter } from './wgpuScene3DTestHelper';
+
+function makeKey(lightingModel: WgpuClassicLightingModel): WgpuClassicDefineKey {
+  return {
+    alphaMaskEnabled: false,
+    doubleSided: false,
+    hasAlphaMap: false,
+    hasDiffuseMap: false,
+    hasNormalMap: false,
+    hasSpecularMap: false,
+    lightingModel,
+  };
+}
+
+describe('bindWgpuClassicSurface', () => {
+  it('creates a material bind group + buffer once per key and rewrites the uniform each call', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = ensureWgpuClassicPipeline(state, makeKey('phong'), 'bgra8unorm');
+    const key = {};
+    bindWgpuClassicSurface(state, pipeline, key, [1, 0, 0, 1], [1, 1, 1, 1], 32, 0.5, null, null, null, null);
+    bindWgpuClassicSurface(state, pipeline, key, [0, 1, 0, 1], [1, 1, 1, 1], 64, 0.5, null, null, null, null);
+
+    expect(fake.calls.filter((c) => c.name === 'createBindGroup').length).toBe(1);
+    expect(fake.calls.filter((c) => c.name === 'writeBuffer').length).toBe(2);
+  });
+
+  // The per-map rebuild conditions (swap / unready→ready / ready→ready / version bump / sampler change)
+  // are proven directly against isWgpuMaterialBindGroupRebuildNeeded in wgpuMeshPipeline.test.ts; the binder
+  // wires that predicate around buildWgpuMaterialBindGroup. The unchanged-binds-no-rebuild case is the
+  // "creates a material bind group … once per key" test above.
+
+  it('exercises the real sampler path with a non-null primary texture and builds nothing new in steady state', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = ensureWgpuClassicPipeline(state, makeKey('phong'), 'bgra8unorm');
+    const key = {};
+    // A ready diffuse (primary) map so bind() actually runs getWgpuMaterialSampler → getWgpuSampler (the
+    // path an already-resolved-sampler helper test bypasses). Same shared binder that PBR uses.
+    const diffuseMap = createTexture({ image: { source: {} } as unknown as ImageResource });
+    bindWgpuClassicSurface(state, pipeline, key, [1, 0, 0, 1], [1, 1, 1, 1], 32, 0.5, diffuseMap, null, null, null);
+    const count = (name: string) => fake.calls.filter((c) => c.name === name).length;
+    const [samplers, bindGroups, buffers] = [count('createSampler'), count('createBindGroup'), count('createBuffer')];
+    expect(samplers).toBeGreaterThanOrEqual(1); // the primary sampler was built once on first bind
+
+    // Re-bind the unchanged textured material: the sampler + view resolution run again (getWgpuSampler
+    // cache hit via its packed-number key), but no new GPUSampler / bind group / buffer is constructed —
+    // steady state builds nothing beyond the per-bind uniform write.
+    bindWgpuClassicSurface(state, pipeline, key, [1, 0, 0, 1], [1, 1, 1, 1], 32, 0.5, diffuseMap, null, null, null);
+    bindWgpuClassicSurface(state, pipeline, key, [1, 0, 0, 1], [1, 1, 1, 1], 32, 0.5, diffuseMap, null, null, null);
+    expect(count('createSampler')).toBe(samplers);
+    expect(count('createBindGroup')).toBe(bindGroups);
+    expect(count('createBuffer')).toBe(buffers);
+  });
+});
+
+describe('buildWgpuClassicDefineKey', () => {
+  it('encodes the lighting model first so the three models never collide', () => {
+    expect(buildWgpuClassicDefineKey(makeKey('lambert'))[0]).toBe('l');
+    expect(buildWgpuClassicDefineKey(makeKey('phong'))[0]).toBe('p');
+    expect(buildWgpuClassicDefineKey(makeKey('blinnphong'))[0]).toBe('b');
+
+    const keys = new Set([
+      buildWgpuClassicDefineKey(makeKey('lambert')),
+      buildWgpuClassicDefineKey(makeKey('phong')),
+      buildWgpuClassicDefineKey(makeKey('blinnphong')),
+    ]);
+    expect(keys.size).toBe(3);
+  });
+
+  it('encodes the alpha map as a distinct variant', () => {
+    const withAlpha = { ...makeKey('blinnphong'), hasAlphaMap: true };
+    expect(buildWgpuClassicDefineKey(withAlpha)).not.toBe(buildWgpuClassicDefineKey(makeKey('blinnphong')));
+  });
+});
+
+describe('compileWgpuClassicPipeline', () => {
+  it('builds a render pipeline with a material bind-group layout', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = compileWgpuClassicPipeline(state, makeKey('lambert'), 'bgra8unorm');
+
+    expect(pipeline.pipeline).toBeDefined();
+    expect(pipeline.materialBindGroupLayout).toBeDefined();
+    expect(fake.calls.some((c) => c.name === 'createShaderModule')).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'createRenderPipeline')).toBe(true);
+  });
+});
+
+describe('ensureWgpuClassicPipeline', () => {
+  it('caches under the classic: namespace with three distinct entries for the three models', () => {
+    const { state } = makeWgpuScene3DState();
+    ensureWgpuClassicPipeline(state, makeKey('lambert'), 'bgra8unorm');
+    ensureWgpuClassicPipeline(state, makeKey('phong'), 'bgra8unorm');
+    ensureWgpuClassicPipeline(state, makeKey('blinnphong'), 'bgra8unorm');
+    // Re-ensuring an existing model must not add a new cache entry.
+    ensureWgpuClassicPipeline(state, makeKey('phong'), 'bgra8unorm');
+
+    const cache = getWgpuScene3DRuntime(state).pipelineCache;
+    const classicKeys = [...cache.keys()].filter((k) => k.startsWith('classic:'));
+    expect(classicKeys.length).toBe(3);
+  });
+});
+
+describe('getWgpuClassicModuleSourceForKey', () => {
+  it('gates the alpha-map const + coverage multiply off the alpha-map flag', () => {
+    const none = getWgpuClassicModuleSourceForKey(makeKey('blinnphong'));
+    expect(none).toContain('const HAS_ALPHA_MAP : bool = false;');
+    const withAlpha = getWgpuClassicModuleSourceForKey({ ...makeKey('blinnphong'), hasAlphaMap: true });
+    expect(withAlpha).toContain('const HAS_ALPHA_MAP : bool = true;');
+    expect(withAlpha).toContain('alphaTexture');
+    expect(withAlpha).toContain('textureSample(alphaTexture, alphaSampler, in.uv).g');
+  });
+
+  it('emits the lighting-model const matching the model and folds the others off', () => {
+    const phong = getWgpuClassicModuleSourceForKey(makeKey('phong'));
+    expect(phong).toContain('const LIGHTING_PHONG : bool = true;');
+    expect(phong).toContain('const LIGHTING_BLINNPHONG : bool = false;');
+
+    const blinn = getWgpuClassicModuleSourceForKey(makeKey('blinnphong'));
+    expect(blinn).toContain('const LIGHTING_BLINNPHONG : bool = true;');
+    expect(blinn).toContain('const LIGHTING_PHONG : bool = false;');
+
+    const lambert = getWgpuClassicModuleSourceForKey(makeKey('lambert'));
+    expect(lambert).toContain('const LIGHTING_PHONG : bool = false;');
+    expect(lambert).toContain('const LIGHTING_BLINNPHONG : bool = false;');
+  });
+
+  it('emits the palette and skin attributes only for the HAS_SKIN variant', () => {
+    expect(getWgpuClassicModuleSourceForKey(makeKey('blinnphong'))).not.toContain('jointTexture');
+    expect(getWgpuClassicModuleSourceForKey(makeKey('blinnphong'), true, makeWgpuSkinningAdapter())).toContain(
+      '@group(1) @binding(1) var jointTexture',
+    );
+  });
+
+  it('declares the group(3) shadow bindings and shadow-maps the directional term', () => {
+    const source = getWgpuClassicModuleSourceForKey(makeKey('blinnphong'));
+    expect(source).toContain('@group(3) @binding(0) var<uniform> shadow : Shadow;');
+    expect(source).toContain('@group(3) @binding(1) var shadowMap : texture_depth_2d;');
+    expect(source).toContain('@group(3) @binding(2) var shadowSampler : sampler_comparison;');
+    // The whole directional contribution is scaled by the PCF factor; ambient stays unshadowed.
+    expect(source).toContain('direct * sampleDirectionalShadow(in.worldPosition)');
+    expect(source.match(/direct \* sampleDirectionalShadow\(in\.worldPosition\)/g)).toHaveLength(1);
+  });
+
+  it('consumes every packed punctual-light family through the shared classic BRDF', () => {
+    const source = getWgpuClassicModuleSourceForKey(makeKey('blinnphong'));
+    expect(source).toContain('let pointCount = u32(frame.punctualCounts.x);');
+    expect(source).toContain('frame.pointLights[point * 2u + 1u].xyz * atten');
+    expect(source).toContain('let spotCount = u32(frame.punctualCounts.y);');
+    expect(source).toContain('frame.spotLights[spot * 4u + 1u].xyz * atten * cone');
+    expect(source).toContain('let hemisphereCount = u32(frame.punctualCounts.z);');
+    expect(source).toContain('frame.hemisphereLights[hemisphere * 3u + 1u].xyz');
+    expect(source.match(/shadeClassicLight\(/g)).toHaveLength(4);
+  });
+});
+
+describe('getWgpuClassicSharedSamplerModuleSourceForKey', () => {
+  it('retains the legacy shared-sampler binding contract for shaded composition', () => {
+    const source = getWgpuClassicSharedSamplerModuleSourceForKey(makeKey('blinnphong'));
+    expect(source).toContain('@group(2) @binding(1) var materialSampler : sampler;');
+    expect(source).toContain('@group(2) @binding(2) var diffuseTexture : texture_2d<f32>;');
+    expect(source).toContain('@group(2) @binding(5) var alphaTexture : texture_2d<f32>;');
+    expect(source).toContain('textureSample(normalTexture, materialSampler, in.uv)');
+    expect(source).not.toContain('diffuseSampler');
+  });
+});

package/src/wgpuDebugPrelude.test.ts

@@ -0,0 +1,79 @@
+import type { WgpuDebugDefineKey } from '@flighthq/types';
+
+import {
+  bindWgpuDebugSurface,
+  buildWgpuDebugDefineKey,
+  compileWgpuDebugPipeline,
+  ensureWgpuDebugPipeline,
+  getWgpuDebugModuleSourceForKey,
+} from './wgpuDebugPrelude';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+const DEPTH: WgpuDebugDefineKey = { hasNormalMap: false, mode: 'depth' };
+const NORMAL: WgpuDebugDefineKey = { hasNormalMap: false, mode: 'normal' };
+const NORMAL_MAP: WgpuDebugDefineKey = { hasNormalMap: true, mode: 'normal' };
+
+describe('bindWgpuDebugSurface', () => {
+  it('creates a material bind group once per key and writes its uniform', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = compileWgpuDebugPipeline(state, DEPTH, 'bgra8unorm');
+    const key = {};
+    bindWgpuDebugSurface(state, pipeline, key, 0.1, 100, 1);
+    const groups = fake.calls.filter((c) => c.name === 'createBindGroup').length;
+    bindWgpuDebugSurface(state, pipeline, key, 0.1, 100, 1);
+    expect(fake.calls.filter((c) => c.name === 'createBindGroup').length).toBe(groups);
+    expect(fake.calls.some((c) => c.name === 'writeBuffer')).toBe(true);
+  });
+});
+
+describe('buildWgpuDebugDefineKey', () => {
+  it('produces distinct stable strings per mode and normal-map flag', () => {
+    expect(buildWgpuDebugDefineKey(DEPTH)).toBe('d-');
+    expect(buildWgpuDebugDefineKey(NORMAL)).toBe('n-');
+    expect(buildWgpuDebugDefineKey(NORMAL_MAP)).toBe('nm');
+  });
+});
+
+describe('compileWgpuDebugPipeline', () => {
+  it('compiles a module and builds the pipeline with a 3-entry material layout', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = compileWgpuDebugPipeline(state, NORMAL, 'rgba16float');
+    expect(pipeline.pipeline).toBeDefined();
+    expect(fake.calls.some((c) => c.name === 'createShaderModule')).toBe(true);
+    const matLayout = fake.calls
+      .filter((c) => c.name === 'createBindGroupLayout')
+      .map((c) => c.args[0] as { entries: unknown[] })
+      .find((d) => d.entries.length === 3);
+    expect(matLayout).toBeDefined();
+  });
+});
+
+describe('ensureWgpuDebugPipeline', () => {
+  it('caches variants under the debug namespace with distinct depth and normal entries', () => {
+    const { state } = makeWgpuScene3DState();
+    const depthFirst = ensureWgpuDebugPipeline(state, DEPTH, 'bgra8unorm');
+    const depthSecond = ensureWgpuDebugPipeline(state, DEPTH, 'bgra8unorm');
+    expect(depthSecond).toBe(depthFirst);
+
+    const normalPipeline = ensureWgpuDebugPipeline(state, NORMAL, 'bgra8unorm');
+    expect(normalPipeline).not.toBe(depthFirst);
+
+    const keys = [...getWgpuScene3DRuntime(state).pipelineCache.keys()];
+    expect(keys.some((k) => k.startsWith('debug:'))).toBe(true);
+    expect(keys).toContain('debug:bgra8unorm|d-|opaque|rigid');
+    expect(keys).toContain('debug:bgra8unorm|n-|opaque|rigid');
+  });
+});
+
+describe('getWgpuDebugModuleSourceForKey', () => {
+  it('emits the right mode const and includes the shared prelude + fs_main', () => {
+    const depthSource = getWgpuDebugModuleSourceForKey(DEPTH);
+    expect(depthSource).toContain('const MODE : i32 = DEPTH_MODE');
+    expect(getWgpuDebugModuleSourceForKey(NORMAL)).toContain('const MODE : i32 = NORMAL_MODE');
+    expect(depthSource).toContain('const HAS_NORMAL_MAP : bool = false');
+    expect(getWgpuDebugModuleSourceForKey(NORMAL_MAP)).toContain('const HAS_NORMAL_MAP : bool = true');
+    expect(depthSource).toContain('struct Frame');
+    expect(depthSource).toContain('fn fs_main');
+  });
+});

package/src/wgpuEnvironmentCube.test.ts

@@ -0,0 +1,86 @@
+import type { CubeTexture, Environment, ImageResource } from '@flighthq/types';
+
+import { ensureWgpuEnvironmentSourceCube, updateWgpuEnvironmentCubeFace } from './wgpuEnvironmentCube';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+// The GPU upload + sampling is validated by the functional `env-skybox` / `env-ibl` captures (jsdom has no
+// real WebGPU cube texture). These cover the CPU-side wiring: the six-face upload, the caching identity,
+// and the "no complete cube" sentinel path callers depend on to no-op — mirroring scene-gl's cube test.
+
+function completeEnvironment(): Environment {
+  const face = { source: {} as CanvasImageSource, data: null, width: 4, height: 4 } as ImageResource;
+  const cube = {
+    colorSpace: 'srgb',
+    faces: [face, face, face, face, face, face],
+    sampler: {},
+  } as unknown as CubeTexture;
+  return { environment: cube, intensity: 1 } as Environment;
+}
+
+function dataFace(): ImageResource {
+  return { source: null, data: new Uint8ClampedArray(4 * 4 * 4), width: 4, height: 4 } as ImageResource;
+}
+
+function dataOnlyEnvironment(): Environment {
+  const face = dataFace();
+  const cube = {
+    colorSpace: 'srgb',
+    faces: [face, face, face, face, face, face],
+    sampler: {},
+  } as unknown as CubeTexture;
+  return { environment: cube, intensity: 1 } as Environment;
+}
+
+describe('ensureWgpuEnvironmentSourceCube', () => {
+  it('returns null when the environment has no complete source cube', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(ensureWgpuEnvironmentSourceCube(state, { environment: null, intensity: 1 } as Environment)).toBe(null);
+  });
+
+  it('uploads six faces into a cube texture and caches the view', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const view = ensureWgpuEnvironmentSourceCube(state, completeEnvironment());
+    expect(view).not.toBe(null);
+    expect(fake.calls.filter((c) => c.name === 'copyExternalImageToTexture').length).toBe(6);
+    expect(getWgpuScene3DRuntime(state).environmentSourceCube).not.toBe(null);
+  });
+
+  it('uploads a data-only cube through queue.writeTexture', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const view = ensureWgpuEnvironmentSourceCube(state, dataOnlyEnvironment());
+    expect(view).not.toBe(null);
+    const writes = fake.calls.filter((c) => c.name === 'writeTexture');
+    expect(writes.length).toBe(6);
+    expect(fake.calls.filter((c) => c.name === 'copyExternalImageToTexture').length).toBe(0);
+    // rgba8unorm data face: tightly-packed rows of width*4 bytes.
+    expect((writes[0].args[2] as { bytesPerRow: number }).bytesPerRow).toBe(16);
+    expect(writes[0].args[1]).toBeInstanceOf(Uint8ClampedArray);
+  });
+
+  it('re-uses the cached cube view without re-uploading', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const view = ensureWgpuEnvironmentSourceCube(state, completeEnvironment());
+    const uploads = fake.calls.filter((c) => c.name === 'copyExternalImageToTexture').length;
+    const again = ensureWgpuEnvironmentSourceCube(state, completeEnvironment());
+    expect(again).toBe(view);
+    expect(fake.calls.filter((c) => c.name === 'copyExternalImageToTexture').length).toBe(uploads);
+  });
+});
+
+describe('updateWgpuEnvironmentCubeFace', () => {
+  it('returns false when no source cube has been built yet', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    expect(updateWgpuEnvironmentCubeFace(state, 2, dataFace())).toBe(false);
+    expect(fake.calls.some((c) => c.name === 'writeTexture')).toBe(false);
+  });
+
+  it('restamps a single face of the built cube without rebuilding the other five', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    ensureWgpuEnvironmentSourceCube(state, dataOnlyEnvironment());
+    const afterBuild = fake.calls.filter((c) => c.name === 'writeTexture').length;
+    expect(afterBuild).toBe(6);
+    expect(updateWgpuEnvironmentCubeFace(state, 2, dataFace())).toBe(true);
+    expect(fake.calls.filter((c) => c.name === 'writeTexture').length).toBe(afterBuild + 1);
+  });
+});

package/src/wgpuEnvironmentIblBake.test.ts

@@ -0,0 +1,79 @@
+import type { CubeTexture, Environment, ImageResource } from '@flighthq/types';
+
+import { bakeWgpuEnvironmentIbl, destroyWgpuScene3DIbl } from './wgpuEnvironmentIblBake';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+// The GPU bake (irradiance / prefiltered specular / BRDF LUT) is validated by the functional `env-ibl`
+// capture — jsdom cannot run WGSL. These cover the CPU-side wiring: the no-op sentinel, the split-sum set's
+// formats + mip chain stored on the runtime, the bake WGSL compile, and the destroy teardown — mirroring
+// scene-gl's bake test.
+
+function completeEnvironment(): Environment {
+  const face = { source: {} as CanvasImageSource, width: 4, height: 4 } as ImageResource;
+  const cube = {
+    colorSpace: 'srgb',
+    faces: [face, face, face, face, face, face],
+    sampler: {},
+  } as unknown as CubeTexture;
+  return { environment: cube, intensity: 1 } as Environment;
+}
+
+describe('bakeWgpuEnvironmentIbl', () => {
+  it('is a no-op leaving runtime.ibl null when the environment has no source cube', () => {
+    const { state } = makeWgpuScene3DState();
+    bakeWgpuEnvironmentIbl(state, { environment: null, intensity: 1 } as Environment);
+    expect(getWgpuScene3DRuntime(state).ibl).toBe(null);
+  });
+
+  it('bakes the split-sum set: rgba16float irradiance + prefiltered cubes + BRDF LUT with the mip chain', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    bakeWgpuEnvironmentIbl(state, completeEnvironment());
+
+    const runtime = getWgpuScene3DRuntime(state);
+    expect(runtime.ibl).not.toBe(null);
+    expect(runtime.ibl!.prefilteredMipCount).toBe(5);
+    expect(runtime.ibl!.intensity).toBe(1);
+
+    const bakeTextures = fake.calls.filter(
+      (c) => c.name === 'createTexture' && (c.args[0] as GPUTextureDescriptor).format === 'rgba16float',
+    );
+    // irradiance cube + prefiltered cube + BRDF LUT.
+    expect(bakeTextures.length).toBe(3);
+    // The prefiltered cube declares the full roughness mip chain up front.
+    expect(bakeTextures.some((c) => (c.args[0] as GPUTextureDescriptor).mipLevelCount === 5)).toBe(true);
+    // The bake WGSL is compiled (GGX importance sampling for the prefiltered/BRDF passes).
+    expect(
+      fake.calls.some(
+        (c) =>
+          c.name === 'createShaderModule' &&
+          String((c.args[0] as { code: string }).code).includes('importanceSampleGGX'),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('destroyWgpuScene3DIbl', () => {
+  it('frees the baked textures + source cube and clears the runtime slots', () => {
+    const { state } = makeWgpuScene3DState();
+    bakeWgpuEnvironmentIbl(state, completeEnvironment());
+
+    const runtime = getWgpuScene3DRuntime(state);
+    let destroyed = 0;
+    runtime.ibl!.brdfLut.destroy = () => void destroyed++;
+    runtime.ibl!.irradianceCube.destroy = () => void destroyed++;
+    runtime.ibl!.prefilteredCube.destroy = () => void destroyed++;
+
+    destroyWgpuScene3DIbl(state);
+    expect(destroyed).toBe(3);
+    expect(runtime.ibl).toBe(null);
+    expect(runtime.environmentSourceCube).toBe(null);
+    expect(runtime.environmentSourceCubeView).toBe(null);
+  });
+
+  it('is a safe no-op when no bake ran for the state', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(() => destroyWgpuScene3DIbl(state)).not.toThrow();
+    expect(() => destroyWgpuScene3DIbl(state)).not.toThrow();
+  });
+});

package/src/wgpuEnvironmentSkybox.test.ts

@@ -0,0 +1,56 @@
+import { createCamera3D } from '@flighthq/camera';
+import type { Camera3D, CubeTexture, Environment, ImageResource } from '@flighthq/types';
+
+import { drawWgpuEnvironmentSkybox } from './wgpuEnvironmentSkybox';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+// The skybox draw itself is validated by the functional `env-skybox` capture (jsdom cannot run WGSL). These
+// cover the CPU-side wiring: the no-complete-cube sentinel no-op, and the pipeline/bind/draw call shape of
+// the backdrop pass — mirroring scene-gl's skybox test.
+
+function makeCamera(): Camera3D {
+  return createCamera3D({ far: 100, near: 0.1, projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' } });
+}
+
+function completeEnvironment(): Environment {
+  const face = { source: {} as CanvasImageSource, width: 4, height: 4 } as ImageResource;
+  const cube = {
+    colorSpace: 'srgb',
+    faces: [face, face, face, face, face, face],
+    sampler: {},
+  } as unknown as CubeTexture;
+  return { environment: cube, intensity: 1 } as Environment;
+}
+
+describe('drawWgpuEnvironmentSkybox', () => {
+  it('is a no-op when the environment has no complete source cube', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const before = fake.calls.length;
+    expect(() =>
+      drawWgpuEnvironmentSkybox(state, { environment: null, intensity: 1 } as Environment, makeCamera(), 1),
+    ).not.toThrow();
+    expect(fake.calls.length).toBe(before);
+  });
+
+  it('binds the cube + uniform and draws the fullscreen backdrop', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    drawWgpuEnvironmentSkybox(state, completeEnvironment(), makeCamera(), 1);
+
+    expect(fake.calls.some((c) => c.name === 'setPipeline')).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'setBindGroup' && c.args[0] === 1)).toBe(true);
+    expect(fake.calls.some((c) => c.name === 'draw' && c.args[0] === 3)).toBe(true);
+  });
+
+  it('compiles skybox WGSL that reconstructs the ray from the inverse view-projection', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    drawWgpuEnvironmentSkybox(state, completeEnvironment(), makeCamera(), 1);
+
+    const shader = fake.calls.find(
+      (c) =>
+        c.name === 'createShaderModule' &&
+        String((c.args[0] as { code: string }).code).includes('inverseViewProjection'),
+    );
+    expect(shader).toBeDefined();
+    expect(String((shader!.args[0] as { code: string }).code)).toContain('texture_cube<f32>');
+  });
+});

package/src/wgpuMatcapPrelude.test.ts

@@ -0,0 +1,70 @@
+import type { LinearColor, WgpuMatcapDefineKey } from '@flighthq/types';
+
+import {
+  bindWgpuMatcapSurface,
+  buildWgpuMatcapDefineKey,
+  compileWgpuMatcapPipeline,
+  ensureWgpuMatcapPipeline,
+  getWgpuMatcapModuleSourceForKey,
+} from './wgpuMatcapPrelude';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+const FLAT: WgpuMatcapDefineKey = { alphaMaskEnabled: false, doubleSided: false, hasMatcap: false };
+const TINT: LinearColor = [0.5, 0.25, 0.1, 1];
+
+describe('bindWgpuMatcapSurface', () => {
+  it('creates a material bind group once per key and writes its uniform', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = compileWgpuMatcapPipeline(state, FLAT, 'bgra8unorm');
+    const key = {};
+    bindWgpuMatcapSurface(state, pipeline, key, TINT, 0.5);
+    const groups = fake.calls.filter((c) => c.name === 'createBindGroup').length;
+    bindWgpuMatcapSurface(state, pipeline, key, TINT, 0.5);
+    expect(fake.calls.filter((c) => c.name === 'createBindGroup').length).toBe(groups);
+    expect(fake.calls.some((c) => c.name === 'writeBuffer')).toBe(true);
+  });
+});
+
+describe('buildWgpuMatcapDefineKey', () => {
+  it('produces distinct stable strings per flag set', () => {
+    expect(buildWgpuMatcapDefineKey(FLAT)).toBe('---');
+    expect(buildWgpuMatcapDefineKey({ alphaMaskEnabled: true, doubleSided: true, hasMatcap: true })).toBe('mdt');
+  });
+});
+
+describe('compileWgpuMatcapPipeline', () => {
+  it('compiles a module and builds the pipeline with a 3-entry material layout', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = compileWgpuMatcapPipeline(state, FLAT, 'rgba16float');
+    expect(pipeline.pipeline).toBeDefined();
+    expect(fake.calls.some((c) => c.name === 'createShaderModule')).toBe(true);
+    const matLayout = fake.calls
+      .filter((c) => c.name === 'createBindGroupLayout')
+      .map((c) => c.args[0] as { entries: unknown[] })
+      .find((d) => d.entries.length === 3);
+    expect(matLayout).toBeDefined();
+  });
+});
+
+describe('ensureWgpuMatcapPipeline', () => {
+  it('caches one pipeline per define key + format under the matcap namespace', () => {
+    const { state } = makeWgpuScene3DState();
+    const a = ensureWgpuMatcapPipeline(state, FLAT, 'bgra8unorm');
+    const b = ensureWgpuMatcapPipeline(state, FLAT, 'bgra8unorm');
+    expect(a).toBe(b);
+    expect([...getWgpuScene3DRuntime(state).pipelineCache.keys()].some((k) => k.startsWith('matcap:'))).toBe(true);
+  });
+});
+
+describe('getWgpuMatcapModuleSourceForKey', () => {
+  it('emits the feature consts and includes the shared prelude + fs_main', () => {
+    expect(getWgpuMatcapModuleSourceForKey(FLAT)).toContain('const HAS_MATCAP : bool = false');
+    expect(getWgpuMatcapModuleSourceForKey({ ...FLAT, alphaMaskEnabled: true })).toContain(
+      'const ALPHA_MASK : bool = true',
+    );
+    const source = getWgpuMatcapModuleSourceForKey(FLAT);
+    expect(source).toContain('struct Frame');
+    expect(source).toContain('fn fs_main');
+  });
+});

package/src/wgpuMeshMaterialRegistry.test.ts

@@ -0,0 +1,55 @@
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import type { WgpuMeshMaterialRenderer } from '@flighthq/types';
+import { DefaultMaterialKind, StandardPbrMaterialKind } from '@flighthq/types';
+
+import {
+  getWgpuMeshMaterialRenderer,
+  registerWgpuMeshMaterialRenderer,
+  resolveWgpuMeshMaterialRenderer,
+} from './wgpuMeshMaterialRegistry';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+function makeRenderer(): WgpuMeshMaterialRenderer {
+  return { bind: () => {}, draw: () => {} };
+}
+
+describe('getWgpuMeshMaterialRenderer', () => {
+  it('returns a registered renderer by kind, else null', () => {
+    const { state } = makeWgpuScene3DState();
+    const renderer = makeRenderer();
+    expect(getWgpuMeshMaterialRenderer(state, StandardPbrMaterialKind)).toBeNull();
+    registerWgpuMeshMaterialRenderer(state, StandardPbrMaterialKind, renderer);
+    expect(getWgpuMeshMaterialRenderer(state, StandardPbrMaterialKind)).toBe(renderer);
+  });
+});
+
+describe('registerWgpuMeshMaterialRenderer', () => {
+  it('registers a renderer in the scene-wgpu 3D registry', () => {
+    const { state } = makeWgpuScene3DState();
+    const renderer = makeRenderer();
+    registerWgpuMeshMaterialRenderer(state, StandardPbrMaterialKind, renderer);
+    expect(getWgpuMeshMaterialRenderer(state, StandardPbrMaterialKind)).toBe(renderer);
+  });
+});
+
+describe('resolveWgpuMeshMaterialRenderer', () => {
+  it('resolves by the material kind', () => {
+    const { state } = makeWgpuScene3DState();
+    const renderer = makeRenderer();
+    registerWgpuMeshMaterialRenderer(state, StandardPbrMaterialKind, renderer);
+    expect(resolveWgpuMeshMaterialRenderer(state, createStandardPbrMaterial())).toBe(renderer);
+  });
+
+  it('falls back to DefaultMaterialKind for an unregistered kind or null material', () => {
+    const { state } = makeWgpuScene3DState();
+    const fallback = makeRenderer();
+    registerWgpuMeshMaterialRenderer(state, DefaultMaterialKind, fallback);
+    expect(resolveWgpuMeshMaterialRenderer(state, createStandardPbrMaterial())).toBe(fallback);
+    expect(resolveWgpuMeshMaterialRenderer(state, null)).toBe(fallback);
+  });
+
+  it('returns null when neither the kind nor the default is registered', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(resolveWgpuMeshMaterialRenderer(state, createStandardPbrMaterial())).toBeNull();
+  });
+});