@forgeax/engine-render 0.1.19 → 0.1.21

package/src/__tests__/typed-pipeline-topology.unit.test.ts

@@ -1,17 +1,32 @@
 import { readFileSync } from 'node:fs';
+import { mat4, vec3 } from '@forgeax/engine-math';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiDevice } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { ok } from '@forgeax/engine-types';
 import { beforeAll, describe, expect, it } from 'vitest';
+import { shouldExecuteStandardClusterMembershipPass } from '../pipeline/standard-lighting/graph';
+import {
+  prepareStandardLighting,
+  type StandardLightFrame,
+} from '../pipeline/standard-lighting/prepare';
+import {
+  deriveStandardTopologyInput,
+  standardLightingTopologySignature,
+} from '../pipeline/standard-lighting/topology';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
 import { standardPipeline } from '../pipeline/standard-pipeline';
 import { DEFAULT_STANDARD_PROFILE } from '../pipeline/standard-profile';
-import { isMotionBlurTemporalDemand } from '../record/typed-frame-graph';
+import {
+  isMotionBlurTemporalDemand,
+  resolvePostProcessChainAdmission,
+} from '../record/typed-frame-graph';
 import type {
   RenderPipeline,
   RenderPipelineFrame,
   RenderPipelineTopology,
 } from '../render-pipeline';
+import { resolveOutputDither } from '../render-pipeline';
 import { standardTemporalPostOrder } from '../temporal/standard-scene-data';
 
 let device: RhiDevice;
@@ -39,8 +54,8 @@ function topology(
     },
     camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'on' },
     shadow: {
-      mapSize: 1024,
-      cascadeCount: 4,
+      directional: { mapSize: 1024, cascadeCount: 4 },
+      spotMapSize: 1024,
       pointCount: 1,
       pointFaceSize: 512,
       spotCount: 1,
@@ -57,13 +72,65 @@ function topology(
   };
 }
 
+function zeroStandardLighting(caps: { compute: boolean; storageBuffer: boolean }, localCount = 1) {
+  const prepared = prepareStandardLighting({
+    directional: undefined,
+    local: Array.from({ length: localCount }, (_, index) => ({
+      kind: 'point' as const,
+      shadowed: false,
+      position: vec3.create(index, 0, -4),
+      range: 2,
+    })),
+    view: mat4.create(),
+    projection: mat4.create(),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: DEFAULT_STANDARD_PROFILE.lightCount,
+    renderPath: 'forward',
+  });
+  if (!prepared.ok) throw prepared.error;
+  const transport = selectStandardClusterTransport(
+    { ...caps, membershipPipelineReady: caps.compute },
+    prepared.value,
+  );
+  if (!transport.ok) return transport;
+  return deriveStandardTopologyInput({
+    kind: 'clustered',
+    prepared: prepared.value,
+    transport: transport.value,
+  });
+}
+
+function noLocalStandardLighting() {
+  const prepared = prepareStandardLighting({
+    directional: undefined,
+    local: [],
+    view: mat4.create(),
+    projection: mat4.create(),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: 1,
+    renderPath: 'forward',
+  });
+  if (!prepared.ok) throw prepared.error;
+  return deriveStandardTopologyInput({ kind: 'no-local-lights', prepared: prepared.value });
+}
+
 function compile(pipeline: RenderPipeline, input: RenderPipelineTopology) {
   const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+  const standardLighting = zeroStandardLighting({
+    compute: input.lane.compute,
+    storageBuffer: input.lane.storageBuffer,
+  });
+  if (!standardLighting.ok) return standardLighting;
   const importedHistory =
     input.camera.antialias === 'taa' ? createImportedHistory(graph) : undefined;
   const built = pipeline.build(
     {
       graph,
+      standardLighting: standardLighting.value,
       capabilities: { rgba16floatRenderable: true },
       ...(importedHistory === undefined ? {} : { taaHistory: importedHistory }),
       projectGpuDriven: () => ok(undefined),
@@ -78,6 +145,38 @@ function compile(pipeline: RenderPipeline, input: RenderPipelineTopology) {
   });
 }
 
+function disabledDirectionalTopology(): RenderPipelineTopology {
+  return topology('forgeax::standard', {
+    shadow: {
+      directional: 'disabled',
+      pointCount: 0,
+      pointFaceSize: 512,
+      spotCount: 0,
+    } as unknown as RenderPipelineTopology['shadow'],
+  });
+}
+
+function disabledDirectionalVolumeTopology(lightKind: 'point' | 'spot'): RenderPipelineTopology {
+  return topology('forgeax::standard', {
+    shadow: {
+      directional: 'disabled',
+      spotMapSize: 1024,
+      pointCount: 0,
+      pointFaceSize: 512,
+      spotCount: lightKind === 'spot' ? 1 : 0,
+    },
+    volumetricFog: {
+      enabled: true,
+      lightKind,
+      lightEntity: 1,
+      format: 'rgba8unorm',
+      extent: { width: 8, height: 8, depth: 8 },
+      froxelExtent: { width: 16, height: 16, depth: 8 },
+      resolvedExtent: { width: 8, height: 8, depth: 1 },
+    },
+  });
+}
+
 function createImportedHistory(graph: RenderGraphBuilder<RenderPipelineFrame>) {
   const target = (label: string) => {
     const texture = graph.importTexture(
@@ -104,6 +203,248 @@ function createImportedHistory(graph: RenderGraphBuilder<RenderPipelineFrame>) {
 }
 
 describe('typed built-in pipeline topology', () => {
+  it('defaults final output dither on and accepts an asset-level opt-out', () => {
+    expect(resolveOutputDither(undefined)).toBe(true);
+    expect(resolveOutputDither({ outputDither: true })).toBe(true);
+    expect(resolveOutputDither({ outputDither: false })).toBe(false);
+  });
+
+  it('omits every Directional shadow graph resource and pass when disabled', () => {
+    const compiled = compile(standardPipeline, disabledDirectionalTopology());
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const info = compiled.value.inspect();
+    expect(info.resources.some((resource) => resource.label === 'directional-shadow-depth')).toBe(
+      false,
+    );
+    expect(
+      info.passes.some(
+        (pass) =>
+          pass.name.startsWith('shadowCascade') || pass.name === 'directional-shadow-observation',
+      ),
+    ).toBe(false);
+    const main = info.passes.find((pass) => pass.name === 'main');
+    expect(main?.accesses.some((access) => access.resource === 'directional-shadow-depth')).toBe(
+      false,
+    );
+  });
+
+  it('falsifies a test-only shadow-off topology that still builds a Directional pass', () => {
+    const compiled = compile(standardPipeline, disabledDirectionalTopology());
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const count = compiled.value
+      .inspect()
+      .passes.filter(
+        (pass) =>
+          pass.name.startsWith('shadowCascade') || pass.name === 'directional-shadow-observation',
+      ).length;
+    const expected = process.env.FALSIFY === 'shadow-off-still-builds-pass' ? 1 : 0;
+    expect(count).toBe(expected);
+  });
+
+  it.each([
+    'point',
+    'spot',
+  ] as const)('keeps %s volumetric fog graphable when directional shadows are disabled', (lightKind) => {
+    const compiled = compile(standardPipeline, disabledDirectionalVolumeTopology(lightKind));
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const info = compiled.value.inspect();
+    expect(info.resources.some((resource) => resource.label === 'directional-shadow-depth')).toBe(
+      false,
+    );
+    expect(info.passes.some((pass) => pass.name === 'volume-inject')).toBe(true);
+    expect(
+      info.passes.some(
+        (pass) =>
+          pass.name.startsWith('shadowCascade') || pass.name === 'directional-shadow-observation',
+      ),
+    ).toBe(false);
+  });
+
+  it('derives topology only from prepared transport facts', () => {
+    const frame: StandardLightFrame = {
+      directional: undefined,
+      local: [{ kind: 'point', shadowed: false, position: vec3.create(0, 0, -4), range: 2 }],
+      view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+      projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 32,
+      renderPath: 'forward',
+    };
+    const prepared = prepareStandardLighting(frame);
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const transport = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: true },
+      prepared.value,
+    );
+    expect(transport.ok).toBe(true);
+    if (!transport.ok) return;
+    const derived = deriveStandardTopologyInput({
+      prepared: prepared.value,
+      kind: 'clustered',
+      transport: transport.value,
+    });
+    expect(derived.ok).toBe(true);
+    if (!derived.ok) return;
+    expect(derived.value.kind).toBe('clustered');
+    if (derived.value.kind !== 'clustered') return;
+    expect(derived.value.transport.kind).toBe('compute-storage');
+    expect(derived.value.prepared).toBe(prepared.value);
+  });
+
+  it('keeps graph identity stable for per-frame light movement and count changes', () => {
+    const make = (localCount: number) => {
+      const prepared = prepareStandardLighting({
+        directional: undefined,
+        local: Array.from({ length: localCount }, (_, index) => ({
+          kind: index % 2 === 0 ? ('point' as const) : ('spot' as const),
+          shadowed: false,
+          position: vec3.create(index, 0, -4),
+          range: 2,
+        })),
+        view: mat4.create(),
+        projection: mat4.create(),
+        near: 0.1,
+        far: 100,
+        grid: { x: 4, y: 3, z: 4 },
+        lightCount: 32,
+        renderPath: 'forward',
+      });
+      if (!prepared.ok) throw prepared.error;
+      const transport = selectStandardClusterTransport(
+        { compute: true, storageBuffer: true, membershipPipelineReady: true },
+        prepared.value,
+      );
+      if (!transport.ok) throw transport.error;
+      const input = deriveStandardTopologyInput({
+        kind: 'clustered',
+        prepared: prepared.value,
+        transport: transport.value,
+      });
+      if (!input.ok) throw input.error;
+      return input.value;
+    };
+    expect(standardLightingTopologySignature(make(1))).toBe(
+      standardLightingTopologySignature(make(2)),
+    );
+    const empty = noLocalStandardLighting();
+    expect(empty.ok).toBe(true);
+    if (!empty.ok) return;
+    expect(standardLightingTopologySignature(make(1))).not.toBe(
+      standardLightingTopologySignature(empty.value),
+    );
+    expect(standardLightingTopologySignature(undefined)).not.toBe(
+      standardLightingTopologySignature(empty.value),
+    );
+  });
+
+  it('keeps the clustered graph and ABI stable across local-light 1 to 0 to 1', () => {
+    const capabilities = { compute: true, storageBuffer: true };
+    const one = zeroStandardLighting(capabilities, 1);
+    const zero = zeroStandardLighting(capabilities, 0);
+    const oneAgain = zeroStandardLighting(capabilities, 1);
+    expect(one.ok && zero.ok && oneAgain.ok).toBe(true);
+    if (!one.ok || !zero.ok || !oneAgain.ok) return;
+    expect(one.value.kind).toBe('clustered');
+    expect(zero.value.kind).toBe('clustered');
+    expect(oneAgain.value.kind).toBe('clustered');
+    expect(standardLightingTopologySignature(zero.value)).toBe(
+      standardLightingTopologySignature(one.value),
+    );
+    expect(standardLightingTopologySignature(oneAgain.value)).toBe(
+      standardLightingTopologySignature(one.value),
+    );
+
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const built = standardPipeline.build(
+      {
+        graph,
+        standardLighting: zero.value,
+        capabilities: { rgba16floatRenderable: true },
+        projectGpuDriven: () => ok(undefined),
+        contributeFeatures: () => ok(undefined),
+      },
+      topology('forgeax::standard', {
+        shadow: {
+          directional: 'disabled',
+          pointCount: 0,
+          pointFaceSize: 512,
+          spotCount: 0,
+        } as unknown as RenderPipelineTopology['shadow'],
+        camera: { tonemap: 'none', antialias: 'none', bloom: 'off' },
+      }),
+    );
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const compiled = graph.compile({ device, surfaceSize: { width: 800, height: 600 } });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const info = compiled.value.inspect();
+    expect(info.passes.map((pass) => pass.name)).toContain('cluster-membership-producer');
+    expect(info.resources.map((resource) => resource.label)).toContain('hdrp-light-data');
+  });
+
+  it('evaluates Cluster membership from the current frame, not graph-build light count', () => {
+    const one = zeroStandardLighting({ compute: true, storageBuffer: true }, 1);
+    const zero = zeroStandardLighting({ compute: true, storageBuffer: true }, 0);
+    expect(one.ok && zero.ok).toBe(true);
+    if (!one.ok || !zero.ok) return;
+    const asFrame = (standardLighting: typeof one.value) =>
+      ({ standardLighting }) as unknown as RenderPipelineFrame;
+    expect(shouldExecuteStandardClusterMembershipPass(asFrame(zero.value))).toBe(false);
+    expect(shouldExecuteStandardClusterMembershipPass(asFrame(one.value))).toBe(true);
+    expect(shouldExecuteStandardClusterMembershipPass(asFrame(zero.value))).toBe(false);
+  });
+
+  it('rejects raw capability and light data at the topology adapter boundary', () => {
+    const empty = zeroStandardLighting({ compute: true, storageBuffer: true });
+    expect(empty.ok).toBe(true);
+    if (!empty.ok) return;
+    expect(empty.value.kind).toBe('clustered');
+    if (empty.value.kind !== 'clustered') return;
+    const derived = deriveStandardTopologyInput({
+      kind: 'clustered',
+      prepared: empty.value.prepared,
+      transport: empty.value.transport,
+      lights: [],
+    } as unknown as Parameters<typeof deriveStandardTopologyInput>[0]);
+    expect(derived.ok).toBe(false);
+    if (derived.ok) return;
+    expect(derived.error.code).toBe('topology-input-invalid');
+  });
+
+  it('accepts an explicit no-local topology without allocating Cluster resources', () => {
+    const standardLighting = noLocalStandardLighting();
+    expect(standardLighting.ok).toBe(true);
+    if (!standardLighting.ok) return;
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const built = standardPipeline.build(
+      {
+        graph,
+        standardLighting: standardLighting.value,
+        capabilities: { rgba16floatRenderable: false },
+        projectGpuDriven: () => ok(undefined),
+        contributeFeatures: () => ok(undefined),
+      },
+      topology('forgeax::standard', {
+        lane: { compute: false, storageBuffer: false, multisample: false, maxColorAttachments: 4 },
+        camera: { tonemap: 'none', antialias: 'none', bloom: 'off' },
+      }),
+    );
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const compiled = graph.compile({ device, surfaceSize: { width: 800, height: 600 } });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const info = compiled.value.inspect();
+    expect(info.passes.map((pass) => pass.name)).not.toContain('cluster-membership-producer');
+    expect(info.resources.map((resource) => resource.label)).not.toContain('hdrp-light-data');
+  });
   it('declares explicit output target domain and avoids alternate sRGB views', () => {
     const source = readFileSync(new URL('../render-pipeline.ts', import.meta.url), 'utf8');
     const postChainSource = readFileSync(
@@ -116,6 +457,25 @@ describe('typed built-in pipeline topology', () => {
     expect(source).not.toContain('viewFormats: [topology.surface.viewFormat]');
   });
 
+  it('forwards the output dither override into the fullscreen UBO write', () => {
+    const typedSource = readFileSync(
+      new URL('../typed-render-graph-primitives.ts', import.meta.url),
+      'utf8',
+    );
+    const dispatcherSource = readFileSync(
+      new URL('../render-graph-primitives.ts', import.meta.url),
+      'utf8',
+    );
+    expect(typedSource).toContain(
+      'paramsOverride: options.paramsTransform(frame.postProcessParams.get(options.shader))',
+    );
+    expect(dispatcherSource).toContain('paramsOverride?: Uint8Array');
+    expect(dispatcherSource).toContain(
+      'const data = paramsOverride ?? ctx.postProcessParams.get(shader);',
+    );
+    expect(dispatcherSource).toContain('input.paramsOverride,');
+  });
+
   it('declares stable JSON-safe output and observation inspection facts', () => {
     const source = readFileSync(new URL('../render-contract.ts', import.meta.url), 'utf8');
     for (const field of [
@@ -138,7 +498,7 @@ describe('typed built-in pipeline topology', () => {
     const compiled = compile(
       standardPipeline,
       topology('forgeax::standard', {
-        standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting: 'clustered', ssao: true },
+        standardProfile: { ...DEFAULT_STANDARD_PROFILE, renderPath: 'deferred', ssao: true },
       }),
     );
     expect(compiled.ok).toBe(true);
@@ -147,6 +507,7 @@ describe('typed built-in pipeline topology', () => {
     const names = info.passes.map((pass) => pass.name);
     const ordered = [
       'cluster-membership-producer',
+      'directional-shadow-observation',
       'g-buffer',
       'ssao-calc',
       'ssao-blur',
@@ -162,6 +523,8 @@ describe('typed built-in pipeline topology', () => {
     }
     expect(names.filter((name) => name.startsWith('point-shadow-'))).toHaveLength(6);
     expect(names.filter((name) => name.startsWith('shadowCascade'))).toHaveLength(4);
+    expect(names).toContain('directional-shadow-observation');
+    expect(names).toContain('linear-hdr-observation');
 
     const membership = info.passes.find((pass) => pass.name === 'cluster-membership-producer');
     expect(membership?.kind).toBe('compute');
@@ -185,11 +548,11 @@ describe('typed built-in pipeline topology', () => {
     const compiled = compile(
       standardPipeline,
       topology('forgeax::standard', {
-        standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting: 'clustered' },
+        standardProfile: { ...DEFAULT_STANDARD_PROFILE, renderPath: 'deferred' },
         config: { ssao: { enabled: false } },
         lane: {
           compute: false,
-          storageBuffer: false,
+          storageBuffer: true,
           multisample: false,
           maxColorAttachments: 8,
         },
@@ -245,7 +608,23 @@ describe('typed built-in pipeline topology', () => {
     expect(effect1?.dependencies).toContain('post-effect-copy-1');
   });
 
-  it('removes unsupported MSAA and composite post work on the fallback lane', () => {
+  it('admits the fullscreen post-effect chain atomically', () => {
+    const visited: string[] = [];
+    const pending = resolvePostProcessChainAdmission(['example::a', 'example::b'], (identity) => {
+      visited.push(identity);
+      return identity === 'example::a';
+    });
+    expect(pending).toEqual({ admitted: [], pending: true });
+    expect(visited).toEqual(['example::a', 'example::b']);
+
+    const ready = resolvePostProcessChainAdmission(['example::a', 'example::b'], () => true);
+    expect(ready).toEqual({
+      admitted: ['example::a', 'example::b'],
+      pending: false,
+    });
+  });
+
+  it('removes unsupported MSAA while retaining the CPU storage lane', () => {
     const compiled = compile(
       standardPipeline,
       topology('forgeax::standard', {
@@ -253,7 +632,7 @@ describe('typed built-in pipeline topology', () => {
         config: { postEffects: ['example::a'] },
         lane: {
           compute: false,
-          storageBuffer: false,
+          storageBuffer: true,
           multisample: false,
           maxColorAttachments: 4,
         },
@@ -263,7 +642,7 @@ describe('typed built-in pipeline topology', () => {
     if (!compiled.ok) return;
     const info = compiled.value.inspect();
     expect(info.resources.some((resource) => resource.label.includes('msaa'))).toBe(false);
-    expect(info.passes.some((pass) => pass.name.startsWith('post-effect-'))).toBe(false);
+    expect(info.passes.some((pass) => pass.name.startsWith('post-effect-'))).toBe(true);
   });
 
   it('declares one TAA producer and resolve for TAA demand', () => {
@@ -299,9 +678,12 @@ describe('typed built-in pipeline topology', () => {
 
   it('fails closed when TAA history imports are missing', () => {
     const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const standardLighting = zeroStandardLighting({ compute: true, storageBuffer: true });
+    if (!standardLighting.ok) throw standardLighting.error;
     const built = standardPipeline.build(
       {
         graph,
+        standardLighting: standardLighting.value,
         capabilities: { rgba16floatRenderable: true },
         projectGpuDriven: () => ok(undefined),
         contributeFeatures: () => ok(undefined),
@@ -326,7 +708,7 @@ describe('typed built-in pipeline topology', () => {
         temporal: { taa: true, motionBlur: true },
         lane: {
           compute: false,
-          storageBuffer: false,
+          storageBuffer: true,
           multisample: false,
           maxColorAttachments: 4,
         },
@@ -412,11 +794,11 @@ describe('typed built-in pipeline topology', () => {
     ).toHaveLength(0);
   });
 
-  it('returns a structured HDRP capability refusal before graph compilation', () => {
+  it('keeps deferred attachment admission independent from the Cluster transport', () => {
     const built = compile(
       standardPipeline,
       topology('forgeax::standard', {
-        standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting: 'clustered' },
+        standardProfile: { ...DEFAULT_STANDARD_PROFILE, renderPath: 'deferred' },
         lane: {
           compute: true,
           storageBuffer: true,
@@ -425,8 +807,7 @@ describe('typed built-in pipeline topology', () => {
         },
       }),
     );
-    expect(built.ok).toBe(false);
-    if (!built.ok) expect(built.error.code).toBe('hdrp-deferred-caps-insufficient');
+    expect(built.ok).toBe(true);
   });
 });
 

package/src/__tests__/urp-pipeline-targets.unit.test.ts

@@ -40,10 +40,10 @@ describe('urp render feature targets', () => {
     });
   });
 
-  it('keeps the surface target for non-storage-buffer LDR frames', () => {
+  it('publishes a float target for non-storage-buffer LDR frames', () => {
     expect(targets('none', 'none', false)?.[0]).toMatchObject({
       kind: 'scene-color',
-      format: 'bgra8unorm-srgb',
+      format: 'rgba16float',
       sampleCount: 1,
     });
   });

package/src/__tests__/visibility-resolver.unit.test.ts

@@ -82,4 +82,19 @@ describe('visibility resolver truth table', () => {
     expect(result.get(parent)?.intent).toBeUndefined();
     expect(result.get(child)?.effective).toBe('visible');
   });
+
+  it('invalidates the cached snapshot when visibility intent changes', () => {
+    const world = new World();
+    const parent = spawn(world, 'visible');
+    const child = spawn(world, 'inherited', parent);
+
+    const visible = resolveVisibility(world);
+    expect(visible.effective(child)).toBe('visible');
+
+    world.set(parent, Visibility, { state: VisibilityStateValue.hidden }).unwrap();
+
+    const hidden = resolveVisibility(world);
+    expect(hidden).not.toBe(visible);
+    expect(hidden.effective(child)).toBe('hidden');
+  });
 });

package/src/__tests__/volume-optics-oracle.unit.test.ts

@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const integrateShader = readFileSync(
+  fileURLToPath(new URL('../../../shader/src/volume/volume-integrate.wgsl', import.meta.url)),
+  'utf8',
+);
+
+const EPSILON = 1e-6;
+
+function clampExponent(value: number): number {
+  return Math.min(Math.max(value, -80), 80);
+}
+
+function beerLambert(extinction: number, distance: number, density: number): number {
+  const opticalDepth = Math.max(extinction * Math.max(distance, 0) * Math.max(density, 0), 0);
+  return Math.exp(-Math.min(opticalDepth, 80));
+}
+
+function henyeyGreenstein(cosTheta: number, anisotropy: number): number {
+  const g = Math.min(Math.max(anisotropy, -0.999), 0.999);
+  const denominator = Math.max(1 + g * g - 2 * g * cosTheta, EPSILON);
+  return (1 - g * g) / (4 * Math.PI * denominator ** 1.5);
+}
+
+describe('volumetric optics CPU oracle', () => {
+  it('requires the true volume integration shader owner', () => {
+    expect(integrateShader).toContain('fn hg');
+    expect(integrateShader).toContain('FOUR_PI');
+    expect(integrateShader).toContain('textureStore(resolved');
+    expect(integrateShader).not.toContain('apply_fog');
+  });
+
+  it('does not apply density twice to single-scatter radiance', () => {
+    expect(integrateShader).not.toContain('phase * sample.g * sample.r * (1.0 - transmittance)');
+    expect(integrateShader).toContain(
+      'let local_scatter = radiance * volume_params.albedo.xyz * phase *',
+    );
+    expect(integrateShader).toContain('VOLUME_LIGHT_PHASE_SCALE * (1.0 - local_transmittance) +');
+  });
+
+  it('converts the shared integrated-light basis once before normalized HG', () => {
+    expect(integrateShader).toContain('const VOLUME_LIGHT_PHASE_SCALE : f32 = FOUR_PI;');
+    expect(integrateShader).toContain('phase *\n        VOLUME_LIGHT_PHASE_SCALE *');
+  });
+
+  it('keeps empty density at identity transmittance', () => {
+    expect(beerLambert(2, 100, 0)).toBeCloseTo(1, 6);
+    expect(beerLambert(0, 100, 4)).toBeCloseTo(1, 6);
+  });
+
+  it('makes transmittance monotonic for increasing density', () => {
+    const samples = [0, 0.1, 0.5, 1, 4].map((density) => beerLambert(1.2, 3, density));
+    for (let index = 1; index < samples.length; index += 1) {
+      expect(samples[index]).toBeLessThanOrEqual((samples[index - 1] ?? 0) + EPSILON);
+    }
+    expect(samples.every(Number.isFinite)).toBe(true);
+    expect(samples.every((value) => value >= 0 && value <= 1)).toBe(true);
+  });
+
+  it('keeps phase finite and distinguishes forward and backward scattering', () => {
+    const isotropic = henyeyGreenstein(0, 0);
+    const forward = henyeyGreenstein(1, 0.7);
+    const backward = henyeyGreenstein(-1, 0.7);
+    expect(isotropic).toBeCloseTo(1 / (4 * Math.PI), 6);
+    expect(forward).toBeGreaterThan(backward);
+    expect([isotropic, forward, backward].every(Number.isFinite)).toBe(true);
+  });
+
+  it('clamps exponent input without producing NaN or Infinity', () => {
+    const values = [-Infinity, -120, 0, 120, Infinity].map((value) =>
+      Math.exp(clampExponent(value)),
+    );
+    expect(values.every(Number.isFinite)).toBe(true);
+    expect(values.every((value) => value > 0)).toBe(true);
+  });
+
+  it('cuts integration at the nearer depth or authored distance', () => {
+    const depthDistance = 4;
+    const maxDistance = 2;
+    expect(Math.min(depthDistance, maxDistance)).toBe(2);
+    expect(beerLambert(1, Math.min(depthDistance, maxDistance), 1)).toBeCloseTo(Math.exp(-2), 6);
+  });
+});