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

package/src/enableGlScene3DForwardLightSelectionGuards.test.ts

@@ -0,0 +1,84 @@
+import { createCamera3D, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createPointLight } from '@flighthq/lighting';
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log';
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import { prepareScene3DRender } from '@flighthq/render';
+import { createMesh, createNode3D, Node3DKind } from '@flighthq/scene3d';
+import type { Camera3D, Scene3DLightsLike } from '@flighthq/types';
+
+import { drawGlScene3D } from './drawGlScene3D';
+import {
+  areGlScene3DForwardLightSelectionGuardsEnabled,
+  enableGlScene3DForwardLightSelectionGuards,
+} from './enableGlScene3DForwardLightSelectionGuards';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import { prepareGlScene3DForwardLights } from './prepareGlScene3DForwardLights';
+import { registerStandardPbrGlMaterial } from './registerStandardPbrGlMaterial';
+
+function camera(): Camera3D {
+  const result = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' },
+  });
+  setCamera3DViewMatrix4FromLookAt(result, { x: 0, y: 0, z: 5 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+  return result;
+}
+
+function excessLights(): Scene3DLightsLike {
+  return {
+    ambient: null,
+    directional: null,
+    point: Array.from({ length: 5 }, (_, x) => createPointLight({ position: { x: x - 2, y: 0, z: 2 }, range: 10 })),
+  };
+}
+
+describe('areGlScene3DForwardLightSelectionGuardsEnabled', () => {
+  it('reports false until guards are installed, then true', () => {
+    const { state } = makeGlScene3DState();
+    expect(areGlScene3DForwardLightSelectionGuardsEnabled(state)).toBe(false);
+    enableGlScene3DForwardLightSelectionGuards(state);
+    expect(areGlScene3DForwardLightSelectionGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableGlScene3DForwardLightSelectionGuards', () => {
+  it('warns when excess punctual lights draw without a prepared selection', () => {
+    const { state } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+    enableGlScene3DForwardLightSelectionGuards(state);
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]));
+    const sink = createMemoryLogSink(8);
+    addLogSink(sink.sink);
+    try {
+      drawGlScene3D(state, scene, camera(), excessLights());
+      const entries = getMemoryLogSinkEntries(sink);
+      expect(entries).toHaveLength(1);
+      expect(String((entries[0].data as Record<string, unknown>).message)).toContain('prepareGlScene3DForwardLights');
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+
+  it('stays silent when the explicit per-object selection is supplied', () => {
+    const { state } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+    enableGlScene3DForwardLightSelectionGuards(state);
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]));
+    const view = camera();
+    const lights = excessLights();
+    const selected = prepareGlScene3DForwardLights(state, prepareScene3DRender(state, scene, view, lights), lights);
+    const sink = createMemoryLogSink(8);
+    addLogSink(sink.sink);
+    try {
+      drawGlScene3D(state, scene, view, lights, selected);
+      expect(getMemoryLogSinkEntries(sink)).toHaveLength(0);
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+});

package/src/explainGlScene3DForwardLightSelection.test.ts

@@ -0,0 +1,32 @@
+import { createPointLight } from '@flighthq/lighting';
+import type { GlScene3DForwardLightList, Scene3DLightsLike } from '@flighthq/types';
+
+import { explainGlScene3DForwardLightSelection } from './explainGlScene3DForwardLightSelection';
+
+function lights(count: number): Scene3DLightsLike {
+  return {
+    ambient: null,
+    directional: null,
+    point: Array.from({ length: count }, () => createPointLight()),
+  };
+}
+
+describe('explainGlScene3DForwardLightSelection', () => {
+  it('reports a required selection when input truncation would occur', () => {
+    expect(explainGlScene3DForwardLightSelection(lights(5))).toEqual({
+      pointLightCount: 5,
+      reason: 'selection-required',
+      selectionPrepared: false,
+      spotLightCount: 0,
+    });
+  });
+
+  it('reports when a selection was prepared', () => {
+    const prepared: GlScene3DForwardLightList = { meshCount: 0, meshLightBlocks: [] };
+    expect(explainGlScene3DForwardLightSelection(lights(5), prepared).reason).toBe('selection-prepared');
+  });
+
+  it('reports when punctual inputs fit the fixed budget', () => {
+    expect(explainGlScene3DForwardLightSelection(lights(4)).reason).toBe('within-budget');
+  });
+});

package/src/glClassicPrelude.test.ts

@@ -0,0 +1,214 @@
+import type { GlClassicDefineKey } from '@flighthq/types';
+
+import {
+  buildGlClassicDefineKey,
+  compileGlClassicProgram,
+  ensureGlClassicProgram,
+  getGlClassicFragmentSource,
+  getGlClassicFragmentSourceForKey,
+  getGlClassicVertexSource,
+  getGlClassicVertexSourceForKey,
+} from './glClassicPrelude';
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeFakeGl2, makeGlScene3DState } from './glScene3DTestHelper';
+
+const LAMBERT: GlClassicDefineKey = {
+  alphaMaskEnabled: false,
+  hasAlphaMap: false,
+  hasDiffuseMap: false,
+  hasNormalMap: false,
+  hasSpecularMap: false,
+  hasUvTransform: false,
+  lightingModel: 'lambert',
+};
+const PHONG: GlClassicDefineKey = { ...LAMBERT, lightingModel: 'phong' };
+const BLINNPHONG: GlClassicDefineKey = { ...LAMBERT, lightingModel: 'blinnphong' };
+
+describe('buildGlClassicDefineKey', () => {
+  it('encodes the lighting model first, then the feature flags', () => {
+    expect(buildGlClassicDefineKey(LAMBERT)).toBe('l-------');
+    expect(buildGlClassicDefineKey(PHONG)).toBe('p-------');
+    expect(buildGlClassicDefineKey(BLINNPHONG)).toBe('b-------');
+    expect(
+      buildGlClassicDefineKey({
+        alphaMaskEnabled: true,
+        hasAlphaMap: true,
+        hasDiffuseMap: true,
+        hasNormalMap: true,
+        hasSpecularMap: true,
+        hasUvTransform: true,
+        lightingModel: 'phong',
+      }),
+    ).toBe('pmdsnau-');
+  });
+
+  it('encodes a non-identity uv transform in the u slot ahead of skin', () => {
+    expect(buildGlClassicDefineKey({ ...LAMBERT, hasUvTransform: true })).toBe('l-----u-');
+    expect(buildGlClassicDefineKey({ ...LAMBERT, hasUvTransform: true })).not.toBe(buildGlClassicDefineKey(LAMBERT));
+  });
+
+  it('sets the trailing skin flag so a skinned variant keys distinctly', () => {
+    expect(buildGlClassicDefineKey({ ...LAMBERT, hasSkin: true })).toBe('l------k');
+    expect(buildGlClassicDefineKey({ ...LAMBERT, hasSkin: true })).not.toBe(buildGlClassicDefineKey(LAMBERT));
+  });
+
+  it('produces distinct strings per lighting model so they never collide', () => {
+    const keys = new Set([
+      buildGlClassicDefineKey(LAMBERT),
+      buildGlClassicDefineKey(PHONG),
+      buildGlClassicDefineKey(BLINNPHONG),
+    ]);
+    expect(keys.size).toBe(3);
+  });
+});
+
+describe('compileGlClassicProgram', () => {
+  it('compiles, links, and resolves the classic + lit uniform locations', () => {
+    const gl = makeFakeGl2();
+    const program = compileGlClassicProgram(gl, PHONG);
+    expect(program.locDiffuse).not.toBeNull();
+    expect(program.locSpecular).not.toBeNull();
+    expect(program.locShininess).not.toBeNull();
+    expect(program.locNormalMap).not.toBeNull();
+    expect(program.locNormalScale).not.toBeNull();
+    expect(program.locAlphaCutoff).not.toBeNull();
+    // Spread from resolveGlLitLocations.
+    expect(program.locDirectional).not.toBeNull();
+    expect(program.locCameraPosition).not.toBeNull();
+    expect(gl.calls.some((c) => c.name === 'linkProgram')).toBe(true);
+  });
+});
+
+describe('ensureGlClassicProgram', () => {
+  it('caches a variant under the classic namespace and reuses it', () => {
+    const { state, gl } = makeGlScene3DState();
+    const first = ensureGlClassicProgram(state, LAMBERT);
+    const links = gl.calls.filter((c) => c.name === 'linkProgram').length;
+    const second = ensureGlClassicProgram(state, LAMBERT);
+    expect(second).toBe(first);
+    expect(gl.calls.filter((c) => c.name === 'linkProgram').length).toBe(links);
+    expect([...getGlScene3DRuntime(state).programCache.keys()].some((k) => k.startsWith('classic:'))).toBe(true);
+  });
+
+  it('caches a distinct entry per lighting model', () => {
+    const { state } = makeGlScene3DState();
+    const lambert = ensureGlClassicProgram(state, LAMBERT);
+    const phong = ensureGlClassicProgram(state, PHONG);
+    const blinnPhong = ensureGlClassicProgram(state, BLINNPHONG);
+    expect(lambert).not.toBe(phong);
+    expect(phong).not.toBe(blinnPhong);
+    expect(lambert).not.toBe(blinnPhong);
+    expect(getGlScene3DRuntime(state).programCache.size).toBe(3);
+  });
+
+  it('folds the render-state skinned-run flag into a distinct HAS_SKIN variant', () => {
+    const { state } = makeGlScene3DState();
+    const rigid = ensureGlClassicProgram(state, LAMBERT);
+    getGlScene3DRuntime(state).activeSkinnedRun = true;
+    const skinned = ensureGlClassicProgram(state, LAMBERT);
+
+    expect(skinned).not.toBe(rigid);
+    expect([...getGlScene3DRuntime(state).programCache.keys()]).toContain('classic:l------k');
+    expect(skinned.locJointTexture).not.toBeNull();
+  });
+});
+
+describe('getGlClassicFragmentSource', () => {
+  it('returns the fragment body without a version/define block', () => {
+    const source = getGlClassicFragmentSource();
+    expect(source).toContain('fragColor');
+    expect(source).not.toContain('#version 300 es');
+  });
+});
+
+describe('getGlClassicFragmentSourceForKey', () => {
+  it('includes the lighting-model and feature defines only when set', () => {
+    expect(getGlClassicFragmentSourceForKey(LAMBERT)).not.toContain('#define LIGHTING_PHONG');
+    expect(getGlClassicFragmentSourceForKey(LAMBERT)).not.toContain('#define LIGHTING_BLINNPHONG');
+    expect(getGlClassicFragmentSourceForKey(PHONG)).toContain('#define LIGHTING_PHONG');
+    expect(getGlClassicFragmentSourceForKey(BLINNPHONG)).toContain('#define LIGHTING_BLINNPHONG');
+    expect(getGlClassicFragmentSourceForKey({ ...PHONG, hasDiffuseMap: true })).toContain('#define HAS_DIFFUSE_MAP');
+    expect(getGlClassicFragmentSourceForKey({ ...PHONG, hasSpecularMap: true })).toContain('#define HAS_SPECULAR_MAP');
+    expect(getGlClassicFragmentSourceForKey({ ...PHONG, hasNormalMap: true })).toContain('#define HAS_NORMAL_MAP');
+    expect(getGlClassicFragmentSourceForKey({ ...PHONG, hasAlphaMap: true })).toContain('#define HAS_ALPHA_MAP');
+    expect(getGlClassicFragmentSourceForKey({ ...PHONG, alphaMaskEnabled: true })).toContain('#define ALPHA_MASK');
+  });
+
+  it('gates the alpha-map define off the key and always carries the guarded sampler + coverage multiply', () => {
+    // The define is what varies by key; the #ifdef-guarded sampler and multiply are unconditional raw
+    // text (same as the normal/specular maps), compiled out unless HAS_ALPHA_MAP is defined.
+    expect(getGlClassicFragmentSourceForKey(BLINNPHONG)).not.toContain('#define HAS_ALPHA_MAP');
+    const withAlpha = getGlClassicFragmentSourceForKey({ ...BLINNPHONG, hasAlphaMap: true });
+    expect(withAlpha).toContain('#define HAS_ALPHA_MAP');
+    expect(withAlpha).toContain('uniform sampler2D u_alphaMap;');
+    expect(withAlpha).toContain('diffuse.a *= texture(u_alphaMap, v_uv0).g;');
+  });
+
+  it('includes the standard light block uniforms', () => {
+    const source = getGlClassicFragmentSourceForKey(LAMBERT);
+    expect(source).toContain('u_directionalRadiance');
+    expect(source).toContain('u_ambientRadiance');
+    expect(source).toContain('u_cameraPosition');
+  });
+
+  it('shadow-maps the directional term (and only the directional term)', () => {
+    const source = getGlClassicFragmentSourceForKey(LAMBERT);
+    // The shared light block already declares the shadow uniforms + sampleDirectionalShadow; the classic
+    // path multiplies its directional contribution by that factor, matching the PBR family.
+    expect(source).toContain('sampleDirectionalShadow(v_worldPosition)');
+    // Exactly one call — point/spot/ambient stay unshadowed, so the helper appears once in main().
+    expect(source.match(/sampleDirectionalShadow\(v_worldPosition\)/g)).toHaveLength(1);
+  });
+
+  it('uses reflect() for Phong and the half vector for BlinnPhong', () => {
+    expect(getGlClassicFragmentSourceForKey(PHONG)).toContain('reflect(');
+    expect(getGlClassicFragmentSourceForKey(BLINNPHONG)).toContain('normalize(lightDir + viewDir)');
+  });
+
+  it('emits the MAX_FORWARD_LIGHTS spec constant and loops the punctual light arrays', () => {
+    const source = getGlClassicFragmentSourceForKey(LAMBERT);
+    expect(source).toContain('#define MAX_FORWARD_LIGHTS');
+    expect(source).toContain('u_pointLights');
+    expect(source).toContain('u_spotLights');
+    expect(source).toContain('u_hemisphereLights');
+    // Every light type routes through the one shared classic BRDF.
+    expect(source).toContain('shadeClassicLight');
+  });
+});
+
+describe('getGlClassicVertexSource', () => {
+  it('returns the vertex body without a version/define block', () => {
+    const source = getGlClassicVertexSource();
+    expect(source).toContain('a_position');
+    expect(source).not.toContain('#version 300 es');
+  });
+});
+
+describe('getGlClassicVertexSourceForKey', () => {
+  it('passes world position, normal, tangent, and uv varyings', () => {
+    const source = getGlClassicVertexSourceForKey(LAMBERT);
+    expect(source).toContain('v_worldPosition');
+    expect(source).toContain('v_normal');
+    expect(source).toContain('v_tangent');
+    expect(source).toContain('v_uv0');
+    expect(source).toContain('#version 300 es');
+  });
+
+  it('injects the skin declarations and HAS_SKIN define only for the skinned variant', () => {
+    // The #ifdef HAS_SKIN guard lives in the body unconditionally; only the #define and the injected
+    // attribute/uniform declarations are skin-specific.
+    const rigid = getGlClassicVertexSourceForKey(LAMBERT);
+    expect(rigid).not.toContain('#define HAS_SKIN');
+    expect(rigid).not.toContain('a_joints0');
+    expect(rigid).not.toContain('mat4 skinMatrix()');
+
+    const skinned = getGlClassicVertexSourceForKey({ ...LAMBERT, 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');
+    expect(skinned).toContain('a_weights0');
+  });
+});

package/src/glDebugPrelude.test.ts

@@ -0,0 +1,94 @@
+import type { GlDebugDefineKey } from '@flighthq/types';
+
+import {
+  bindGlDebugNormalMap,
+  bindGlDebugRange,
+  buildGlDebugDefineKey,
+  compileGlDebugProgram,
+  ensureGlDebugProgram,
+  getGlDebugFragmentSourceForKey,
+  getGlDebugVertexSourceForKey,
+} from './glDebugPrelude';
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeFakeGl2, makeGlScene3DState } from './glScene3DTestHelper';
+
+const DEPTH: GlDebugDefineKey = { hasNormalMap: false, mode: 'depth' };
+const NORMAL: GlDebugDefineKey = { hasNormalMap: false, mode: 'normal' };
+const NORMAL_MAP: GlDebugDefineKey = { hasNormalMap: true, mode: 'normal' };
+
+describe('bindGlDebugNormalMap', () => {
+  it('uploads the normal scale and binds no texture when no map is present', () => {
+    const { state, gl } = makeGlScene3DState();
+    const program = compileGlDebugProgram(gl, NORMAL);
+    bindGlDebugNormalMap(state, program, null, 2);
+    expect(gl.calls.some((c) => c.name === 'uniform1f')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'bindTexture')).toBe(false);
+  });
+});
+
+describe('bindGlDebugRange', () => {
+  it('uploads the near and far linearization range', () => {
+    const { state, gl } = makeGlScene3DState();
+    const program = compileGlDebugProgram(gl, DEPTH);
+    bindGlDebugRange(state, program, 0.1, 100);
+    expect(gl.calls.filter((c) => c.name === 'uniform1f').length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe('buildGlDebugDefineKey', () => {
+  it('produces distinct stable strings per mode and normal-map flag', () => {
+    expect(buildGlDebugDefineKey(DEPTH)).toBe('d-');
+    expect(buildGlDebugDefineKey(NORMAL)).toBe('n-');
+    expect(buildGlDebugDefineKey(NORMAL_MAP)).toBe('nm');
+  });
+});
+
+describe('compileGlDebugProgram', () => {
+  it('compiles, links, and resolves the debug uniforms including the normal matrix', () => {
+    const gl = makeFakeGl2();
+    const program = compileGlDebugProgram(gl, NORMAL);
+    expect(program.locNormalMatrix).not.toBeNull();
+    expect(program.locNormalScale).not.toBeNull();
+    expect(program.locViewProjection).not.toBeNull();
+    expect(gl.calls.some((c) => c.name === 'linkProgram')).toBe(true);
+  });
+});
+
+describe('ensureGlDebugProgram', () => {
+  it('caches variants under the debug namespace with distinct depth and normal entries', () => {
+    const { state, gl } = makeGlScene3DState();
+    const depthFirst = ensureGlDebugProgram(state, DEPTH);
+    const depthSecond = ensureGlDebugProgram(state, DEPTH);
+    expect(depthSecond).toBe(depthFirst);
+
+    const normalProgram = ensureGlDebugProgram(state, NORMAL);
+    expect(normalProgram).not.toBe(depthFirst);
+
+    const keys = [...getGlScene3DRuntime(state).programCache.keys()];
+    expect(keys.some((k) => k.startsWith('debug:'))).toBe(true);
+    expect(keys).toContain('debug:d-');
+    expect(keys).toContain('debug:n-');
+    // The two distinct variants compiled exactly once each.
+    expect(gl.calls.filter((c) => c.name === 'linkProgram').length).toBe(2);
+  });
+});
+
+describe('getGlDebugFragmentSourceForKey', () => {
+  it('gates the mode and normal-map branches by define', () => {
+    expect(getGlDebugFragmentSourceForKey(DEPTH)).toContain('#define DEPTH_MODE');
+    expect(getGlDebugFragmentSourceForKey(DEPTH)).not.toContain('#define NORMAL_MODE');
+    expect(getGlDebugFragmentSourceForKey(NORMAL)).toContain('#define NORMAL_MODE');
+    expect(getGlDebugFragmentSourceForKey(NORMAL)).not.toContain('#define HAS_NORMAL_MAP');
+    expect(getGlDebugFragmentSourceForKey(NORMAL_MAP)).toContain('#define HAS_NORMAL_MAP');
+  });
+});
+
+describe('getGlDebugVertexSourceForKey', () => {
+  it('carries the model, normal, and view-projection uniforms for both modes', () => {
+    const source = getGlDebugVertexSourceForKey(NORMAL);
+    expect(source).toContain('u_model');
+    expect(source).toContain('u_normalMatrix');
+    expect(source).toContain('u_viewProjection');
+    expect(getGlDebugVertexSourceForKey(DEPTH)).toContain('a_position');
+  });
+});

package/src/glEnvironmentCube.test.ts

@@ -0,0 +1,71 @@
+import type { CubeTexture, Environment, ImageResource } from '@flighthq/types';
+
+import { ensureGlEnvironmentSourceCube, getGlCubeFaceTarget, updateGlEnvironmentCubeFace } from './glEnvironmentCube';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+
+// The GPU upload + sampling is validated by the functional `env-skybox` capture (jsdom has no real
+// WebGL2 cubemap). These cover the CPU-side guards: the face-target arithmetic, the "no complete
+// cube" sentinel path that callers depend on to no-op, and the data-only face upload path.
+
+function dataFace(size: number): ImageResource {
+  return { source: null, data: new Uint8ClampedArray(size * size * 4), width: size, height: size } as ImageResource;
+}
+
+function dataOnlyEnvironment(size: number): Environment {
+  const face = dataFace(size);
+  const cube = {
+    colorSpace: 'srgb',
+    faces: [face, face, face, face, face, face],
+    sampler: {},
+  } as unknown as CubeTexture;
+  return { environment: cube, intensity: 1 } as Environment;
+}
+
+describe('ensureGlEnvironmentSourceCube', () => {
+  it('returns null when the environment has no source cube', () => {
+    const { state } = makeGlScene3DState();
+    const environment = { environment: null, intensity: 1 } as Environment;
+    expect(ensureGlEnvironmentSourceCube(state, environment)).toBe(null);
+  });
+
+  it('uploads a data-only cube through the raw-pixel texImage2D overload', () => {
+    const { state, gl } = makeGlScene3DState();
+    const environment = dataOnlyEnvironment(4);
+    const texture = ensureGlEnvironmentSourceCube(state, environment);
+    expect(texture).not.toBe(null);
+    const uploads = gl.calls.filter((c) => c.name === 'texImage2D');
+    expect(uploads.length).toBe(6);
+    // The raw-pixel overload passes width/height/border and the data buffer (9 args), not an element (6 args).
+    for (const upload of uploads) {
+      expect(upload.args.length).toBe(9);
+      expect(upload.args[3]).toBe(4);
+      expect(upload.args[4]).toBe(4);
+      expect(upload.args[8]).toBeInstanceOf(Uint8ClampedArray);
+    }
+  });
+});
+
+describe('getGlCubeFaceTarget', () => {
+  it('maps face index onto TEXTURE_CUBE_MAP_POSITIVE_X + face', () => {
+    const gl = { TEXTURE_CUBE_MAP_POSITIVE_X: 0x8515 } as WebGL2RenderingContext;
+    expect(getGlCubeFaceTarget(gl, 0)).toBe(0x8515);
+    expect(getGlCubeFaceTarget(gl, 5)).toBe(0x851a);
+  });
+});
+
+describe('updateGlEnvironmentCubeFace', () => {
+  it('returns false when no source cube has been built yet', () => {
+    const { state, gl } = makeGlScene3DState();
+    expect(updateGlEnvironmentCubeFace(state, 2, dataFace(4))).toBe(false);
+    expect(gl.calls.some((c) => c.name === 'texImage2D')).toBe(false);
+  });
+
+  it('restamps a single face of the built cube without rebuilding the other five', () => {
+    const { state, gl } = makeGlScene3DState();
+    ensureGlEnvironmentSourceCube(state, dataOnlyEnvironment(4));
+    const afterBuild = gl.calls.filter((c) => c.name === 'texImage2D').length;
+    expect(afterBuild).toBe(6);
+    expect(updateGlEnvironmentCubeFace(state, 2, dataFace(4))).toBe(true);
+    expect(gl.calls.filter((c) => c.name === 'texImage2D').length).toBe(afterBuild + 1);
+  });
+});

package/src/glEnvironmentIblBake.test.ts

@@ -0,0 +1,31 @@
+import type { Environment } from '@flighthq/types';
+
+import { bakeGlEnvironmentIbl, destroyGlEnvironmentIblBakePrograms } from './glEnvironmentIblBake';
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+
+// The GPU bake (irradiance / prefiltered specular / BRDF LUT) is validated by the functional `env-ibl`
+// capture — software jsdom has no float-cube render path. This covers the guard: with no source cube
+// the bake is a no-op and leaves runtime.ibl null, so the PBR ambient falls back to the flat term.
+
+describe('bakeGlEnvironmentIbl', () => {
+  it('is a no-op leaving runtime.ibl null when the environment has no source cube', () => {
+    const { state } = makeGlScene3DState();
+    const environment = { environment: null, intensity: 1 } as Environment;
+    bakeGlEnvironmentIbl(state, environment);
+    expect(getGlScene3DRuntime(state).ibl).toBe(null);
+  });
+});
+
+describe('destroyGlEnvironmentIblBakePrograms', () => {
+  // The bake shader programs are created only along the float-cube render path, which jsdom cannot
+  // drive (see the note above); their teardown is exercised end-to-end by the functional capture.
+  // Here we cover the guard: with no bake having run for the state, teardown is a safe, repeatable
+  // no-op that issues no GL deletes.
+  it('is a safe no-op when no bake ran for the state', () => {
+    const { state, gl } = makeGlScene3DState();
+    destroyGlEnvironmentIblBakePrograms(state);
+    destroyGlEnvironmentIblBakePrograms(state);
+    expect(gl.calls.some((c) => c.name.startsWith('delete'))).toBe(false);
+  });
+});

package/src/glEnvironmentSkybox.test.ts

@@ -0,0 +1,24 @@
+import { createCamera3D, createPerspectiveProjection } from '@flighthq/camera';
+import type { Environment } from '@flighthq/types';
+
+import { drawGlEnvironmentSkybox } from './glEnvironmentSkybox';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+
+// The skybox draw itself is validated by the functional `env-skybox` capture. This covers the guard:
+// with no complete source cube the pass is a no-op (it must not touch GL), so an app that always calls
+// it before drawGlScene3D pays nothing until an environment is bound.
+
+describe('drawGlEnvironmentSkybox', () => {
+  it('is a no-op when the environment has no source cube', () => {
+    const { state, gl } = makeGlScene3DState();
+    const environment = { environment: null, intensity: 1 } as Environment;
+    const camera = createCamera3D({
+      far: 100,
+      near: 0.1,
+      projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+    });
+    const before = gl.calls.length;
+    expect(() => drawGlEnvironmentSkybox(state, environment, camera, 1)).not.toThrow();
+    expect(gl.calls.length).toBe(before);
+  });
+});