@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/specular-environment-scale.dawn.test.ts

@@ -0,0 +1,156 @@
+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_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+} from '../gpu-usage';
+
+/**
+ * Numeric Dawn proof for the shared Skylight/ReflectionProbe scalar decode.
+ * The material source tests cover both PROBE_BLEND branches; this test keeps
+ * the sentinel arithmetic and AO multiplication executable on a real device.
+ */
+it('decodes regular and probe-sentinel specular environment scales without tint metadata leakage', async () => {
+  const compiler = await import(
+    /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+  );
+  const source = readFileSync(resolve('packages/shader/src/ibl-sampling.wgsl'), 'utf8');
+  const compiled = await compiler.compileShader(
+    `${source}
+@group(0) @binding(0) var<storage, read> cases: array<vec4<f32>>;
+@group(0) @binding(1) var<storage, read> aoValues: array<f32>;
+@group(0) @binding(2) var<storage, read_write> outputs: array<vec4<f32>>;
+@compute @workgroup_size(4) fn probe_scale(@builtin(global_invocation_id) id: vec3<u32>) {
+  let scale = decodeSpecularEnvironmentScale(cases[id.x].xyz, cases[id.x].w);
+  // RGB is the decoded scale. Alpha is the same lobe after the material AO
+  // factor, matching the detached fallback's post-environment multiplication.
+  outputs[id.x] = vec4<f32>(scale, scale.x * aoValues[id.x]);
+}`,
+    {
+      id: 'forgeax::specular-environment-scale-test',
+      imports: {
+        'forgeax_pbr::ibl_shared': readFileSync(
+          resolve('packages/shader/src/ibl-shared.wgsl'),
+          'utf8',
+        ),
+      },
+    },
+  );
+  if (!compiled.ok) throw compiled.error;
+
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const cases = device
+    .createBuffer({
+      size: 64,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const aoValues = device
+    .createBuffer({
+      size: 16,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const outputs = device
+    .createBuffer({ size: 64, usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC })
+    .unwrap();
+  const readback = device
+    .createBuffer({ size: 64, usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST })
+    .unwrap();
+
+  try {
+    device.queue
+      .writeBuffer(
+        cases,
+        0,
+        new Float32Array([
+          0.25,
+          0.5,
+          0.75,
+          1.5, // regular Skylight: non-unit tint and intensity
+          0.2,
+          0.4,
+          0.8,
+          0.25, // regular Skylight: second tint/intensity pair
+          3.0,
+          -2.0,
+          7.0,
+          -1.4, // probe sentinel: color lanes are non-zero box metadata
+          8.0,
+          9.0,
+          10.0,
+          -1.0, // zero-intensity probe sentinel
+        ]),
+      )
+      .unwrap();
+    device.queue.writeBuffer(aoValues, 0, new Float32Array([0.35, 0.8, 0.6, 0.25])).unwrap();
+
+    const layout = device
+      .createBindGroupLayout({
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            buffer: { type: 'read-only-storage' },
+          },
+          {
+            binding: 1,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            buffer: { type: 'read-only-storage' },
+          },
+          { binding: 2, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'storage' } },
+        ],
+      })
+      .unwrap();
+    const module = createShaderModuleImmediate(device, { code: compiled.value.wgsl }).unwrap();
+    const pipeline = device
+      .createComputePipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }).unwrap(),
+        compute: { module, entryPoint: 'probe_scale' },
+      })
+      .unwrap();
+    const bindGroup = device
+      .createBindGroup({
+        layout,
+        entries: [
+          { binding: 0, resource: { kind: 'buffer', value: { buffer: cases } } },
+          { binding: 1, resource: { kind: 'buffer', value: { buffer: aoValues } } },
+          { binding: 2, resource: { kind: 'buffer', value: { buffer: outputs } } },
+        ],
+      })
+      .unwrap();
+    const encoder = device.createCommandEncoder().unwrap();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(1);
+    pass.end();
+    encoder.copyBufferToBuffer(outputs, 0, readback, 0, 64);
+    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 = [
+      [0.375, 0.75, 1.125, 0.13125],
+      [0.05, 0.1, 0.2, 0.04],
+      [0.4, 0.4, 0.4, 0.24],
+      [0.0, 0.0, 0.0, 0.0],
+    ].flat();
+    values.forEach((value, index) => {
+      const target = expected[index];
+      if (target === undefined) throw new Error(`Unexpected output lane ${index}`);
+      expect(value, `specular environment scale lane ${index}`).toBeCloseTo(target, 5);
+    });
+  } finally {
+    device.destroyBuffer(cases).unwrap();
+    device.destroyBuffer(aoValues).unwrap();
+    device.destroyBuffer(outputs).unwrap();
+    device.destroyBuffer(readback).unwrap();
+  }
+});

package/src/__tests__/ssr-admission-matrix.integration.test.ts

@@ -80,7 +80,6 @@ describe('SSR M0 admission matrix', () => {
   it.each([
     ['producer', { format, temporal }, 'rebuild'],
     ['format', { reflectionFallback, temporal }, 'retry'],
-    ['temporal', { reflectionFallback, format }, 'retry'],
   ] as const)('blocks when the %s receipt is absent', (_, receipts, action) => {
     const result = admitSsrM0({ requested: true, identity, ...receipts });
     expect(result.status).toBe('fallback-only');
@@ -88,6 +87,13 @@ describe('SSR M0 admission matrix', () => {
     expect(result.failure?.detail.action).toBe(action);
   });
 
+  it('admits fresh spatial SSR before any temporal history has been submitted', () => {
+    const result = admitSsrM0({ requested: true, identity, reflectionFallback, format });
+    expect(result.status).toBe('admitted');
+    expect(result.work.historyCount).toBe(0);
+    expect(result.work.temporalDemand).toBe(0);
+  });
+
   it('publishes a typed owner recovery action on every blocked path', () => {
     const notRequested = admitSsrM0({ requested: false, identity });
     expect(notRequested.failure?.detail.action).toBe('retry');

package/src/__tests__/ssr-confidence-compose.unit.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import { composeSsrReflection } from '../ssr/composition';
+import { buildSsrTracePlan, computeSsrConfidence } from '../ssr/graph';
+
+const baseSpecular = [0.2, 0.3, 0.4] as const;
+const screenSpecular = [0.8, 0.7, 0.9] as const;
+const fallbackSpecular = [0.1, 0.2, 0.3] as const;
+
+describe('SSR spatial confidence and composition contract', () => {
+  it('multiplies every bounded confidence factor without exceeding one', () => {
+    const confidence = computeSsrConfidence({
+      hit: 0.9,
+      thickness: 0.8,
+      facing: 0.7,
+      edge: 0.6,
+      roughness: 0.5,
+      temporal: 0.4,
+    });
+    expect(confidence).toBeCloseTo(0.06048, 12);
+    expect(confidence).toBeGreaterThanOrEqual(0);
+    expect(confidence).toBeLessThanOrEqual(1);
+  });
+
+  it('returns zero for non-finite or out-of-range factors instead of hiding invalid input', () => {
+    expect(
+      computeSsrConfidence({
+        hit: 1,
+        thickness: 1,
+        facing: 1,
+        edge: 1,
+        roughness: Number.NaN,
+        temporal: 1,
+      }),
+    ).toBe(0);
+    expect(
+      computeSsrConfidence({
+        hit: 1.01,
+        thickness: 1,
+        facing: 1,
+        edge: 1,
+        roughness: 1,
+        temporal: 1,
+      }),
+    ).toBe(0);
+  });
+
+  it('keeps the Standard lobe unchanged at zero and replaces only its fallback delta at one', () => {
+    expect(
+      composeSsrReflection({ c: 0, baseSpecular, screenSpecular, fallbackSpecular }),
+    ).toMatchObject({ ok: true, value: baseSpecular });
+    const full = composeSsrReflection({
+      c: 1,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(full.ok).toBe(true);
+    if (full.ok) {
+      expect(full.value[0]).toBeCloseTo(0.9, 12);
+      expect(full.value[1]).toBeCloseTo(0.8, 12);
+      expect(full.value[2]).toBeCloseTo(1, 12);
+    }
+    const half = composeSsrReflection({
+      c: 0.5,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(half.ok).toBe(true);
+    if (half.ok) {
+      expect(half.value[0]).toBeCloseTo(0.55, 12);
+      expect(half.value[1]).toBeCloseTo(0.55, 12);
+      expect(half.value[2]).toBeCloseTo(0.7, 12);
+    }
+  });
+
+  it('keeps trace work bounded and explicitly half-resolution', () => {
+    expect(buildSsrTracePlan()).toEqual({
+      resolution: 'half',
+      coarseSteps: 48,
+      refineSteps: 5,
+    });
+  });
+});

package/src/__tests__/ssr-coordinate-oracle.unit.test.ts

@@ -0,0 +1,28 @@
+import { expect, it } from 'vitest';
+import { ssrCoordinateErrors } from './ssr-gpu-dispatch';
+
+it('checks continuous mirror-hit UVs and rejects nearest-texel quantization', () => {
+  // Receiver (32.5, 16.5) in the 64x32 analytical mirror fixture hits
+  // UV (0.6409469116, 0.5203439343). The source is a linear UV ramp.
+  const words = Array<number>(64 * 16 * 4).fill(0);
+  const offset = (8 * 64 + 16) * 4;
+  words.splice(offset, 4, 14625, 14378, 0, 0x3c00);
+  const continuous = ssrCoordinateErrors(words);
+  expect(continuous).toHaveLength(1);
+  expect(continuous[0]).toBeLessThan(0.0003);
+
+  // The nearest texel instead encodes UV (0.6484375, 0.515625).
+  words.splice(offset, 4, 14640, 14368, 0, 0x3c00);
+  expect(ssrCoordinateErrors(words)[0]).toBeGreaterThan(0.007);
+});
+
+it('retains partial wall footprints and rejects back-facing receiver contamination', () => {
+  const words = Array<number>(64 * 16 * 4).fill(0);
+  const offset = (8 * 64 + 19) * 4;
+  // Only column 39 covers the wall at this hit; column 38 is the receiver.
+  words.splice(offset, 4, 14576, 14369, 0, 0x3800);
+  expect(ssrCoordinateErrors(words)).toHaveLength(1);
+  expect(ssrCoordinateErrors(words)[0]).toBeLessThan(0.0003);
+  words.splice(offset, 4, 13721, 13536, 0, 0x3800);
+  expect(ssrCoordinateErrors(words)[0]).toBeGreaterThan(0.25);
+});

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,91 @@
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { describe, expect, it } from 'vitest';
+import {
+  admittedSsrSpatial,
+  runSsrGpuDispatch,
+  runSsrViewDistanceProbe,
+  type SsrShaderManifest,
+  sourcesFromManifest,
+  ssrCoordinateErrors,
+} from './ssr-gpu-dispatch';
+import { runSsrReprojectionProbe } from './ssr-reprojection-probe';
+
+describe('SSR GPU dispatch Browser WebGPU probe', () => {
+  it('executes the admitted Hi-Z and trace shaders and reads a finite result', 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;
+    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);
+    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.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] ?? [];
+    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);
+
+    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]);
+  });
+});

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

@@ -0,0 +1,112 @@
+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);
+    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]);
+  });
+});