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

package/src/wgpuMeshUpload.test.ts

@@ -0,0 +1,177 @@
+import {
+  CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT,
+  createBoxMeshGeometry,
+  createMeshGeometry,
+  setMeshGeometrySkinBindPose,
+  updateMeshMorph,
+} from '@flighthq/mesh';
+import { createMesh } from '@flighthq/scene3d';
+import type { MeshGeometryRuntime, MeshMorph, VertexAttributeLayout } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { ensureWgpuMeshUpload } from './wgpuMeshUpload';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+import { registerWgpuGpuSkinning } from './wgpuSkinPalette';
+
+const POSITION_LAYOUT: VertexAttributeLayout = {
+  attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+  stride: 12,
+};
+
+function lastUploadedVertices(calls: readonly { name: string; args: readonly unknown[] }[]): Float32Array {
+  const writes = calls.filter((call) => call.name === 'writeBuffer');
+  const write = writes[writes.length - 2]!;
+  return new Float32Array(
+    write.args[2] as ArrayBuffer,
+    write.args[3] as number,
+    (write.args[4] as number) / Float32Array.BYTES_PER_ELEMENT,
+  );
+}
+
+describe('ensureWgpuMeshUpload', () => {
+  it('uploads vertex + index buffers and caches by geometry', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const upload = ensureWgpuMeshUpload(state, geometry);
+
+    expect(upload).not.toBeNull();
+    expect(upload!.vertexBuffer).toBeDefined();
+    expect(upload!.indexBuffer).toBeDefined();
+    expect(upload!.indexCount).toBe(geometry.indices!.length);
+    expect(upload!.version).toBe(geometry.version);
+    expect(fake.calls.filter((c) => c.name === 'writeBuffer').length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('returns the cached upload without re-uploading when version is unchanged', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const first = ensureWgpuMeshUpload(state, geometry);
+    const writesAfterFirst = fake.calls.filter((c) => c.name === 'writeBuffer').length;
+    const second = ensureWgpuMeshUpload(state, geometry);
+    expect(second).toBe(first);
+    expect(fake.calls.filter((c) => c.name === 'writeBuffer').length).toBe(writesAfterFirst);
+  });
+
+  it('re-uploads when geometry.version changes', () => {
+    const { state } = makeWgpuScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const first = ensureWgpuMeshUpload(state, geometry);
+    geometry.version++;
+    const second = ensureWgpuMeshUpload(state, geometry);
+    expect(second).not.toBe(first);
+    expect(second!.version).toBe(geometry.version);
+  });
+
+  it('uploads captured bind-pose positions for a GPU-skinned geometry', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    registerWgpuGpuSkinning(state);
+    const vertices = new Float32Array(20);
+    vertices[0] = 9;
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 0, 0]),
+      layout: CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT,
+      vertices,
+    });
+    setMeshGeometrySkinBindPose(geometry, {
+      joints: new Float32Array([0, 0, 0, 0]),
+      normals: new Float32Array([0, 1, 0]),
+      positions: new Float32Array([1, 2, 3]),
+      skinnedNormals: new Float32Array(3),
+      skinnedPositions: new Float32Array(3),
+      weights: new Float32Array([1, 0, 0, 0]),
+    });
+
+    const upload = ensureWgpuMeshUpload(state, geometry, true);
+    const write = fake.calls.find((call) => call.name === 'writeBuffer')!;
+    const uploadedVertices = new Float32Array(
+      write.args[2] as ArrayBuffer,
+      write.args[3] as number,
+      (write.args[4] as number) / 4,
+    );
+
+    expect(upload?.skinBindUploaded).toBe(true);
+    expect(Array.from(uploadedVertices.slice(0, 3))).toEqual([1, 2, 3]);
+    expect(geometry.vertices[0]).toBe(9);
+  });
+
+  it('re-uploads morph-blended vertices as weights change', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 0, 0]),
+      layout: POSITION_LAYOUT,
+      vertices: new Float32Array([0, 0, 0]),
+    });
+    const morph: MeshMorph = {
+      targets: [{ normalDeltas: null, positionDeltas: new Float32Array([4, 0, 0]), tangentDeltas: null }],
+      weights: new Float32Array([1]),
+    };
+    const mesh = createMesh(geometry, []);
+    mesh.morph = morph;
+
+    updateMeshMorph(mesh);
+    ensureWgpuMeshUpload(state, geometry);
+    expect(lastUploadedVertices(fake.calls)[0]).toBeCloseTo(4);
+
+    morph.weights[0] = 0.5;
+    updateMeshMorph(mesh);
+    ensureWgpuMeshUpload(state, geometry);
+    expect(lastUploadedVertices(fake.calls)[0]).toBeCloseTo(2);
+  });
+
+  it('uploads current morphed vertices instead of a frozen skin bind pose for GPU skinning', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    registerWgpuGpuSkinning(state);
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 0, 0]),
+      layout: CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT,
+      vertices: new Float32Array(20),
+    });
+    geometry.vertices[0] = 1;
+    setMeshGeometrySkinBindPose(geometry, {
+      joints: new Float32Array([0, 0, 0, 0]),
+      normals: new Float32Array([0, 1, 0]),
+      positions: new Float32Array([1, 0, 0]),
+      skinnedNormals: new Float32Array(3),
+      skinnedPositions: new Float32Array(3),
+      weights: new Float32Array([1, 0, 0, 0]),
+    });
+    const morph: MeshMorph = {
+      targets: [{ normalDeltas: null, positionDeltas: new Float32Array([4, 0, 0]), tangentDeltas: null }],
+      weights: new Float32Array([1]),
+    };
+    const mesh = createMesh(geometry, []);
+    mesh.morph = morph;
+
+    updateMeshMorph(mesh);
+    ensureWgpuMeshUpload(state, geometry, true);
+    expect(lastUploadedVertices(fake.calls)[0]).toBeCloseTo(5);
+
+    morph.weights[0] = 2;
+    updateMeshMorph(mesh);
+    ensureWgpuMeshUpload(state, geometry, true);
+    expect(lastUploadedVertices(fake.calls)[0]).toBeCloseTo(9);
+  });
+
+  it('mirrors the upload onto MeshGeometryRuntime.webgpuData', () => {
+    const { state } = makeWgpuScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const upload = ensureWgpuMeshUpload(state, geometry);
+    const meshRuntime = geometry[EntityRuntimeKey] as MeshGeometryRuntime;
+    expect(meshRuntime.webgpuData as unknown).toBe(upload);
+  });
+
+  it('returns null for non-indexed geometry', () => {
+    const { state } = makeWgpuScene3DState();
+    const geometry = createMeshGeometry({
+      indices: null,
+      layout: {
+        attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+        stride: 12,
+      },
+      vertices: new Float32Array(9),
+    });
+    expect(ensureWgpuMeshUpload(state, geometry)).toBeNull();
+    expect(getWgpuScene3DRuntime(state).uploadCache.get(geometry)).toBeUndefined();
+  });
+});

package/src/wgpuParticleEmitter3D.test.ts

@@ -0,0 +1,200 @@
+import { createCamera3D } from '@flighthq/camera';
+import { createMatrix4, setVector3 } from '@flighthq/geometry';
+import { addNodeChild, invalidateNodeLocalTransform } from '@flighthq/node';
+import { createParticleEmitter3D, reserveParticleEmitter3D } from '@flighthq/particleemitter';
+import { createNode3D, Node3DKind } from '@flighthq/scene3d';
+import type { Camera3D, ParticleEmitter3D, Scene3DLightsLike } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { destroyWgpuParticleEmitter3DResources, drawWgpuScene3DParticleEmitter3Ds } from './wgpuParticleEmitter3D';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+function makeCamera(): Camera3D {
+  const cam = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' },
+  });
+  cam.view = createMatrix4();
+  return cam;
+}
+
+function makeLights(): Scene3DLightsLike {
+  return { ambient: null, directional: null };
+}
+
+function makeEmitterWithParticles(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 * 2;
+    data.transforms[tt + 2] = 0;
+    data.transforms[tt + 3] = 1;
+    data.positionsZ[i] = i * 3;
+    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;
+}
+
+function makeAtlasEmitter(regionWidth: number, regionHeight: number): ParticleEmitter3D {
+  const emitter = makeEmitterWithParticles(1);
+  const img = document.createElement('img');
+  emitter.data.atlas = {
+    image: { source: img, width: 128, height: 128 },
+    regions: [{ id: 0, x: 0, y: 0, width: regionWidth, height: regionHeight }],
+  } as unknown as NonNullable<ParticleEmitter3D['data']['atlas']>;
+  return emitter;
+}
+
+function findInstanceWrite(calls: { name: string; args: unknown[] }[]): Float32Array | undefined {
+  // The instance upload is the writeBuffer whose data is a Float32Array longer than the 8-float corner
+  // quad; the frame upload passes an ArrayBuffer and the corner buffer a length-8 array.
+  const call = calls.find(
+    (c) => c.name === 'writeBuffer' && c.args[2] instanceof Float32Array && (c.args[2] as Float32Array).length > 8,
+  );
+  return call?.args[2] as Float32Array | undefined;
+}
+
+function pipelineDescriptors(calls: { name: string; args: unknown[] }[]): Record<string, unknown>[] {
+  return calls.filter((c) => c.name === 'createRenderPipeline').map((c) => c.args[0] as Record<string, unknown>);
+}
+
+function hasTextureConstant(descriptor: Record<string, unknown>): number {
+  const fragment = descriptor['fragment'] as { constants: Record<string, number> };
+  return fragment.constants['HAS_TEXTURE'];
+}
+
+describe('destroyWgpuParticleEmitter3DResources', () => {
+  it('is a no-op when no resources were created', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(() => destroyWgpuParticleEmitter3DResources(state)).not.toThrow();
+  });
+
+  it('drops resources after a draw', () => {
+    const { state } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(() => destroyWgpuParticleEmitter3DResources(state)).not.toThrow();
+  });
+});
+
+describe('drawWgpuScene3DParticleEmitter3Ds', () => {
+  it('is a no-op when the scene has no particle emitter nodes', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(false);
+  });
+
+  it('skips emitters with zero particles', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createParticleEmitter3D());
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(fake.calls.some((c) => c.name === 'drawIndexed')).toBe(false);
+  });
+
+  it('issues one instanced indexed draw of 6 indices per emitter', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(5));
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const draw = fake.calls.find((c) => c.name === 'drawIndexed');
+    expect(draw).toBeDefined();
+    expect(draw!.args[0]).toBe(6);
+    expect(draw!.args[1]).toBe(5);
+  });
+
+  it('uploads the per-instance data to a vertex buffer', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(3));
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(findInstanceWrite(fake.calls)).toBeDefined();
+  });
+
+  it('normalizes the particle quad to an aspect-ratio unit square, not the region pixel size', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeAtlasEmitter(64, 32));
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const instanceData = findInstanceWrite(fake.calls)!;
+    // Instance floats [13]/[14] carry the normalized quad size for the first particle.
+    expect(instanceData[13]).toBeCloseTo(1);
+    expect(instanceData[14]).toBeCloseTo(0.5);
+  });
+
+  it('compiles the textured pipeline variant for an atlas emitter', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeAtlasEmitter(64, 64));
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(pipelineDescriptors(fake.calls).some((d) => hasTextureConstant(d) === 1)).toBe(true);
+  });
+
+  it('compiles the untextured pipeline variant for an atlas-less emitter', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const descriptors = pipelineDescriptors(fake.calls);
+    expect(descriptors.length).toBe(1);
+    expect(hasTextureConstant(descriptors[0])).toBe(0);
+  });
+
+  it('reuses the cached pipeline on a second draw', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    // One variant compiled once across both draws — the shader module and pipeline are cached per state.
+    expect(pipelineDescriptors(fake.calls).length).toBe(1);
+  });
+
+  it('skips the node world transform for world-space particles', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = makeEmitterWithParticles(1);
+    emitter.data.transforms[0] = 1;
+    emitter.data.transforms[1] = 2;
+    emitter.data.positionsZ[0] = 3;
+    setVector3(emitter.position, 10, 20, 30);
+    invalidateNodeLocalTransform(emitter);
+    emitter.data.worldSpace = true;
+    addNodeChild(scene, emitter);
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const instanceData = findInstanceWrite(fake.calls)!;
+    // Already baked into world space, so the (10,20,30) node translation is not re-applied.
+    expect(instanceData[0]).toBeCloseTo(1);
+    expect(instanceData[1]).toBeCloseTo(2);
+    expect(instanceData[2]).toBeCloseTo(3);
+  });
+
+  it('applies the node world transform for local-space particles', () => {
+    const { state, fake } = makeWgpuScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = makeEmitterWithParticles(1);
+    emitter.data.transforms[0] = 1;
+    emitter.data.transforms[1] = 2;
+    emitter.data.positionsZ[0] = 3;
+    setVector3(emitter.position, 10, 20, 30);
+    invalidateNodeLocalTransform(emitter);
+    addNodeChild(scene, emitter);
+    drawWgpuScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const instanceData = findInstanceWrite(fake.calls)!;
+    expect(instanceData[0]).toBeCloseTo(11);
+    expect(instanceData[1]).toBeCloseTo(22);
+    expect(instanceData[2]).toBeCloseTo(33);
+  });
+});

package/src/wgpuPbrPipelineCache.test.ts

@@ -0,0 +1,67 @@
+import type { WgpuPbrDefineKey } from '@flighthq/types';
+
+import { compileWgpuPbrPipeline, ensureWgpuPbrPipeline } from './wgpuPbrPipelineCache';
+import { getWgpuScene3DRuntime } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+
+function key(overrides?: Partial<WgpuPbrDefineKey>): WgpuPbrDefineKey {
+  return {
+    alphaMaskEnabled: false,
+    anisotropyEnabled: false,
+    clearcoatEnabled: false,
+    doubleSided: false,
+    hasAlphaMap: false,
+    hasBaseColorMap: false,
+    hasEmissiveMap: false,
+    hasMetallicRoughnessMap: false,
+    hasNormalMap: false,
+    hasOcclusionMap: false,
+    iridescenceEnabled: false,
+    sheenEnabled: false,
+    specularEnabled: false,
+    subsurfaceEnabled: false,
+    transmissionEnabled: false,
+    ...overrides,
+  };
+}
+
+describe('compileWgpuPbrPipeline', () => {
+  it('compiles a module and builds the pipeline + material bind-group layout', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    const pipeline = compileWgpuPbrPipeline(state, key(), 'rgba16float');
+    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);
+  });
+
+  it('bakes back-face culling unless the key is doubleSided', () => {
+    const { fake, state } = makeWgpuScene3DState();
+    compileWgpuPbrPipeline(state, key(), 'bgra8unorm');
+    compileWgpuPbrPipeline(state, key({ doubleSided: true }), 'bgra8unorm');
+    const pipelineCalls = fake.calls.filter((c) => c.name === 'createRenderPipeline');
+    const culled = pipelineCalls[0].args[0] as { primitive: { cullMode: string } };
+    const doubleSided = pipelineCalls[1].args[0] as { primitive: { cullMode: string } };
+    expect(culled.primitive.cullMode).toBe('back');
+    expect(doubleSided.primitive.cullMode).toBe('none');
+  });
+});
+
+describe('ensureWgpuPbrPipeline', () => {
+  it('caches one pipeline per define key + format', () => {
+    const { state } = makeWgpuScene3DState();
+    const a = ensureWgpuPbrPipeline(state, key(), 'rgba16float');
+    const b = ensureWgpuPbrPipeline(state, key(), 'rgba16float');
+    expect(a).toBe(b);
+    expect(getWgpuScene3DRuntime(state).pipelineCache.size).toBe(1);
+  });
+
+  it('compiles distinct variants for distinct format, standard, or extension defines', () => {
+    const { state } = makeWgpuScene3DState();
+    ensureWgpuPbrPipeline(state, key(), 'rgba16float');
+    ensureWgpuPbrPipeline(state, key(), 'bgra8unorm');
+    ensureWgpuPbrPipeline(state, key({ doubleSided: true }), 'rgba16float');
+    ensureWgpuPbrPipeline(state, key({ clearcoatEnabled: true }), 'rgba16float');
+    expect(getWgpuScene3DRuntime(state).pipelineCache.size).toBe(4);
+  });
+});

package/src/wgpuPbrPrelude.test.ts

@@ -0,0 +1,162 @@
+import type { WgpuPbrDefineKey } from '@flighthq/types';
+
+import {
+  buildWgpuPbrDefineKey,
+  buildWgpuPbrDefineSource,
+  getWgpuPbrModuleBody,
+  getWgpuPbrModuleSourceForKey,
+} from './wgpuPbrPrelude';
+import { makeWgpuSkinningAdapter } from './wgpuScene3DTestHelper';
+
+function key(overrides?: Partial<WgpuPbrDefineKey>): WgpuPbrDefineKey {
+  return {
+    alphaMaskEnabled: false,
+    anisotropyEnabled: false,
+    clearcoatEnabled: false,
+    doubleSided: false,
+    hasAlphaMap: false,
+    hasBaseColorMap: false,
+    hasEmissiveMap: false,
+    hasMetallicRoughnessMap: false,
+    hasNormalMap: false,
+    hasOcclusionMap: false,
+    iridescenceEnabled: false,
+    sheenEnabled: false,
+    specularEnabled: false,
+    subsurfaceEnabled: false,
+    transmissionEnabled: false,
+    ...overrides,
+  };
+}
+
+const NONE = key();
+const STANDARD_ALL = key({
+  alphaMaskEnabled: true,
+  doubleSided: true,
+  hasBaseColorMap: true,
+  hasEmissiveMap: true,
+  hasMetallicRoughnessMap: true,
+  hasNormalMap: true,
+  hasOcclusionMap: true,
+});
+const ALL = key({
+  ...STANDARD_ALL,
+  anisotropyEnabled: true,
+  clearcoatEnabled: true,
+  iridescenceEnabled: true,
+  sheenEnabled: true,
+  specularEnabled: true,
+  subsurfaceEnabled: true,
+  transmissionEnabled: true,
+});
+
+describe('buildWgpuPbrDefineKey', () => {
+  it('produces a stable, distinct string per flag set', () => {
+    expect(buildWgpuPbrDefineKey(NONE)).toBe('--------:-------');
+    expect(buildWgpuPbrDefineKey(STANDARD_ALL)).toBe('mdbnroe-:-------');
+    expect(buildWgpuPbrDefineKey(ALL)).toBe('mdbnroe-:CSAIPUT');
+    expect(buildWgpuPbrDefineKey(key({ alphaMaskEnabled: true }))).toBe('m-------:-------');
+    expect(buildWgpuPbrDefineKey(key({ doubleSided: true }))).toBe('-d------:-------');
+    expect(buildWgpuPbrDefineKey(key({ hasBaseColorMap: true }))).toBe('--b-----:-------');
+    expect(buildWgpuPbrDefineKey(key({ hasNormalMap: true }))).toBe('---n----:-------');
+    expect(buildWgpuPbrDefineKey(key({ hasMetallicRoughnessMap: true }))).toBe('----r---:-------');
+    expect(buildWgpuPbrDefineKey(key({ hasOcclusionMap: true }))).toBe('-----o--:-------');
+    expect(buildWgpuPbrDefineKey(key({ hasEmissiveMap: true }))).toBe('------e-:-------');
+    expect(buildWgpuPbrDefineKey(key({ hasAlphaMap: true }))).toBe('-------a:-------');
+    expect(buildWgpuPbrDefineKey(key({ clearcoatEnabled: true }))).toBe('--------:C------');
+    expect(buildWgpuPbrDefineKey(key({ transmissionEnabled: true }))).toBe('--------:------T');
+  });
+
+  it('is identical for identical flags (cache soundness)', () => {
+    expect(buildWgpuPbrDefineKey(key(ALL))).toBe(buildWgpuPbrDefineKey(key(ALL)));
+  });
+});
+
+describe('buildWgpuPbrDefineSource', () => {
+  it('emits a const bool flag block reflecting the key', () => {
+    const source = buildWgpuPbrDefineSource(key({ hasBaseColorMap: true, doubleSided: true }));
+    expect(source).toContain('const HAS_BASE_COLOR_MAP : bool = true;');
+    expect(source).toContain('const DOUBLE_SIDED : bool = true;');
+    expect(source).toContain('const ALPHA_MASK : bool = false;');
+    expect(source).toContain('const HAS_NORMAL_MAP : bool = false;');
+  });
+
+  it('emits a const for every extension lobe', () => {
+    const all = buildWgpuPbrDefineSource(ALL);
+    expect(all).toContain('const CLEARCOAT : bool = true;');
+    expect(all).toContain('const SHEEN : bool = true;');
+    expect(all).toContain('const ANISOTROPY : bool = true;');
+    expect(all).toContain('const IRIDESCENCE : bool = true;');
+    expect(all).toContain('const SPECULAR_EXT : bool = true;');
+    expect(all).toContain('const SUBSURFACE : bool = true;');
+    expect(all).toContain('const TRANSMISSION : bool = true;');
+
+    const none = buildWgpuPbrDefineSource(NONE);
+    expect(none).toContain('const CLEARCOAT : bool = false;');
+    expect(none).toContain('const TRANSMISSION : bool = false;');
+    expect(none).toContain('const HAS_ALPHA_MAP : bool = false;');
+  });
+
+  it('gates the alpha-map const off the dedicated coverage-map flag', () => {
+    expect(buildWgpuPbrDefineSource(key({ hasAlphaMap: true }))).toContain('const HAS_ALPHA_MAP : bool = true;');
+  });
+});
+
+describe('getWgpuPbrModuleBody', () => {
+  it('declares the entry points and bind-group structs', () => {
+    const body = getWgpuPbrModuleBody();
+    expect(body).toContain('fn vs_main');
+    expect(body).toContain('fn fs_main');
+    expect(body).toContain('struct Frame');
+    expect(body).toContain('struct MaterialBlock');
+    expect(body).toContain('var<uniform> frame');
+  });
+
+  it('samples every standard map through its own sampler binding', () => {
+    const body = getWgpuPbrModuleBody();
+    expect(body).toContain('textureSample(baseColorTexture, baseColorSampler, in.uv)');
+    expect(body).toContain('textureSample(metallicRoughnessTexture, metallicRoughnessSampler, in.uv)');
+    expect(body).toContain('textureSample(normalTexture, normalSampler, in.uv)');
+    expect(body).toContain('textureSample(occlusionTexture, occlusionSampler, in.uv)');
+    expect(body).toContain('textureSample(emissiveTexture, emissiveSampler, in.uv)');
+    expect(body).toContain('textureSample(alphaTexture, alphaSampler, in.uv)');
+  });
+
+  it('includes the extension lobe helpers behind their const flags', () => {
+    const body = getWgpuPbrModuleBody();
+    expect(body).toContain('distributionGgxAnisotropic');
+    expect(body).toContain('distributionCharlie');
+    expect(body).toContain('iridescentFresnel');
+    expect(body).toContain('if (CLEARCOAT)');
+    expect(body).toContain('if (TRANSMISSION)');
+  });
+
+  // Image-based-lighting shares group(3) with shadow so PBR stays within WebGPU's required
+  // maxBindGroups minimum of 4.
+  it('declares the group(3) IBL bindings and applies the split-sum ambient term', () => {
+    const body = getWgpuPbrModuleBody();
+    expect(body).toContain('@group(3) @binding(3) var<uniform> ibl');
+    expect(body).toContain('var iblIrradiance : texture_cube<f32>');
+    expect(body).toContain('var iblPrefiltered : texture_cube<f32>');
+    expect(body).toContain('var iblBrdf : texture_2d<f32>');
+    expect(body).toContain('fn sampleIblAmbient');
+    expect(body).toContain('fresnelSchlickRoughness');
+    // split-sum specular = prefiltered * (F * brdf.x + brdf.y)
+    expect(body).toContain('prefiltered * (F * brdf.x + brdf.y)');
+    // gated ambient: IBL when enabled, else the flat ambient term.
+    expect(body).toContain('if (ibl.params.x > 0.5)');
+  });
+});
+
+describe('getWgpuPbrModuleSourceForKey', () => {
+  it('prepends the flag block to the module body', () => {
+    const k = key({ hasNormalMap: true });
+    const source = getWgpuPbrModuleSourceForKey(k);
+    expect(source.startsWith(buildWgpuPbrDefineSource(k))).toBe(true);
+    expect(source).toContain('fn fs_main');
+    expect(source).toContain('@interpolate(flat) objectAlpha : f32');
+    expect(source).toContain('alpha * in.objectAlpha');
+    expect(source).not.toContain('jointTexture');
+    expect(getWgpuPbrModuleSourceForKey(k, true, makeWgpuSkinningAdapter())).toContain('textureLoad(jointTexture');
+  });
+});

package/src/wgpuScene3DRuntime.test.ts

@@ -0,0 +1,35 @@
+import type { WgpuRenderStateRuntime } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { getWgpuScene3DRuntime, getWgpuSkinningAdapter } from './wgpuScene3DRuntime';
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+import { registerWgpuGpuSkinning } from './wgpuSkinPalette';
+
+describe('getWgpuScene3DRuntime', () => {
+  it('lazily creates one runtime per state and returns the same instance', () => {
+    const { state } = makeWgpuScene3DState();
+    const a = getWgpuScene3DRuntime(state);
+    const b = getWgpuScene3DRuntime(state);
+    expect(a).toBe(b);
+    expect(a.materialRegistry).toBeInstanceOf(Map);
+    expect(a.pipelineCache).toBeInstanceOf(Map);
+    expect(a.activeMeshPipeline).toBeNull();
+  });
+
+  it('surfaces the registry and upload cache through the header runtime slots', () => {
+    const { state } = makeWgpuScene3DState();
+    const scene = getWgpuScene3DRuntime(state);
+    const stateRuntime = state[EntityRuntimeKey] as WgpuRenderStateRuntime;
+    expect(stateRuntime.sceneMeshMaterialRegistry).toBe(scene.materialRegistry);
+    expect(stateRuntime.sceneMeshUploadCache).toBe(scene.uploadCache);
+  });
+});
+
+describe('getWgpuSkinningAdapter', () => {
+  it('returns the state-scoped opt-in adapter', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(getWgpuSkinningAdapter(state)).toBeNull();
+    registerWgpuGpuSkinning(state);
+    expect(getWgpuSkinningAdapter(state)).not.toBeNull();
+  });
+});

package/src/wgpuScene3DTime.test.ts

@@ -0,0 +1,20 @@
+import { makeWgpuScene3DState } from './wgpuScene3DTestHelper';
+import { getWgpuScene3DTime, setWgpuScene3DTime } from './wgpuScene3DTime';
+
+describe('getWgpuScene3DTime', () => {
+  it('defaults to zero and reads the state-scoped value', () => {
+    const { state } = makeWgpuScene3DState();
+    expect(getWgpuScene3DTime(state)).toBe(0);
+    setWgpuScene3DTime(state, 2.5);
+    expect(getWgpuScene3DTime(state)).toBe(2.5);
+  });
+});
+
+describe('setWgpuScene3DTime', () => {
+  it('does not leak across render states', () => {
+    const first = makeWgpuScene3DState().state;
+    const second = makeWgpuScene3DState().state;
+    setWgpuScene3DTime(first, 4);
+    expect(getWgpuScene3DTime(second)).toBe(0);
+  });
+});