@forgeax/engine-shader 0.1.2

package/src/__tests__/fog-oracle.unit.test.ts

@@ -0,0 +1,132 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const fogWgsl = readFileSync(fileURLToPath(new URL('../fog.wgsl', import.meta.url)), 'utf8');
+const commonWgsl = readFileSync(fileURLToPath(new URL('../common.wgsl', import.meta.url)), 'utf8');
+
+interface FogCase {
+  readonly name: string;
+  readonly originY: number;
+  readonly directionY: number;
+  readonly distance: number;
+  readonly density: number;
+  readonly heightFalloff: number;
+  readonly maxOpacity: number;
+  readonly expectedOpacity: number;
+}
+
+function opticalDepth(input: FogCase): number {
+  const rho0 = input.density * Math.exp(-input.heightFalloff * input.originY);
+  const q = input.heightFalloff * input.directionY;
+  if (Math.abs(q) < 1e-6) return rho0 * input.distance;
+  return (rho0 * (1 - Math.exp(-q * input.distance))) / q;
+}
+
+function fogOpacity(input: FogCase): number {
+  return input.maxOpacity * (1 - Math.exp(-Math.max(opticalDepth(input), 0)));
+}
+
+const cases: readonly FogCase[] = [
+  {
+    name: 'uniform',
+    originY: 0,
+    directionY: 0,
+    distance: 10,
+    density: 0.1,
+    heightFalloff: 0,
+    maxOpacity: 1,
+    expectedOpacity: 0.6321205588,
+  },
+  {
+    name: 'horizontal-height',
+    originY: 2,
+    directionY: 0,
+    distance: 5,
+    density: 0.2,
+    heightFalloff: 0.5,
+    maxOpacity: 1,
+    expectedOpacity: 0.3077993724,
+  },
+  {
+    name: 'upward-height',
+    originY: 0,
+    directionY: 1,
+    distance: 4,
+    density: 0.2,
+    heightFalloff: 0.5,
+    maxOpacity: 1,
+    expectedOpacity: 0.2923926197,
+  },
+  {
+    name: 'downward-height',
+    originY: 0,
+    directionY: -1,
+    distance: 4,
+    density: 0.2,
+    heightFalloff: 0.5,
+    maxOpacity: 1,
+    expectedOpacity: 0.9223561116,
+  },
+  {
+    name: 'small-q-limit',
+    originY: 1.5,
+    directionY: 0.5,
+    distance: 7,
+    density: 0.03,
+    heightFalloff: 1e-12,
+    maxOpacity: 1,
+    expectedOpacity: 0.189415754,
+  },
+  {
+    name: 'max-opacity',
+    originY: 0,
+    directionY: 0,
+    distance: 10,
+    density: 0.5,
+    heightFalloff: 0,
+    maxOpacity: 0.25,
+    expectedOpacity: 0.2483155133,
+  },
+];
+
+describe('Fog optical-depth CPU oracle (M2)', () => {
+  it('reports case-wise expected, observed, delta, and verdict', () => {
+    const report = cases.map((input) => {
+      const observed = fogOpacity(input);
+      const delta = Math.abs(observed - input.expectedOpacity);
+      return {
+        name: input.name,
+        expected: input.expectedOpacity,
+        observed,
+        delta,
+        verdict: delta <= 1e-9,
+      };
+    });
+    for (const result of report) {
+      expect(result.verdict, `${result.name}: ${JSON.stringify(result)}`).toBe(true);
+    }
+  });
+
+  it('keeps HDR scene radiance and alpha while mixing in linear space', () => {
+    const scene = [2, 4, 8, 0.37] as const;
+    const fog = [0.5, 1.5, 3] as const;
+    const opacity = 0.25;
+    const mixed = scene.map((value, index) =>
+      index === 3 ? value : (1 - opacity) * value + opacity * (fog[index] ?? 0),
+    );
+    expect(mixed).toEqual([1.625, 3.375, 6.75, 0.37]);
+  });
+
+  it('has one shared Fog WGSL owner with finite ray and height inputs', () => {
+    expect(fogWgsl).toContain('#define_import_path forgeax_view::fog');
+    expect(fogWgsl).toContain('#import forgeax_view::common::{FogViewParams, FogRay}');
+    expect(fogWgsl).toMatch(/fn apply_fog\s*\(/);
+    expect((fogWgsl.match(/fn apply_fog\s*\(/g) ?? []).length).toBe(1);
+    expect(fogWgsl).toContain('FOG_Q_EPSILON');
+    expect(fogWgsl).toContain('FOG_EXP_LIMIT');
+    expect(fogWgsl).toContain('max(tau, 0.0)');
+    expect(fogWgsl).toContain('color.a');
+    expect(commonWgsl).toMatch(/fog\s*:\s*FogViewParams/);
+  });
+});

package/src/__tests__/fog-orthographic-ray.unit.test.ts

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const shaderFiles = [
+  'default-standard-pbr.wgsl',
+  'default-standard-pbr-skin.wgsl',
+  'unlit.wgsl',
+  'sprite.wgsl',
+  'sprite-lit.wgsl',
+  'msdf-text.wgsl',
+] as const;
+
+function source(name: (typeof shaderFiles)[number]): string {
+  return readFileSync(fileURLToPath(new URL(`../${name}`, import.meta.url)), 'utf8');
+}
+
+function subtract(a: readonly number[], b: readonly number[]): number[] {
+  return a.map((value, index) => value - (b[index] ?? 0));
+}
+
+function dot(a: readonly number[], b: readonly number[]): number {
+  return a.reduce((sum, value, index) => sum + value * (b[index] ?? 0), 0);
+}
+
+function scale(a: readonly number[], scalar: number): number[] {
+  return a.map((value) => value * scalar);
+}
+
+describe('Fog orthographic fragment ray contract', () => {
+  it('derives the camera-plane origin from the current fragment for every built-in material', () => {
+    for (const name of shaderFiles) {
+      const shader = source(name);
+      expect(shader, name).toContain(
+        'worldPos - direction * dot(worldPos - viewParams.cameraPos, direction)',
+      );
+      expect(shader, name).not.toContain('origin = nearPoint;');
+      expect(shader.match(/applySceneFog\(/g)?.length, name).toBeGreaterThanOrEqual(2);
+    }
+  });
+
+  it('keeps a tilted orthographic camera pixel on its own ray rather than the center ray', () => {
+    const camera = [4, 2, -3];
+    const direction = [0.3, -0.8, 0.5];
+    const length = Math.hypot(...direction);
+    const unitDirection = direction.map((value) => value / length);
+    const lateral = [1, 0, -0.6];
+    const fragment = camera
+      .map((value, index) => value + (lateral[index] ?? 0))
+      .map((value, index) => value + (unitDirection[index] ?? 0) * 7);
+    const origin = subtract(
+      fragment,
+      scale(unitDirection, dot(subtract(fragment, camera), unitDirection)),
+    );
+
+    expect(origin[0]).toBeCloseTo(5, 8);
+    expect(origin[1]).toBeCloseTo(2, 8);
+    expect(origin[2]).toBeCloseTo(-3.6, 8);
+    expect(dot(subtract(fragment, origin), unitDirection)).toBeCloseTo(7, 8);
+    expect(dot(subtract(origin, camera), unitDirection)).toBeCloseTo(0, 8);
+  });
+});

package/src/__tests__/fog-producer-matrix.integration.test.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const SHADER_FILES = [
+  'default-standard-pbr.wgsl',
+  'default-standard-pbr-skin.wgsl',
+  'unlit.wgsl',
+  'sprite.wgsl',
+  'sprite-lit.wgsl',
+  'msdf-text.wgsl',
+  'skybox.wgsl',
+] as const;
+
+const shaderSource = (file: string): string =>
+  readFileSync(fileURLToPath(new URL(`../${file}`, import.meta.url)), 'utf8');
+
+const count = (source: string, pattern: RegExp): number => source.match(pattern)?.length ?? 0;
+
+function producerContract(source: string): boolean {
+  return (
+    /#import\s+forgeax_view::common::\{[^}]*\bFogRay\b[^}]*\}/.test(source) &&
+    /#import\s+forgeax_view::fog::\{[^}]*\bapply_fog\b[^}]*\}/.test(source) &&
+    count(source, /\bapply_fog\s*\(/g) === 1 &&
+    count(source, /\bFogRay\s*\(/g) >= 1 &&
+    (source.includes('view.fog') || source.includes('viewParams.fog'))
+  );
+}
+
+function body(source: string, entry: string, nextEntry: string): string {
+  const start = source.indexOf(entry);
+  const end = nextEntry === '' ? -1 : source.indexOf(nextEntry, start + entry.length);
+  return source.slice(start, end === -1 ? source.length : end);
+}
+
+describe('built-in Fog producer matrix', () => {
+  it('requires one shared Fog module call and a real FogRay for every built-in output', () => {
+    for (const file of SHADER_FILES) {
+      const source = shaderSource(file);
+      expect(producerContract(source), file).toBe(true);
+    }
+  });
+
+  it('keeps deferred G-buffer and temporal/reactive outputs free of Fog', () => {
+    const pbr = shaderSource('default-standard-pbr.wgsl');
+    const gbuffer = body(pbr, 'fn fs_gbuffer', 'struct TemporalVsOut');
+    const temporal = body(pbr, 'fn fs_temporal', '');
+
+    expect(gbuffer).not.toContain('applySceneFog(');
+    expect(gbuffer).not.toContain('apply_fog(');
+    expect(temporal).not.toContain('applySceneFog(');
+    expect(temporal).not.toContain('apply_fog(');
+  });
+
+  it('turns deletion, duplication, and non-scene output coverage into red verdicts', () => {
+    const source = shaderSource('default-standard-pbr.wgsl');
+    expect(producerContract(source)).toBe(true);
+
+    const deleted = source.replace(/#import\s+forgeax_view::fog::\{[^\n]+\}\n?/, '');
+    expect(producerContract(deleted)).toBe(false);
+
+    const duplicated = `${source}\n${source.match(/\bapply_fog\s*\([\s\S]*?\);/)?.[0] ?? ''}`;
+    expect(producerContract(duplicated)).toBe(false);
+
+    const gbufferStart = source.indexOf('fn fs_gbuffer');
+    const gbufferFogged = `${source.slice(0, gbufferStart)}${source
+      .slice(gbufferStart)
+      .replace(
+        'let baseUv =',
+        'let _falsify = applySceneFog(vec3<f32>(1.0), 1.0, vec3<f32>(0.0));\n  let baseUv =',
+      )}`;
+    expect(gbufferFogged).not.toBe(source);
+    expect(body(gbufferFogged, 'fn fs_gbuffer', 'struct TemporalVsOut')).toContain(
+      'applySceneFog(',
+    );
+  });
+});

package/src/__tests__/hdrp-ssao-compile.test.ts

@@ -0,0 +1,185 @@
+// @forgeax/engine-shader/__tests__/hdrp-ssao-compile.test.ts -
+// Structural unit test for hdrp-ssao.wgsl (M2 / w7).
+// feat-20260612-hdrp-ssao.
+//
+// This package physically isolates naga (4 grep gates in scripts/), so the
+// test is source-level structural (same pattern as fxaa-shader.test.ts +
+// ibl-modules-parse.test.ts). Read the WGSL source via node:fs and assert:
+//
+//   (a) file exists and declares define_import_path
+//   (b) two fragment entry points — fs_ssao_calc + fs_ssao_blur
+//   (c) imports fullscreen_triangle + FullscreenOutput from common.wgsl
+//   (d) calc output is @location(0) f32 (R8 scalar)
+//   (e) SSAO uniform group (@group(0)) with 3 mat4 fields
+//   (f) kernel uniform buffer @binding
+//   (g) noise texture + depth + normal texture bindings
+//   (h) blur @location(0) output is f32 (R8 scalar)
+//
+// RED before w8 (hdrp-ssao.wgsl does not exist yet).
+// GREEN after w8 writes the file.
+
+import { beforeAll, describe, expect, it } from 'vitest';
+
+// ── node:* imports (dynamic, vite-ignore — same pattern as fxaa-shader.test.ts) ──
+
+interface NodeFs {
+  readFileSync: (p: string, enc: string) => string;
+}
+interface NodePath {
+  resolve: (...parts: string[]) => string;
+  dirname: (p: string) => string;
+}
+interface NodeUrl {
+  fileURLToPath: (u: string) => string;
+}
+
+let ssaoSource!: string;
+let srcDir!: string;
+let fs!: NodeFs;
+
+beforeAll(async () => {
+  const fsId = 'node:fs';
+  const pathId = 'node:path';
+  const urlId = 'node:url';
+  fs = (await import(/* @vite-ignore */ fsId)) as NodeFs;
+  const path = (await import(/* @vite-ignore */ pathId)) as NodePath;
+  const url = (await import(/* @vite-ignore */ urlId)) as NodeUrl;
+  const here = url.fileURLToPath(import.meta.url);
+  srcDir = path.resolve(path.dirname(here), '..');
+  ssaoSource = fs.readFileSync(path.resolve(srcDir, 'hdrp-ssao.wgsl'), 'utf8');
+});
+
+function stripComments(src: string): string {
+  return src
+    .split(/\r?\n/)
+    .map((line: string) => line.replace(/\/\/.*$/, ''))
+    .join('\n');
+}
+
+describe('hdrp-ssao.wgsl structural compile test (M2 / w7)', () => {
+  it('(a) declares #define_import_path', () => {
+    const m = /^\s*#define_import_path\s+(\S+)\s*$/m.exec(ssaoSource);
+    expect(m?.[1]).toBe('forgeax_hdrp::ssao');
+  });
+
+  it('(b1) has fs_ssao_calc fragment entry point', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(/@fragment\s+fn\s+fs_ssao_calc\b/);
+  });
+
+  it('(b2) has fs_ssao_blur fragment entry point', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(/@fragment\s+fn\s+fs_ssao_blur\b/);
+  });
+
+  it('(c1) imports fullscreen_triangle from forgeax_view::common', () => {
+    expect(ssaoSource).toMatch(
+      /#import\s+forgeax_view::common\s*::\s*\{[^}]*\bfullscreen_triangle\b[^}]*\}/,
+    );
+  });
+
+  it('(c2) imports FullscreenOutput from forgeax_view::common', () => {
+    expect(ssaoSource).toMatch(
+      /#import\s+forgeax_view::common\s*::\s*\{[^}]*\bFullscreenOutput\b[^}]*\}/,
+    );
+  });
+
+  it('(d) fs_ssao_calc outputs @location(0) f32 (R8 scalar)', () => {
+    // fs_ssao_calc fragment signature: @location(0) f32
+    const codeOnly = stripComments(ssaoSource);
+    const blockMatch = /fn\s+fs_ssao_calc\b[\s\S]*?->\s*@location\(0\)\s+f32/.exec(codeOnly);
+    expect(blockMatch).toBeTruthy();
+  });
+
+  it('(e1) declares SSAO uniform struct with view + projection + inverseProjection (3 mat4<f32>)', () => {
+    // The uniform struct must have exactly 3 mat4x4<f32> fields.
+    const codeOnly = stripComments(ssaoSource);
+    // Accept either SsaoUniform or unnamed struct at @group(0).
+    // Look for a struct with 3 mat4 fields before the @group(0) binding.
+    const mat4Matches = codeOnly.match(/mat4x4<f32>/g);
+    expect(mat4Matches).toBeTruthy();
+    expect(mat4Matches?.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('(e2) SSAO uniform UBO is at @group(0) @binding(0)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(/@group\(0\)\s*@binding\(0\)\s+var<uniform>\s+\w+_uniform/);
+  });
+
+  it('(f) kernel uniform buffer is declared (array<vec4<f32>>)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(/@group\(0\)\s*@binding\(1\)\s+var<uniform>\s+\w+/);
+    expect(codeOnly).toMatch(/array<vec4<f32>,\s*64>/);
+  });
+
+  it('(g1) noise texture binding is present (@binding(2) texture_2d<f32>)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(
+      /@group\(0\)\s*@binding\(2\)\s+var\s+\w+_texture\s*:\s*texture_2d<f32>/,
+    );
+  });
+
+  it('(g2) noise sampler binding is present (@binding(3))', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(/@group\(0\)\s*@binding\(3\)\s+var\s+\w+_sampler\s*:\s*sampler/);
+  });
+
+  it('(g3) g-buffer normal texture binding is present (@binding(4) texture_2d<f32>)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(/@group\(0\)\s*@binding\(4\)\s+var\s+\w+\s*:\s*texture_2d<f32>/);
+  });
+
+  it('(g4) hdrDepth texture binding is present (@binding(5) texture_depth_2d)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    expect(codeOnly).toMatch(/@group\(0\)\s*@binding\(5\)\s+var\s+\w+\s*:\s*texture_depth_2d/);
+  });
+
+  it('(h) fs_ssao_blur outputs @location(0) f32 (R8 scalar)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    const blockMatch = /fn\s+fs_ssao_blur\b[\s\S]*?->\s*@location\(0\)\s+f32/.exec(codeOnly);
+    expect(blockMatch).toBeTruthy();
+  });
+});
+
+// ── M8 / w36 + w37 ssao-blur input fix RED ──────────────────────────────────
+//
+// plan-strategy §D-D: fs_ssao_blur currently reads gbuffer_normal +
+// ssao_noise_sampler — that is a typo carried from copy-paste of fs_ssao_calc.
+// The blur should read the half-res ssaoRaw output of fs_ssao_calc through a
+// dedicated ssaoSampler. These assertions go RED until w37 fixes the WGSL.
+
+describe('hdrp-ssao.wgsl ssao-blur input fix (M8 / w36 + w37)', () => {
+  it('(i1) ssaoRaw texture binding is declared (@binding for half-res calc output)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    // After D-D: ssao-blur reads ssaoRaw, so the WGSL must declare a
+    // ssaoRaw: texture_2d<f32> binding.
+    expect(codeOnly).toMatch(/var\s+ssaoRaw\s*:\s*texture_2d<f32>/);
+  });
+
+  it('(i2) ssaoSampler binding is declared (paired with ssaoRaw)', () => {
+    const codeOnly = stripComments(ssaoSource);
+    // The companion sampler bound alongside ssaoRaw for the blur tap loop.
+    expect(codeOnly).toMatch(/var\s+ssaoSampler\s*:\s*sampler/);
+  });
+
+  it('(i3) fs_ssao_blur body reads ssaoRaw, NOT gbuffer_normal', () => {
+    const codeOnly = stripComments(ssaoSource);
+    // Carve out the fs_ssao_blur function body.
+    const blurMatch = /fn\s+fs_ssao_blur\b[\s\S]*?\n\}/.exec(codeOnly);
+    expect(blurMatch).toBeTruthy();
+    if (!blurMatch) return;
+    const body = blurMatch[0];
+    expect(body).toMatch(/textureSample\s*\(\s*ssaoRaw\b/);
+    // The blur must not reference gbuffer_normal at all.
+    expect(body).not.toMatch(/\bgbuffer_normal\b/);
+  });
+
+  it('(i4) fs_ssao_blur body samples through ssaoSampler', () => {
+    const codeOnly = stripComments(ssaoSource);
+    const blurMatch = /fn\s+fs_ssao_blur\b[\s\S]*?\n\}/.exec(codeOnly);
+    expect(blurMatch).toBeTruthy();
+    if (!blurMatch) return;
+    const body = blurMatch[0];
+    expect(body).toMatch(/ssaoSampler\b/);
+  });
+});

package/src/__tests__/ibl-irradiance.unit.test.ts

@@ -0,0 +1,43 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface NodeFs {
+  readFileSync: (path: string, encoding: string) => string;
+}
+
+interface NodePath {
+  resolve: (...parts: string[]) => string;
+  dirname: (path: string) => string;
+}
+
+interface NodeUrl {
+  fileURLToPath: (url: string) => string;
+}
+
+let fs!: NodeFs;
+let path!: NodePath;
+let srcDir!: string;
+let irradianceSource!: string;
+
+beforeAll(async () => {
+  fs = (await import(/* @vite-ignore */ 'node:fs')) as NodeFs;
+  path = (await import(/* @vite-ignore */ 'node:path')) as NodePath;
+  const url = (await import(/* @vite-ignore */ 'node:url')) as NodeUrl;
+  srcDir = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+  irradianceSource = fs.readFileSync(path.resolve(srcDir, 'ibl-irradiance.wgsl'), 'utf8');
+});
+
+describe('IBL irradiance payload contract', () => {
+  it('records that convolution produces E times pi before the Lambert divide', () => {
+    expect(irradianceSource).toContain('IRRADIANCE_PAYLOAD_E_TIMES_PI');
+    expect(irradianceSource).toMatch(/irradiance\s*=\s*PI\s*\*\s*irradiance/);
+  });
+
+  it('keeps the constant-environment analytic oracle finite and explicit', () => {
+    const environment = 0.72;
+    const convolvedPayload = environment * Math.PI;
+    const diffuseRadiance = convolvedPayload / Math.PI;
+
+    expect(diffuseRadiance).toBeCloseTo(environment, 12);
+    expect(Number.isFinite(diffuseRadiance)).toBe(true);
+  });
+});

package/src/__tests__/ibl-sampling.unit.test.ts

@@ -0,0 +1,40 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface NodeFs {
+  readFileSync: (path: string, encoding: string) => string;
+}
+
+interface NodePath {
+  resolve: (...parts: string[]) => string;
+  dirname: (path: string) => string;
+}
+
+interface NodeUrl {
+  fileURLToPath: (url: string) => string;
+}
+
+let fs!: NodeFs;
+let path!: NodePath;
+let srcDir!: string;
+let samplingSource!: string;
+
+beforeAll(async () => {
+  fs = (await import(/* @vite-ignore */ 'node:fs')) as NodeFs;
+  path = (await import(/* @vite-ignore */ 'node:path')) as NodePath;
+  const url = (await import(/* @vite-ignore */ 'node:url')) as NodeUrl;
+  srcDir = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+  samplingSource = fs.readFileSync(path.resolve(srcDir, 'ibl-sampling.wgsl'), 'utf8');
+});
+
+describe('IBL diffuse sampling payload contract', () => {
+  it('names the sampled payload as E over pi at the canonical sampling owner', () => {
+    expect(samplingSource).toContain('irradianceEOverPi');
+    expect(samplingSource).toMatch(/irradianceEOverPi\s*\/\s*PI/);
+  });
+
+  it('does not divide the same diffuse payload twice', () => {
+    const diffuseBody = samplingSource.match(/fn sampleIblDiffuse\([\s\S]*?\n\}/)?.[0] ?? '';
+    expect(diffuseBody.match(/\/\s*PI/g) ?? []).toHaveLength(1);
+    expect(diffuseBody).not.toMatch(/irradianceEOverPi\s*\/\s*PI[\s\S]*\/\s*PI/);
+  });
+});

package/src/__tests__/lighting-punctual.unit.test.ts

@@ -0,0 +1,66 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const shaderPath = join(dirname(fileURLToPath(import.meta.url)), '../lighting-punctual.wgsl');
+const hdrpShaderPath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '../hdrp-cluster-forward.wgsl',
+);
+const pbrShaderPath = join(dirname(fileURLToPath(import.meta.url)), '../default-standard-pbr.wgsl');
+
+describe('direct punctual lighting shader contract', () => {
+  it('exposes independent point and spot paths with explicit range and cone inputs', async () => {
+    const source = await readFile(shaderPath, 'utf8');
+
+    expect(source).toContain('fn evalPoint(');
+    expect(source).toContain('fn evalSpot(');
+    expect(source).toContain('invRangeSquared');
+    expect(source).toContain('cosInner');
+    expect(source).toContain('cosOuter');
+    expect(source).toContain('smoothstep(cosOuter, cosInner');
+  });
+
+  it('does not introduce a separate physical-light component or intensity profile', async () => {
+    const source = await readFile(shaderPath, 'utf8');
+
+    expect(source).not.toContain('PhysicalLight');
+    expect(source).not.toMatch(/intensityMultiplier|magicMultiplier|profile/);
+  });
+
+  it('leaves spot direction normalization to extract instead of HDRP', async () => {
+    const source = await readFile(shaderPath, 'utf8');
+
+    expect(source).toContain('lightDir');
+    expect(source).not.toContain('normalize(lightDir)');
+  });
+
+  it('keeps cluster punctual evaluation in the shared lighting owner', async () => {
+    const source = await readFile(hdrpShaderPath, 'utf8');
+
+    expect(source).toContain('kind_and_shadow');
+    expect(source).toContain('evalPoint');
+    expect(source).toContain('evalSpot');
+    expect(source).toContain('evalSpotShadowed');
+    expect(source).not.toContain('fn evaluate_point_light(');
+    expect(source).not.toContain('fn evaluate_spot_light(');
+    expect(source).not.toMatch(/kind\s*==\s*KIND_POINT[\s\S]{0,80}else\s*\{/);
+  });
+
+  it('decodes HDRP spot cone lanes in the shared evaluator order', async () => {
+    const source = await readFile(hdrpShaderPath, 'utf8');
+
+    expect(source).toContain('light.color.w, light.direction.w, light.position.w');
+    expect(source).not.toContain('light.direction.w, light.color.w, light.position.w');
+  });
+
+  it('passes precomputed base and clearcoat roughness/F0 facts to cluster lights', async () => {
+    const source = await readFile(pbrShaderPath, 'utf8');
+
+    expect(source).toContain(
+      'evaluate_cluster_lights(in.ndc, in.viewZ, in.worldPos, n, v, albedo, metallic, a, f0)',
+    );
+    expect(source).toContain('coatAlpha, vec3<f32>(0.04)');
+  });
+});

package/src/__tests__/manifest.fixture.json

@@ -0,0 +1,22 @@
+{
+  "entries": [
+    {
+      "hash": "abc12345",
+      "wgsl": "@vertex fn vs_main() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); } @fragment fn fs_main() -> @location(0) vec4<f32> { return vec4<f32>(1.0); }",
+      "glsl": null,
+      "bindings": "[]"
+    },
+    {
+      "hash": "def67890",
+      "wgsl": "@vertex fn vs_main() -> @builtin(position) vec4<f32> { return vec4<f32>(1.0); } @fragment fn fs_main() -> @location(0) vec4<f32> { return vec4<f32>(0.5); }",
+      "glsl": "",
+      "bindings": "[]"
+    },
+    {
+      "hash": "ssao001",
+      "wgsl": "@vertex fn vs_ssao(@builtin(vertex_index) vertex_index : u32) -> SsaoVsOut { return SsaoVsOut(); } @fragment fn fs_ssao_calc(in : SsaoVsOut) -> @location(0) f32 { return 1.0; } @fragment fn fs_ssao_blur(in : SsaoVsOut) -> @location(0) f32 { return 1.0; }",
+      "glsl": null,
+      "bindings": "[]"
+    }
+  ]
+}

package/src/__tests__/material-artifact-dedup.unit.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { MaterialArtifactRegistry } from '../material/artifact-registry.js';
+
+describe('material artifact deduplication', () => {
+  it('shares immutable artifacts by specialization key and rejects conflicts', () => {
+    const registry = new MaterialArtifactRegistry();
+    const first = Object.freeze({ key: 'key-a', bytes: new Uint8Array([1]) });
+    const second = Object.freeze({ key: 'key-a', bytes: new Uint8Array([2]) });
+
+    expect(registry.register(first)).toEqual({ ok: true, value: first });
+    expect(registry.register({ key: 'key-a', bytes: new Uint8Array([1]) })).toEqual({
+      ok: true,
+      value: first,
+    });
+    expect(registry.register(second)).toMatchObject({
+      ok: false,
+      error: { code: 'material-artifact-conflict' },
+    });
+    expect(registry.get('key-a')).toBe(first);
+  });
+});