@forgeax/engine-render 0.1.28 → 0.1.30

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-format-probe-gating.integration.test.ts

@@ -0,0 +1,82 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { RhiNullAdapter, rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../assembly/factory';
+import type { SsrAdmissionIdentity } from '../ssr/identity';
+
+const identity: SsrAdmissionIdentity = {
+  sourceHead: 'head',
+  sourceTree: 'tree',
+  lockSha256: 'lock',
+  buildSha256: 'build',
+};
+
+function manifestUrl(): string {
+  return `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+}
+
+describe('SSR format-probe gating', () => {
+  it.each([
+    false,
+    true,
+  ])('prepares only explicitly configured SSR before initialization completes (%s)', async (configured) => {
+    const adapter = new RhiNullAdapter();
+    const deviceResult = await adapter.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok) return;
+    const device = deviceResult.value;
+    let probeCalls = 0;
+    let markProbeStarted = () => {};
+    const probeStarted = new Promise<void>((resolve) => {
+      markProbeStarted = resolve;
+    });
+    let releaseProbe = () => {};
+    const probeBarrier = new Promise<void>((resolve) => {
+      releaseProbe = resolve;
+    });
+    const probe = device.probeTextureFormatCapability.bind(device);
+    (
+      device as RhiDevice & {
+        probeTextureFormatCapability: RhiDevice['probeTextureFormatCapability'];
+      }
+    ).probeTextureFormatCapability = async () => {
+      probeCalls += 1;
+      markProbeStarted();
+      await probeBarrier;
+      return probe();
+    };
+    const observedRhi = {
+      ...rhi,
+      requestAdapter: async () =>
+        ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => ok(device),
+        }),
+    };
+    let initialized = false;
+    const initialization = createRenderer(
+      { getContext: () => null },
+      { rhi: observedRhi, ...(configured ? { ssrIdentity: identity } : {}) },
+      { shaderManifestUrl: manifestUrl() },
+    ).then((renderer) => {
+      initialized = true;
+      return renderer;
+    });
+    if (configured) {
+      await probeStarted;
+      expect(initialized).toBe(false);
+      releaseProbe();
+    }
+    const renderer = await initialization;
+
+    expect(probeCalls).toBe(configured ? 1 : 0);
+    // Inspection neither starts a second probe nor allocates frame work.
+    renderer.inspect();
+    renderer.inspect();
+    expect(probeCalls).toBe(configured ? 1 : 0);
+    expect(renderer.inspect().ssrDependencies.work.temporalDemand).toBe(0);
+    await renderer.dispose();
+  });
+});

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

@@ -0,0 +1,99 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { beforeAll, describe, expect, it } from 'vitest';
+import {
+  admittedSsrSpatial,
+  runSsrGpuDispatch,
+  runSsrViewDistanceProbe,
+  type SsrShaderManifest,
+  sourcesFromManifest,
+  ssrCoordinateErrors,
+} 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', () => {
+  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);
+    sources = sourcesFromManifest((await response.json()) as SsrShaderManifest);
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    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, sources.trace)) {
+      expect(distances[0]).toBeCloseTo(6.58, 4);
+      expect(distances[1]).toBeCloseTo(12, 4);
+    }
+  });
+
+  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.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);
+    expect(hit.pixel.some((value) => value !== 0)).toBe(true);
+    const hiz = hit.hizPixels[0] ?? [];
+    // Independently derive the view distance at the leftmost pixel of the
+    // inclined receiver from its plane equation and real perspective ray.
+    const dx = (((0.5 / 64) * 2 - 1) * 2) / Math.sqrt(3);
+    expect(hiz[0]).toBeCloseTo(6 / (1 - dx), 2);
+    const trace = hit.tracePixels[0] ?? [];
+    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);
+  }, 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);
+  });
+
+  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(result.tracePixels[0] ?? [], recessedSource);
+    expect(errors.length).toBeGreaterThan(10);
+    expect(errors.filter((error) => error > 0.002).length / errors.length).toBeLessThan(0.05);
+  });
+
+  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);
+  });
+
+  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

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { describe, expect, it } from 'vitest';
+import {
+  admittedSsrSpatial,
+  runSsrGpuDispatch,
+  runSsrViewDistanceProbe,
+  sourcesFromManifest,
+  ssrCoordinateErrors,
+} from './ssr-gpu-dispatch';
+import { runSsrReprojectionProbe } from './ssr-reprojection-probe';
+
+describe('SSR GPU dispatch Dawn probe', () => {
+  it('executes the admitted Hi-Z and trace shaders and reads a finite result', async () => {
+    expect(admittedSsrSpatial().status).toBe('admitted');
+    // CI hydrates the shared-app projection; local builds publish the same
+    // shader producer under shared-build-inputs. Never depend on a demo dist.
+    const manifestPath = ['shared-app-inputs', 'shared-build-inputs']
+      .map((directory) => resolve(process.cwd(), directory, 'shaders/manifest.json'))
+      .find(existsSync);
+    if (manifestPath === undefined)
+      throw new Error('SSR Dawn requires the built shared shader manifest');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
+      readonly entries: readonly { readonly wgsl: string }[];
+    };
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    expect(await runSsrReprojectionProbe(device, sourcesFromManifest(manifest).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,
+    )) {
+      expect(distances[0]).toBeCloseTo(6.58, 4);
+      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');
+    expect(hit.passNames.filter((name) => name === 'ssr-compose')).toHaveLength(1);
+    expect(hit.passNames).toContain('ssr-trace');
+    expect(hit.resourceNames).toContain('ssr-resolved');
+    expect(hit.pixels).toHaveLength(300);
+    expect(new Set(hit.pixels.map((pixel) => pixel.join(','))).size).toBe(1);
+    expect(hit.pixel.some((value) => value !== 0)).toBe(true);
+    // The history must store the actually shaded receiver/wall normal, not a
+    // normal reconstructed across their depth discontinuity. Alpha is the
+    // independent reflection confidence in the same four-byte texel.
+    const surfaceNormals = new Set(
+      Array.from({ length: hit.surfacePixels.length / 4 }, (_, p) =>
+        hit.surfacePixels.slice(p * 4, p * 4 + 3).join(','),
+      ),
+    );
+    expect(surfaceNormals).toEqual(new Set(['218,128,218', '0,128,128']));
+    expect(hit.surfacePixels.filter((_, i) => i % 4 === 3).some((value) => value > 0)).toBe(true);
+    const hiz = hit.hizPixels[0] ?? [];
+    // Independently derive the view distance at the leftmost pixel of the
+    // inclined receiver from its plane equation and real perspective ray.
+    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);
+    // The analytical mirror faces a real wall across a broad interior region.
+    // A positive-but-nearly-zero boundary hit is not a useful reflection.
+    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);
+
+    const coordinates = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 1, {
+      coordinateSource: true,
+    });
+    const errors = ssrCoordinateErrors(coordinates.tracePixels[0] ?? []);
+    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]);
+
+    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]);
+  });
+});