@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/ssr-reflection-mip-reducer.dawn.test.ts

@@ -0,0 +1,309 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createShaderModuleImmediate, rhi } from '@forgeax/engine-rhi-webgpu';
+import { expect, it } from 'vitest';
+import { GPU_SHADER_STAGE_COMPUTE } from '../gpu-stage';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_STORAGE_BINDING,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+
+type Pixel = readonly [number, number, number, number];
+
+const BYTES_PER_PIXEL = 8;
+const READBACK_BYTES_PER_ROW = 256;
+
+function readShader(name: string): string {
+  return readFileSync(resolve(process.cwd(), `packages/shader/src/${name}.wgsl`), 'utf8');
+}
+
+function halfToFloat(bits: number): number {
+  const sign = (bits & 0x8000) === 0 ? 1 : -1;
+  const exponent = (bits >>> 10) & 0x1f;
+  const fraction = bits & 0x3ff;
+  if (exponent === 0) return sign * 2 ** -14 * (fraction / 1024);
+  if (exponent === 0x1f) return fraction === 0 ? sign * Infinity : Number.NaN;
+  return sign * 2 ** (exponent - 15) * (1 + fraction / 1024);
+}
+
+function floatToHalf(value: number): number {
+  if (!Number.isFinite(value)) return value < 0 ? 0xfc00 : 0x7c00;
+  const sign = value < 0 ? 0x8000 : 0;
+  const absolute = Math.abs(value);
+  if (absolute === 0) return sign;
+  if (absolute >= 65504) return sign | 0x7bff;
+  const exponent = Math.floor(Math.log2(absolute));
+  if (exponent < -14) return sign | Math.round(absolute / 2 ** -24);
+  const mantissa = absolute / 2 ** exponent - 1;
+  return sign | ((exponent + 15) << 10) | Math.round(mantissa * 1024);
+}
+
+async function createDevice() {
+  return (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+}
+
+async function compileTemporalShader(): Promise<string> {
+  const compiler = (await import(
+    /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+  )) as {
+    compileShader(
+      source: string,
+      options: { id: string; imports: Record<string, string> },
+    ): Promise<{ ok: boolean; value?: { wgsl: string }; error?: unknown }>;
+  };
+  const result = await compiler.compileShader(readShader('ssr-temporal'), {
+    id: 'forgeax_ssr::temporal',
+    imports: { 'forgeax_view::common': readShader('common') },
+  });
+  if (!result.ok || result.value === undefined) throw new Error(JSON.stringify(result.error));
+  return result.value.wgsl;
+}
+
+async function runReducer(
+  shader: string,
+  sourceWidth: number,
+  sourceHeight: number,
+  targetWidth: number,
+  targetHeight: number,
+  sourcePixels: readonly Pixel[],
+): Promise<number[]> {
+  const device = await createDevice();
+  const source = device
+    .createTexture({
+      size: { width: sourceWidth, height: sourceHeight, depthOrArrayLayers: 1 },
+      format: 'rgba16float',
+      textureBindingViewDimension: '2d',
+      usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    })
+    .unwrap();
+  const target = device
+    .createTexture({
+      size: { width: targetWidth, height: targetHeight, depthOrArrayLayers: 1 },
+      format: 'rgba16float',
+      textureBindingViewDimension: '2d',
+      usage: GPU_TEXTURE_USAGE_STORAGE_BINDING | GPU_TEXTURE_USAGE_COPY_SRC,
+    })
+    .unwrap();
+  const readback = device
+    .createBuffer({
+      size: READBACK_BYTES_PER_ROW * targetHeight,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  try {
+    const packed = new Uint16Array(sourceWidth * sourceHeight * 4);
+    for (let i = 0; i < sourcePixels.length; i++) {
+      const pixel = sourcePixels[i];
+      if (pixel === undefined) throw new Error(`missing source pixel ${i}`);
+      for (const channel of [0, 1, 2, 3] as const) {
+        packed[i * 4 + channel] = floatToHalf(pixel[channel]);
+      }
+    }
+    device.queue
+      .writeTexture(
+        { texture: source },
+        packed,
+        {
+          bytesPerRow: sourceWidth * BYTES_PER_PIXEL,
+          rowsPerImage: sourceHeight,
+        },
+        { width: sourceWidth, height: sourceHeight, depthOrArrayLayers: 1 },
+      )
+      .unwrap();
+
+    const module = createShaderModuleImmediate(device, { code: shader }).unwrap();
+    const layout = device
+      .createBindGroupLayout({
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+          },
+          {
+            binding: 7,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            storageTexture: { access: 'write-only', format: 'rgba16float', viewDimension: '2d' },
+          },
+        ],
+      })
+      .unwrap();
+    const pipeline = device
+      .createComputePipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }).unwrap(),
+        compute: { module, entryPoint: 'ssr_reflection_mip' },
+      })
+      .unwrap();
+    const sourceView = device.createTextureView(source, { dimension: '2d' }).unwrap();
+    const targetView = device.createTextureView(target, { dimension: '2d' }).unwrap();
+    const group = device
+      .createBindGroup({
+        layout,
+        entries: [
+          { binding: 0, resource: { kind: 'textureView', value: sourceView } },
+          { binding: 7, resource: { kind: 'textureView', value: targetView } },
+        ],
+      })
+      .unwrap();
+    const encoder = device.createCommandEncoder().unwrap();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, group);
+    pass.dispatchWorkgroups(Math.ceil(targetWidth / 8), Math.ceil(targetHeight / 8), 1);
+    pass.end();
+    encoder.copyTextureToBuffer(
+      { texture: target },
+      { buffer: readback, bytesPerRow: READBACK_BYTES_PER_ROW, rowsPerImage: targetHeight },
+      { width: targetWidth, height: targetHeight, depthOrArrayLayers: 1 },
+    );
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    await device.queue.onSubmittedWorkDone();
+    const mapped = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+    const bytes = new DataView(mapped.getMappedRange().unwrap().slice(0));
+    const values: number[] = [];
+    for (let y = 0; y < targetHeight; y++) {
+      for (let x = 0; x < targetWidth; x++) {
+        const offset = y * READBACK_BYTES_PER_ROW + x * BYTES_PER_PIXEL;
+        for (let channel = 0; channel < 4; channel++) {
+          values.push(halfToFloat(bytes.getUint16(offset + channel * 2, true)));
+        }
+      }
+    }
+    mapped.unmap();
+    return values;
+  } finally {
+    device.destroyTexture(source).unwrap();
+    device.destroyTexture(target).unwrap();
+    device.destroyBuffer(readback).unwrap();
+  }
+}
+
+function averageFootprint(
+  pixels: readonly Pixel[],
+  sourceWidth: number,
+  sourceHeight: number,
+  targetX: number,
+  targetY: number,
+  targetWidth: number,
+  targetHeight: number,
+): Pixel {
+  const firstX = Math.floor((targetX * sourceWidth) / targetWidth);
+  const endX = Math.floor(((targetX + 1) * sourceWidth) / targetWidth);
+  const firstY = Math.floor((targetY * sourceHeight) / targetHeight);
+  const endY = Math.floor(((targetY + 1) * sourceHeight) / targetHeight);
+  const sum: [number, number, number, number] = [0, 0, 0, 0];
+  let count = 0;
+  for (let y = firstY; y < endY; y++) {
+    for (let x = firstX; x < endX; x++) {
+      const pixel = pixels[y * sourceWidth + x];
+      if (pixel === undefined) throw new Error(`missing footprint pixel ${x},${y}`);
+      for (const channel of [0, 1, 2, 3] as const) sum[channel] += pixel[channel];
+      count += 1;
+    }
+  }
+  if (count === 0) throw new Error(`empty footprint at ${targetX},${targetY}`);
+  return [sum[0] / count, sum[1] / count, sum[2] / count, sum[3] / count];
+}
+
+it('uses the production four-load 2x2 reducer for even extents', async () => {
+  const sourceWidth = 6;
+  const sourceHeight = 4;
+  const targetWidth = 3;
+  const targetHeight = 2;
+  const pixels = Array.from({ length: sourceWidth * sourceHeight }, (_, index): Pixel => {
+    const x = index % sourceWidth;
+    const y = Math.floor(index / sourceWidth);
+    return [1 + x + y * sourceWidth, 0.25 + x * 0.5, 0.5 + y * 0.75, 0.25 + ((x + y) % 4) * 0.25];
+  });
+  const values = await runReducer(
+    await compileTemporalShader(),
+    sourceWidth,
+    sourceHeight,
+    targetWidth,
+    targetHeight,
+    pixels,
+  );
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      const expected = averageFootprint(
+        pixels,
+        sourceWidth,
+        sourceHeight,
+        x,
+        y,
+        targetWidth,
+        targetHeight,
+      );
+      const offset = (y * targetWidth + x) * 4;
+      for (const channel of [0, 1, 2, 3] as const) {
+        expect(values[offset + channel]).toBeCloseTo(expected[channel], 2);
+      }
+    }
+  }
+});
+
+it('keeps the explicit footprint reducer for odd extents and bounded confidence', async () => {
+  const sourceWidth = 5;
+  const sourceHeight = 3;
+  const targetWidth = 2;
+  const targetHeight = 1;
+  const pixels = Array.from({ length: sourceWidth * sourceHeight }, (_, index): Pixel => {
+    const x = index % sourceWidth;
+    const y = Math.floor(index / sourceWidth);
+    return [0.5 + x * 0.25, 2 + y, 0.125 + (x + y) * 0.0625, ((x + y) % 5) * 0.25];
+  });
+  const values = await runReducer(
+    await compileTemporalShader(),
+    sourceWidth,
+    sourceHeight,
+    targetWidth,
+    targetHeight,
+    pixels,
+  );
+  for (let x = 0; x < targetWidth; x++) {
+    const expected = averageFootprint(
+      pixels,
+      sourceWidth,
+      sourceHeight,
+      x,
+      0,
+      targetWidth,
+      targetHeight,
+    );
+    const offset = x * 4;
+    for (const channel of [0, 1, 2, 3] as const) {
+      expect(values[offset + channel]).toBeCloseTo(expected[channel], 2);
+    }
+    expect(values[offset + 3]).toBeGreaterThanOrEqual(0);
+    expect(values[offset + 3]).toBeLessThanOrEqual(1);
+    expect(values.slice(offset, offset + 4).every(Number.isFinite)).toBe(true);
+  }
+});
+
+it('keeps premultiplied radiance through hit and miss footprints', async () => {
+  const pixels: readonly Pixel[] = [
+    [4, 2, 1, 1],
+    [0, 0, 0, 0],
+    [0, 0, 0, 0],
+    [2, 1, 0.5, 0.5],
+  ];
+  const values = await runReducer(await compileTemporalShader(), 2, 2, 1, 1, pixels);
+  // The input is the presentation representation (a * L, a). A miss carries
+  // no RGB mass, so the reduced value remains premultiplied rather than
+  // turning into a black radiance sample.
+  expect(values[0]).toBeCloseTo(1.5, 2);
+  expect(values[1]).toBeCloseTo(0.75, 2);
+  expect(values[2]).toBeCloseTo(0.375, 2);
+  expect(values[3]).toBeCloseTo(0.375, 2);
+  expect(values[3]).toBeGreaterThan(0);
+  const [red, green, blue, alpha] = values;
+  if (red === undefined || green === undefined || blue === undefined || alpha === undefined) {
+    throw new Error('the reducer must return one complete RGBA pixel');
+  }
+  expect(red / alpha).toBeCloseTo(4, 2);
+  expect(green / alpha).toBeCloseTo(2, 2);
+  expect(blue / alpha).toBeCloseTo(1, 2);
+});

package/src/__tests__/ssr-reprojection-probe.ts

@@ -0,0 +1,90 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { createShaderModuleImmediate } from '@forgeax/engine-rhi-webgpu';
+import { GPU_SHADER_STAGE_COMPUTE } from '../gpu-stage';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+
+/** Runs the cooked production reprojection function, not a CPU translation. */
+export async function runSsrReprojectionProbe(device: RhiDevice, source: string) {
+  const module = createShaderModuleImmediate(device, {
+    code: `${source}
+@group(1) @binding(0) var<storage, read_write> reprojectionProbe: array<vec4<f32>>;
+@compute @workgroup_size(1) fn probe_ssr_reprojection() {
+  reprojectionProbe[0] = vec4<f32>(reprojectUv(vec2<f32>(0.5), vec2<f32>(0.0)),
+    reprojectUv(vec2<f32>(0.5), vec2<f32>(0.125, -0.0625)));
+}`,
+  }).unwrap();
+  const paramsLayout = device
+    .createBindGroupLayout({
+      entries: [{ binding: 6, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'uniform' } }],
+    })
+    .unwrap();
+  const outputLayout = device
+    .createBindGroupLayout({
+      entries: [{ binding: 0, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'storage' } }],
+    })
+    .unwrap();
+  const layout = device
+    .createPipelineLayout({ bindGroupLayouts: [paramsLayout, outputLayout] })
+    .unwrap();
+  const pipeline = device
+    .createComputePipeline({ layout, compute: { module, entryPoint: 'probe_ssr_reprojection' } })
+    .unwrap();
+  const params = device
+    .createBuffer({ size: 32, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST })
+    .unwrap();
+  const output = device
+    .createBuffer({ size: 16, usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC })
+    .unwrap();
+  const readback = device
+    .createBuffer({ size: 16, usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST })
+    .unwrap();
+  try {
+    const paramsGroup = device
+      .createBindGroup({
+        layout: paramsLayout,
+        entries: [{ binding: 6, resource: { kind: 'buffer', value: { buffer: params } } }],
+      })
+      .unwrap();
+    const outputGroup = device
+      .createBindGroup({
+        layout: outputLayout,
+        entries: [{ binding: 0, resource: { kind: 'buffer', value: { buffer: output } } }],
+      })
+      .unwrap();
+    const samples = [];
+    // No jitter, alternating subpixel jitter, and the reverse transition.
+    // Fixed unjittered history must return the same motion-only coordinates.
+    for (const jitter of [
+      [0, 0, 0, 0],
+      [0.25 / 64, -0.25 / 32, -0.25 / 64, 0.25 / 32],
+      [-0.25 / 64, 0.25 / 32, 0.25 / 64, -0.25 / 32],
+    ]) {
+      const payload = new Float32Array(8);
+      payload.set(jitter, 4);
+      device.queue.writeBuffer(params, 0, payload).unwrap();
+      const encoder = device.createCommandEncoder().unwrap();
+      const pass = encoder.beginComputePass();
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, paramsGroup);
+      pass.setBindGroup(1, outputGroup);
+      pass.dispatchWorkgroups(1);
+      pass.end();
+      encoder.copyBufferToBuffer(output, 0, readback, 0, 16);
+      device.queue.submit([encoder.finish().unwrap()]).unwrap();
+      const mapped = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+      samples.push([...new Float32Array(mapped.getMappedRange().unwrap().slice(0))]);
+      mapped.unmap();
+    }
+    return samples;
+  } finally {
+    device.destroyBuffer(params).unwrap();
+    device.destroyBuffer(output).unwrap();
+    device.destroyBuffer(readback).unwrap();
+  }
+}

package/src/__tests__/ssr-roughness-mip.dawn.test.ts

@@ -0,0 +1,163 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createShaderModuleImmediate, rhi } from '@forgeax/engine-rhi-webgpu';
+import { expect, it } from 'vitest';
+import { GPU_SHADER_STAGE_COMPUTE } from '../gpu-stage';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+} from '../gpu-usage';
+
+it('samples the production reflection pyramid at roughness squared LOD with confidence weighting', async () => {
+  const source = readFileSync(
+    resolve(process.cwd(), 'packages/shader/src/ssr-compose.wgsl'),
+    'utf8',
+  );
+  const start = source.indexOf('fn ssrReflectionLod(');
+  const end = source.indexOf('@fragment\nfn fs_ssr_compose', start);
+  expect(start).toBeGreaterThan(0);
+  expect(end).toBeGreaterThan(start);
+  const temporalSource = readFileSync(
+    resolve(process.cwd(), 'packages/shader/src/ssr-temporal.wgsl'),
+    'utf8',
+  );
+  const temporalStart = temporalSource.indexOf('fn resolveSsrTemporal(');
+  const temporalEnd = temporalSource.indexOf('\n}\n', temporalStart) + 3;
+  expect(temporalStart).toBeGreaterThan(0);
+  expect(temporalEnd).toBeGreaterThan(temporalStart);
+  const temporalHelpers = temporalSource.slice(
+    temporalSource.indexOf('fn isFinite('),
+    temporalSource.indexOf('fn finitePositive('),
+  );
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const texture = device
+    .createTexture({
+      size: { width: 4, height: 4, depthOrArrayLayers: 1 },
+      mipLevelCount: 3,
+      // Match the production HDR pyramid, including the filtering precision.
+      format: 'rgba16float',
+      textureBindingViewDimension: '2d',
+      usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    })
+    .unwrap();
+  const output = device
+    .createBuffer({ size: 128, usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC })
+    .unwrap();
+  const readback = device
+    .createBuffer({ size: 128, usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST })
+    .unwrap();
+  try {
+    // Distinct levels falsify accidental mip-zero-only sampling. The middle
+    // level has zero confidence and must not introduce its green radiance.
+    for (let level = 0; level < 3; level++) {
+      const size = 4 >> level;
+      const color = [
+        [0x3c00, 0, 0, 0x3c00],
+        // Zero-confidence presentation texels carry no RGB payload.
+        [0, 0, 0, 0],
+        [0, 0, 0x3c00, 0x3c00],
+      ][level];
+      if (color === undefined) throw new Error('Missing mip fixture color');
+      const data = new Uint16Array(size * size * 4);
+      for (let pixel = 0; pixel < size * size; pixel++) data.set(color, pixel * 4);
+      device.queue
+        .writeTexture(
+          { texture, mipLevel: level, origin: [0, 0, 0] },
+          data,
+          { offset: 0, bytesPerRow: size * 8, rowsPerImage: size },
+          { width: size, height: size, depthOrArrayLayers: 1 },
+        )
+        .unwrap();
+    }
+    const module = createShaderModuleImmediate(device, {
+      code: `
+@group(0) @binding(0) var radiance: texture_2d<f32>;
+@group(0) @binding(1) var radianceSampler: sampler;
+@group(0) @binding(2) var<storage, read_write> result: array<vec4<f32>>;
+${source.slice(start, end)}
+struct ProbeParams { historyValid: u32, maxHistoryWeight: f32 };
+const params = ProbeParams(1u, 0.9);
+${temporalHelpers}
+${temporalSource.slice(temporalStart, temporalEnd)}
+@compute @workgroup_size(1) fn probe() {
+  result[0] = sampleRoughSsr(vec2<f32>(0.5), 0.0);
+  result[1] = sampleRoughSsr(vec2<f32>(0.5), 0.5);
+  result[2] = sampleRoughSsr(vec2<f32>(0.5), 1.0);
+  result[3] = sampleRoughSsr(vec2<f32>(0.5), sqrt(0.75));
+  // Miss -> hit must not mix black history; hit -> miss decays confidence
+  // without darkening radiance; disocclusion rejects that carry immediately.
+  let red = vec4<f32>(1.0, 0.0, 0.0, 1.0);
+  let empty = vec4<f32>(0.0);
+  result[4] = resolveSsrTemporal(red, empty, 0.0, vec3<f32>(0), vec3<f32>(1), true, true, true, empty);
+  result[5] = resolveSsrTemporal(empty, red, 1.0, vec3<f32>(0), vec3<f32>(0), true, true, true, empty);
+  result[6] = resolveSsrTemporal(empty, red, 1.0, vec3<f32>(0), vec3<f32>(0), true, false, true, empty);
+  result[7] = resolveSsrTemporal(red, empty, 1.0, vec3<f32>(0), vec3<f32>(1), true, true, true, empty);
+}`,
+    }).unwrap();
+    const groupLayout = device
+      .createBindGroupLayout({
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'float', viewDimension: '2d' },
+          },
+          { binding: 1, visibility: GPU_SHADER_STAGE_COMPUTE, sampler: { type: 'filtering' } },
+          { binding: 2, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'storage' } },
+        ],
+      })
+      .unwrap();
+    const layout = device.createPipelineLayout({ bindGroupLayouts: [groupLayout] }).unwrap();
+    const pipeline = device
+      .createComputePipeline({ layout, compute: { module, entryPoint: 'probe' } })
+      .unwrap();
+    const view = device.createTextureView(texture, { baseMipLevel: 0, mipLevelCount: 3 }).unwrap();
+    const sampler = device
+      .createSampler({
+        addressModeU: 'clamp-to-edge',
+        addressModeV: 'clamp-to-edge',
+        minFilter: 'linear',
+        magFilter: 'linear',
+        mipmapFilter: 'linear',
+      })
+      .unwrap();
+    const group = device
+      .createBindGroup({
+        layout: groupLayout,
+        entries: [
+          { binding: 0, resource: { kind: 'textureView', value: view } },
+          { binding: 1, resource: { kind: 'sampler', value: sampler } },
+          { binding: 2, resource: { kind: 'buffer', value: { buffer: output } } },
+        ],
+      })
+      .unwrap();
+    const encoder = device.createCommandEncoder().unwrap();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, group);
+    pass.dispatchWorkgroups(1);
+    pass.end();
+    encoder.copyBufferToBuffer(output, 0, readback, 0, 128);
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    const mapped = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+    const values = [...new Float32Array(mapped.getMappedRange().unwrap().slice(0))];
+    mapped.unmap();
+    const expected = [
+      // sampleRoughSsr exposes the premultiplied presentation value; the
+      // production fragment unpremultiplies once before material blending.
+      1, 0, 0, 1, 0.5, 0, 0, 0.5, 0, 0, 1, 1, 0, 0, 0.5, 0.5, 1, 0, 0, 1, 1, 0, 0, 0.9, 0, 0, 0, 0,
+      0.1, 0, 0, 1,
+    ];
+    for (const [i, value] of expected.entries()) expect(values[i]).toBeCloseTo(value, 5);
+  } finally {
+    device.destroyTexture(texture).unwrap();
+    device.destroyBuffer(output).unwrap();
+    device.destroyBuffer(readback).unwrap();
+  }
+});

package/src/__tests__/ssr-shader-prewarm.unit.test.ts

@@ -0,0 +1,59 @@
+import type { ShaderModule } from '@forgeax/engine-rhi';
+import type { ManifestEntry } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { prewarmSsrShaders } from '../assembly/ssr-shader-prewarm';
+
+const entries = [
+  'ssr_hiz_seed',
+  'ssr_hiz_reduce',
+  'ssr_trace',
+  'ssr_temporal',
+  'vs_ssr_compose',
+].map((entry) => ({ wgsl: `fn ${entry}() {}` }) as ManifestEntry);
+
+describe('SSR bundle preparation', () => {
+  it('does no compile or publication for an absent optional bundle', async () => {
+    const compile = vi.fn(),
+      seed = vi.fn();
+    expect(await prewarmSsrShaders([], compile, seed)).toBeUndefined();
+    expect(compile).not.toHaveBeenCalled();
+    expect(seed).not.toHaveBeenCalled();
+  });
+
+  it('rejects an incomplete bundle before compilation', async () => {
+    const compile = vi.fn(),
+      seed = vi.fn();
+    await expect(prewarmSsrShaders(entries.slice(0, 4), compile, seed)).rejects.toMatchObject({
+      code: 'shader-compile-failed',
+    });
+    expect(compile).not.toHaveBeenCalled();
+    expect(seed).not.toHaveBeenCalled();
+  });
+
+  it('never seeds a partial generation when a later module fails', async () => {
+    const seed = vi.fn();
+    const compile = vi.fn(async (label: string) => {
+      if (label === 'ssr_temporal') throw new Error('compile failed');
+      return {} as ShaderModule;
+    });
+    await expect(prewarmSsrShaders(entries, compile, seed)).rejects.toThrow('compile failed');
+    expect(seed).not.toHaveBeenCalled();
+  });
+
+  it('returns and seeds all five stages only after the final compile', async () => {
+    const seed = vi.fn();
+    const compile = vi.fn(async () => {
+      expect(seed).not.toHaveBeenCalled();
+      return {} as ShaderModule;
+    });
+    const sources = await prewarmSsrShaders(entries, compile, seed);
+    expect(seed).toHaveBeenCalledTimes(5);
+    expect(sources).toEqual({
+      hiz: 'fn ssr_hiz_seed() {}',
+      hizReduce: 'fn ssr_hiz_reduce() {}',
+      trace: 'fn ssr_trace() {}',
+      temporal: 'fn ssr_temporal() {}',
+      compose: 'fn vs_ssr_compose() {}',
+    });
+  });
+});