@forgeax/engine-render 0.1.32 → 0.1.33

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

@@ -3,6 +3,7 @@ import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
 import { buildEngineShaderManifest } from '@forgeax/engine-vite-plugin-shader';
 import { describe, expect, it } from 'vitest';
 import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../light-buffer-layout';
+import { VOLUMETRIC_FOG_PARAMS_BYTES } from '../volume/resources';
 
 const MAP_READ = 0x0001;
 const BUFFER_COPY_DST = 0x0008;
@@ -19,6 +20,13 @@ const BYTES_PER_PIXEL = 8;
 const MAX_CLUSTER_LIGHTS = 256;
 const CLUSTER_LIGHT_DATA_BYTES = MAX_CLUSTER_LIGHTS * BYTES_PER_DIRECT_LIGHT_SLOT;
 const CLUSTER_UNIFORM_BYTES = 32;
+const VOLUME_BOUNDS_MIN_Z = 0.1;
+const VOLUME_BOUNDS_MAX_Z = 0.9;
+const NON_UNIFORM_BOUNDS_MAX_Z = 8.1;
+const MAX_NON_UNIFORM_BEER_ERROR = 0.001;
+const NON_UNIFORM_EXTINCTION = 0.05;
+const MIN_NON_UNIFORM_REFERENCE_SEPARATION = 0.05;
+const MIN_NON_UNIFORM_GPU_SEPARATION = 0.05;
 const engineManifest = await buildEngineShaderManifest();
 
 interface StageValues {
@@ -33,6 +41,106 @@ interface VolumeStageReadbacks {
   readonly integrate: StageValues;
 }
 
+interface StageReadbackOptions {
+  readonly sceneDepthClear?: number;
+  readonly densityByte?: number;
+  /** Optional RGBA8 density field for the production integrate stage. */
+  readonly densityData?: Uint8Array;
+  readonly boundsMinZ?: number;
+  readonly boundsMaxZ?: number;
+  readonly maxDistance?: number;
+  readonly viewDepthScale?: number;
+  readonly extinction?: number;
+  readonly frameIndex?: number;
+  /** Depth clear used by the stable shadow receiver fixture. */
+  readonly shadowDepthClear?: number;
+  /** Unshadowed punctual light isolates ray integration from packed visibility. */
+  readonly localLight?: 'point' | 'spot';
+  /** Uniform-step diagnostic; omitted means the untouched production shader. */
+  readonly integratorStepCount?: number;
+}
+
+interface DensityField {
+  readonly data: Uint8Array;
+  readonly zRed: readonly number[];
+}
+
+function createNonUniformDensityField(redValues?: readonly number[]): DensityField {
+  const data = new Uint8Array(4 * SIZE * SIZE * SIZE);
+  const zRed: number[] = [];
+  for (let z = 0; z < SIZE; z += 1) {
+    // Keep X/Y constant. The default field changes only the first Z texel;
+    // the fine-density probe supplies a faster, seam-matched sequence.
+    // The exercised camera ray crosses the first-to-second texel transition
+    // under all three production density scales, so flattening the field to
+    // its first texel produces a measurable, independently falsifiable result.
+    const red = redValues?.[z] ?? (z === 0 ? 128 : 255);
+    zRed.push(red / 255);
+    for (let y = 0; y < SIZE; y += 1) {
+      for (let x = 0; x < SIZE; x += 1) {
+        const offset = ((z * SIZE + y) * SIZE + x) * 4;
+        data[offset] = red;
+        data[offset + 1] = 255;
+        data[offset + 2] = 255;
+        data[offset + 3] = 255;
+      }
+    }
+  }
+  return { data, zRed };
+}
+
+function createFlattenedDensityField(field: DensityField): DensityField {
+  const red = Math.round((field.zRed[0] ?? 0) * 255);
+  const data = new Uint8Array(4 * SIZE * SIZE * SIZE);
+  for (let z = 0; z < SIZE; z += 1) {
+    for (let y = 0; y < SIZE; y += 1) {
+      for (let x = 0; x < SIZE; x += 1) {
+        const offset = ((z * SIZE + y) * SIZE + x) * 4;
+        data[offset] = red;
+        data[offset + 1] = 255;
+        data[offset + 2] = 255;
+        data[offset + 3] = 255;
+      }
+    }
+  }
+  return { data, zRed: Array.from({ length: SIZE }, () => red / 255) };
+}
+
+function sampleClampedLinear(values: readonly number[], coordinate: number): number {
+  const scaled = coordinate * values.length - 0.5;
+  const lower = Math.floor(scaled);
+  const upper = lower + 1;
+  const interpolation = scaled - lower;
+  const clampIndex = (index: number): number => Math.max(0, Math.min(values.length - 1, index));
+  const lowerValue = values[clampIndex(lower)] ?? 0;
+  const upperValue = values[clampIndex(upper)] ?? 0;
+  return lowerValue + (upperValue - lowerValue) * interpolation;
+}
+
+function nonUniformScatteringDensity(field: DensityField, worldZ: number): number {
+  let grain = sampleClampedLinear(field.zRed, (worldZ * 0.1) % 1) + 0.5;
+  grain *= sampleClampedLinear(field.zRed, (worldZ * 0.05) % 1) + 0.5;
+  grain *= sampleClampedLinear(field.zRed, (worldZ * 0.02) % 1) + 0.5;
+  return Math.max(2 * grain - 1, 0);
+}
+
+function nonUniformBeerReference(
+  field: DensityField,
+  extinction = 1,
+  sampleCount = 16_384,
+  boundsMinZ = VOLUME_BOUNDS_MIN_Z,
+  boundsMaxZ = VOLUME_BOUNDS_MAX_Z,
+): number {
+  const interval = boundsMaxZ - boundsMinZ;
+  const segmentLength = interval / sampleCount;
+  let opticalDepth = 0;
+  for (let sample = 0; sample < sampleCount; sample += 1) {
+    const worldZ = boundsMinZ + (sample + 0.5) * segmentLength;
+    opticalDepth += nonUniformScatteringDensity(field, worldZ) * segmentLength;
+  }
+  return Math.exp(-extinction * opticalDepth);
+}
+
 function halfToFloat(bits: number): number {
   const sign = (bits & 0x8000) === 0 ? 1 : -1;
   const exponent = (bits >>> 10) & 0x1f;
@@ -42,12 +150,50 @@ function halfToFloat(bits: number): number {
   return sign * 2 ** (exponent - 15) * (1 + fraction / 1024);
 }
 
+function firstStageValue(values: readonly number[], label: string): number {
+  const value = values[0];
+  if (value === undefined) throw new Error(`missing stage readback value: ${label}`);
+  return value;
+}
+
 function manifestShader(marker: string): string {
   const entry = engineManifest.entries.find(({ wgsl }) => wgsl.includes(marker));
   if (entry === undefined) throw new Error(`missing cooked shader entry: ${marker}`);
   return entry.wgsl;
 }
 
+function productionIntegratorShader(stepCount?: number): string {
+  const source = manifestShader('fn volume_integrate');
+  if (stepCount === undefined) return source;
+  if (!Number.isInteger(stepCount) || stepCount < 1) {
+    throw new Error(`invalid production integrator step count: ${stepCount}`);
+  }
+  const functionStart = source.indexOf('fn volume_integrate');
+  if (functionStart < 0) throw new Error('production integrator function missing');
+  const prefix = source.slice(0, functionStart);
+  const body = source.slice(functionStart);
+  // The cooked manifest constant-folds the source-level loop count into the
+  // step-length divisor and loop guard. Replace both literals in that one
+  // production function to compile the same WGSL with a diagnostic schedule;
+  // an omitted override always exercises the unmodified production manifest.
+  // Diagnostic schedules disable local refinement to expose the old defect.
+  const productionCount = body.match(/< (\d+)u\b/)?.[1];
+  if (productionCount === undefined) throw new Error('production ray loop count missing');
+  const stepLengthMarker = new RegExp(`f32\\(${productionCount}u\\)`, 'g');
+  const loopGuardMarker = new RegExp(`< ${productionCount}u\\b`, 'g');
+  const stepLengthOccurrences = body.match(stepLengthMarker)?.length ?? 0;
+  const loopGuardOccurrences = body.match(loopGuardMarker)?.length ?? 0;
+  if (stepLengthOccurrences !== 1 || loopGuardOccurrences !== 1) {
+    throw new Error(
+      `production integrator step markers: length=${stepLengthOccurrences}, guard=${loopGuardOccurrences}`,
+    );
+  }
+  return `${prefix}${body
+    .replace(stepLengthMarker, `f32(${stepCount}u)`)
+    .replace(loopGuardMarker, `< ${stepCount}u`)
+    .replace(/select\(1u, 4u,/, 'select(1u, 1u,')} `;
+}
+
 function identityMatrix(target: Float32Array, offset: number): void {
   target[offset] = 1;
   target[offset + 5] = 1;
@@ -74,12 +220,18 @@ async function requestDevice(): Promise<RhiDevice> {
 }
 
 async function runInjectReadback(
-  sceneDepthClear = 1,
-  densitySource: number | 'height-gradient' | 'depth-gradient' = 255,
-  heightOffset = 0,
-  frameIndex = 0,
-  slopedShadow = false,
+  options: StageReadbackOptions = {},
 ): Promise<VolumeStageReadbacks> {
+  const sceneDepthClear = options.sceneDepthClear ?? 1;
+  const densityByte = options.densityByte ?? 255;
+  const boundsMinZ = options.boundsMinZ ?? VOLUME_BOUNDS_MIN_Z;
+  const boundsMaxZ = options.boundsMaxZ ?? VOLUME_BOUNDS_MAX_Z;
+  const maxDistance = options.maxDistance ?? 2;
+  const viewDepthScale = options.viewDepthScale ?? 1;
+  const extinction = options.extinction ?? 1;
+  const frameIndex = options.frameIndex ?? 0;
+  const shadowDepthClear = options.shadowDepthClear ?? 1;
+  const integratorStepCount = options.integratorStepCount;
   const device = await requestDevice();
   const moduleResult = await createShaderModule(device, {
     code: manifestShader('fn volume_inject'),
@@ -91,7 +243,7 @@ async function runInjectReadback(
     label: 'stage-readback.volume-temporal',
   });
   const integrateModule = await createShaderModule(device, {
-    code: manifestShader('fn volume_integrate'),
+    code: productionIntegratorShader(integratorStepCount),
     label: 'stage-readback.volume-integrate',
   });
   if (!temporalModule.ok) throw temporalModule.error;
@@ -191,7 +343,7 @@ async function runInjectReadback(
   });
   const paramsBuffer = device.createBuffer({
     label: 'stage-readback.params',
-    size: 128,
+    size: VOLUMETRIC_FOG_PARAMS_BYTES,
     usage: 0x0040 | BUFFER_COPY_DST,
   });
   const lightDataBuffer = device.createBuffer({
@@ -232,28 +384,36 @@ async function runInjectReadback(
 
   const viewData = new Float32Array(240);
   for (const offset of [0, 28, 44, 60, 76, 92, 196, 212]) identityMatrix(viewData, offset);
+  viewData[44 + 10] = viewDepthScale;
   viewData[24] = 0;
-  viewData[25] = heightOffset;
-  viewData[44 + 13] = heightOffset;
+  viewData[25] = 0;
   viewData[26] = -1;
-  viewData[124] = slopedShadow ? 1 : 0;
-  viewData[108] = 10;
-  if (slopedShadow) viewData[28 + 2] = 0.5;
+  viewData[124] = 0;
   viewData[228] = 0.1;
   viewData[229] = 10;
   viewData[230] = 0;
   viewData[235] = 1;
-  const paramsData = new Float32Array(32);
-  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);
+  const paramsData = new Float32Array(VOLUMETRIC_FOG_PARAMS_BYTES / 4);
+  paramsData.set([-1, -1, boundsMinZ, 0], 0);
+  paramsData.set([1, 1, boundsMaxZ, 0], 4);
+  paramsData.set([extinction, extinction, extinction, 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([0, -1, 0, frameIndex], 20);
   paramsData.set([1, 1, 1, 0], 24);
-  paramsData.set([2, 0, 0, 0], 28);
-  paramsData[23] = frameIndex;
+  paramsData.set([maxDistance, 0, 0, 0], 28);
   const lightData = new Uint8Array(CLUSTER_LIGHT_DATA_BYTES);
+  if (options.localLight !== undefined) {
+    paramsData[30] = options.localLight === 'point' ? 1 : 2;
+    const light = new Float32Array(lightData.buffer);
+    light.set([0, 0, 5.37, 0, 1, 1, 1, Math.cos(Math.PI / 8), 0, 0, -1, Math.cos(Math.PI / 6)]);
+    // Zero shadow intensity makes this a pure punctual-light integral. No
+    // projected image or shadow map can hide an undersampled light peak.
+    new Uint32Array(lightData.buffer).set(
+      [options.localLight === 'point' ? 0 : 1, 0xffffffff, 0xffffffff, 0xffffffff],
+      16,
+    );
+  }
   const clusterUniformData = new Float32Array(8);
   const clusterGrid = new Uint32Array(clusterUniformData.buffer);
   clusterGrid[0] = 1;
@@ -270,22 +430,12 @@ async function runInjectReadback(
   );
   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);
-  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 densityData =
+    options.densityData ?? new Uint8Array((BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE);
+  if (options.densityData === undefined) densityData.fill(densityByte);
+  if (densityData.length !== (BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE) {
+    throw new Error(`Dawn volume stage readback density field length: ${densityData.length}`);
+  }
   const densityWrite = device.queue.writeTexture(
     { texture: densityTexture.value },
     densityData,
@@ -462,7 +612,7 @@ async function runInjectReadback(
       colorAttachments: [],
       depthStencilAttachment: {
         view,
-        depthClearValue: index === 0 ? sceneDepthClear : slopedShadow ? 0.5 : 1,
+        depthClearValue: index === 0 ? sceneDepthClear : shadowDepthClear,
         depthLoadOp: 'clear',
         depthStoreOp: 'store',
       },
@@ -543,23 +693,112 @@ async function runInjectReadback(
   };
 }
 
+// Independent radiative-transfer quadrature: a homogeneous medium and an
+// unshadowed punctual source. The near-light peak and spot cone make the old
+// 24 midpoint schedule visibly wrong even though its Beer transmittance passes.
+function punctualReference(kind: 'point' | 'spot', samples = 16_384): number[] {
+  const sigma = 0.01 * (2 * (128 / 255 + 0.5) ** 3 - 1);
+  return Array.from({ length: SIZE * SIZE }, (_, pixel) => {
+    const x = (((pixel % SIZE) + 0.5) / SIZE) * 2 - 1;
+    const y = 1 - ((Math.floor(pixel / SIZE) + 0.5) / SIZE) * 2;
+    const ds = 20 / samples;
+    let radiance = 0;
+    for (let i = 0; i < samples; i += 1) {
+      const s = (i + 0.5) * ds;
+      const z = 0.1 + s;
+      const distanceSquared = x * x + y * y + (5.37 - z) ** 2;
+      const cosine = (5.37 - z) / Math.sqrt(distanceSquared);
+      const t = Math.max(
+        0,
+        Math.min(
+          1,
+          (cosine - Math.cos(Math.PI / 6)) / (Math.cos(Math.PI / 8) - Math.cos(Math.PI / 6)),
+        ),
+      );
+      const cone = kind === 'point' ? 1 : t * t * (3 - 2 * t);
+      radiance += ((sigma * Math.exp(-sigma * s) * cone) / distanceSquared) * ds;
+    }
+    return radiance;
+  });
+}
+
 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);
+    const first = await runInjectReadback({ frameIndex: 0, shadowDepthClear: 0.5 });
+    const next = await runInjectReadback({ frameIndex: 1, shadowDepthClear: 0.5 });
+    expect(first.inject).toEqual(next.inject);
     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.each([
+    'point',
+    'spot',
+  ] as const)('resolves the %s light peak without coherent ray bands', async (localLight) => {
+    const reference = punctualReference(localLight);
+    const refined = punctualReference(localLight, 32_768);
+    expect(Math.max(...reference.map((v, i) => Math.abs(v - (refined[i] ?? 0)) / v))).toBeLessThan(
+      0.0001,
+    );
+    const options = {
+      localLight,
+      densityByte: 128,
+      extinction: 0.01,
+      boundsMaxZ: 20.1,
+      maxDistance: 20.1,
+      viewDepthScale: 21,
+    };
+    const maximumRelativeError = (values: VolumeStageReadbacks): number =>
+      Math.max(
+        ...values.integrate.red.map(
+          (v, i) => Math.abs(v - (reference[i] ?? 0)) / (reference[i] ?? 1),
+        ),
+      );
+    const production = await runInjectReadback(options);
+    const undersampled = await runInjectReadback({ ...options, integratorStepCount: 24 });
+    const resolved = await runInjectReadback({ ...options, integratorStepCount: 96 });
+    const refinedGpu = await runInjectReadback({ ...options, integratorStepCount: 384 });
+    const errors = {
+      refined: maximumRelativeError(refinedGpu),
+      production: maximumRelativeError(production),
+      undersampled: maximumRelativeError(undersampled),
+      resolved: maximumRelativeError(resolved),
+    };
+    // biome-ignore lint/suspicious/noConsole: production GPU spatial regression evidence.
+    console.info('[volumetric-fog-stage-readback] punctual-convergence', localLight, errors);
+    expect(errors.undersampled).toBeGreaterThan(0.1);
+    expect(errors.refined).toBeLessThan(0.003);
+    expect(errors.production).toBeLessThan(0.03);
+  });
+
+  it('retains fine density variation away from punctual light refinement', async () => {
+    // Matching end texels avoid an artificial discontinuity at the repeated
+    // texture seam. The interior stripes expose coarse-step density aliasing.
+    const field = createNonUniformDensityField([0, 255, 0, 255, 0, 255, 0, 0]);
+    const reference = nonUniformBeerReference(field, 0.05, 16_384, 0.1, 20.1);
+    const refined = nonUniformBeerReference(field, 0.05, 32_768, 0.1, 20.1);
+    expect(Math.abs(reference - refined)).toBeLessThan(0.0001);
+    const options = {
+      densityData: field.data,
+      extinction: 0.05,
+      boundsMaxZ: 20.1,
+      maxDistance: 20.1,
+      viewDepthScale: 21,
+    };
+    const production = firstStageValue(
+      (await runInjectReadback(options)).integrate.alpha,
+      'fine density',
+    );
+    const coarse = firstStageValue(
+      (await runInjectReadback({ ...options, integratorStepCount: 24 })).integrate.alpha,
+      'coarse density',
+    );
+    // biome-ignore lint/suspicious/noConsole: independent fine-density regression evidence.
+    console.info('[volumetric-fog-stage-readback] fine-density', { reference, production, coarse });
+    expect(Math.abs(coarse - reference)).toBeGreaterThan(0.005);
+    expect(Math.abs(production - reference)).toBeLessThan(0.002);
+  });
+
   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
@@ -580,23 +819,170 @@ 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 values = await runInjectReadback({ sceneDepthClear: 0.57 });
     const transmittance = values.integrate.alpha[0];
-    // White encodes density one; integrate only the visible 0.47-unit segment.
-    expect(transmittance).toBeCloseTo(Math.exp(-0.47), 2);
+    // 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);
     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('keeps a zero medium transparent and applies Beer-Lambert monotonically', async () => {
+    const empty = await runInjectReadback({ densityByte: 0 });
+    const medium = await runInjectReadback({ densityByte: 128 });
+    const dense = await runInjectReadback({ densityByte: 255 });
+    const emptyScattering = firstStageValue(empty.integrate.red, 'empty scattering');
+    const denseScattering = firstStageValue(dense.integrate.red, 'dense scattering');
+    const mediumScattering = firstStageValue(medium.integrate.red, 'medium scattering');
+    const emptyTransmission = firstStageValue(empty.integrate.alpha, 'empty transmission');
+    const mediumTransmission = firstStageValue(medium.integrate.alpha, 'medium transmission');
+    const denseTransmission = firstStageValue(dense.integrate.alpha, 'dense transmission');
+    expect(emptyScattering).toBeCloseTo(0, 2);
+    expect(emptyTransmission).toBeCloseTo(1, 2);
+    expect(denseTransmission).toBeLessThan(mediumTransmission);
+    expect(mediumTransmission).toBeLessThan(emptyTransmission);
+    expect(denseScattering).toBeGreaterThan(mediumScattering);
   });
 
-  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);
+  it('keeps extinction monotonic and bounds temporal jitter spread', async () => {
+    const lowExtinction = await runInjectReadback({ densityByte: 128, extinction: 0.25 });
+    const highExtinction = await runInjectReadback({ densityByte: 128, extinction: 1 });
+    const lowTransmission = firstStageValue(lowExtinction.integrate.alpha, 'low extinction');
+    const highTransmission = firstStageValue(highExtinction.integrate.alpha, 'high extinction');
+    expect(highTransmission).toBeLessThan(lowTransmission);
+
+    const samples: number[] = [];
+    for (let frameIndex = 0; frameIndex < 4; frameIndex += 1) {
+      const value = await runInjectReadback({ densityByte: 128, frameIndex });
+      const transmission = firstStageValue(value.integrate.alpha, `frame ${frameIndex}`);
+      expect(Number.isFinite(transmission)).toBe(true);
+      samples.push(transmission);
+    }
+    const spread = Math.max(...samples) - Math.min(...samples);
+    // Frame ordinals must not change a fixed World-time density integral.
+    // This remains separate from continuous-frame history and spatial accuracy.
+    expect(spread).toBeLessThan(0.2);
+  });
+
+  it('converges production step-count variants to the homogeneous Beer oracle', async () => {
+    const sceneDepthClear = 0.57;
+    const sourceDensity = 2 * 1.5 ** 3 - 1;
+    const oracle = Math.exp(-0.47 * sourceDensity);
+    const transmissions = await Promise.all(
+      [6, 12, 24].map(async (integratorStepCount) => {
+        const values = await runInjectReadback({
+          sceneDepthClear,
+          integratorStepCount,
+        });
+        return firstStageValue(values.integrate.alpha, `${integratorStepCount}-step transmission`);
+      }),
+    );
+    for (const transmission of transmissions) {
+      expect(transmission).toBeCloseTo(oracle, 2);
+    }
+    expect(Math.max(...transmissions) - Math.min(...transmissions)).toBeLessThan(0.01);
+  });
+
+  it('converges production steps against an independent non-uniform Beer reference', async () => {
+    const field = createNonUniformDensityField();
+    const flattenedField = createFlattenedDensityField(field);
+    const reference = nonUniformBeerReference(
+      field,
+      NON_UNIFORM_EXTINCTION,
+      16_384,
+      VOLUME_BOUNDS_MIN_Z,
+      NON_UNIFORM_BOUNDS_MAX_Z,
+    );
+    const refinedReference = nonUniformBeerReference(
+      field,
+      NON_UNIFORM_EXTINCTION,
+      32_768,
+      VOLUME_BOUNDS_MIN_Z,
+      NON_UNIFORM_BOUNDS_MAX_Z,
+    );
+    const flattenedReference = nonUniformBeerReference(
+      flattenedField,
+      NON_UNIFORM_EXTINCTION,
+      16_384,
+      VOLUME_BOUNDS_MIN_Z,
+      NON_UNIFORM_BOUNDS_MAX_Z,
+    );
+    expect(Math.abs(reference - refinedReference)).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR / 10);
+    expect(Math.abs(reference - flattenedReference)).toBeGreaterThan(
+      MIN_NON_UNIFORM_REFERENCE_SEPARATION,
+    );
+    const stepCounts = [24, 48, 96] as const;
+    const transmissions = await Promise.all(
+      stepCounts.map(async (integratorStepCount) => {
+        const values = await runInjectReadback({
+          boundsMaxZ: NON_UNIFORM_BOUNDS_MAX_Z,
+          densityData: field.data,
+          extinction: NON_UNIFORM_EXTINCTION,
+          integratorStepCount,
+          maxDistance: NON_UNIFORM_BOUNDS_MAX_Z,
+          viewDepthScale: 10,
+        });
+        return firstStageValue(
+          values.integrate.alpha,
+          `${integratorStepCount}-step non-uniform transmission`,
+        );
+      }),
+    );
+    const flattenedValues = await runInjectReadback({
+      boundsMaxZ: NON_UNIFORM_BOUNDS_MAX_Z,
+      densityData: flattenedField.data,
+      extinction: NON_UNIFORM_EXTINCTION,
+      integratorStepCount: 96,
+      maxDistance: NON_UNIFORM_BOUNDS_MAX_Z,
+      viewDepthScale: 10,
+    });
+    const flattenedTransmission = firstStageValue(
+      flattenedValues.integrate.alpha,
+      'flattened-field transmission',
+    );
+    const defaultValues = await runInjectReadback({
+      boundsMaxZ: NON_UNIFORM_BOUNDS_MAX_Z,
+      densityData: field.data,
+      extinction: NON_UNIFORM_EXTINCTION,
+      maxDistance: NON_UNIFORM_BOUNDS_MAX_Z,
+      viewDepthScale: 10,
+    });
+    const defaultTransmission = firstStageValue(
+      defaultValues.integrate.alpha,
+      'production transmission',
+    );
+    const errors = transmissions.map((transmission) => Math.abs(transmission - reference));
+    const flattenedError = Math.abs(flattenedTransmission - flattenedReference);
+    const defaultError = Math.abs(defaultTransmission - reference);
+    // biome-ignore lint/suspicious/noConsole: non-uniform production convergence receipt.
+    console.info(
+      '[volumetric-fog-stage-readback] non-uniform-convergence',
+      JSON.stringify({
+        reference,
+        refinedReference,
+        flattenedReference,
+        stepCounts,
+        transmissions,
+        errors,
+        flattenedTransmission,
+        flattenedError,
+        defaultTransmission,
+        defaultError,
+      }),
+    );
+    for (const error of errors) expect(error).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
+    expect(flattenedError).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
+    expect(defaultError).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
+    expect(Math.abs((transmissions[2] ?? NaN) - flattenedTransmission)).toBeGreaterThan(
+      MIN_NON_UNIFORM_GPU_SEPARATION,
+    );
+    const spread = Math.max(...transmissions) - Math.min(...transmissions);
+    // rgba16float readback quantizes nearby step variants onto the same value,
+    // so strict error ordering is not a stable production contract. Keep the
+    // independent reference and require a bounded cross-step spread instead.
+    expect(spread).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
   });
 });

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

@@ -8,6 +8,7 @@ const signature: VolumeTemporalSignature = {
   densityGeneration: 3,
   width: 1280,
   height: 720,
+  worldTimeSeconds: 4,
 };
 
 describe('volumetric fog temporal contract', () => {
@@ -23,11 +24,37 @@ describe('volumetric fog temporal contract', () => {
     ['fog-revision', { ...signature, fogRevision: 3 }],
     ['light-revision', { ...signature, lightRevision: 8 }],
     ['density-generation', { ...signature, densityGeneration: 4 }],
+    ['simulation-time', { ...signature, worldTimeSeconds: 4.5 }],
     ['resize', { ...signature, width: 640, height: 360 }],
   ] as const)('resets history for %s', (reason, next) => {
     expect(resolveVolumeTemporalReset(signature, next)).toEqual({ reset: true, reason });
   });
 
+  it.each([1 / 144, 1 / 60, 1 / 30, 1 / 15])('retains animated history at dt=%s', (delta) => {
+    expect(
+      resolveVolumeTemporalReset(signature, { ...signature, worldTimeSeconds: 4 + delta }),
+    ).toEqual({ reset: false });
+  });
+
+  it.each([3.9, 4.101, NaN, Infinity])('rejects discontinuous time %s', (worldTimeSeconds) => {
+    expect(resolveVolumeTemporalReset(signature, { ...signature, worldTimeSeconds })).toEqual({
+      reset: true,
+      reason: 'simulation-time',
+    });
+  });
+
+  it('rejects changed clock availability', () => {
+    const { worldTimeSeconds: _time, ...withoutTime } = signature;
+    expect(resolveVolumeTemporalReset(signature, withoutTime)).toEqual({
+      reset: true,
+      reason: 'simulation-time',
+    });
+    expect(resolveVolumeTemporalReset(withoutTime, signature)).toEqual({
+      reset: true,
+      reason: 'simulation-time',
+    });
+  });
+
   it('rejects out-of-screen reprojection and depth discontinuity without NaN', () => {
     expect(
       resolveVolumeTemporalReset(signature, signature, { reprojection: 'out-of-screen' }),