@forgeax/engine-render 0.1.29 → 0.1.31

package/src/__tests__/standard-pbr-artifact-assembly.unit.test.ts

@@ -1,6 +1,10 @@
 import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
 import { describe, expect, it } from 'vitest';
-import { assembleStandardPbrArtifact } from '../assembly/material/assembly';
+import {
+  assembleStandardPbrArtifact,
+  resolveMaterialShaderArtifact,
+  resolveStandardPbrArtifact,
+} from '../assembly/material/assembly';
 
 const source = '@vertex fn vs_main() -> @builtin(position) vec4<f32> { return vec4(0.0); }';
 
@@ -23,6 +27,24 @@ describe('Standard PBR artifact assembly', () => {
     );
   });
 
+  it('retains shader UV aliases beyond the minimum geometry receipt after recovery', () => {
+    const receipt = createStandardPbrArtifactReceipt();
+    const wgsl = `struct VsIn { @location(2) uv: vec2<f32>, @location(12) uv7: vec2<f32>, }
+@vertex fn vs_scene_index(input: VsIn) -> @builtin(position) vec4<f32> { return vec4(input.uv, 0., 1.); }`;
+    const artifact = resolveMaterialShaderArtifact(
+      'forgeax::default-standard-pbr',
+      {
+        findMaterialArtifact: () => ({
+          ok: true,
+          value: { source: wgsl, paramSchema: [], receipt },
+        }),
+      } as unknown as Parameters<typeof resolveMaterialShaderArtifact>[1],
+      { address: 'scene-index' },
+    );
+    expect(artifact?.uvSetCount).toBe(8);
+    expect(artifact?.receipt).toBe(receipt);
+  });
+
   it('adds the skin palette receipt facts for the skinned registry entry', () => {
     const artifact = assembleStandardPbrArtifact('forgeax::default-standard-pbr-skin', source);
     const receipt = createStandardPbrArtifactReceipt(true);
@@ -35,4 +57,219 @@ describe('Standard PBR artifact assembly', () => {
   it('rejects unsupported shader identifiers without manufacturing an artifact', () => {
     expect(assembleStandardPbrArtifact('forgeax::default-unlit', source)).toBeUndefined();
   });
+
+  it('fails closed when a geometry-specific color fact has no matching producer receipt', () => {
+    expect(
+      assembleStandardPbrArtifact(
+        'forgeax::default-standard-pbr',
+        { source, paramSchema: [] },
+        { vertexColorAvailable: true },
+      ),
+    ).toBeUndefined();
+    expect(
+      assembleStandardPbrArtifact(
+        'forgeax::default-standard-pbr',
+        { source, paramSchema: [], receipt: createStandardPbrArtifactReceipt() },
+        { vertexColorAvailable: true },
+      ),
+    ).toBeUndefined();
+  });
+
+  it('selects the published COLOR_0 ABI and keeps colored/plain identities apart', () => {
+    const plain = createStandardPbrArtifactReceipt();
+    const colored = createStandardPbrArtifactReceipt(false, true);
+    const shader = {
+      findMaterialArtifact: () => ({
+        ok: true as const,
+        value: { source: 'fallback', paramSchema: [], receipt: plain },
+      }),
+      materialShaderManifestEntries: () => [
+        {
+          identifier: 'forgeax::default-standard-pbr',
+          sourcePath: 'default-standard-pbr.wgsl',
+          composedWgsl: 'fallback',
+          paramSchema: '[]',
+          variants: [
+            {
+              definesKey: 'VERTEX_COLOR_AVAILABLE=false',
+              defines: { VERTEX_COLOR_AVAILABLE: false },
+              composedWgsl: 'plain-variant',
+              receipt: plain,
+            },
+            {
+              definesKey: 'VERTEX_COLOR_AVAILABLE=true',
+              defines: { VERTEX_COLOR_AVAILABLE: true },
+              composedWgsl: 'colored-variant',
+              receipt: colored,
+            },
+          ],
+        },
+      ],
+    } as unknown as Parameters<typeof resolveStandardPbrArtifact>[1];
+
+    const coloredArtifact = resolveStandardPbrArtifact('forgeax::default-standard-pbr', shader, {
+      vertexColorAvailable: true,
+    });
+    const plainArtifact = resolveStandardPbrArtifact('forgeax::default-standard-pbr', shader, {
+      vertexColorAvailable: false,
+    });
+
+    expect(coloredArtifact?.wgsl).toBe('colored-variant');
+    expect(coloredArtifact?.receipt).toEqual(colored);
+    expect(coloredArtifact?.receipt?.vertexInputs).toContainEqual({
+      semantic: 'color',
+      location: 13,
+      format: 'float32x4',
+    });
+    expect(plainArtifact?.wgsl).toBe('plain-variant');
+    expect(plainArtifact?.receipt).toEqual(plain);
+    expect(plainArtifact?.receipt?.vertexInputs).not.toContainEqual(
+      expect.objectContaining({ semantic: 'color' }),
+    );
+    expect(coloredArtifact?.receipt?.receiptIdentity).not.toBe(
+      plainArtifact?.receipt?.receiptIdentity,
+    );
+
+    const custom = resolveMaterialShaderArtifact(
+      'game::custom-surface',
+      {
+        findMaterialArtifact: () => ({
+          ok: true as const,
+          value: { source: 'custom-fallback', paramSchema: [], receipt: plain },
+        }),
+        materialShaderManifestEntries: () => [
+          {
+            identifier: 'game::custom-surface',
+            sourcePath: 'custom.wgsl',
+            composedWgsl: 'custom-fallback',
+            paramSchema: '[]',
+            variants: [
+              {
+                definesKey: 'VERTEX_COLOR_AVAILABLE=true',
+                defines: { VERTEX_COLOR_AVAILABLE: true },
+                composedWgsl: 'custom-colored',
+                receipt: colored,
+              },
+            ],
+          },
+        ],
+      } as unknown as Parameters<typeof resolveMaterialShaderArtifact>[1],
+      { vertexColorAvailable: true },
+    );
+    expect(custom?.wgsl).toBe('custom-colored');
+    expect(custom?.receipt).toEqual(colored);
+  });
+
+  it('routes built-in Standard shadow requests through the shadow-caster artifact', () => {
+    const rigidPlain = createStandardPbrArtifactReceipt();
+    const rigidColor = createStandardPbrArtifactReceipt(false, true);
+    const skinPlain = createStandardPbrArtifactReceipt(true);
+    const shadowEntry = {
+      identifier: 'forgeax::default-shadow-caster',
+      sourcePath: 'default-shadow-caster.wgsl',
+      composedWgsl: 'shadow-primary',
+      paramSchema: '[]',
+      variants: [
+        {
+          definesKey: 'SKINNING_DISABLED=true+VERTEX_COLOR_AVAILABLE=false',
+          defines: { SKINNING_DISABLED: true, VERTEX_COLOR_AVAILABLE: false },
+          composedWgsl: 'shadow-rigid-plain-with-fs_shadow',
+          receipt: rigidPlain,
+        },
+        {
+          definesKey: 'SKINNING_DISABLED=true+VERTEX_COLOR_AVAILABLE=true',
+          defines: { SKINNING_DISABLED: true, VERTEX_COLOR_AVAILABLE: true },
+          composedWgsl: 'shadow-rigid-color-with-fs_shadow',
+          receipt: rigidColor,
+        },
+        {
+          definesKey: 'SKINNING_DISABLED=false+VERTEX_COLOR_AVAILABLE=false',
+          defines: { SKINNING_DISABLED: false, VERTEX_COLOR_AVAILABLE: false },
+          composedWgsl: 'shadow-skin-plain-with-fs_shadow',
+          receipt: skinPlain,
+        },
+      ],
+    };
+    const standardEntry = {
+      identifier: 'forgeax::default-standard-pbr',
+      sourcePath: 'default-standard-pbr.wgsl',
+      composedWgsl: 'standard-forward-without-fs_shadow',
+      paramSchema: '[]',
+      variants: [],
+    };
+
+    for (const entries of [
+      [standardEntry, shadowEntry],
+      [shadowEntry, standardEntry],
+    ]) {
+      const shader = {
+        findMaterialArtifact: (identifier: string) => ({
+          ok: true as const,
+          value: {
+            source: identifier === 'forgeax::default-shadow-caster' ? 'shadow-primary' : 'standard',
+            paramSchema: [],
+            receipt: rigidPlain,
+          },
+        }),
+        materialShaderManifestEntries: () => entries,
+      } as unknown as Parameters<typeof resolveMaterialShaderArtifact>[1];
+
+      const rigidColorArtifact = resolveMaterialShaderArtifact(
+        'forgeax::default-standard-pbr',
+        shader,
+        {
+          address: 'scene-index',
+          deformation: 'rigid',
+          pass: 'shadow',
+          vertexColorAvailable: true,
+        },
+      );
+      const skinPlainArtifact = resolveMaterialShaderArtifact(
+        'forgeax::default-standard-pbr-skin',
+        shader,
+        { address: 'scene-index', deformation: 'skin', pass: 'shadow' },
+      );
+
+      expect(rigidColorArtifact?.material).toBe('forgeax::default-shadow-caster');
+      expect(rigidColorArtifact?.fragmentEntry).toBe('fs_shadow');
+      expect(rigidColorArtifact?.wgsl).toBe('shadow-rigid-color-with-fs_shadow');
+      expect(rigidColorArtifact?.receipt).toEqual(rigidColor);
+      expect(skinPlainArtifact?.material).toBe('forgeax::default-shadow-caster');
+      expect(skinPlainArtifact?.wgsl).toBe('shadow-skin-plain-with-fs_shadow');
+      expect(skinPlainArtifact?.receipt).toEqual(skinPlain);
+    }
+  });
+  it('reuses immutable publications and invalidates changed registry or manifest identities', () => {
+    const receipt = createStandardPbrArtifactReceipt();
+    let entry = { source, paramSchema: [], receipt };
+    let manifest = {
+      identifier: 'game::surface',
+      sourcePath: 'surface.wgsl',
+      composedWgsl: source,
+      paramSchema: '[]',
+      variants: [{ definesKey: '', defines: {}, composedWgsl: 'first', receipt }],
+    };
+    const registry = {
+      findMaterialArtifact: () => ({ ok: true, value: entry }),
+      materialShaderManifestEntries: () => [manifest].values(),
+    } as unknown as Parameters<typeof resolveMaterialShaderArtifact>[1];
+    const resolve = () =>
+      resolveMaterialShaderArtifact('game::surface', registry, { address: 'scene-index' });
+    const first = resolve();
+    expect(first?.wgsl).toBe('first');
+    expect(resolve()).toBe(first);
+    expect(
+      resolveMaterialShaderArtifact('game::surface', registry, { address: 'direct' })?.vertexEntry,
+    ).toBe(receipt.directEntry);
+    manifest = {
+      ...manifest,
+      variants: [{ definesKey: '', defines: {}, receipt, composedWgsl: 'second' }],
+    };
+    const second = resolve();
+    expect(second).not.toBe(first);
+    expect(second?.wgsl).toBe('second');
+    expect(resolve()).toBe(second);
+    entry = { ...entry };
+    expect(resolve()).not.toBe(second);
+  });
 });

package/src/__tests__/standard-profile-oracle.unit.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { freezeRenderProfile, validateRenderProfile } from '../assembly/renderer-facade';
 import { AUTO_EXPOSURE_PRESET_V1 } from '../pipeline/standard-output/auto-exposure/preset';
 import {
   DEFAULT_STANDARD_PROFILE,
@@ -77,3 +78,29 @@ describe('Standard profile oracle', () => {
     expect(AUTO_EXPOSURE_PRESET_V1.histogramBins).toBe(256);
   });
 });
+
+describe('SSAO public profile', () => {
+  it('preserves immutable AO parameters through the public profile', () => {
+    const ssao = { radius: 0.8, bias: 0.01, intensity: 1.5, quality: 'low' as const };
+    const profile = { ...DEFAULT_STANDARD_PROFILE, renderPath: 'deferred' as const, ssao };
+    expect(validateRenderProfile(profile)).toBeUndefined();
+    const frozen = freezeRenderProfile(profile);
+    ssao.radius = 2;
+    expect(frozen.ssao).toEqual({ radius: 0.8, bias: 0.01, intensity: 1.5, quality: 'low' });
+    expect(Object.isFrozen(frozen.ssao)).toBe(true);
+  });
+  it('rejects unavailable normals and malformed parameter objects', () => {
+    expect(validateRenderProfile({ ...DEFAULT_STANDARD_PROFILE, ssao: true })).toContain(
+      'deferred',
+    );
+    for (const ssao of [[], null, { quality: 'ultra' }, { radius: Number.NaN }, { other: 1 }]) {
+      expect(
+        validateRenderProfile({
+          ...DEFAULT_STANDARD_PROFILE,
+          renderPath: 'deferred',
+          ssao,
+        } as unknown as StandardProfile),
+      ).toBeTypeOf('string');
+    }
+  });
+});

package/src/__tests__/taa-coverage-edge.dawn.test.ts

@@ -92,6 +92,11 @@ async function resolveCoverage(source: string, edge: boolean) {
             sampler: { type: 'filtering' as const },
           })),
           { binding: 8, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'uniform' } },
+          {
+            binding: 11,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'unfilterable-float' as const, viewDimension: '2d' as const },
+          },
         ],
       })
       .unwrap();
@@ -124,6 +129,7 @@ async function resolveCoverage(source: string, edge: boolean) {
           { binding: 8, resource: { kind: 'buffer', value: { buffer: params } } },
           { binding: 9, resource: { kind: 'textureView', value: age.view } },
           { binding: 10, resource: { kind: 'textureView', value: age.view } },
+          { binding: 11, resource: { kind: 'textureView', value: currentTemporal.view } },
         ],
       })
       .unwrap();

package/src/__tests__/taa-neighborhood-equivalence.dawn.test.ts

@@ -522,7 +522,7 @@ async function runPair(
             visibility: GPU_SHADER_STAGE_FRAGMENT,
             texture: { sampleType: 'float' as const, viewDimension: '2d' as const },
           })),
-          ...[4, 6, 10].map((binding) => ({
+          ...[4, 6, 10, 11].map((binding) => ({
             binding,
             visibility: GPU_SHADER_STAGE_FRAGMENT,
             texture: { sampleType: 'unfilterable-float' as const, viewDimension: '2d' as const },
@@ -586,6 +586,10 @@ async function runPair(
           { binding: 8, resource: { kind: 'buffer', value: { buffer: params } } },
           { binding: 9, resource: { kind: 'textureView', value: historyStability.view } },
           { binding: 10, resource: { kind: 'textureView', value: secondaryReactivity.view } },
+          // Ordinary TAA does not allocate an output-domain coverage target.
+          // The production resolve still declares the stable binding and uses
+          // this current-temporal fallback while hasCurrentCoverage is zero.
+          { binding: 11, resource: { kind: 'textureView', value: currentTemporal.view } },
         ],
       })
       .unwrap();

package/src/__tests__/taa-stability-feedback.ts

@@ -162,6 +162,7 @@ export async function verifyTaaStabilityFeedback(
             { binding: 8, resource: { kind: 'buffer', value: { buffer: params } } },
             { binding: 9, resource: { kind: 'textureView', value: state.stability[index].view } },
             { binding: 10, resource: { kind: 'textureView', value: secondary.view } },
+            { binding: 11, resource: { kind: 'textureView', value: temporal.view } },
           ],
         })
         .unwrap();

package/src/__tests__/temporal-reset-matrix.unit.test.ts

@@ -97,8 +97,8 @@ describe('TemporalView reset matrix', () => {
     expect(next.jitter).toEqual(HALTON_23_8[1]);
   });
 
-  it('records the unreachable TAAU sibling as dependency-deferred', () => {
-    expect(TEMPORAL_TAAU_DEPENDENCY_STATUS).toBe('dependency-deferred');
+  it('records the renderer TAAU owner as available while volume stays deferred', () => {
+    expect(TEMPORAL_TAAU_DEPENDENCY_STATUS).toBe('available');
     expect(VOLUME_TAAU_DEPENDENCY.status).toBe('dependency-deferred');
     expect(VOLUME_TAAU_DEPENDENCY.siblingFeature).toBe('feat-20260831-taau-dynamic-resolution');
     expect(VOLUME_TAAU_DEPENDENCY.candidateShas).toHaveLength(2);

package/src/__tests__/temporal-view.unit.test.ts

@@ -39,6 +39,23 @@ describe('TemporalView v1', () => {
     expect(view.jitterCancellationUv).toEqual([jitter[0] / 1280, jitter[1] / 720]);
   });
 
+  it('uses the fixed internal extent for TAAU jitter while preserving output dimensions', () => {
+    const view = createTemporalView({
+      antialias: 'taa',
+      width: 200,
+      height: 150,
+      internalWidth: 128,
+      internalHeight: 96,
+      frameIndex: 1,
+    });
+    const jitter = (HALTON_23_8[1] ?? [0, 0]) as readonly [number, number];
+    expect(view.input.width).toBe(200);
+    expect(view.input.height).toBe(150);
+    expect(view.input.internalWidth).toBe(128);
+    expect(view.input.internalHeight).toBe(96);
+    expect(view.jitterCancellationUv).toEqual([jitter[0] / 128, jitter[1] / 96]);
+  });
+
   it.each([
     ['first-frame', undefined, 'first-frame'],
     ['resize', { width: 640, height: 360 }, 'resize'],

package/src/__tests__/transmission-prewarm.unit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import {
   type MaterialShaderManifestEntry,
+  selectGpuDrivenSceneIndexVariant,
   selectHdrpPbrPrewarmVariants,
   selectProbePrewarmVariants,
   selectStandardPbrTransmissionPrewarmVariants,
@@ -57,6 +58,16 @@ function transmissionVariant(definesKey: string, transmission: boolean) {
   };
 }
 
+function coverageTransmissionVariant(definesKey: string, transmission: boolean) {
+  const base = transmissionVariant(definesKey, transmission);
+  return {
+    ...base,
+    definesKey: `COVERAGE_ONLY=true+${definesKey}`,
+    defines: { ...base.defines, COVERAGE_ONLY: true },
+    composedWgsl: `coverage-${transmission}`,
+  };
+}
+
 function probeTransmissionVariant(definesKey: string, transmission: boolean) {
   const base = transmissionVariant(definesKey, transmission);
   return {
@@ -82,6 +93,18 @@ describe('Standard transmission exact-key prewarm selection', () => {
       'TRANSMISSION_AVAILABLE=true',
     );
   });
+
+  it('keeps coverage-only variants out of the ordinary prewarm set', () => {
+    const entry = standardEntry([
+      coverageTransmissionVariant(falseKey, false),
+      transmissionVariant(falseKey, false),
+      coverageTransmissionVariant(trueKey, true),
+      transmissionVariant(trueKey, true),
+    ]);
+    expect(
+      selectStandardPbrTransmissionPrewarmVariants(entry, true).map((item) => item.definesKey),
+    ).toEqual([falseKey, trueKey]);
+  });
 });
 
 describe('HDRP PBR capability prewarm selection', () => {
@@ -170,3 +193,37 @@ describe('probe material module prewarm capability selection', () => {
     expect(selected.map((candidate) => candidate.definesKey)).toEqual([goodKey]);
   });
 });
+
+describe('GPU-driven scene-index prewarm capability selection', () => {
+  it('uses the non-reflection-fallback variant for the dedicated scene-index ABI', () => {
+    const makeVariant = (reflectionFallback: boolean) => {
+      const defines = {
+        CLUSTER_FORWARD_AVAILABLE: false,
+        DIRECTIONAL_PCSS_AVAILABLE: true,
+        EXTENDED_LIGHTING_AVAILABLE: true,
+        GPU_DRIVEN_SCENE_INDEX_AVAILABLE: true,
+        PROBE_BLEND_AVAILABLE: false,
+        PROJECTOR_AVAILABLE: true,
+        REFLECTION_FALLBACK_AVAILABLE: reflectionFallback,
+        STORAGE_BUFFER_AVAILABLE: true,
+        TRANSMISSION_AVAILABLE: false,
+        VERTEX_COLOR_AVAILABLE: false,
+      };
+      return {
+        defines,
+        definesKey: Object.entries(defines)
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([name, value]) => `${name}=${value}`)
+          .join('+'),
+        composedWgsl: JSON.stringify(defines),
+      };
+    };
+    const selected = selectGpuDrivenSceneIndexVariant(
+      standardEntry([makeVariant(true), makeVariant(false)]),
+      true,
+      true,
+      true,
+    );
+    expect(selected?.defines.REFLECTION_FALLBACK_AVAILABLE).toBe(false);
+  });
+});

package/src/__tests__/volumetric-fog-stage-readback.dawn.test.ts

@@ -73,7 +73,13 @@ async function requestDevice(): Promise<RhiDevice> {
   return device.value;
 }
 
-async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadbacks> {
+async function runInjectReadback(
+  sceneDepthClear = 1,
+  densitySource: number | 'height-gradient' | 'depth-gradient' = 255,
+  heightOffset = 0,
+  frameIndex = 0,
+  slopedShadow = false,
+): Promise<VolumeStageReadbacks> {
   const device = await requestDevice();
   const moduleResult = await createShaderModule(device, {
     code: manifestShader('fn volume_inject'),
@@ -227,22 +233,26 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   const viewData = new Float32Array(240);
   for (const offset of [0, 28, 44, 60, 76, 92, 196, 212]) identityMatrix(viewData, offset);
   viewData[24] = 0;
-  viewData[25] = 0;
+  viewData[25] = heightOffset;
+  viewData[44 + 13] = heightOffset;
   viewData[26] = -1;
-  viewData[124] = 0;
+  viewData[124] = slopedShadow ? 1 : 0;
+  viewData[108] = 10;
+  if (slopedShadow) viewData[28 + 2] = 0.5;
   viewData[228] = 0.1;
   viewData[229] = 10;
   viewData[230] = 0;
   viewData[235] = 1;
   const paramsData = new Float32Array(32);
-  paramsData.set([-1, -1, 0.1, 0], 0);
-  paramsData.set([1, 1, 0.9, 0], 4);
+  paramsData.set([-1, heightOffset - 1, 0.1, 0], 0);
+  paramsData.set([1, heightOffset + 1, 0.9, 0], 4);
   paramsData.set([1, 1, 1, 0], 8);
   paramsData.set([1, 1, 1, 0], 12);
   paramsData.set([0, 0, 0, 0], 16);
   paramsData.set([0, -1, 0, 0], 20);
   paramsData.set([1, 1, 1, 0], 24);
   paramsData.set([2, 0, 0, 0], 28);
+  paramsData[23] = frameIndex;
   const lightData = new Uint8Array(CLUSTER_LIGHT_DATA_BYTES);
   const clusterUniformData = new Float32Array(8);
   const clusterGrid = new Uint32Array(clusterUniformData.buffer);
@@ -261,7 +271,21 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   if (!viewWrite.ok || !paramsWrite.ok || !lightDataWrite.ok || !clusterUniformWrite.ok)
     throw new Error('Dawn volume stage readback unavailable: uniform upload failed');
   const densityData = new Uint8Array((BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE);
-  densityData.fill(255);
+  for (let z = 0; z < SIZE; z++)
+    for (let y = 0; y < SIZE; y++)
+      for (let x = 0; x < SIZE; x++) {
+        const value =
+          densitySource === 'height-gradient'
+            ? Math.round((y / (SIZE - 1)) * 255)
+            : densitySource === 'depth-gradient'
+              ? Math.round((z / (SIZE - 1)) * 255)
+              : densitySource;
+        densityData.fill(
+          value,
+          ((z * SIZE + y) * SIZE + x) * 4,
+          ((z * SIZE + y) * SIZE + x + 1) * 4,
+        );
+      }
   const densityWrite = device.queue.writeTexture(
     { texture: densityTexture.value },
     densityData,
@@ -438,7 +462,7 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
       colorAttachments: [],
       depthStencilAttachment: {
         view,
-        depthClearValue: index === 0 ? sceneDepthClear : 1,
+        depthClearValue: index === 0 ? sceneDepthClear : slopedShadow ? 0.5 : 1,
         depthLoadOp: 'clear',
         depthStoreOp: 'store',
       },
@@ -520,6 +544,22 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
 }
 
 describe('volumetric fog production stage readback on Dawn', () => {
+  it('keeps static shadow visibility stable across renderer frame phases', async () => {
+    const first = await runInjectReadback(1, 255, 0, 0, true);
+    const next = await runInjectReadback(1, 255, 0, 1, true);
+    expect(first.inject.red.some((value) => value === 0)).toBe(true);
+    expect(first.inject.red.some((value) => value > 0.9)).toBe(true);
+    expect(next.inject).toEqual(first.inject);
+  });
+  it('keeps a static depth-density field stable across renderer frame phases', async () => {
+    const first = await runInjectReadback(1, 'depth-gradient', 0, 0);
+    for (const frameIndex of [1, 7]) {
+      const next = await runInjectReadback(1, 'depth-gradient', 0, frameIndex);
+      expect(next.integrate.alpha).toEqual(first.integrate.alpha);
+      expect(next.integrate.red).toEqual(first.integrate.red);
+    }
+    expect(first.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.4), 2);
+  });
   it('injects raw density then resolves a 2d integrated volume', async () => {
     const values = await runInjectReadback();
     // biome-ignore lint/suspicious/noConsole: stage readback is machine evidence
@@ -542,12 +582,21 @@ describe('volumetric fog production stage readback on Dawn', () => {
   it('clips the final ray step to the scene-depth segment', async () => {
     const values = await runInjectReadback(0.57);
     const transmittance = values.integrate.alpha[0];
-    // The fixture uploads an all-white source texture. The authored Three
-    // smoke expression therefore evaluates to 2 * 1.5^3 - 1 = 5.75 before
-    // Beer-Lambert consumes it; only the final 0.47-unit segment is allowed
-    // to contribute after the scene-depth clip.
-    const sourceDensity = 2 * 1.5 ** 3 - 1;
-    expect(transmittance).toBeCloseTo(Math.exp(-0.47 * sourceDensity), 2);
+    // White encodes density one; integrate only the visible 0.47-unit segment.
+    expect(transmittance).toBeCloseTo(Math.exp(-0.47), 2);
     expect(values.integrate.red[0]).toBeGreaterThan(0);
   });
+  it.each([0, 64, 128])('preserves authored uniform density %s/255', async (densityByte) => {
+    const values = await runInjectReadback(0.57, densityByte);
+    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp((-0.47 * densityByte) / 255), 2);
+    if (densityByte === 0) expect(values.integrate.red.every((value) => value === 0)).toBe(true);
+  });
+
+  it.each([
+    0, 20,
+  ])('maps height density through world bounds translated by %s', async (heightOffset) => {
+    const values = await runInjectReadback(0.57, 'height-gradient', heightOffset);
+    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.47), 2);
+    expect(values.integrate.alpha[(SIZE - 1) * SIZE]).toBeCloseTo(1, 3);
+  });
 });

package/src/__tests__/volumetric-fog-topology.unit.test.ts

@@ -34,9 +34,9 @@ describe('volumetric fog RenderGraph topology', () => {
     expect(composite).toContain('abs(neighbor.a - center.a) * 6.0');
   });
 
-  it('uses the pinned twelve-step ray integration while retaining packed visibility depth', () => {
+  it('derives deterministic integration density from the authored froxel depth', () => {
     const integrate = shaderSource('volume-integrate.wgsl');
-    expect(integrate).toContain('let ray_step_count = 12u;');
+    expect(integrate).toContain('let ray_step_count = visibility_depth;');
     expect(integrate).toContain('for (var step = 0u; step < ray_step_count; step = step + 1u)');
     expect(integrate).toContain('let visibility_depth = max(textureNumLayers(froxel) * 4u, 1u);');
   });
@@ -44,7 +44,7 @@ describe('volumetric fog RenderGraph topology', () => {
   it('keeps the Beer-Lambert extinction input physically non-negative', () => {
     const integrate = shaderSource('volume-integrate.wgsl');
     expect(integrate).toContain(
-      'let density_value = max(volume_scattering_density(world_position, frame_index), 0.0);',
+      'let density_value = max(volume_scattering_density(world_position), 0.0);',
     );
   });
 
@@ -130,8 +130,8 @@ describe('volumetric fog RenderGraph topology', () => {
     expect(shaderSource('volume-inject.wgsl')).toContain('fn ray_box_interval');
     expect(shaderSource('volume-inject.wgsl')).toContain('view.inverseViewProj');
     expect(shaderSource('volume-inject.wgsl')).not.toContain('textureSampleLevel(density');
-    expect(shaderSource('volume-inject.wgsl')).toContain('stratified32');
-    expect(shaderSource('volume-inject.wgsl')).toContain('dither_unorm8');
+    expect(shaderSource('volume-inject.wgsl')).not.toContain('stratified32');
+    expect(shaderSource('volume-inject.wgsl')).not.toContain('dither_unorm8');
     expect(shaderSource('volume-integrate.wgsl')).toContain('exp(-sigma_scale');
     expect(shaderSource('volume-integrate.wgsl')).toContain('textureSampleLevel(froxel');
     expect(shaderSource('volume-integrate.wgsl')).toContain('textureStore(resolved');
@@ -159,8 +159,8 @@ describe('volumetric fog RenderGraph topology', () => {
     const integrate = shaderSource('volume-integrate.wgsl');
     expect(inject).toContain('(f32(logical_slice) + 0.5) / f32(logical_depth)');
     expect(inject).not.toContain('depth_phase');
-    expect(integrate).toContain('fn stratified32');
-    expect(integrate).toContain('segment_start + segment_length * depth_phase');
+    expect(integrate).not.toContain('fn stratified32');
+    expect(integrate).toContain('segment_start + segment_length * 0.5');
   });
 
   it('keeps temporal history graph-owned and slot-selectable', () => {

package/src/assembly/atmosphere-shader-prewarm.ts

@@ -2,7 +2,7 @@ import { RhiError, type ShaderModule } from '@forgeax/engine-rhi';
 import type { ManifestEntry } from '@forgeax/engine-types';
 import type { AtmosphereShaderSources } from '../render-contract';
 
-/** Admit and compile the complete analytic-atmosphere shader pair atomically. */
+/** Admit and compile the complete analytic-atmosphere shader programs atomically. */
 export async function prewarmAtmosphereShaders(
   entries: readonly ManifestEntry[],
   compile: (label: string, source: string) => Promise<ShaderModule>,
@@ -11,6 +11,7 @@ export async function prewarmAtmosphereShaders(
   const stages = [
     ['cube', 'atmosphere_cube', 'atmosphere_cubemap_vs'],
     ['background', 'atmosphere_background', 'atmosphere_background_vs'],
+    ['ibl', 'atmosphere_ibl', 'atmosphere_ibl_vs'],
   ] as const;
   const resolved = stages.map(([stage, label, entryPoint]) => ({
     stage,
@@ -22,7 +23,7 @@ export async function prewarmAtmosphereShaders(
   if (missing !== undefined) {
     throw new RhiError({
       code: 'shader-compile-failed',
-      expected: 'shader manifest contains both analytic-atmosphere utility entries',
+      expected: 'shader manifest contains all analytic-atmosphere utility entries',
       hint: `add the package-owned WGSL entry for '${missing.label}' to the engine shader manifest`,
     });
   }