@forgeax/engine-render 0.1.28 → 0.1.30

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

@@ -0,0 +1,158 @@
+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);
+  // Probe intensity is applied while blending local and global radiance.
+  // The outer scale stays one for either sentinel, including zero intensity.
+  // 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],
+      [1, 1, 1, 0.6],
+      [1, 1, 1, 0.25],
+    ].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__/ssao-config.unit.test.ts

@@ -13,6 +13,7 @@ describe('SSAO parameter authority', () => {
       radius: SSAO_DEFAULT_RADIUS,
       bias: SSAO_DEFAULT_BIAS,
       intensity: SSAO_DEFAULT_INTENSITY,
+      quality: 'high',
     });
   });
 
@@ -21,9 +22,15 @@ describe('SSAO parameter authority', () => {
       radius: 0.65,
       bias: 0.025,
       intensity: 1.4,
+      quality: 'high',
     });
   });
 
+  it.each([NaN, Infinity, -Infinity])('rejects non-finite parameters (%s)', (value) => {
+    for (const field of ['radius', 'bias', 'intensity'])
+      expect(resolveSsaoParameters({ [field]: value }).ok).toBe(false);
+  });
+
   it('returns structured failures for invalid radius and bias', () => {
     const invalidRadius = resolveSsaoParameters({ radius: 0 });
     const invalidBias = resolveSsaoParameters({ bias: -0.1 });

package/src/__tests__/ssao-surface.dawn.test.ts

@@ -0,0 +1,252 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { mat4 } from '@forgeax/engine-math';
+import { expect, it } from 'vitest';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  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 { generateSsaoKernel, generateSsaoNoise } from '../ssao-buffers';
+
+// Analytic tilted plane: y + z + 4 = 0. Every hemisphere sample lies in
+// empty space. Exercise the production fragment program, not a CPU AO copy.
+it.each([
+  ['plane', 16],
+  ['plane', 32],
+  ['plane', 64],
+  ['orthographic', 64],
+  ['contact', 64],
+  ['distant-edge', 64],
+  ['background', 64],
+] as const)('production SSAO %s with %i samples', async (scene, sampleCount) => {
+  const compiler = await import(
+    /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+  );
+  const compiled = await compiler.compileShader(
+    readFileSync(resolve('packages/shader/src/hdrp-ssao.wgsl'), 'utf8'),
+    {
+      id: 'forgeax_hdrp::ssao',
+      imports: {
+        'forgeax_view::common': readFileSync(resolve('packages/shader/src/common.wgsl'), 'utf8'),
+      },
+    },
+  );
+  if (!compiled.ok) throw compiled.error;
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) throw new Error('Dawn adapter unavailable');
+  const device = await adapter.requestDevice();
+  const errors: string[] = [];
+  device.addEventListener('uncapturederror', (event) => errors.push(event.error.message));
+  const size = 128;
+  const texture = (format: GPUTextureFormat, width = size, height = size) =>
+    device.createTexture({
+      size: [width, height],
+      format,
+      usage:
+        GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+        GPU_TEXTURE_USAGE_TEXTURE_BINDING |
+        GPU_TEXTURE_USAGE_COPY_SRC |
+        GPU_TEXTURE_USAGE_COPY_DST,
+    });
+  const depth = texture('depth32float');
+  const normal = texture('rgba16float');
+  const aoSize = size / 2;
+  const raw = texture('r8unorm', aoSize, aoSize);
+  const blurred = texture('r8unorm', aoSize, aoSize);
+  const noise = texture('rgba32float', 4, 4);
+  const uniform = device.createBuffer({
+    size: 256,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const kernel = device.createBuffer({
+    size: 1024,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const readback = device.createBuffer({
+    size: 256 * aoSize,
+    usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
+  });
+  try {
+    const projection = mat4.create();
+    if (scene === 'orthographic') mat4.orthographic(projection, -3, 3, 3, -3, 0.1, 100);
+    else mat4.perspective(projection, Math.PI / 3, 1, 0.1, 100);
+    const inverse = mat4.create();
+    mat4.invert(inverse, projection);
+    const payload = new Float32Array(64);
+    payload.set(mat4.identity(mat4.create()));
+    payload.set(projection, 16);
+    payload.set(inverse, 32);
+    payload.set([1, 0.5, 0.025, sampleCount], 48);
+    device.queue.writeBuffer(uniform, 0, payload);
+    device.queue.writeBuffer(
+      kernel,
+      0,
+      new Float32Array(generateSsaoKernel().flatMap((v) => [...v, 0])),
+    );
+    const noiseRgb = generateSsaoNoise();
+    const noiseRgba = new Float32Array(64);
+    for (let i = 0; i < 16; i++) noiseRgba.set(noiseRgb.subarray(i * 3, i * 3 + 3), i * 4);
+    device.queue.writeTexture({ texture: noise }, noiseRgba, { bytesPerRow: 64 }, [4, 4]);
+    const seedModule = device.createShaderModule({
+      code: `
+      struct Out { @builtin(position) pos: vec4f, @location(0) uv: vec2f };
+      @vertex fn vs(@builtin(vertex_index) i:u32)->Out {
+        let p = array<vec2f,3>(vec2f(-1,-1),vec2f(3,-1),vec2f(-1,3));
+        return Out(vec4f(p[i],0,1),p[i]*vec2f(0.5,-0.5)+0.5);
+      }
+      struct Fragment { @builtin(frag_depth) depth:f32, @location(0) normal:vec4f };
+      @fragment fn fs(in:Out)->Fragment {
+        let rayY = (1.0-2.0*in.uv.y)*0.577350269;
+        let distance = ${scene === 'orthographic' ? '4.0+(1.0-2.0*in.uv.y)*3.0' : scene === 'plane' ? '4.0/(1.0-rayY)' : scene === 'contact' ? 'select(4.0,3.75,in.uv.x>0.5)' : scene === 'distant-edge' ? 'select(4.0,1.0,in.uv.x>0.5)' : '100.0'};
+        return Fragment(${scene === 'orthographic' ? '(distance-0.1)/99.9' : scene === 'background' ? '1.0' : '100.0/99.9-10.0/(99.9*distance)'},${scene === 'plane' || scene === 'orthographic' ? 'vec4f(0.5,0.853553391,0.853553391,1)' : 'vec4f(0.5,0.5,1,1)'});
+      }`,
+    });
+    const seed = device.createRenderPipeline({
+      layout: 'auto',
+      vertex: { module: seedModule, entryPoint: 'vs' },
+      fragment: { module: seedModule, entryPoint: 'fs', targets: [{ format: 'rgba16float' }] },
+      depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'always' },
+    });
+    const module = device.createShaderModule({ code: compiled.value.wgsl });
+    const layout = device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: 2, buffer: { type: 'uniform' } },
+        { binding: 1, visibility: 2, buffer: { type: 'uniform' } },
+        { binding: 2, visibility: 2, texture: { sampleType: 'unfilterable-float' } },
+        { binding: 3, visibility: 2, sampler: { type: 'non-filtering' } },
+        { binding: 4, visibility: 2, texture: { sampleType: 'unfilterable-float' } },
+        { binding: 5, visibility: 2, texture: { sampleType: 'depth' } },
+        { binding: 6, visibility: 2, sampler: { type: 'non-filtering' } },
+      ],
+    });
+    const calc = device.createRenderPipeline({
+      layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+      vertex: { module, entryPoint: 'vs_ssao' },
+      fragment: { module, entryPoint: 'fs_ssao_calc', targets: [{ format: 'r8unorm' }] },
+    });
+    const sampler = device.createSampler({ addressModeU: 'repeat', addressModeV: 'repeat' });
+    const bindings = device.createBindGroup({
+      layout,
+      entries: [
+        { binding: 0, resource: { buffer: uniform } },
+        { binding: 1, resource: { buffer: kernel } },
+        { binding: 2, resource: noise.createView() },
+        { binding: 3, resource: sampler },
+        { binding: 4, resource: normal.createView() },
+        { binding: 5, resource: depth.createView() },
+        { binding: 6, resource: device.createSampler() },
+      ],
+    });
+    const encoder = device.createCommandEncoder();
+    const seedPass = encoder.beginRenderPass({
+      colorAttachments: [{ view: normal.createView(), loadOp: 'clear', storeOp: 'store' }],
+      depthStencilAttachment: {
+        view: depth.createView(),
+        depthLoadOp: 'clear',
+        depthStoreOp: 'store',
+        depthClearValue: 1,
+      },
+    });
+    seedPass.setPipeline(seed);
+    seedPass.draw(3);
+    seedPass.end();
+    const pass = encoder.beginRenderPass({
+      colorAttachments: [{ view: raw.createView(), loadOp: 'clear', storeOp: 'store' }],
+    });
+    pass.setPipeline(calc);
+    pass.setBindGroup(0, bindings);
+    pass.draw(3);
+    pass.end();
+    encoder.copyTextureToBuffer({ texture: raw }, { buffer: readback, bytesPerRow: 256 }, [
+      aoSize,
+      aoSize,
+    ]);
+    device.queue.submit([encoder.finish()]);
+    await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ);
+    const values = new Uint8Array(readback.getMappedRange());
+    const mean = (x0: number, x1: number) => {
+      let sum = 0;
+      for (let y = 8; y < aoSize - 8; y++)
+        for (let x = x0; x < x1; x++) sum += 1 - (values[y * 256 + x] ?? NaN) / 255;
+      return sum / ((aoSize - 16) * (x1 - x0));
+    };
+    expect(errors).toEqual([]);
+    if (scene === 'contact') {
+      expect(
+        mean(aoSize / 2 - 4, aoSize / 2),
+        'nearby foreground occludes the contact band',
+      ).toBeGreaterThan(0.02);
+      expect(mean(8, 16), 'open surface away from contact stays clear').toBeLessThan(0.01);
+    } else {
+      if (scene === 'distant-edge') expect(mean(aoSize / 2 - 4, aoSize / 2)).toBeLessThan(0.005);
+      expect(
+        mean(8, aoSize - 8),
+        'unoccluded surface and distant silhouettes stay clear',
+      ).toBeLessThan(0.01);
+    }
+    readback.unmap();
+    const blurLayout = device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: 2, buffer: { type: 'uniform' } },
+        { binding: 4, visibility: 2, texture: { sampleType: 'unfilterable-float' } },
+        { binding: 5, visibility: 2, texture: { sampleType: 'depth' } },
+        { binding: 6, visibility: 2, sampler: { type: 'non-filtering' } },
+        { binding: 7, visibility: 2, texture: { sampleType: 'unfilterable-float' } },
+      ],
+    });
+    const blurPipeline = device.createRenderPipeline({
+      layout: device.createPipelineLayout({ bindGroupLayouts: [blurLayout] }),
+      vertex: { module, entryPoint: 'vs_ssao' },
+      fragment: { module, entryPoint: 'fs_ssao_blur', targets: [{ format: 'r8unorm' }] },
+    });
+    const blurGroup = device.createBindGroup({
+      layout: blurLayout,
+      entries: [
+        { binding: 0, resource: { buffer: uniform } },
+        { binding: 4, resource: normal.createView() },
+        { binding: 5, resource: depth.createView() },
+        { binding: 6, resource: device.createSampler() },
+        { binding: 7, resource: raw.createView() },
+      ],
+    });
+    const filterEncoder = device.createCommandEncoder();
+    const filter = filterEncoder.beginRenderPass({
+      colorAttachments: [{ view: blurred.createView(), loadOp: 'clear', storeOp: 'store' }],
+    });
+    filter.setPipeline(blurPipeline);
+    filter.setBindGroup(0, blurGroup);
+    filter.draw(3);
+    filter.end();
+    filterEncoder.copyTextureToBuffer(
+      { texture: blurred },
+      { buffer: readback, bytesPerRow: 256 },
+      [aoSize, aoSize],
+    );
+    device.queue.submit([filterEncoder.finish()]);
+    await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ);
+    const filtered = new Uint8Array(readback.getMappedRange());
+    if (scene === 'contact') {
+      let foreground = 0;
+      for (let y = 8; y < aoSize - 8; y++)
+        for (let x = aoSize / 2; x < aoSize / 2 + 3; x++)
+          foreground += 1 - (filtered[y * 256 + x] ?? NaN) / 255;
+      expect(
+        foreground / ((aoSize - 16) * 3),
+        'bilateral blur must not bleed contact AO onto the foreground',
+      ).toBeLessThan(0.005);
+    }
+    expect(errors).toEqual([]);
+    readback.unmap();
+  } finally {
+    for (const resource of [depth, normal, raw, blurred, noise, uniform, kernel, readback])
+      resource.destroy();
+    device.destroy();
+  }
+});

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);
+});