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

package/src/glShadowMap.test.ts

@@ -0,0 +1,219 @@
+import { createCamera3D, createOrthographicProjection, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createVector3 } from '@flighthq/geometry';
+import { createMeshGeometry, updateMeshMorph } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import { createMesh, createNode3D, Node3DKind } from '@flighthq/scene3d';
+import type { Skin, VertexAttributeLayout } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import { drawGlScene3DShadowMap } from './glShadowMap';
+
+const POSITION_LAYOUT: VertexAttributeLayout = {
+  attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+  stride: 12,
+};
+
+// A layout carrying joints0 (what hasMeshGeometrySkin keys off) so a mesh with a skin GPU-skins.
+const SKINNED_LAYOUT: VertexAttributeLayout = {
+  attributes: [
+    { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+    { byteOffset: 12, format: 'float32x4', semantic: 'joints0' },
+    { byteOffset: 28, format: 'float32x4', semantic: 'weights0' },
+  ],
+  stride: 44,
+};
+
+function lastUploadedVertices(calls: readonly { name: string; args: readonly unknown[] }[]): Float32Array {
+  const data = calls
+    .filter((c) => c.name === 'bufferData')
+    .map((c) => c.args[1])
+    .filter((d): d is Float32Array => d instanceof Float32Array);
+  return data[data.length - 1]!;
+}
+
+function makeShadowState() {
+  const { state, gl } = makeGlScene3DState();
+
+  const calls = gl.calls;
+  const record =
+    (name: string, result?: unknown) =>
+    (...args: unknown[]): unknown => {
+      calls.push({ name, args });
+      return result;
+    };
+
+  Object.assign(gl as unknown as Record<string, unknown>, {
+    FRAMEBUFFER: 0x8d40,
+    FRAMEBUFFER_BINDING: 0x8ca6,
+    VIEWPORT: 0x0ba2,
+    DEPTH_BUFFER_BIT: 0x100,
+    COLOR_BUFFER_BIT: 0x4000,
+    FRONT: 0x0404,
+    MAX_SAMPLES: 0x8d57,
+    LINEAR: 0x2601,
+    NEAREST: 0x2600,
+    TEXTURE_MIN_FILTER: 0x2801,
+    TEXTURE_MAG_FILTER: 0x2800,
+    TEXTURE_WRAP_S: 0x2802,
+    TEXTURE_WRAP_T: 0x2803,
+    CLAMP_TO_EDGE: 0x812f,
+    COLOR_ATTACHMENT0: 0x8ce0,
+    DEPTH_STENCIL_ATTACHMENT: 0x821a,
+    DEPTH24_STENCIL8: 0x88f0,
+    DEPTH_STENCIL: 0x84f9,
+    UNSIGNED_INT_24_8: 0x84fa,
+    RENDERBUFFER: 0x8d41,
+    createFramebuffer: () => ({}),
+    deleteFramebuffer: () => {},
+    bindFramebuffer: record('bindFramebuffer'),
+    viewport: record('viewport'),
+    getParameter: (param: number) => {
+      const gl2 = gl as unknown as Record<string, number>;
+      if (param === gl2['MAX_SAMPLES']) return 4;
+      if (param === gl2['FRAMEBUFFER_BINDING']) return null;
+      if (param === gl2['VIEWPORT']) return new Int32Array([0, 0, 256, 256]);
+      return null;
+    },
+    clear: record('clear'),
+    createRenderbuffer: () => ({}),
+    bindRenderbuffer: () => {},
+    deleteRenderbuffer: () => {},
+    framebufferTexture2D: () => {},
+    framebufferRenderbuffer: () => {},
+    getExtension: () => ({}),
+  });
+
+  (state[EntityRuntimeKey] as unknown as Record<string, unknown>).currentFramebuffer = null;
+
+  return { state, gl };
+}
+
+function makeShadowCamera() {
+  const camera = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: createOrthographicProjection({ halfHeight: 10, halfWidth: 10 }),
+  });
+  setCamera3DViewMatrix4FromLookAt(camera, createVector3(0, 10, 10), createVector3(0, 0, 0), createVector3(0, 1, 0));
+  return camera;
+}
+
+describe('drawGlScene3DShadowMap', () => {
+  it('lazily creates the shadow target on the first call', () => {
+    const { state } = makeShadowState();
+    const scene = createNode3D(Node3DKind);
+    const camera = makeShadowCamera();
+
+    drawGlScene3DShadowMap(state, scene, camera);
+
+    expect(getGlScene3DRuntime(state).shadowTarget).not.toBeNull();
+  });
+
+  it('reuses the same shadow target on subsequent calls', () => {
+    const { state } = makeShadowState();
+    const scene = createNode3D(Node3DKind);
+    const camera = makeShadowCamera();
+
+    drawGlScene3DShadowMap(state, scene, camera);
+    const firstTarget = getGlScene3DRuntime(state).shadowTarget;
+
+    drawGlScene3DShadowMap(state, scene, camera);
+    const secondTarget = getGlScene3DRuntime(state).shadowTarget;
+
+    expect(secondTarget).toBe(firstTarget);
+  });
+
+  it('records the light-space matrix on the runtime', () => {
+    const { state } = makeShadowState();
+    const scene = createNode3D(Node3DKind);
+    const camera = makeShadowCamera();
+
+    drawGlScene3DShadowMap(state, scene, camera);
+
+    const shadow = getGlScene3DRuntime(state).shadow;
+    expect(shadow).not.toBeNull();
+    expect(shadow!.matrix).not.toBeNull();
+  });
+
+  it('sets up the depth pass with front-face culling', () => {
+    const { state, gl } = makeShadowState();
+    const scene = createNode3D(Node3DKind);
+    const camera = makeShadowCamera();
+
+    drawGlScene3DShadowMap(state, scene, camera);
+
+    const frontValue = (gl as unknown as Record<string, number>)['FRONT'];
+    const cullFaceCall = gl.calls.find((c) => c.name === 'cullFace' && c.args[0] === frontValue);
+    expect(cullFaceCall).toBeDefined();
+
+    const cullFaceConstant = (gl as unknown as Record<string, number>)['CULL_FACE'];
+    const enableCullFaceCall = gl.calls.find((c) => c.name === 'enable' && c.args[0] === cullFaceConstant);
+    expect(enableCullFaceCall).toBeDefined();
+  });
+
+  it('records the caster at the pose the app blended before the pass', () => {
+    const { state, gl } = makeShadowState();
+    const scene = createNode3D(Node3DKind);
+    const geometry = createMeshGeometry({ layout: POSITION_LAYOUT, vertices: new Float32Array([0, 0, 0, 1, 0, 0]) });
+    const mesh = createMesh(geometry, []);
+    // Weight 1 on a target that raises y by 5. The morph is blended by the app's prepareScene3DMorph
+    // before any draw (here updateMeshMorph stands in for it); the depth pass just uploads that pose,
+    // it no longer re-blends internally — otherwise the cull would have already lagged a frame.
+    mesh.morph = {
+      targets: [{ normalDeltas: null, positionDeltas: new Float32Array([0, 5, 0, 0, 5, 0]), tangentDeltas: null }],
+      weights: new Float32Array([1]),
+    };
+    addNodeChild(scene, mesh);
+    updateMeshMorph(mesh);
+
+    drawGlScene3DShadowMap(state, scene, makeShadowCamera());
+
+    const uploaded = lastUploadedVertices(gl.calls);
+    expect(uploaded[1]).toBe(5);
+    expect(uploaded[4]).toBe(5);
+  });
+
+  it('draws a GPU-skinned caster through the HAS_SKIN depth variant', () => {
+    const { state } = makeShadowState();
+    const scene = createNode3D(Node3DKind);
+    const geometry = createMeshGeometry({
+      layout: SKINNED_LAYOUT,
+      vertices: new Float32Array([0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0]),
+    });
+    const mesh = createMesh(geometry, []);
+    const skin: Skin = {
+      skeleton: {
+        [EntityRuntimeKey]: undefined,
+        inverseBindMatrices: new Float32Array(16),
+        jointMatrices: new Float32Array(16),
+        joints: [],
+        names: null,
+      },
+    };
+    mesh.skin = skin;
+    addNodeChild(scene, mesh);
+
+    drawGlScene3DShadowMap(state, scene, makeShadowCamera());
+
+    // A skinned caster compiles + uses the dedicated HAS_SKIN depth program rather than the rigid one.
+    expect([...getGlScene3DRuntime(state).programCache.keys()]).toContain('shadow:depth:skin');
+  });
+
+  it('restores the previous framebuffer after the depth pass', () => {
+    const { state, gl } = makeShadowState();
+    const scene = createNode3D(Node3DKind);
+    const camera = makeShadowCamera();
+
+    drawGlScene3DShadowMap(state, scene, camera);
+
+    const framebufferConstant = (gl as unknown as Record<string, number>)['FRAMEBUFFER'];
+    const bindFramebufferCalls = gl.calls.filter((c) => c.name === 'bindFramebuffer');
+    const lastBindFramebuffer = bindFramebufferCalls[bindFramebufferCalls.length - 1];
+
+    expect(lastBindFramebuffer).toBeDefined();
+    expect(lastBindFramebuffer.args[0]).toBe(framebufferConstant);
+    expect(lastBindFramebuffer.args[1]).toBeNull();
+  });
+});

package/src/glToonPrelude.test.ts

@@ -0,0 +1,118 @@
+import type { GlToonDefineKey } from '@flighthq/types';
+
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeFakeGl2, makeGlScene3DState } from './glScene3DTestHelper';
+import {
+  buildGlToonDefineKey,
+  compileGlToonProgram,
+  ensureGlToonProgram,
+  getGlToonFragmentSourceForKey,
+  getGlToonVertexSourceForKey,
+} from './glToonPrelude';
+
+const FLAT: GlToonDefineKey = {
+  alphaMaskEnabled: false,
+  hasBaseColorMap: false,
+  hasRamp: false,
+  hasUvTransform: false,
+};
+
+describe('buildGlToonDefineKey', () => {
+  it('produces distinct stable strings per flag set', () => {
+    expect(buildGlToonDefineKey(FLAT)).toBe('-----');
+    expect(
+      buildGlToonDefineKey({ alphaMaskEnabled: true, hasBaseColorMap: true, hasRamp: true, hasUvTransform: true }),
+    ).toBe('mbru-');
+    expect(buildGlToonDefineKey({ ...FLAT, hasRamp: true })).toBe('--r--');
+  });
+
+  it('encodes a non-identity uv transform in the u slot ahead of skin', () => {
+    expect(buildGlToonDefineKey({ ...FLAT, hasUvTransform: true })).toBe('---u-');
+    expect(buildGlToonDefineKey({ ...FLAT, hasUvTransform: true })).not.toBe(buildGlToonDefineKey(FLAT));
+  });
+
+  it('appends a skinned flag that differs from the rigid key', () => {
+    expect(buildGlToonDefineKey({ ...FLAT, hasSkin: true })).toBe('----k');
+    expect(buildGlToonDefineKey({ ...FLAT, hasSkin: true })).not.toBe(buildGlToonDefineKey(FLAT));
+  });
+});
+
+describe('compileGlToonProgram', () => {
+  it('compiles, links, and resolves the lit + toon uniform locations', () => {
+    const gl = makeFakeGl2();
+    const program = compileGlToonProgram(gl, FLAT);
+    // Lit base locations (spread from resolveGlLitLocations).
+    expect(program.locDirectional).not.toBeNull();
+    expect(program.locAmbientRadiance).not.toBeNull();
+    expect(program.locCameraPosition).not.toBeNull();
+    // Toon material locations.
+    expect(program.locBaseColor).not.toBeNull();
+    expect(program.locSteps).not.toBeNull();
+    expect(program.locRamp).not.toBeNull();
+    expect(program.locBaseColorMap).not.toBeNull();
+    expect(program.locAlphaCutoff).not.toBeNull();
+    // Shared vertex transforms.
+    expect(program.locModel).not.toBeNull();
+    expect(program.locNormalMatrix).not.toBeNull();
+    expect(program.locViewProjection).not.toBeNull();
+    expect(gl.calls.some((c) => c.name === 'linkProgram')).toBe(true);
+  });
+});
+
+describe('ensureGlToonProgram', () => {
+  it('caches a variant under the toon namespace and reuses it', () => {
+    const { state, gl } = makeGlScene3DState();
+    const first = ensureGlToonProgram(state, FLAT);
+    const links = gl.calls.filter((c) => c.name === 'linkProgram').length;
+    const second = ensureGlToonProgram(state, FLAT);
+    expect(second).toBe(first);
+    expect(gl.calls.filter((c) => c.name === 'linkProgram').length).toBe(links);
+    expect([...getGlScene3DRuntime(state).programCache.keys()].some((k) => k.startsWith('toon:'))).toBe(true);
+  });
+});
+
+describe('getGlToonFragmentSourceForKey', () => {
+  it('includes the light block and gates feature defines on their flag', () => {
+    expect(getGlToonFragmentSourceForKey(FLAT)).toContain('u_directional');
+    expect(getGlToonFragmentSourceForKey(FLAT)).toContain('#define MAX_FORWARD_LIGHTS');
+    expect(getGlToonFragmentSourceForKey(FLAT)).not.toContain('#define HAS_BASE_COLOR_MAP');
+    expect(getGlToonFragmentSourceForKey(FLAT)).not.toContain('#define HAS_RAMP');
+    expect(getGlToonFragmentSourceForKey({ ...FLAT, hasBaseColorMap: true })).toContain('#define HAS_BASE_COLOR_MAP');
+    expect(getGlToonFragmentSourceForKey({ ...FLAT, hasRamp: true })).toContain('#define HAS_RAMP');
+    expect(getGlToonFragmentSourceForKey({ ...FLAT, alphaMaskEnabled: true })).toContain('#define ALPHA_MASK');
+  });
+
+  it('shadow-maps the banded directional term (and only the directional term)', () => {
+    // The banded directional contribution is multiplied by the shared sampleDirectionalShadow factor,
+    // matching the classic/PBR families; ambient stays unshadowed, so the helper appears once.
+    for (const key of [FLAT, { ...FLAT, hasRamp: true }]) {
+      const source = getGlToonFragmentSourceForKey(key);
+      expect(source).toContain('sampleDirectionalShadow(v_worldPosition)');
+      expect(source.match(/sampleDirectionalShadow\(v_worldPosition\)/g)).toHaveLength(1);
+    }
+  });
+});
+
+describe('getGlToonVertexSourceForKey', () => {
+  it('passes world position and normal varyings through the shared vertex transforms', () => {
+    const source = getGlToonVertexSourceForKey(FLAT);
+    expect(source).toContain('#version 300 es');
+    expect(source).toContain('v_worldPosition');
+    expect(source).toContain('v_normal');
+    expect(source).toContain('u_viewProjection');
+    expect(source).toContain('u_normalMatrix');
+  });
+
+  it('injects the skin declarations only for the skinned variant', () => {
+    const skinned = getGlToonVertexSourceForKey({ ...FLAT, hasSkin: true });
+    expect(skinned).toContain('#define HAS_SKIN');
+    expect(skinned).not.toContain('#define MAX_JOINTS');
+    expect(skinned).toContain('sampler2D u_jointTexture');
+    expect(skinned).toContain('texelFetch');
+    expect(skinned).toContain('mat4 skinMatrix()');
+    expect(skinned).toContain('a_joints0');
+    const rigid = getGlToonVertexSourceForKey(FLAT);
+    expect(rigid).not.toContain('#define HAS_SKIN');
+    expect(rigid).not.toContain('a_joints0');
+  });
+});

package/src/glUnlitPrelude.test.ts

@@ -0,0 +1,156 @@
+import type { LinearColor, VideoTexture, GlUnlitDefineKey } from '@flighthq/types';
+
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeFakeGl2, makeGlScene3DState } from './glScene3DTestHelper';
+import {
+  bindGlUnlitSurface,
+  bindGlUnlitVideoSurface,
+  buildGlUnlitDefineKey,
+  compileGlUnlitProgram,
+  ensureGlUnlitProgram,
+  getGlUnlitFragmentSourceForKey,
+  getGlUnlitVertexSourceForKey,
+} from './glUnlitPrelude';
+
+function makeReadyVideoTexture(frameId: number): VideoTexture {
+  return {
+    frameId,
+    sampler: null,
+    source: { element: { readyState: 4, videoWidth: 320, videoHeight: 240 } as unknown as HTMLVideoElement },
+  } as unknown as VideoTexture;
+}
+
+const FLAT: GlUnlitDefineKey = {
+  alphaMaskEnabled: false,
+  hasColorMap: false,
+  hasUvTransform: false,
+  vertexColor: false,
+};
+const COLOR: LinearColor = [0.5, 0.25, 0.1, 1];
+
+describe('bindGlUnlitSurface', () => {
+  it('uploads the color, intensity, and alpha cutoff', () => {
+    const { state, gl } = makeGlScene3DState();
+    const program = compileGlUnlitProgram(gl, FLAT);
+    bindGlUnlitSurface(state, program, COLOR, 2, null, 0.5);
+    expect(gl.calls.some((c) => c.name === 'uniform4f')).toBe(true);
+    expect(gl.calls.filter((c) => c.name === 'uniform1f').length).toBeGreaterThanOrEqual(2);
+    // No color map → no texture bind.
+    expect(gl.calls.some((c) => c.name === 'bindTexture')).toBe(false);
+  });
+});
+
+describe('bindGlUnlitVideoSurface', () => {
+  it('uploads the color/intensity/cutoff and binds the video map on unit 0', () => {
+    const { state, gl } = makeGlScene3DState();
+    const program = compileGlUnlitProgram(gl, { ...FLAT, hasColorMap: true });
+    bindGlUnlitVideoSurface(state, program, COLOR, 1, makeReadyVideoTexture(2), 0.5);
+    expect(gl.calls.some((c) => c.name === 'uniform4f')).toBe(true);
+    // Live frame uploaded and the map sampler set to unit 0.
+    expect(gl.calls.some((c) => c.name === 'texImage2D')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'bindTexture')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'uniform1i')).toBe(true);
+  });
+
+  it('does not upload a frame that has not advanced (the dirty-gate)', () => {
+    const { state, gl } = makeGlScene3DState();
+    const program = compileGlUnlitProgram(gl, { ...FLAT, hasColorMap: true });
+    const videoMap = makeReadyVideoTexture(3);
+    bindGlUnlitVideoSurface(state, program, COLOR, 1, videoMap, 0.5);
+    const uploads = gl.calls.filter((c) => c.name === 'texImage2D').length;
+    bindGlUnlitVideoSurface(state, program, COLOR, 1, videoMap, 0.5);
+    expect(gl.calls.filter((c) => c.name === 'texImage2D').length).toBe(uploads);
+  });
+});
+
+describe('buildGlUnlitDefineKey', () => {
+  it('produces distinct stable strings per flag set', () => {
+    expect(buildGlUnlitDefineKey(FLAT)).toBe('-----');
+    expect(
+      buildGlUnlitDefineKey({ alphaMaskEnabled: true, hasColorMap: true, hasUvTransform: true, vertexColor: true }),
+    ).toBe('mcvu-');
+    expect(buildGlUnlitDefineKey({ ...FLAT, vertexColor: true })).toBe('--v--');
+  });
+
+  it('encodes a non-identity uv transform with a u slot and keys it distinctly', () => {
+    expect(buildGlUnlitDefineKey({ ...FLAT, hasUvTransform: true })).toBe('---u-');
+    expect(buildGlUnlitDefineKey({ ...FLAT, hasUvTransform: true })).not.toBe(buildGlUnlitDefineKey(FLAT));
+  });
+
+  it('encodes the skinned variant with a trailing k and keys it distinctly', () => {
+    expect(buildGlUnlitDefineKey({ ...FLAT, hasSkin: true }).endsWith('k')).toBe(true);
+    expect(buildGlUnlitDefineKey({ ...FLAT, hasSkin: true })).not.toBe(buildGlUnlitDefineKey(FLAT));
+  });
+});
+
+describe('compileGlUnlitProgram', () => {
+  it('compiles, links, and resolves the unlit uniforms with a null normal matrix', () => {
+    const gl = makeFakeGl2();
+    const program = compileGlUnlitProgram(gl, FLAT);
+    expect(program.locColor).not.toBeNull();
+    expect(program.locIntensity).not.toBeNull();
+    expect(program.locNormalMatrix).toBeNull();
+    expect(gl.calls.some((c) => c.name === 'linkProgram')).toBe(true);
+  });
+});
+
+describe('ensureGlUnlitProgram', () => {
+  it('caches a variant under the unlit namespace and reuses it', () => {
+    const { state, gl } = makeGlScene3DState();
+    const first = ensureGlUnlitProgram(state, FLAT);
+    const links = gl.calls.filter((c) => c.name === 'linkProgram').length;
+    const second = ensureGlUnlitProgram(state, FLAT);
+    expect(second).toBe(first);
+    expect(gl.calls.filter((c) => c.name === 'linkProgram').length).toBe(links);
+    expect([...getGlScene3DRuntime(state).programCache.keys()].some((k) => k.startsWith('unlit:'))).toBe(true);
+  });
+
+  it('compiles the skinned variant as a distinct cache entry', () => {
+    const { state } = makeGlScene3DState();
+    ensureGlUnlitProgram(state, FLAT);
+    getGlScene3DRuntime(state).activeSkinnedRun = true;
+    ensureGlUnlitProgram(state, FLAT);
+    const keys = [...getGlScene3DRuntime(state).programCache.keys()];
+    expect(keys.some((k) => k.startsWith('unlit:') && k.endsWith('k'))).toBe(true);
+    expect(keys.filter((k) => k.startsWith('unlit:')).length).toBe(2);
+  });
+});
+
+describe('getGlUnlitFragmentSourceForKey', () => {
+  it('includes feature defines only when their flag is set', () => {
+    expect(getGlUnlitFragmentSourceForKey(FLAT)).not.toContain('#define HAS_COLOR_MAP');
+    expect(getGlUnlitFragmentSourceForKey({ ...FLAT, hasColorMap: true })).toContain('#define HAS_COLOR_MAP');
+    expect(getGlUnlitFragmentSourceForKey({ ...FLAT, alphaMaskEnabled: true })).toContain('#define ALPHA_MASK');
+  });
+});
+
+describe('getGlUnlitVertexSourceForKey', () => {
+  it('defines VERTEX_COLOR only in the vertex-color variant', () => {
+    expect(getGlUnlitVertexSourceForKey(FLAT)).not.toContain('#define VERTEX_COLOR');
+    expect(getGlUnlitVertexSourceForKey({ ...FLAT, vertexColor: true })).toContain('#define VERTEX_COLOR');
+    // The color0 attribute lives behind the #ifdef, so it is present in the body string either way.
+    expect(getGlUnlitVertexSourceForKey({ ...FLAT, vertexColor: true })).toContain('a_color0');
+  });
+
+  it('defines HAS_UV_TRANSFORM and applies the transform only in the uv-transform variant', () => {
+    // applyUvTransform is always in the body (identity when undefined); the define + uniform are gated.
+    expect(getGlUnlitVertexSourceForKey(FLAT)).not.toContain('#define HAS_UV_TRANSFORM');
+    const transformed = getGlUnlitVertexSourceForKey({ ...FLAT, hasColorMap: true, hasUvTransform: true });
+    expect(transformed).toContain('#define HAS_UV_TRANSFORM');
+    expect(transformed).toContain('uniform mat3 u_uvTransform');
+    expect(transformed).toContain('v_uv0 = applyUvTransform(a_uv0)');
+  });
+
+  it('splices the skin declarations and HAS_SKIN defines only in the skinned variant', () => {
+    const skinned = getGlUnlitVertexSourceForKey({ ...FLAT, hasSkin: true });
+    expect(skinned).toContain('#define HAS_SKIN');
+    expect(skinned).not.toContain('#define MAX_JOINTS');
+    expect(skinned).toContain('sampler2D u_jointTexture');
+    expect(skinned).toContain('texelFetch');
+    expect(skinned).toContain('mat4 skinMatrix()');
+    expect(skinned).toContain('a_joints0');
+    const flat = getGlUnlitVertexSourceForKey(FLAT);
+    expect(flat).not.toContain('#define HAS_SKIN');
+    expect(flat).not.toContain('a_joints0');
+  });
+});

package/src/glWireframePrelude.test.ts

@@ -0,0 +1,46 @@
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeFakeGl2, makeGlScene3DState } from './glScene3DTestHelper';
+import {
+  compileGlWireframeProgram,
+  ensureGlWireframeProgram,
+  getGlWireframeFragmentSource,
+  getGlWireframeVertexSource,
+} from './glWireframePrelude';
+
+describe('compileGlWireframeProgram', () => {
+  it('compiles, links, and resolves the color + transform locations with a null normal matrix', () => {
+    const gl = makeFakeGl2();
+    const program = compileGlWireframeProgram(gl);
+    expect(program.locColor).not.toBeNull();
+    expect(program.locViewProjection).not.toBeNull();
+    expect(program.locNormalMatrix).toBeNull();
+    expect(gl.calls.some((c) => c.name === 'linkProgram')).toBe(true);
+  });
+});
+
+describe('ensureGlWireframeProgram', () => {
+  it('caches the single wireframe program under the wireframe namespace', () => {
+    const { state, gl } = makeGlScene3DState();
+    const first = ensureGlWireframeProgram(state);
+    const links = gl.calls.filter((c) => c.name === 'linkProgram').length;
+    const second = ensureGlWireframeProgram(state);
+    expect(second).toBe(first);
+    expect(gl.calls.filter((c) => c.name === 'linkProgram').length).toBe(links);
+    expect([...getGlScene3DRuntime(state).programCache.keys()].some((k) => k.startsWith('wireframe:'))).toBe(true);
+  });
+});
+
+describe('getGlWireframeFragmentSource', () => {
+  it('outputs the flat color uniform', () => {
+    expect(getGlWireframeFragmentSource()).toContain('u_color');
+  });
+});
+
+describe('getGlWireframeVertexSource', () => {
+  it('transforms position by model and view-projection', () => {
+    const source = getGlWireframeVertexSource();
+    expect(source).toContain('a_position');
+    expect(source).toContain('u_viewProjection');
+    expect(source).toContain('u_model');
+  });
+});

package/src/glWireframeUpload.test.ts

@@ -0,0 +1,50 @@
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import { destroyGlWireframeUpload, ensureGlWireframeUpload } from './glWireframeUpload';
+
+describe('destroyGlWireframeUpload', () => {
+  it('deletes the VAO and the line-index buffer, but not the shared vertex buffer', () => {
+    const { state, gl } = makeGlScene3DState();
+    const upload = ensureGlWireframeUpload(state, createBoxMeshGeometry());
+    const deletesBefore = gl.calls.filter((c) => c.name === 'deleteBuffer').length;
+    destroyGlWireframeUpload(state, upload);
+    // Exactly the line-index buffer is freed here; the interleaved vertex buffer belongs to the
+    // triangle mesh upload and is freed by destroyGlMeshUpload for that geometry.
+    expect(gl.calls.filter((c) => c.name === 'deleteBuffer').length).toBe(deletesBefore + 1);
+    expect(gl.calls.filter((c) => c.name === 'deleteVertexArray').length).toBe(1);
+    const deletedBuffer = gl.calls.find((c) => c.name === 'deleteBuffer');
+    expect(deletedBuffer!.args[0]).toBe(upload.lineIndexBuffer);
+  });
+});
+
+describe('ensureGlWireframeUpload', () => {
+  it('builds a line-index VAO and uploads the derived line buffer', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const upload = ensureGlWireframeUpload(state, geometry);
+    expect(upload.vao).toBeDefined();
+    expect(upload.lineIndexBuffer).toBeDefined();
+    // The element-array upload holds the derived line list: two indices per triangle edge, six per
+    // triangle (independent of the Uint16/Uint32 index width).
+    const triangleCount = geometry.indices!.length / 3;
+    const lineUpload = gl.calls.find(
+      (c) =>
+        c.name === 'bufferData' &&
+        c.args[0] === gl.ELEMENT_ARRAY_BUFFER &&
+        ArrayBuffer.isView(c.args[1] as ArrayBufferView) &&
+        (c.args[1] as Uint16Array | Uint32Array).length === triangleCount * 6,
+    );
+    expect(lineUpload).toBeDefined();
+  });
+
+  it('re-binds the cached VAO without rebuilding when the version is unchanged', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const first = ensureGlWireframeUpload(state, geometry);
+    const builds = gl.calls.filter((c) => c.name === 'createVertexArray').length;
+    const second = ensureGlWireframeUpload(state, geometry);
+    expect(second).toBe(first);
+    expect(gl.calls.filter((c) => c.name === 'createVertexArray').length).toBe(builds);
+  });
+});

package/src/iridescencePbrGlMeshMaterialRenderer.test.ts

@@ -0,0 +1,86 @@
+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 { getGlMeshMaterialRenderer } from './glMeshMaterialRegistry';
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import {
+  iridescencePbrGlMeshMaterialRenderer,
+  registerIridescencePbrGlMaterial,
+} from './iridescencePbrGlMeshMaterialRenderer';
+
+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(),
+    normalMatrix: createMatrix3() as Matrix3,
+    subset: geometry.subsets[0],
+    worldMatrix: createMatrix4() as Matrix4,
+  };
+}
+
+describe('iridescencePbrGlMeshMaterialRenderer', () => {
+  it('bind uploads the light block, standard block, and iridescence uniforms', () => {
+    const { state, gl } = makeGlScene3DState();
+    iridescencePbrGlMeshMaterialRenderer.bind(
+      state,
+      createIridescencePbrMaterial({ iridescence: 1 }),
+      makeLights(),
+      makeCamera(),
+    );
+    expect(gl.calls.some((c) => c.name === 'useProgram')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'uniform4f')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'uniformMatrix4fv')).toBe(true);
+    expect(gl.calls.filter((c) => c.name === 'uniform1f').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('caches the iridescence program under the pbr: namespace', () => {
+    const { state } = makeGlScene3DState();
+    iridescencePbrGlMeshMaterialRenderer.bind(state, createIridescencePbrMaterial(), makeLights(), makeCamera());
+    const cache = getGlScene3DRuntime(state).programCache;
+    expect(cache.size).toBe(1);
+    expect([...cache.keys()][0].startsWith('pbr:')).toBe(true);
+  });
+
+  it('draw issues an indexed draw after bind', () => {
+    const { state, gl } = makeGlScene3DState();
+    const proxy = makeProxy();
+    iridescencePbrGlMeshMaterialRenderer.bind(state, proxy.material, makeLights(), makeCamera());
+    iridescencePbrGlMeshMaterialRenderer.draw(state, proxy, createBoxMeshGeometry());
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(true);
+  });
+
+  it('draw is a no-op before bind', () => {
+    const { state, gl } = makeGlScene3DState();
+    iridescencePbrGlMeshMaterialRenderer.draw(state, makeProxy(), createBoxMeshGeometry());
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(false);
+  });
+});
+
+describe('registerIridescencePbrGlMaterial', () => {
+  it('installs the renderer for IridescencePbrMaterialKind', () => {
+    const { state } = makeGlScene3DState();
+    registerIridescencePbrGlMaterial(state);
+    expect(getGlMeshMaterialRenderer(state, IridescencePbrMaterialKind)).toBe(iridescencePbrGlMeshMaterialRenderer);
+  });
+});