@forgeax/engine-render 0.1.29 → 0.1.31

package/src/__tests__/ssr-cube-silhouette.dawn.test.ts

@@ -0,0 +1,270 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { expect, it } from 'vitest';
+import {
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  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,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
+
+// Independent analytic raster inputs and mirror-box oracle reproduce the ordinary
+// plane + cube example. No captured GPU handles, pixels or shader outputs are fixtures.
+it.each([
+  0, 0.07, -0.07,
+])('keeps the reflected cube silhouette connected without exterior rays (camera offset %f)', async (offset) => {
+  const compiler = await import(
+    /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+  );
+  const source = (name: string) =>
+    readFileSync(resolve(`packages/shader/src/${name}.wgsl`), 'utf8');
+  const compile = async (name: string, id: string) => {
+    const result = await compiler.compileShader(source(name), {
+      id,
+      imports: { 'forgeax_view::common': source('common') },
+    });
+    if (!result.ok) throw result.error;
+    return result.value.wgsl;
+  };
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) throw new Error('Dawn adapter unavailable');
+  const device = await adapter.requestDevice();
+  device.pushErrorScope('validation');
+  try {
+    const size = 512,
+      half = size / 2;
+    const projection = mat4.create(),
+      camera = mat4.create(),
+      vp = mat4.create(),
+      inverse = mat4.create();
+    mat4.perspective(projection, Math.PI / 3, 1, 0.1, 20);
+    mat4.lookAt(
+      camera,
+      vec3.create(6 + offset, 3, 6 - offset),
+      vec3.create(offset, 0, -offset),
+      vec3.create(0, 1, 0),
+    );
+    mat4.multiply(vp, projection, camera);
+    mat4.invert(inverse, vp);
+    const values = new Float32Array(VIEW_UNIFORM_BYTES / 4);
+    values.set(vp);
+    values.set([6 + offset, 3, 6 - offset], 24);
+    values.set(inverse, 44);
+    values.set([0.1, 20, 0, 0], 228);
+    values.set([12, 0.2, 0.65, 1], 236);
+    const view = device.createBuffer({
+      size: VIEW_UNIFORM_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    device.queue.writeBuffer(view, 0, values);
+    const sampled = GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_RENDER_ATTACHMENT;
+    const depth = device.createTexture({
+      size: [size, size],
+      format: 'depth32float',
+      usage: sampled,
+    });
+    const color = () =>
+      device.createTexture({ size: [size, size], format: 'rgba16float', usage: sampled });
+    const normal = color(),
+      radiance = color(),
+      fallback = color(),
+      temporal = color();
+    const hiz = device.createTexture({
+      size: [half, half],
+      mipLevelCount: 9,
+      format: 'r32float',
+      usage: GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_STORAGE_BINDING,
+    });
+    const traced = device.createTexture({
+      size: [half, half],
+      format: 'rgba16float',
+      usage: GPU_TEXTURE_USAGE_STORAGE_BINDING | GPU_TEXTURE_USAGE_COPY_SRC,
+    });
+    const reactive = device.createTexture({
+      size: [half, half],
+      format: 'r32float',
+      usage: GPU_TEXTURE_USAGE_STORAGE_BINDING,
+    });
+    const seed = device.createShaderModule({
+      code: `
+@group(0) @binding(0) var<uniform> vp: mat4x4<f32>;
+@vertex fn vs(@builtin(vertex_index) i:u32)->@builtin(position) vec4<f32> {
+ let p=array<vec2<f32>,3>(vec2<f32>(-1.0),vec2<f32>(3.0,-1.0),vec2<f32>(-1.0,3.0));return vec4<f32>(p[i],0.0,1.0);
+}
+struct Out { @builtin(frag_depth) depth:f32, @location(0) normal:vec4<f32>, @location(1) color:vec4<f32>, @location(2) fallback:vec4<f32>, @location(3) temporal:vec4<f32> };
+@fragment fn fs(@builtin(position) p:vec4<f32>)->Out {
+ let screen=vec2<f32>(p.x/${size}.0*2.0-1.0,1.0-p.y/${size}.0*2.0)/sqrt(3.0);
+ let eye=vec3<f32>(${6 + offset},3.0,${6 - offset});
+ let d=vec3<f32>(-2.0/3.0,-1.0/3.0,-2.0/3.0)+screen.x*vec3<f32>(sqrt(0.5),0.0,-sqrt(0.5))+screen.y*vec3<f32>(-1.0/sqrt(18.0),sqrt(8.0/9.0),-1.0/sqrt(18.0));
+ let lower=min((vec3<f32>(-1.0)-eye)/d,(vec3<f32>(1.0)-eye)/d);
+ let upper=max((vec3<f32>(-1.0)-eye)/d,(vec3<f32>(1.0)-eye)/d);
+ let enter=max(max(lower.x,lower.y),lower.z);let leave=min(min(upper.x,upper.y),upper.z);
+ var t=select(1e6,(-1.0-eye.y)/d.y,d.y<0.0);var n=vec3<f32>(0.0,1.0,0.0);var c=vec3<f32>(0.1,0.2,0.4);var roughness=0.08;
+ if (enter>0.0 && enter<leave && enter<t) {
+  t=enter;let hit=eye+d*t;let a=abs(hit);n=vec3<f32>(0.0);
+  if(a.x>=a.y && a.x>=a.z){n.x=sign(hit.x);}else if(a.y>=a.z){n.y=sign(hit.y);}else{n.z=sign(hit.z);}
+  c=vec3<f32>(1.0,0.05,0.02);roughness=0.4;
+ }
+ let clip=vp*vec4<f32>(eye+d*t,1.0);var out:Out;
+ out.depth=clamp(clip.z/clip.w,0.0,1.0);out.normal=vec4<f32>(n*0.5+0.5,roughness);out.color=vec4<f32>(c,1.0);out.fallback=vec4<f32>(0.1,0.1,0.1,1.0);out.temporal=vec4<f32>(0.0);return out;
+}`,
+    });
+    const seedPipeline = await device.createRenderPipelineAsync({
+      layout: 'auto',
+      vertex: { module: seed, entryPoint: 'vs' },
+      fragment: {
+        module: seed,
+        entryPoint: 'fs',
+        targets: Array.from({ length: 4 }, () => ({ format: 'rgba16float' as const })),
+      },
+      depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'always' },
+    });
+    const compute = async (name: string, id: string, entryPoint: string) =>
+      device.createComputePipelineAsync({
+        layout: 'auto',
+        compute: {
+          module: device.createShaderModule({ code: await compile(name, id) }),
+          entryPoint,
+        },
+      });
+    const seedHiz = await compute('ssr-hiz', 'forgeax_ssr::hiz', 'ssr_hiz_seed');
+    const reduceHiz = await compute('ssr-hiz-reduce', 'forgeax_ssr::hiz_reduce', 'ssr_hiz_reduce');
+    const trace = await compute('ssr-trace', 'forgeax_ssr::trace', 'ssr_trace');
+    const encoder = device.createCommandEncoder();
+    const raster = encoder.beginRenderPass({
+      colorAttachments: [normal, radiance, fallback, temporal].map((t) => ({
+        view: t.createView(),
+        loadOp: 'clear' as const,
+        storeOp: 'store' as const,
+        clearValue: [0, 0, 0, 0],
+      })),
+      depthStencilAttachment: {
+        view: depth.createView(),
+        depthClearValue: 1,
+        depthLoadOp: 'clear',
+        depthStoreOp: 'store',
+      },
+    });
+    raster.setPipeline(seedPipeline);
+    raster.setBindGroup(
+      0,
+      device.createBindGroup({
+        layout: seedPipeline.getBindGroupLayout(0),
+        entries: [{ binding: 0, resource: { buffer: view } }],
+      }),
+    );
+    raster.draw(3);
+    raster.end();
+    const dispatch = (
+      pipeline: GPUComputePipeline,
+      entries: GPUBindGroupEntry[],
+      extent: number,
+    ) => {
+      const pass = encoder.beginComputePass();
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(
+        0,
+        device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries }),
+      );
+      pass.dispatchWorkgroups(Math.ceil(extent / 8), Math.ceil(extent / 8));
+      pass.end();
+    };
+    for (let level = 0; level < 9; level++) {
+      dispatch(
+        level === 0 ? seedHiz : reduceHiz,
+        [
+          {
+            binding: 0,
+            resource:
+              level === 0
+                ? depth.createView()
+                : hiz.createView({ baseMipLevel: level - 1, mipLevelCount: 1 }),
+          },
+          { binding: 1, resource: hiz.createView({ baseMipLevel: level, mipLevelCount: 1 }) },
+          ...(level === 0 ? [{ binding: 2, resource: { buffer: view } }] : []),
+        ],
+        half >> level,
+      );
+    }
+    dispatch(
+      trace,
+      [depth, normal, radiance, hiz, traced]
+        .map<GPUBindGroupEntry>((t, binding) => ({ binding, resource: t.createView() }))
+        .concat([
+          { binding: 5, resource: { buffer: view } },
+          { binding: 6, resource: fallback.createView() },
+          { binding: 7, resource: temporal.createView() },
+          { binding: 8, resource: reactive.createView() },
+        ]),
+      half,
+    );
+    const readback = device.createBuffer({
+      size: half * half * 8,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    encoder.copyTextureToBuffer({ texture: traced }, { buffer: readback, bytesPerRow: half * 8 }, [
+      half,
+      half,
+    ]);
+    device.queue.submit([encoder.finish()]);
+    await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ);
+    const words = new Uint16Array(readback.getMappedRange().slice(0));
+    readback.unmap();
+    const hits = new Uint8Array(half * half);
+    // Mirror-box slab intersections are independent of the GPU march and Hi-Z.
+    for (let y = 0; y < half; y++)
+      for (let x = 0; x < half; x++) {
+        const sx = (((2 * x + 0.5) / size) * 2 - 1) / Math.sqrt(3),
+          sy = (1 - ((2 * y + 0.5) / size) * 2) / Math.sqrt(3);
+        const d = [
+          -2 / 3 + sx * Math.SQRT1_2 - sy / Math.sqrt(18),
+          -1 / 3 + sy * Math.sqrt(8 / 9),
+          -2 / 3 - sx * Math.SQRT1_2 - sy / Math.sqrt(18),
+        ] as const;
+        let enter = -Infinity,
+          leave = Infinity;
+        const bounds = [
+          [-1, 1],
+          [-3, -1],
+          [-1, 1],
+        ] as const;
+        const eye = [6 + offset, 3, 6 - offset] as const;
+        for (const axis of [0, 1, 2] as const) {
+          const [lo, hi] = bounds[axis];
+          const a = (lo - eye[axis]) / d[axis],
+            b = (hi - eye[axis]) / d[axis];
+          enter = Math.max(enter, Math.min(a, b));
+          leave = Math.min(leave, Math.max(a, b));
+        }
+        hits[y * half + x] = Number(enter > 0 && enter < leave);
+      }
+    let interior = 0,
+      misses = 0,
+      exteriorHits = 0;
+    for (let y = 180; y < half - 1; y++)
+      for (let x = 1; x < half - 1; x++) {
+        const footprint = [-1, 0, 1].flatMap((dy) =>
+          [-1, 0, 1].map((dx) => hits[(y + dy) * half + x + dx] === 1),
+        );
+        const offset = (y * half + x) * 4;
+        const confident = (words[offset + 3] ?? 0) >= 0x3800; // positive half >= 0.5
+        if (footprint.every(Boolean)) {
+          interior++;
+          if (!confident) misses++;
+        }
+        if (!footprint.some(Boolean) && confident && (words[offset] ?? 0) >= 0x3800) exteriorHits++;
+      }
+    expect(await device.popErrorScope()).toBeNull();
+    expect(interior).toBeGreaterThan(1000);
+    expect({ misses, exteriorHits }).toEqual({ misses: 0, exteriorHits: 0 });
+  } finally {
+    device.destroy();
+  }
+}, 30_000);

package/src/__tests__/ssr-gpu-dispatch.browser.test.ts

@@ -1,5 +1,6 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-webgpu';
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import {
   admittedSsrSpatial,
   runSsrGpuDispatch,
@@ -10,31 +11,43 @@ import {
 } from './ssr-gpu-dispatch';
 import { runSsrReprojectionProbe } from './ssr-reprojection-probe';
 
+const confidence = (values: readonly number[]) => values.filter((_, i) => i % 4 === 3);
+
 describe('SSR GPU dispatch Browser WebGPU probe', () => {
-  it('executes the admitted Hi-Z and trace shaders and reads a finite result', async () => {
+  let device: RhiDevice;
+  let sources: ReturnType<typeof sourcesFromManifest>;
+  beforeAll(async () => {
     expect(admittedSsrSpatial().status).toBe('admitted');
     const response = await fetch('/shaders/manifest.json');
     expect(response.ok).toBe(true);
-    const manifest = (await response.json()) as SsrShaderManifest;
+    sources = sourcesFromManifest((await response.json()) as SsrShaderManifest);
     const adapter = (await rhi.requestAdapter()).unwrap();
-    const device = (await adapter.requestDevice()).unwrap();
-    expect(await runSsrReprojectionProbe(device, sourcesFromManifest(manifest).temporal)).toEqual([
+    device = (await adapter.requestDevice()).unwrap();
+  });
+
+  // Independent cases identify the failing invariant. The 300-frame case
+  // also includes cold software-driver compilation and completed readbacks;
+  // its bounded 30-second execution allowance is not a frame-performance gate.
+  it('reprojects history and reconstructs perspective and orthographic view distance', async () => {
+    expect(await runSsrReprojectionProbe(device, sources.temporal)).toEqual([
       [0.5, 0.5, 0.375, 0.5625],
       [0.5, 0.5, 0.375, 0.5625],
       [0.5, 0.5, 0.375, 0.5625],
     ]);
-    for (const distances of await runSsrViewDistanceProbe(
-      device,
-      sourcesFromManifest(manifest).trace,
-    )) {
+    for (const distances of await runSsrViewDistanceProbe(device, sources.trace)) {
       expect(distances[0]).toBeCloseTo(6.58, 4);
       expect(distances[1]).toBeCloseTo(12, 4);
     }
-    const hit = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 300);
+  });
+
+  it('executes 300 stable Hi-Z, trace and temporal frames with finite visible hits', async () => {
+    const hit = await runSsrGpuDispatch(device, sources, 300);
+    expect(hit.passNames.filter((name) => name.startsWith('ssr-hiz-reduce'))).toHaveLength(1);
+    expect(hit.passNames.filter((name) => name.startsWith('ssr-reflection-mip'))).toHaveLength(1);
     expect(hit.passNames).toContain('ssr-hiz-seed');
     expect(hit.passNames).toContain('ssr-trace');
     expect(hit.passNames).toContain('ssr-temporal');
-    expect(hit.passNames).toContain('ssr-trace');
+    expect(hit.passNames.filter((name) => name === 'ssr-compose')).toHaveLength(1);
     expect(hit.resourceNames).toContain('ssr-resolved');
     expect(hit.pixels).toHaveLength(300);
     expect(new Set(hit.pixels.map((pixel) => pixel.join(','))).size).toBe(1);
@@ -45,47 +58,42 @@ describe('SSR GPU dispatch Browser WebGPU probe', () => {
     const dx = (((0.5 / 64) * 2 - 1) * 2) / Math.sqrt(3);
     expect(hiz[0]).toBeCloseTo(6 / (1 - dx), 2);
     const trace = hit.tracePixels[0] ?? [];
-    const confidence = (values: readonly number[]) => values.filter((_, i) => i % 4 === 3);
     expect(confidence(trace).some((value) => value > 0)).toBe(true);
     expect(confidence(trace).filter((value) => value >= 0x3400).length).toBeGreaterThan(40);
     expect(confidence(trace).every((value) => value <= 0x3c00)).toBe(true);
-    const backFace = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 1, {
-      sourceBackFacing: true,
-    });
-    expect(confidence(backFace.tracePixels[0] ?? []).every((value) => value === 0)).toBe(true);
+  }, 30_000);
+
+  it('rejects back-facing sources', async () => {
+    const result = await runSsrGpuDispatch(device, sources, 1, { sourceBackFacing: true });
+    expect(confidence(result.tracePixels[0] ?? []).every((value) => value === 0)).toBe(true);
+  });
 
-    const coordinates = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 1, {
+  it.each([
+    false,
+    true,
+  ])('preserves reflected coordinates (recessed source: %s)', async (recessedSource) => {
+    const result = await runSsrGpuDispatch(device, sources, 1, {
       coordinateSource: true,
+      recessedSource,
     });
-    const errors = ssrCoordinateErrors(coordinates.tracePixels[0] ?? []);
+    const errors = ssrCoordinateErrors(result.tracePixels[0] ?? [], recessedSource);
     expect(errors.length).toBeGreaterThan(10);
     expect(errors.filter((error) => error > 0.002).length / errors.length).toBeLessThan(0.05);
+  });
 
-    const grout = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 1, {
-      coordinateSource: true,
-      recessedSource: true,
-    });
-    const groutErrors = ssrCoordinateErrors(grout.tracePixels[0] ?? [], true);
-    expect(groutErrors.length).toBeGreaterThan(10);
-    expect(groutErrors.filter((error) => error > 0.002).length / groutErrors.length).toBeLessThan(
-      0.05,
-    );
-
-    for (const options of [{ excludedSource: true }, { excludedReceiver: true }]) {
-      const excluded = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 1, options);
-      expect(confidence(excluded.tracePixels[0] ?? []).every((value) => value === 0)).toBe(true);
-    }
-
-    const miss = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 1, {
-      maxDistance: 0.01,
-    });
-    expect(miss.tracePixels[0]?.[3]).toBe(0);
-    expect(miss.tracePixels[0]).not.toEqual(hit.tracePixels[0]);
+  it.each([
+    { excludedSource: true },
+    { excludedReceiver: true },
+  ])('rejects excluded material coverage (%j)', async (options) => {
+    const result = await runSsrGpuDispatch(device, sources, 1, options);
+    expect(confidence(result.tracePixels[0] ?? []).every((value) => value === 0)).toBe(true);
+  });
 
-    const disabled = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 1, {
-      enabled: false,
-    });
-    expect(disabled.tracePixels[0]?.[3]).toBe(0);
-    expect(disabled.tracePixels[0]).not.toEqual(hit.tracePixels[0]);
+  it.each([
+    { maxDistance: 0.01 },
+    { enabled: false },
+  ])('produces zero confidence for an unavailable ray (%j)', async (options) => {
+    const result = await runSsrGpuDispatch(device, sources, 1, options);
+    expect(confidence(result.tracePixels[0] ?? []).every((value) => value === 0)).toBe(true);
   });
 });

package/src/__tests__/ssr-gpu-dispatch.dawn.test.ts

@@ -39,6 +39,10 @@ describe('SSR GPU dispatch Dawn probe', () => {
       expect(distances[1]).toBeCloseTo(12, 4);
     }
     const hit = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 300);
+    // Mip count must not grow CPU pass recording: ordered dispatches share
+    // one compute pass per pyramid, with every level still produced below.
+    expect(hit.passNames.filter((name) => name.startsWith('ssr-hiz-reduce'))).toHaveLength(1);
+    expect(hit.passNames.filter((name) => name.startsWith('ssr-reflection-mip'))).toHaveLength(1);
     expect(hit.passNames).toContain('ssr-hiz-seed');
     expect(hit.passNames).toContain('ssr-trace');
     expect(hit.passNames).toContain('ssr-temporal');

package/src/__tests__/ssr-gpu-dispatch.ts

@@ -887,15 +887,22 @@ export async function runSsrGpuDispatch(
     const submitted = device.queue.submit([finished.value]);
     if (!submitted.ok) throw submitted.error;
     await device.queue.onSubmittedWorkDone();
-    const mapped = await readbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ);
+    // These independent copies share one completed submission. Request all
+    // mappings together instead of paying three browser/driver round trips
+    // for each of the 300 frames; every buffer is still read and validated.
+    const [mapped, traceMapped, hizMapped] = await Promise.all([
+      readbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ),
+      traceReadbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ),
+      hizReadbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ),
+    ]);
     if (!mapped.ok) throw mapped.error;
+    if (!traceMapped.ok) throw traceMapped.error;
+    if (!hizMapped.ok) throw hizMapped.error;
     const range = mapped.value.getMappedRange();
     if (!range.ok) throw range.error;
     const readbackWords = new Uint16Array(range.value.slice(0, bytesPerRow * SSR_GPU_PROBE_HEIGHT));
     pixels.push([...readbackWords.slice(0, 4)]);
     mapped.value.unmap();
-    const traceMapped = await traceReadbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ);
-    if (!traceMapped.ok) throw traceMapped.error;
     const traceRange = traceMapped.value.getMappedRange();
     if (!traceRange.ok) throw traceRange.error;
     const traceWords = new Uint16Array(
@@ -903,8 +910,6 @@ export async function runSsrGpuDispatch(
     );
     tracePixels.push([...traceWords]);
     traceMapped.value.unmap();
-    const hizMapped = await hizReadbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ);
-    if (!hizMapped.ok) throw hizMapped.error;
     const hizRange = hizMapped.value.getMappedRange();
     if (!hizRange.ok) throw hizRange.error;
     const hizWords = new Float32Array(hizRange.value.slice(0, bytesPerRow * SSR_GPU_PROBE_HEIGHT));

package/src/__tests__/ssr-graph-topology.unit.test.ts

@@ -78,7 +78,7 @@ describe('SSR typed spatial graph', () => {
     const compiled = graph.compile({ device, surfaceSize: { width: 5, height: 3 } }).unwrap();
     const info = compiled.inspect();
     const names = info.passes.map((pass) => pass.name);
-    expect(names).toEqual(['seed-inputs', 'ssr-hiz-seed', 'ssr-hiz-reduce-1', 'ssr-trace']);
+    expect(names).toEqual(['seed-inputs', 'ssr-hiz-seed', 'ssr-hiz-reduce-chain', 'ssr-trace']);
     expect(info.resources.map((resource) => resource.label)).toEqual(
       expect.arrayContaining(['ssr-hiz', 'ssr-trace', 'ssr-hit-reactivity']),
     );
@@ -88,7 +88,7 @@ describe('SSR typed spatial graph', () => {
         { resource: 'ssr-hit-reactivity', usage: 'storage-write' },
       ]),
     );
-    expect(info.passes.find((pass) => pass.name === 'ssr-hiz-reduce-1')?.accesses).toEqual([
+    expect(info.passes.find((pass) => pass.name === 'ssr-hiz-reduce-chain')?.accesses).toEqual([
       { resource: 'ssr-hiz', usage: 'sampled-read' },
       { resource: 'ssr-hiz', usage: 'storage-write' },
     ]);

package/src/__tests__/ssr-hiz.browser.test.ts

@@ -125,7 +125,7 @@ describe('SSR Hi-Z spatial Browser WebGPU gate', () => {
     expect(info.passes.map((pass) => pass.name)).toEqual([
       'seed-inputs',
       'ssr-hiz-seed',
-      'ssr-hiz-reduce-1',
+      'ssr-hiz-reduce-chain',
       'ssr-trace',
     ]);
     expect(

package/src/__tests__/ssr-hiz.dawn.test.ts

@@ -125,7 +125,7 @@ describe('SSR Hi-Z spatial Dawn WebGPU gate', () => {
     expect(info.passes.map((pass) => pass.name)).toEqual([
       'seed-inputs',
       'ssr-hiz-seed',
-      'ssr-hiz-reduce-1',
+      'ssr-hiz-reduce-chain',
       'ssr-trace',
     ]);
     expect(

package/src/__tests__/ssr-spatial.integration.test.ts

@@ -122,7 +122,7 @@ describe('SSR spatial RhiNull integration', () => {
     expect(device.framePassNames).toEqual([
       'seed-inputs',
       'ssr-hiz-seed',
-      'ssr-hiz-reduce-1',
+      'ssr-hiz-reduce-chain',
       'ssr-trace',
     ]);
     expect(compiled.value.inspect().resources).toEqual(

package/src/__tests__/standard-cluster-variant-resolution.unit.test.ts

@@ -44,6 +44,46 @@ const noColorVariants = [
 ] as never;
 const noColorManifest = { variants: noColorVariants } as never;
 describe('Standard clustered variant resolution', () => {
+  it.each([
+    false,
+    true,
+  ])('retains colored clustered geometry when reflection fallback is %s', (fallback) => {
+    const projection = deriveVertexLayoutProjection({
+      position: new Float32Array(9),
+      color: new Float32Array(12),
+    });
+    const projected = variantSetFromVertexLayoutProjection(
+      projection,
+      standardTopologyVariantSet({ kind: 'clustered' }, true, true),
+    );
+    if (!projected.ok) throw projected.error;
+    const geometry = projected.value;
+    const request =
+      geometry === '' && fallback
+        ? ''
+        : `${geometry === '' ? '' : `${geometry}+`}REFLECTION_FALLBACK_AVAILABLE=${fallback}`;
+    const resolved = resolveMaterialShaderVariantSet(
+      request,
+      [
+        {
+          defines: {
+            CLUSTER_FORWARD_AVAILABLE: true,
+            STORAGE_BUFFER_AVAILABLE: true,
+            VERTEX_COLOR_AVAILABLE: true,
+            REFLECTION_FALLBACK_AVAILABLE: false,
+          },
+        },
+      ],
+      'webgpu',
+      true,
+    );
+    if (fallback) expect(resolved).toBe('');
+    else
+      expect(resolved).toBe(
+        'CLUSTER_FORWARD_AVAILABLE=true+REFLECTION_FALLBACK_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true',
+      );
+  });
+
   it('derives the canonical capability key for every storage/cluster pair', () => {
     expect(standardCapabilityVariantSet(true, true, true)).toBe(
       'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true',