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

package/src/glShadedBuiltInModifiers.test.ts

@@ -0,0 +1,377 @@
+import {
+  createAnimatedNormalModifier,
+  createDissolveModifier,
+  createEmissiveModifier,
+  createEnvReflectModifier,
+  createFogModifier,
+  createRimModifier,
+  createToonModifier,
+  createVertexDisplaceModifier,
+} from '@flighthq/shading';
+import type { Texture, GlModifierBindContext } from '@flighthq/types';
+import {
+  AnimatedNormalModifierKind,
+  DissolveModifierKind,
+  EmissiveModifierFacing,
+  EmissiveModifierKind,
+  EnvReflectModifierKind,
+  FogModifierKind,
+  FogModifierMode,
+  RimModifierKind,
+  ToonModifierKind,
+  VertexDisplaceModifierKind,
+  VertexDisplaceModifierSource,
+} from '@flighthq/types';
+
+import type { FakeGl2 } from './glScene3DTestHelper';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import {
+  animatedNormalGlModifierSnippet,
+  dissolveGlModifierSnippet,
+  emissiveGlModifierSnippet,
+  envReflectGlModifierSnippet,
+  fogGlModifierSnippet,
+  registerBuiltInGlModifierSnippets,
+  rimGlModifierSnippet,
+  toonGlModifierSnippet,
+  vertexDisplaceGlModifierSnippet,
+} from './glShadedBuiltInModifiers';
+import { resolveGlModifierSnippet } from './glShadedModifierSnippet';
+
+// A Texture whose image is unloaded — the snippet binds the sampler unit without an upload.
+const UNLOADED_TEXTURE = { image: null } as unknown as Texture;
+
+function makeContext(state: ReturnType<typeof makeGlScene3DState>['state'], index = 0): GlModifierBindContext {
+  let unit = 3;
+  return {
+    acquireModifierTextureUnit: () => unit++,
+    index,
+    program: {} as WebGLProgram,
+    state,
+  };
+}
+
+function countCalls(gl: FakeGl2, name: string): number {
+  return gl.calls.filter((c) => c.name === name).length;
+}
+
+describe('animatedNormalGlModifierSnippet', () => {
+  it('reports the disabled/single/dual define signature from map structure', () => {
+    const disabled = createAnimatedNormalModifier({ map: null, scroll: { x: 0, y: 0 } });
+    const single = createAnimatedNormalModifier({ map: UNLOADED_TEXTURE, scroll: { x: 0.1, y: 0 } });
+    const dual = createAnimatedNormalModifier({
+      map: UNLOADED_TEXTURE,
+      scroll: { x: 0.1, y: 0 },
+      secondaryMap: UNLOADED_TEXTURE,
+      secondaryScroll: { x: -0.05, y: 0 },
+    });
+    expect(animatedNormalGlModifierSnippet.getDefineSignature?.(disabled)).toBe('0');
+    expect(animatedNormalGlModifierSnippet.getDefineSignature?.(single)).toBe('1');
+    expect(animatedNormalGlModifierSnippet.getDefineSignature?.(dual)).toBe('2');
+  });
+
+  it('emits u_time-scrolled sampling into the normal for a mapped modifier', () => {
+    const modifier = createAnimatedNormalModifier({ map: UNLOADED_TEXTURE, scroll: { x: 0.1, y: 0 } });
+    const contribution = animatedNormalGlModifierSnippet.contribution(modifier, 0);
+    expect(contribution).toContain('u_animNormalScroll_0 * u_time');
+    expect(contribution).toContain('normal = normalize(tbn * animNormal);');
+  });
+
+  it('emits nothing for a disabled (null-map) modifier', () => {
+    const modifier = createAnimatedNormalModifier({ map: null, scroll: { x: 0, y: 0 } });
+    expect(animatedNormalGlModifierSnippet.declarations?.(modifier, 0)).toBe('');
+    expect(animatedNormalGlModifierSnippet.contribution(modifier, 0)).toBe('');
+  });
+
+  it('bind uploads scroll + strength and binds the sampler unit', () => {
+    const { state, gl } = makeGlScene3DState();
+    const modifier = createAnimatedNormalModifier({ map: UNLOADED_TEXTURE, scroll: { x: 0.2, y: 0.3 }, strength: 2 });
+    animatedNormalGlModifierSnippet.bind?.(modifier, makeContext(state));
+    expect(countCalls(gl, 'uniform2f')).toBe(1);
+    expect(countCalls(gl, 'uniform1f')).toBe(1);
+    expect(countCalls(gl, 'uniform1i')).toBe(1);
+  });
+
+  it('bind is a no-op for a disabled modifier', () => {
+    const { state, gl } = makeGlScene3DState();
+    const modifier = createAnimatedNormalModifier({ map: null, scroll: { x: 0, y: 0 } });
+    animatedNormalGlModifierSnippet.bind?.(modifier, makeContext(state));
+    expect(countCalls(gl, 'uniform2f')).toBe(0);
+    expect(countCalls(gl, 'uniform1i')).toBe(0);
+  });
+
+  it('drops the sampler (no bind) when the texture-unit allocator is exhausted', () => {
+    const { state, gl } = makeGlScene3DState();
+    const modifier = createAnimatedNormalModifier({ map: UNLOADED_TEXTURE, scroll: { x: 0.2, y: 0.3 } });
+    const exhausted: GlModifierBindContext = {
+      acquireModifierTextureUnit: () => -1,
+      index: 0,
+      program: {} as WebGLProgram,
+      state,
+    };
+    animatedNormalGlModifierSnippet.bind?.(modifier, exhausted);
+    expect(countCalls(gl, 'uniform1i')).toBe(0);
+    expect(countCalls(gl, 'activeTexture')).toBe(0);
+  });
+});
+
+describe('dissolveGlModifierSnippet', () => {
+  it('reports the procedural/mapped define signature structurally', () => {
+    expect(dissolveGlModifierSnippet.getDefineSignature?.(createDissolveModifier({ threshold: 0.5 }))).toBe('');
+    expect(
+      dissolveGlModifierSnippet.getDefineSignature?.(createDissolveModifier({ threshold: 0.5, map: UNLOADED_TEXTURE })),
+    ).toBe('m');
+  });
+
+  it('discards below threshold and tints the burn edge into the radiance', () => {
+    const contribution = dissolveGlModifierSnippet.contribution(createDissolveModifier({ threshold: 0.4 }), 0);
+    expect(contribution).toContain('discard;');
+    expect(contribution).toContain('radiance = mix(radiance, u_dissolveEdgeColor_0, dissolveEdge);');
+    expect(contribution).toContain('shadedValueNoise');
+  });
+
+  it('samples the noise map instead of procedural noise when a map is set', () => {
+    const contribution = dissolveGlModifierSnippet.contribution(
+      createDissolveModifier({ threshold: 0.4, map: UNLOADED_TEXTURE }),
+      1,
+    );
+    expect(contribution).toContain('texture(u_dissolveMap_1, v_uv0).r');
+    expect(contribution).not.toContain('shadedValueNoise');
+  });
+
+  it('bind uploads threshold/edge and the noise scale for the procedural variant', () => {
+    const { state, gl } = makeGlScene3DState();
+    dissolveGlModifierSnippet.bind?.(createDissolveModifier({ threshold: 0.5 }), makeContext(state));
+    // threshold + edgeWidth + scale.
+    expect(countCalls(gl, 'uniform1f')).toBe(3);
+    expect(countCalls(gl, 'uniform3f')).toBe(1);
+  });
+});
+
+describe('emissiveGlModifierSnippet', () => {
+  it('reports the mask/gate define signature structurally', () => {
+    expect(emissiveGlModifierSnippet.getDefineSignature?.(createEmissiveModifier({ color: 0xffffffff }))).toBe('');
+    expect(
+      emissiveGlModifierSnippet.getDefineSignature?.(
+        createEmissiveModifier({ color: 0xffffffff, facing: EmissiveModifierFacing.AwayFromLight }),
+      ),
+    ).toBe('g');
+    expect(
+      emissiveGlModifierSnippet.getDefineSignature?.(
+        createEmissiveModifier({
+          color: 0xffffffff,
+          facing: EmissiveModifierFacing.AwayFromLight,
+          mask: UNLOADED_TEXTURE,
+        }),
+      ),
+    ).toBe('mg');
+  });
+
+  it('gates the contribution by facing only when gated', () => {
+    const plain = emissiveGlModifierSnippet.contribution(createEmissiveModifier({ color: 0xffffffff }), 0);
+    expect(plain).not.toContain('u_emissiveFacingSign_0');
+    const gated = emissiveGlModifierSnippet.contribution(
+      createEmissiveModifier({ color: 0xffffffff, facing: EmissiveModifierFacing.AwayFromLight }),
+      0,
+    );
+    expect(gated).toContain('u_emissiveFacingSign_0');
+    expect(gated).toContain('emissive += emissiveTerm;');
+  });
+
+  it('bind uploads color + strength, plus the facing sign when gated', () => {
+    const { state, gl } = makeGlScene3DState();
+    emissiveGlModifierSnippet.bind?.(createEmissiveModifier({ color: 0xffcc88ff }), makeContext(state));
+    expect(countCalls(gl, 'uniform3f')).toBe(1);
+    const plainFloats = countCalls(gl, 'uniform1f');
+    expect(plainFloats).toBe(1);
+
+    const gated = makeGlScene3DState();
+    emissiveGlModifierSnippet.bind?.(
+      createEmissiveModifier({ color: 0xffcc88ff, facing: EmissiveModifierFacing.AwayFromLight, facingSoftness: 0.1 }),
+      makeContext(gated.state),
+    );
+    // strength + facing sign + facing softness.
+    expect(countCalls(gated.gl, 'uniform1f')).toBe(3);
+  });
+});
+
+describe('envReflectGlModifierSnippet', () => {
+  it('has no define signature (single program shape)', () => {
+    expect(envReflectGlModifierSnippet.getDefineSignature).toBeUndefined();
+  });
+
+  it('reflects the view vector and samples the shared prefiltered environment cube', () => {
+    const contribution = envReflectGlModifierSnippet.contribution(createEnvReflectModifier(), 0);
+    expect(contribution).toContain('reflect(-viewDir, normal)');
+    expect(contribution).toContain('textureLod(u_iblPrefiltered, envReflectDir');
+    expect(contribution).toContain('radiance +=');
+  });
+
+  it('declares the shared IBL environment samplers so two instances can be deduped', () => {
+    const declarations = envReflectGlModifierSnippet.declarations?.(createEnvReflectModifier(), 0) ?? '';
+    expect(declarations).toContain('uniform samplerCube u_iblPrefiltered;');
+    expect(declarations).toContain('uniform float u_iblEnabled;');
+  });
+
+  it('bind uploads the tint and the three reflection scalars', () => {
+    const { state, gl } = makeGlScene3DState();
+    envReflectGlModifierSnippet.bind?.(createEnvReflectModifier(), makeContext(state));
+    expect(countCalls(gl, 'uniform3f')).toBe(1);
+    // intensity + fresnel + roughness.
+    expect(countCalls(gl, 'uniform1f')).toBe(3);
+  });
+});
+
+describe('fogGlModifierSnippet', () => {
+  it('reports the mode define signature structurally', () => {
+    expect(fogGlModifierSnippet.getDefineSignature?.(createFogModifier({ color: 0xffffffff }))).toBe('l');
+    expect(
+      fogGlModifierSnippet.getDefineSignature?.(
+        createFogModifier({ color: 0xffffffff, mode: FogModifierMode.Exponential }),
+      ),
+    ).toBe('e');
+    expect(
+      fogGlModifierSnippet.getDefineSignature?.(
+        createFogModifier({ color: 0xffffffff, mode: FogModifierMode.Exponential2 }),
+      ),
+    ).toBe('x');
+  });
+
+  it('emits a near/far ramp for linear and an exp falloff for exponential', () => {
+    const linear = fogGlModifierSnippet.contribution(createFogModifier({ color: 0xffffffff }), 0);
+    expect(linear).toContain('u_fogNear_0');
+    expect(linear).toContain('length(u_cameraPosition - v_worldPosition)');
+    const exp = fogGlModifierSnippet.contribution(
+      createFogModifier({ color: 0xffffffff, mode: FogModifierMode.Exponential }),
+      0,
+    );
+    expect(exp).toContain('exp(-u_fogDensity_0 * fogDist)');
+  });
+
+  it('bind uploads the color and near/far for linear, density for exponential', () => {
+    const linear = makeGlScene3DState();
+    fogGlModifierSnippet.bind?.(createFogModifier({ color: 0xaabbccff }), makeContext(linear.state));
+    expect(countCalls(linear.gl, 'uniform3f')).toBe(1);
+    expect(countCalls(linear.gl, 'uniform1f')).toBe(2);
+
+    const exp = makeGlScene3DState();
+    fogGlModifierSnippet.bind?.(
+      createFogModifier({ color: 0xaabbccff, mode: FogModifierMode.Exponential2, density: 0.02 }),
+      makeContext(exp.state),
+    );
+    expect(countCalls(exp.gl, 'uniform1f')).toBe(1);
+  });
+});
+
+describe('registerBuiltInGlModifierSnippets', () => {
+  it('registers all eight built-in snippets on the state', () => {
+    const { state } = makeGlScene3DState();
+    registerBuiltInGlModifierSnippets(state);
+    expect(resolveGlModifierSnippet(state, AnimatedNormalModifierKind)).toBe(animatedNormalGlModifierSnippet);
+    expect(resolveGlModifierSnippet(state, EmissiveModifierKind)).toBe(emissiveGlModifierSnippet);
+    expect(resolveGlModifierSnippet(state, RimModifierKind)).toBe(rimGlModifierSnippet);
+    expect(resolveGlModifierSnippet(state, EnvReflectModifierKind)).toBe(envReflectGlModifierSnippet);
+    expect(resolveGlModifierSnippet(state, FogModifierKind)).toBe(fogGlModifierSnippet);
+    expect(resolveGlModifierSnippet(state, DissolveModifierKind)).toBe(dissolveGlModifierSnippet);
+    expect(resolveGlModifierSnippet(state, ToonModifierKind)).toBe(toonGlModifierSnippet);
+    expect(resolveGlModifierSnippet(state, VertexDisplaceModifierKind)).toBe(vertexDisplaceGlModifierSnippet);
+  });
+});
+
+describe('rimGlModifierSnippet', () => {
+  it('has no define signature (single program shape)', () => {
+    expect(rimGlModifierSnippet.getDefineSignature).toBeUndefined();
+  });
+
+  it('adds a view-dependent Fresnel term to the radiance', () => {
+    const contribution = rimGlModifierSnippet.contribution(createRimModifier({ color: 0x88ccffff }), 0);
+    expect(contribution).toContain('dot(normal, viewDir)');
+    expect(contribution).toContain('radiance += u_rimColor_0 * rim;');
+  });
+
+  it('bind uploads the rim color and power/intensity/bias uniforms', () => {
+    const { state, gl } = makeGlScene3DState();
+    rimGlModifierSnippet.bind?.(createRimModifier({ color: 0x88ccffff }), makeContext(state));
+    expect(countCalls(gl, 'uniform3f')).toBe(1);
+    expect(countCalls(gl, 'uniform1f')).toBe(3);
+  });
+});
+
+describe('toonGlModifierSnippet', () => {
+  it('has no define signature (single program shape)', () => {
+    expect(toonGlModifierSnippet.getDefineSignature).toBeUndefined();
+  });
+
+  it('quantizes the radiance luminance into cel bands', () => {
+    const contribution = toonGlModifierSnippet.contribution(createToonModifier({ steps: 3 }), 0);
+    expect(contribution).toContain('u_toonSteps_0');
+    expect(contribution).toContain('radiance *=');
+  });
+
+  it('bind uploads steps (floored at 2) and smoothness', () => {
+    const { state, gl } = makeGlScene3DState();
+    toonGlModifierSnippet.bind?.(createToonModifier({ steps: 1 }), makeContext(state));
+    expect(countCalls(gl, 'uniform1f')).toBe(2);
+    const stepsCall = gl.calls.find((c) => c.name === 'uniform1f');
+    expect(stepsCall?.args[1]).toBe(2);
+  });
+});
+
+describe('vertexDisplaceGlModifierSnippet', () => {
+  it('reports the source and fixed-axis define signature structurally', () => {
+    expect(
+      vertexDisplaceGlModifierSnippet.getDefineSignature?.(
+        createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.Sine, amplitude: 1 }),
+      ),
+    ).toBe('s');
+    expect(
+      vertexDisplaceGlModifierSnippet.getDefineSignature?.(
+        createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.HeightMap, amplitude: 1 }),
+      ),
+    ).toBe('h');
+    expect(
+      vertexDisplaceGlModifierSnippet.getDefineSignature?.(
+        createVertexDisplaceModifier({
+          source: VertexDisplaceModifierSource.Sine,
+          amplitude: 1,
+          axis: { x: 0, y: 1, z: 0 },
+        }),
+      ),
+    ).toBe('sa');
+  });
+
+  it('displaces localPosition along the normal with a u_time-scrolled sine wave', () => {
+    const contribution = vertexDisplaceGlModifierSnippet.contribution(
+      createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.Sine, amplitude: 0.2 }),
+      0,
+    );
+    expect(contribution).toContain('normalize(localNormal)');
+    expect(contribution).toContain('u_time * u_vDisplaceSpeed_0');
+    expect(contribution).toContain('localPosition.xyz += vDisplaceAxis * vDisplaceAmount;');
+  });
+
+  it('reads the height map and a fixed axis when configured', () => {
+    const contribution = vertexDisplaceGlModifierSnippet.contribution(
+      createVertexDisplaceModifier({
+        source: VertexDisplaceModifierSource.HeightMap,
+        amplitude: 1,
+        axis: { x: 0, y: 1, z: 0 },
+      }),
+      2,
+    );
+    expect(contribution).toContain('texture(u_vDisplaceMap_2, vertexUv).r');
+    expect(contribution).toContain('normalize(u_vDisplaceAxis_2)');
+  });
+
+  it('bind uploads amplitude plus the sine wave params for the procedural source', () => {
+    const { state, gl } = makeGlScene3DState();
+    vertexDisplaceGlModifierSnippet.bind?.(
+      createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.Sine, amplitude: 0.3 }),
+      makeContext(state),
+    );
+    // amplitude + frequency + speed.
+    expect(countCalls(gl, 'uniform1f')).toBe(3);
+    // direction.
+    expect(countCalls(gl, 'uniform3f')).toBe(1);
+  });
+});

package/src/glShadedModifierSnippet.test.ts

@@ -0,0 +1,46 @@
+import { ModifierSlot } from '@flighthq/types';
+import type { GlModifierSnippet } from '@flighthq/types';
+
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+import { registerGlModifierSnippet, resolveGlModifierSnippet } from './glShadedModifierSnippet';
+
+function makeSnippet(overrides?: Partial<GlModifierSnippet>): GlModifierSnippet {
+  return {
+    kind: 'acme.Test',
+    slot: ModifierSlot.Effect,
+    contribution: () => '// noop',
+    ...overrides,
+  };
+}
+
+describe('registerGlModifierSnippet', () => {
+  it('leaves the modifier registry unallocated until the first registration', () => {
+    const { state } = makeGlScene3DState();
+    expect(getGlScene3DRuntime(state).modifierSnippetRegistry).toBeNull();
+    registerGlModifierSnippet(state, makeSnippet());
+    expect(getGlScene3DRuntime(state).modifierSnippetRegistry).not.toBeNull();
+  });
+
+  it('stores a snippet resolvable by its kind', () => {
+    const { state } = makeGlScene3DState();
+    const snippet = makeSnippet();
+    registerGlModifierSnippet(state, snippet);
+    expect(resolveGlModifierSnippet(state, 'acme.Test')).toBe(snippet);
+  });
+
+  it('is last-write-wins for the same kind', () => {
+    const { state } = makeGlScene3DState();
+    registerGlModifierSnippet(state, makeSnippet());
+    const override = makeSnippet({ contribution: () => '// override' });
+    registerGlModifierSnippet(state, override);
+    expect(resolveGlModifierSnippet(state, 'acme.Test')).toBe(override);
+  });
+});
+
+describe('resolveGlModifierSnippet', () => {
+  it('returns null for an unregistered kind', () => {
+    const { state } = makeGlScene3DState();
+    expect(resolveGlModifierSnippet(state, 'acme.Missing')).toBeNull();
+  });
+});

package/src/glShadedPrelude.test.ts

@@ -0,0 +1,177 @@
+import {
+  createEmissiveModifier,
+  createEnvReflectModifier,
+  createModifierRegistry,
+  createVertexDisplaceModifier,
+  registerModifier,
+} from '@flighthq/shading';
+import type { Modifier, GlShadedDefineKey } from '@flighthq/types';
+import { VertexDisplaceModifierSource } from '@flighthq/types';
+
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeFakeGl2, makeGlScene3DState } from './glScene3DTestHelper';
+import { emissiveGlModifierSnippet, envReflectGlModifierSnippet } from './glShadedBuiltInModifiers';
+import { registerBuiltInGlModifierSnippets, vertexDisplaceGlModifierSnippet } from './glShadedBuiltInModifiers';
+import { buildGlShadedCacheKey, compileGlShadedProgram, ensureGlShadedProgram } from './glShadedPrelude';
+
+const BASE_KEY: GlShadedDefineKey = {
+  alphaMaskEnabled: false,
+  hasDiffuseMap: false,
+  hasNormalMap: false,
+  hasSpecularMap: false,
+  hasUvTransform: false,
+};
+
+function fragmentSourceFrom(calls: { name: string; args: unknown[] }[]): string {
+  const source = calls.find((c) => c.name === 'shaderSource' && String(c.args[1]).includes('fragColor'));
+  return String(source?.args[1] ?? '');
+}
+
+function vertexSourceFrom(calls: { name: string; args: unknown[] }[]): string {
+  const source = calls.find(
+    (c) =>
+      c.name === 'shaderSource' && String(c.args[1]).includes('a_position') && !String(c.args[1]).includes('fragColor'),
+  );
+  return String(source?.args[1] ?? '');
+}
+
+describe('buildGlShadedCacheKey', () => {
+  it('namespaces under shaded: and joins base flags with the modifier define-key', () => {
+    expect(buildGlShadedCacheKey(BASE_KEY, '')).toBe('shaded:------|');
+    expect(buildGlShadedCacheKey({ ...BASE_KEY, hasDiffuseMap: true }, 'EmissiveModifier:m')).toBe(
+      'shaded:-d----|EmissiveModifier:m',
+    );
+  });
+
+  it('encodes a non-identity uv transform in the u slot ahead of skin', () => {
+    expect(buildGlShadedCacheKey({ ...BASE_KEY, hasUvTransform: true }, '')).toBe('shaded:----u-|');
+    expect(buildGlShadedCacheKey({ ...BASE_KEY, hasUvTransform: true }, '')).not.toBe(
+      buildGlShadedCacheKey(BASE_KEY, ''),
+    );
+  });
+
+  it('sets the trailing skin flag so a skinned variant keys distinctly from the rigid one', () => {
+    expect(buildGlShadedCacheKey({ ...BASE_KEY, hasSkin: true }, '')).toBe('shaded:-----k|');
+    expect(buildGlShadedCacheKey({ ...BASE_KEY, hasSkin: true }, '')).not.toBe(buildGlShadedCacheKey(BASE_KEY, ''));
+  });
+});
+
+describe('compileGlShadedProgram', () => {
+  it('assembles the lean base shader with no modifier GLSL for an empty stack', () => {
+    const gl = makeFakeGl2();
+    compileGlShadedProgram(gl, BASE_KEY, [], createModifierRegistry());
+    const fragment = fragmentSourceFrom(gl.calls);
+    expect(fragment).toContain('void main()');
+    expect(fragment).toContain('fragColor');
+    expect(fragment).not.toContain('u_emissiveColor');
+  });
+
+  it('injects a registered modifier snippet at its slot hook', () => {
+    const gl = makeFakeGl2();
+    const registry = createModifierRegistry();
+    registerModifier(registry, emissiveGlModifierSnippet);
+    const modifiers: readonly Modifier[] = [createEmissiveModifier({ color: 0xffcc88ff })];
+    compileGlShadedProgram(gl, BASE_KEY, modifiers, registry);
+    const fragment = fragmentSourceFrom(gl.calls);
+    expect(fragment).toContain('uniform vec3 u_emissiveColor_0;');
+    expect(fragment).toContain('emissive += emissiveTerm;');
+  });
+
+  it('Gram-Schmidt-reorthogonalizes the tangent frame before sampling the normal map', () => {
+    const gl = makeFakeGl2();
+    compileGlShadedProgram(gl, { ...BASE_KEY, hasNormalMap: true }, [], createModifierRegistry());
+    const fragment = fragmentSourceFrom(gl.calls);
+    // The interpolated tangent is projected off the normal (the fix for the skewed-TBN normal-map bug).
+    expect(fragment).toContain('v_tangent.xyz - geometricNormal * dot(v_tangent.xyz, geometricNormal)');
+    expect(fragment).toContain('normal = normalize(tbn * baseTangentNormal);');
+  });
+
+  it('reuses GL_MESH_LIGHT_BLOCK_GLSL rather than declaring a second light block', () => {
+    const gl = makeFakeGl2();
+    compileGlShadedProgram(gl, BASE_KEY, [], createModifierRegistry());
+    const fragment = fragmentSourceFrom(gl.calls);
+    // The shared block declares u_directional exactly once (no forked light loop).
+    expect(fragment.split('uniform vec4 u_directional;').length - 1).toBe(1);
+  });
+
+  it('injects the skin define + vertex declarations only into the skinned vertex source', () => {
+    const gl = makeFakeGl2();
+    compileGlShadedProgram(gl, { ...BASE_KEY, hasSkin: true }, [], createModifierRegistry());
+    const vertex = vertexSourceFrom(gl.calls);
+    expect(vertex).toContain('#define HAS_SKIN');
+    expect(vertex).not.toContain('#define MAX_JOINTS');
+    expect(vertex).toContain('sampler2D u_jointTexture');
+    expect(vertex).toContain('texelFetch');
+    expect(vertex).toContain('mat4 skinMatrix()');
+    expect(vertex).toContain('a_joints0');
+    // Skinning is vertex-only — the fragment scene2d never sees the skin attributes.
+    expect(fragmentSourceFrom(gl.calls)).not.toContain('a_joints0');
+  });
+
+  it('leaves the rigid vertex source free of the skin define and declarations', () => {
+    const gl = makeFakeGl2();
+    compileGlShadedProgram(gl, BASE_KEY, [], createModifierRegistry());
+    const vertex = vertexSourceFrom(gl.calls);
+    expect(vertex).not.toContain('#define HAS_SKIN');
+    expect(vertex).not.toContain('a_joints0');
+    expect(fragmentSourceFrom(gl.calls)).not.toContain('a_joints0');
+  });
+
+  it('injects a Vertex-slot modifier into the vertex source, never the fragment', () => {
+    const gl = makeFakeGl2();
+    const registry = createModifierRegistry();
+    registerModifier(registry, vertexDisplaceGlModifierSnippet);
+    const modifiers: readonly Modifier[] = [
+      createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.Sine, amplitude: 0.2 }),
+    ];
+    compileGlShadedProgram(gl, BASE_KEY, modifiers, registry);
+    const vertex = vertexSourceFrom(gl.calls);
+    expect(vertex).toContain('localPosition.xyz += vDisplaceAxis * vDisplaceAmount;');
+    expect(vertex).toContain('uniform float u_vDisplaceAmplitude_0;');
+    expect(fragmentSourceFrom(gl.calls)).not.toContain('u_vDisplaceAmplitude_0');
+  });
+
+  it('dedupes the shared IBL environment declaration across two env-reflect modifiers', () => {
+    const gl = makeFakeGl2();
+    const registry = createModifierRegistry();
+    registerModifier(registry, envReflectGlModifierSnippet);
+    const modifiers: readonly Modifier[] = [createEnvReflectModifier(), createEnvReflectModifier()];
+    compileGlShadedProgram(gl, BASE_KEY, modifiers, registry);
+    const fragment = fragmentSourceFrom(gl.calls);
+    // The shared samplerCube declares once (deduped), while the per-instance tints stay distinct.
+    expect(fragment.split('uniform samplerCube u_iblPrefiltered;').length - 1).toBe(1);
+    expect(fragment).toContain('u_envReflectTint_0');
+    expect(fragment).toContain('u_envReflectTint_1');
+  });
+});
+
+describe('ensureGlShadedProgram', () => {
+  it('caches the compiled program under a shaded: key and reuses it', () => {
+    const { state } = makeGlScene3DState();
+    const first = ensureGlShadedProgram(state, BASE_KEY, []);
+    const second = ensureGlShadedProgram(state, BASE_KEY, []);
+    expect(second).toBe(first);
+    const keys = [...getGlScene3DRuntime(state).programCache.keys()];
+    expect(keys.some((k) => k.startsWith('shaded:'))).toBe(true);
+  });
+
+  it('folds the render-state skinned-run flag into a distinct HAS_SKIN variant', () => {
+    const { state } = makeGlScene3DState();
+    const rigid = ensureGlShadedProgram(state, BASE_KEY, []);
+    getGlScene3DRuntime(state).activeSkinnedRun = true;
+    const skinned = ensureGlShadedProgram(state, BASE_KEY, []);
+
+    expect(skinned).not.toBe(rigid);
+    expect([...getGlScene3DRuntime(state).programCache.keys()]).toContain('shaded:-----k|');
+    expect(skinned.locJointTexture).not.toBeNull();
+  });
+
+  it('compiles distinct variants for distinct modifier feature-sets', () => {
+    const { state } = makeGlScene3DState();
+    registerBuiltInGlModifierSnippets(state);
+    ensureGlShadedProgram(state, BASE_KEY, []);
+    ensureGlShadedProgram(state, BASE_KEY, [createEmissiveModifier({ color: 0xffffffff })]);
+    const keys = [...getGlScene3DRuntime(state).programCache.keys()].filter((k) => k.startsWith('shaded:'));
+    expect(new Set(keys).size).toBe(2);
+  });
+});