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

package/src/drawGlScene3D.test.ts

@@ -0,0 +1,304 @@
+import { createCamera3D, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createVector3 } from '@flighthq/geometry';
+import { createAmbientLight, createDirectionalLight } from '@flighthq/lighting';
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild, invalidateNodeLocalTransform } from '@flighthq/node';
+import { createParticleEmitter3D, reserveParticleEmitter3D } from '@flighthq/particleemitter';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import { createMesh, createNode3D, Node3DKind } from '@flighthq/scene3d';
+import type { Camera3D, GlRenderTarget, Scene3DLightsLike } from '@flighthq/types';
+
+import { drawGlScene3D } from './drawGlScene3D';
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import { registerStandardPbrGlMaterial } from './registerStandardPbrGlMaterial';
+
+function makeCamera(): Camera3D {
+  const camera = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' },
+  });
+  setCamera3DViewMatrix4FromLookAt(camera, { x: 0, y: 0, z: 5 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+  return camera;
+}
+
+const LIGHTS: Scene3DLightsLike = {
+  ambient: createAmbientLight({ color: 0xffffffff, intensity: 0.2 }),
+  directional: createDirectionalLight({ color: 0xffffffff, direction: createVector3(0, -1, -1), intensity: 1 }),
+};
+
+describe('drawGlScene3D', () => {
+  it('binds once for a run of subsets sharing a material', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const material = createStandardPbrMaterial();
+    const meshA = createMesh(createBoxMeshGeometry(), [material]);
+    const meshB = createMesh(createBoxMeshGeometry(), [material]);
+    addNodeChild(scene, meshA);
+    addNodeChild(scene, meshB);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    // Same material across both meshes: bound once, drawn twice.
+    expect(gl.calls.filter((c) => c.name === 'useProgram').length).toBe(1);
+    expect(gl.calls.filter((c) => c.name === 'drawElements').length).toBe(2);
+  });
+
+  it('invalidates render-gl binding cache after drawing so the present pass re-binds', () => {
+    const { state } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]));
+
+    // Stand in for render-gl having a program bound and cached before the scene draws. The mesh
+    // renderers bind their own programs with raw gl.useProgram, which render-gl's cache never sees;
+    // without the post-draw invalidation the stale program would survive and the effect-pipeline
+    // present pass would set uniforms against a program that is no longer bound (INVALID_OPERATION).
+    const runtime = getGlRenderStateRuntime(state);
+    runtime.currentProgram = {} as WebGLProgram;
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(runtime.currentProgram).toBeNull();
+  });
+
+  it("declares the bound render target 'linear' (scene materials output linear HDR)", () => {
+    const { state } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]));
+
+    const runtime = getGlRenderStateRuntime(state);
+    const target = { colorSpace: 'srgb' } as GlRenderTarget;
+    runtime.currentRenderTarget = target;
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(target.colorSpace).toBe('linear');
+  });
+
+  it('does not draw a disabled mesh', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    mesh.enabled = false;
+    addNodeChild(scene, mesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(false);
+  });
+
+  it('draws each visible mesh subset with its registered material renderer', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    addNodeChild(scene, mesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(gl.calls.some((c) => c.name === 'useProgram')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(true);
+  });
+
+  it('enables GL blend for subsets with alphaMode blend and disables it after', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const blendedMaterial = createStandardPbrMaterial();
+    blendedMaterial.alphaMode = 'blend';
+    const mesh = createMesh(createBoxMeshGeometry(), [blendedMaterial]);
+    addNodeChild(scene, mesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    const enableCalls = gl.calls.filter((c) => c.name === 'enable');
+    const disableCalls = gl.calls.filter((c) => c.name === 'disable');
+    // BLEND = 0x0be2
+    expect(enableCalls.some((c) => c.args[0] === 0x0be2)).toBe(true);
+    expect(disableCalls.some((c) => c.args[0] === 0x0be2)).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'blendFunc')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(true);
+  });
+
+  it('draws opaque subsets before blended subsets regardless of scene order', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    // Add blended first, then opaque — opaque should still draw before blended.
+    const blendedMaterial = createStandardPbrMaterial();
+    blendedMaterial.alphaMode = 'blend';
+    const opaqueMaterial = createStandardPbrMaterial();
+
+    const blendedMesh = createMesh(createBoxMeshGeometry(), [blendedMaterial]);
+    const opaqueMesh = createMesh(createBoxMeshGeometry(), [opaqueMaterial]);
+    addNodeChild(scene, blendedMesh);
+    addNodeChild(scene, opaqueMesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    // Both meshes drawn.
+    expect(gl.calls.filter((c) => c.name === 'drawElements').length).toBe(2);
+    // GL blending was enabled and then disabled (blended pass ran).
+    expect(gl.calls.some((c) => c.name === 'enable' && c.args[0] === 0x0be2)).toBe(true);
+  });
+
+  it('does not enable GL blend when all subsets are opaque', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    addNodeChild(scene, mesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    // No blended subsets: GL_BLEND should not be enabled.
+    expect(gl.calls.some((c) => c.name === 'enable' && c.args[0] === 0x0be2)).toBe(false);
+  });
+
+  it('routes a mesh with node alpha below 1 through the blended pass even with an opaque material', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    // Opaque material, but the node is faded (alpha < 1). prepareScene3DRender (run inside drawGlScene3D)
+    // folds the authored alpha into worldAlpha, and drawGlScene3D must route the fading object through
+    // the blended pass so it composites correctly.
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    mesh.alpha = 0.5;
+    addNodeChild(scene, mesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(gl.calls.some((c) => c.name === 'enable' && c.args[0] === 0x0be2)).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(true);
+    // The resolved node opacity was uploaded to u_objectAlpha (a uniform1f of 0.5).
+    expect(gl.calls.some((c) => c.name === 'uniform1f' && c.args[1] === 0.5)).toBe(true);
+  });
+
+  it('reuses opaque and blended draw records across frames', () => {
+    const { state } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const opaque = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    const blendedMaterial = createStandardPbrMaterial();
+    blendedMaterial.alphaMode = 'blend';
+    const blended = createMesh(createBoxMeshGeometry(), [blendedMaterial]);
+    addNodeChild(scene, opaque);
+    addNodeChild(scene, blended);
+
+    const camera = makeCamera();
+    drawGlScene3D(state, scene, camera, LIGHTS);
+    const runtime = getGlScene3DRuntime(state);
+    const opaqueEntry = runtime.opaqueDrawList[0];
+    const blendedEntry = runtime.blendedDrawList[0];
+
+    drawGlScene3D(state, scene, camera, LIGHTS);
+
+    expect(runtime.opaqueDrawList[0]).toBe(opaqueEntry);
+    expect(runtime.blendedDrawList[0]).toBe(blendedEntry);
+    expect(runtime.opaquePool).toHaveLength(0);
+    expect(runtime.blendedPool).toHaveLength(0);
+  });
+
+  it('keeps a fully-opaque mesh (node alpha 1) in the opaque pass', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    mesh.alpha = 1;
+    addNodeChild(scene, mesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(gl.calls.some((c) => c.name === 'enable' && c.args[0] === 0x0be2)).toBe(false);
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(true);
+  });
+
+  it('skips a subset whose material has no registered renderer (no fallback)', () => {
+    const { state, gl } = makeGlScene3DState();
+    // No registerStandardPbrGlMaterial: nothing resolves.
+    const scene = createNode3D(Node3DKind);
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    addNodeChild(scene, mesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(false);
+  });
+
+  it('sorts blended subsets back-to-front by camera depth', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    const blendedMaterial = createStandardPbrMaterial();
+    blendedMaterial.alphaMode = 'blend';
+
+    // Place two meshes at different Z depths: far (z=-3) and near (z=-1). The far mesh should be
+    // drawn first (larger clip-W, farthest from camera) in the blended pass. Author the depth via the
+    // node's translation z — the translation column of the composed local matrix.
+    const farMesh = createMesh(createBoxMeshGeometry(), [blendedMaterial]);
+    const nearMesh = createMesh(createBoxMeshGeometry(), [blendedMaterial]);
+    farMesh.position.z = -3;
+    invalidateNodeLocalTransform(farMesh);
+    nearMesh.position.z = -1;
+    invalidateNodeLocalTransform(nearMesh);
+    addNodeChild(scene, nearMesh);
+    addNodeChild(scene, farMesh);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    // Both blended meshes are drawn.
+    expect(gl.calls.filter((c) => c.name === 'drawElements').length).toBe(2);
+  });
+
+  it('draws a ParticleEmitter3D node in the scene via the single drawGlScene3D call', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    // An emitter carries no geometry, so it never appears in the visible-mesh list; drawGlScene3D must
+    // run the emitter pass internally. The emitter's instanced pass is the only drawElementsInstanced
+    // caller, so its presence proves the emitter was drawn without a separate manual pass.
+    const emitter = createParticleEmitter3D();
+    reserveParticleEmitter3D(emitter, 2);
+    emitter.data.particleCount = 2;
+    for (let i = 0; i < 2; i++) {
+      emitter.data.transforms[i * 4 + 3] = 1;
+      emitter.data.alphas[i] = 1;
+      emitter.data.colors[i * 3] = 1;
+      emitter.data.colors[i * 3 + 1] = 1;
+      emitter.data.colors[i * 3 + 2] = 1;
+    }
+    addNodeChild(scene, emitter);
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(gl.calls.some((c) => c.name === 'drawElementsInstanced')).toBe(true);
+  });
+
+  it('does not draw an instanced particle pass when the scene has no emitters', () => {
+    const { state, gl } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]));
+
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+
+    expect(gl.calls.some((c) => c.name === 'drawElementsInstanced')).toBe(false);
+  });
+});

package/src/emissiveGlMeshMaterialRenderer.test.ts

@@ -0,0 +1,60 @@
+import { createCamera3D } from '@flighthq/camera';
+import { createMatrix3, createMatrix4 } from '@flighthq/geometry';
+import { createEmissiveMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import type { Camera3D, Scene3DLightBlock, Scene3DRenderProxy } from '@flighthq/types';
+import { EmissiveMaterialKind } from '@flighthq/types';
+
+import { emissiveGlMeshMaterialRenderer, registerEmissiveGlMaterial } from './emissiveGlMeshMaterialRenderer';
+import { getGlMeshMaterialRenderer } from './glMeshMaterialRegistry';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+
+function makeCamera(): Camera3D {
+  return createCamera3D({ far: 100, near: 0.1, projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' } });
+}
+
+const NO_LIGHTS: Scene3DLightBlock = {
+  ambientCount: 0,
+  data: new Float32Array(12),
+  directionalCount: 0,
+  hemisphereCount: 0,
+  pointCount: 0,
+  spotCount: 0,
+  version: 1,
+};
+
+function makeProxy(): Scene3DRenderProxy {
+  const geometry = createBoxMeshGeometry();
+  return {
+    material: createEmissiveMaterial(),
+    normalMatrix: createMatrix3(),
+    subset: geometry.subsets[0],
+    worldMatrix: createMatrix4(),
+  };
+}
+
+describe('emissiveGlMeshMaterialRenderer', () => {
+  it('bind uploads the emissive color scaled by emissiveStrength via the intensity uniform', () => {
+    const { state, gl } = makeGlScene3DState();
+    const material = createEmissiveMaterial({ emissiveStrength: 4 });
+    emissiveGlMeshMaterialRenderer.bind(state, material, NO_LIGHTS, makeCamera());
+    expect(gl.calls.some((c) => c.name === 'uniform4f')).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'uniform1f')).toBe(true);
+  });
+
+  it('draw issues an indexed draw over the subset after bind', () => {
+    const { state, gl } = makeGlScene3DState();
+    const proxy = makeProxy();
+    emissiveGlMeshMaterialRenderer.bind(state, proxy.material, NO_LIGHTS, makeCamera());
+    emissiveGlMeshMaterialRenderer.draw(state, proxy, createBoxMeshGeometry());
+    expect(gl.calls.some((c) => c.name === 'drawElements')).toBe(true);
+  });
+});
+
+describe('registerEmissiveGlMaterial', () => {
+  it('installs the renderer for EmissiveMaterialKind', () => {
+    const { state } = makeGlScene3DState();
+    registerEmissiveGlMaterial(state);
+    expect(getGlMeshMaterialRenderer(state, EmissiveMaterialKind)).toBe(emissiveGlMeshMaterialRenderer);
+  });
+});

package/src/enableGlScene3DColorSpaceGuards.test.ts

@@ -0,0 +1,63 @@
+import { createCamera3D, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createVector3 } from '@flighthq/geometry';
+import { createAmbientLight, createDirectionalLight } 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 { createMesh, createNode3D, Node3DKind } from '@flighthq/scene3d';
+import type { Camera3D, Scene3DLightsLike } from '@flighthq/types';
+
+import { drawGlScene3D } from './drawGlScene3D';
+import {
+  areGlScene3DColorSpaceGuardsEnabled,
+  enableGlScene3DColorSpaceGuards,
+} from './enableGlScene3DColorSpaceGuards';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import { registerStandardPbrGlMaterial } from './registerStandardPbrGlMaterial';
+
+function makeCamera(): Camera3D {
+  const camera = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' },
+  });
+  setCamera3DViewMatrix4FromLookAt(camera, { x: 0, y: 0, z: 5 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+  return camera;
+}
+
+const LIGHTS: Scene3DLightsLike = {
+  ambient: createAmbientLight({ color: 0xffffffff, intensity: 0.2 }),
+  directional: createDirectionalLight({ color: 0xffffffff, direction: createVector3(0, -1, -1), intensity: 1 }),
+};
+
+describe('areGlScene3DColorSpaceGuardsEnabled', () => {
+  it('reports false until guards are installed, then true', () => {
+    const { state } = makeGlScene3DState();
+    expect(areGlScene3DColorSpaceGuardsEnabled(state)).toBe(false);
+    enableGlScene3DColorSpaceGuards(state);
+    expect(areGlScene3DColorSpaceGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableGlScene3DColorSpaceGuards', () => {
+  it('warns once when a scene is drawn directly to the canvas (no target to encode)', () => {
+    const { state } = makeGlScene3DState();
+    registerStandardPbrGlMaterial(state);
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]));
+
+    const sink = createMemoryLogSink(8);
+    addLogSink(sink.sink);
+    try {
+      enableGlScene3DColorSpaceGuards(state);
+      // No beginGlRenderPass: currentRenderTarget is null, so the scene draws straight to the canvas.
+      drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+      const entries = getMemoryLogSinkEntries(sink);
+      expect(entries.length).toBe(1);
+      expect(String((entries[0].data as Record<string, unknown>).message)).toContain('drawGlScene3D');
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+});

package/src/enableGlScene3DCustomShaderGuards.test.ts

@@ -0,0 +1,85 @@
+import { createCamera3D } from '@flighthq/camera';
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log';
+import { createCustomShaderMaterial } from '@flighthq/materials';
+import type { Camera3D, Scene3DLightBlock } from '@flighthq/types';
+
+import {
+  customShaderGlMeshMaterialRenderer,
+  registerGlCustomMaterialShader,
+} from './customShaderGlMeshMaterialRenderer';
+import {
+  areGlScene3DCustomShaderGuardsEnabled,
+  enableGlScene3DCustomShaderGuards,
+} from './enableGlScene3DCustomShaderGuards';
+import { makeFakeGl2, makeGlScene3DState } from './glScene3DTestHelper';
+
+// GL uniform-type enums the mock and the guard compare against (WebGL2 spec values).
+const GL_FLOAT_MAT3 = 0x8b5b;
+const GL_FLOAT_MAT4 = 0x8b5c;
+
+function makeCamera(): Camera3D {
+  return createCamera3D({ far: 100, near: 0.1, projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' } });
+}
+
+const NO_LIGHTS: Scene3DLightBlock = {
+  ambientCount: 0,
+  data: new Float32Array(12),
+  directionalCount: 0,
+  hemisphereCount: 0,
+  pointCount: 0,
+  spotCount: 0,
+  version: 1,
+};
+
+const SOURCE = { fragment: 'frag', vertex: 'vert' };
+
+// Binds a custom-shader material under `shaderKey` with the guard installed, against a fake context whose
+// active uniforms are `activeUniforms`, and returns the messages the guard emitted.
+function bindWithGuard(shaderKey: string, activeUniforms: readonly { name: string; type: number }[]): string[] {
+  const { state } = makeGlScene3DState(makeFakeGl2({ activeUniforms }));
+  registerGlCustomMaterialShader(state, shaderKey, SOURCE);
+  enableGlScene3DCustomShaderGuards(state);
+
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    customShaderGlMeshMaterialRenderer.bind(state, createCustomShaderMaterial({ shaderKey }), NO_LIGHTS, makeCamera());
+    customShaderGlMeshMaterialRenderer.bind(state, createCustomShaderMaterial({ shaderKey }), NO_LIGHTS, makeCamera());
+    return getMemoryLogSinkEntries(sink).map((e) => String((e.data as Record<string, unknown>).message));
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+describe('areGlScene3DCustomShaderGuardsEnabled', () => {
+  it('reports false until guards are installed, then true', () => {
+    const { state } = makeGlScene3DState();
+    expect(areGlScene3DCustomShaderGuardsEnabled(state)).toBe(false);
+    enableGlScene3DCustomShaderGuards(state);
+    expect(areGlScene3DCustomShaderGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableGlScene3DCustomShaderGuards', () => {
+  it('warns once, naming the fix, when u_normalMatrix is declared mat4 instead of mat3', () => {
+    const messages = bindWithGuard('badNormalMatrix', [{ name: 'u_normalMatrix', type: GL_FLOAT_MAT4 }]);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]).toContain('u_normalMatrix');
+    expect(messages[0]).toContain('declares u_normalMatrix as mat4');
+    expect(messages[0]).toContain("Declare 'mat3 u_normalMatrix'");
+  });
+
+  it('stays silent when the built-in uniforms are declared with the expected types', () => {
+    const messages = bindWithGuard('okNormalMatrix', [
+      { name: 'u_normalMatrix', type: GL_FLOAT_MAT3 },
+      { name: 'u_model', type: GL_FLOAT_MAT4 },
+      { name: 'u_viewProjection', type: GL_FLOAT_MAT4 },
+    ]);
+    expect(messages).toHaveLength(0);
+  });
+
+  it('ignores non-built-in uniforms so a custom mat4 uniform is not flagged', () => {
+    const messages = bindWithGuard('customUniform', [{ name: 'u_userTransform', type: GL_FLOAT_MAT4 }]);
+    expect(messages).toHaveLength(0);
+  });
+});

package/src/enableGlScene3DDeformGuards.test.ts

@@ -0,0 +1,98 @@
+import { createCamera3D, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createVector3 } from '@flighthq/geometry';
+import { createAmbientLight, createDirectionalLight } from '@flighthq/lighting';
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log';
+import { CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT, createMeshGeometry, createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import { createMesh, createNode3D, prepareScene3DMorph, Node3DKind } from '@flighthq/scene3d';
+import { createSkeleton3D, prepareScene3DSkinning } from '@flighthq/skeleton3d';
+import type { Camera3D, MeshMorph, Scene3DLightsLike } from '@flighthq/types';
+
+import { drawGlScene3D } from './drawGlScene3D';
+import { areGlScene3DDeformGuardsEnabled, enableGlScene3DDeformGuards } from './enableGlScene3DDeformGuards';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+
+function makeCamera(): Camera3D {
+  const camera = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' },
+  });
+  setCamera3DViewMatrix4FromLookAt(camera, { x: 0, y: 0, z: 5 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+  return camera;
+}
+
+const LIGHTS: Scene3DLightsLike = {
+  ambient: createAmbientLight({ color: 0xffffffff, intensity: 0.2 }),
+  directional: createDirectionalLight({ color: 0xffffffff, direction: createVector3(0, -1, -1), intensity: 1 }),
+};
+
+function morphMesh() {
+  // A box geometry carrying a morph; drawn with no material so the guard (top of the mesh loop) runs
+  // without exercising the material draw path.
+  const mesh = createMesh(createBoxMeshGeometry(), []);
+  const morph: MeshMorph = {
+    targets: [{ normalDeltas: null, positionDeltas: new Float32Array(72), tangentDeltas: null }],
+    weights: new Float32Array([1]),
+  };
+  mesh.morph = morph;
+  return mesh;
+}
+
+function skinnedMesh() {
+  const geometry = createMeshGeometry({
+    layout: CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT,
+    vertices: new Float32Array(20),
+  });
+  const mesh = createMesh(geometry, []);
+  mesh.skin = { skeleton: createSkeleton3D([createNode3D()]) };
+  return mesh;
+}
+
+function drawWithGuard(scene: ReturnType<typeof createNode3D>): number {
+  const { state } = makeGlScene3DState();
+  enableGlScene3DDeformGuards(state);
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    drawGlScene3D(state, scene, makeCamera(), LIGHTS);
+    return getMemoryLogSinkEntries(sink).length;
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+describe('areGlScene3DDeformGuardsEnabled', () => {
+  it('reports false until guards are installed, then true', () => {
+    const { state } = makeGlScene3DState();
+    expect(areGlScene3DDeformGuardsEnabled(state)).toBe(false);
+    enableGlScene3DDeformGuards(state);
+    expect(areGlScene3DDeformGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableGlScene3DDeformGuards', () => {
+  // Runs FIRST, before the fire cases below consume the logOnce keys: a prepared mesh must not reach the
+  // warn branch at all, so this proves silence with fresh keys rather than relying on dedup to hide a bug.
+  it('stays silent once the deform passes have run', () => {
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, morphMesh());
+    addNodeChild(scene, skinnedMesh());
+    // Ready both deformers, exactly as an app would before prepareScene3DRender.
+    prepareScene3DMorph(scene);
+    prepareScene3DSkinning(scene);
+    expect(drawWithGuard(scene)).toBe(0);
+  });
+
+  it('warns when a morphed mesh is drawn without prepareScene3DMorph', () => {
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, morphMesh());
+    expect(drawWithGuard(scene)).toBe(1);
+  });
+
+  it('warns when a GPU-skinned mesh is drawn without prepareScene3DSkinning', () => {
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, skinnedMesh());
+    expect(drawWithGuard(scene)).toBe(1);
+  });
+});