@forgeax/engine-render 0.1.27 → 0.1.29

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

@@ -0,0 +1,279 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { mat4 } from '@forgeax/engine-math';
+import { createShaderModuleImmediate, rhi } from '@forgeax/engine-rhi-webgpu';
+import { expect, it } from 'vitest';
+import { GPU_SHADER_STAGE_COMPUTE } from '../gpu-stage';
+import {
+  GPU_TEXTURE_USAGE_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_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
+
+it('descends a real Hi-Z seed and preserves all four non-center source texels', async () => {
+  const compiler = (await import(
+    /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+  )) as {
+    compileShader(
+      source: string,
+      options: { id: string; imports: Record<string, string> },
+    ): Promise<{ ok: boolean; value?: { wgsl: string }; error?: unknown }>;
+  };
+  const shader = (name: string) =>
+    readFileSync(resolve(process.cwd(), `packages/shader/src/${name}.wgsl`), 'utf8');
+  const common = { 'forgeax_view::common': shader('common') };
+  const trace = await compiler.compileShader(
+    `${shader('ssr-trace')}
+@group(1) @binding(0) var<storage, read_write> rescueProbe: array<vec4<f32>>;
+@compute @workgroup_size(1) fn probe_rescue() {
+  let fullSize = vec2<u32>(4u, 4u);
+  let startUv = vec2<f32>(0.0);
+  let deltaUv = vec2<f32>(1.0);
+  let fallback = 0.0;
+  let endFraction = 1.0;
+  let a = locateSsrHiZCandidate(vec2<f32>(0.25, 0.25), 1u, fullSize,
+    startUv, deltaUv, fallback, endFraction);
+  let b = locateSsrHiZCandidate(vec2<f32>(0.75, 0.25), 1u, fullSize,
+    startUv, deltaUv, fallback, endFraction);
+  let c = locateSsrHiZCandidate(vec2<f32>(0.25, 0.75), 1u, fullSize,
+    startUv, deltaUv, fallback, endFraction);
+  let d = locateSsrHiZCandidate(vec2<f32>(0.75, 0.75), 1u, fullSize,
+    startUv, deltaUv, fallback, endFraction);
+  rescueProbe[0] = vec4<f32>(select(0.0, 1.0, a.valid), vec2<f32>(a.pixel), a.fraction);
+  rescueProbe[1] = vec4<f32>(select(0.0, 1.0, b.valid), vec2<f32>(b.pixel), b.fraction);
+  rescueProbe[2] = vec4<f32>(select(0.0, 1.0, c.valid), vec2<f32>(c.pixel), c.fraction);
+  rescueProbe[3] = vec4<f32>(select(0.0, 1.0, d.valid), vec2<f32>(d.pixel), d.fraction);
+  let valid = ssrRescueCandidateInRay(vec3<f32>(0.0, 0.0, -1.0),
+    vec3<f32>(0.0, 0.0, -1.0), 2.0, vec3<f32>(0.0, 0.0, -2.0),
+    vec3<f32>(0.0, 0.0, 1.0), fullSize, vec2<u32>(2u, 2u));
+  let behind = ssrRescueCandidateInRay(vec3<f32>(0.0, 0.0, -2.0),
+    vec3<f32>(1.0, 0.0, 0.0), 2.0, vec3<f32>(-1.0, 0.0, -2.0),
+    vec3<f32>(1.0, 0.0, 0.0), fullSize, vec2<u32>(1u, 2u));
+  let beyond = ssrRescueCandidateInRay(vec3<f32>(0.0, 0.0, -1.0),
+    vec3<f32>(0.0, 0.0, -1.0), 2.0, vec3<f32>(0.0, 0.0, -4.0),
+    vec3<f32>(0.0, 0.0, 1.0), fullSize, vec2<u32>(2u, 2u));
+  let silhouette = ssrRescueCandidateInRay(vec3<f32>(0.0, 0.0, -1.0),
+    vec3<f32>(0.0, 0.0, -1.0), 2.0, vec3<f32>(1.0, 0.0, -2.0),
+    vec3<f32>(0.0, 0.0, 1.0), fullSize, vec2<u32>(3u, 2u));
+  rescueProbe[4] = vec4<f32>(select(0.0, 1.0, valid), select(0.0, 1.0, behind),
+    select(0.0, 1.0, beyond), select(0.0, 1.0, silhouette));
+}`,
+    { id: 'forgeax_ssr::hiz-rescue-trace', imports: common },
+  );
+  if (!trace.ok || !trace.value) throw new Error(JSON.stringify(trace.error));
+  const hiz = await compiler.compileShader(shader('ssr-hiz'), {
+    id: 'forgeax_ssr::hiz-rescue-seed',
+    imports: common,
+  });
+  if (!hiz.ok || !hiz.value) throw new Error(JSON.stringify(hiz.error));
+
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const depth = device
+    .createTexture({
+      size: { width: 4, height: 4, depthOrArrayLayers: 1 },
+      format: 'depth32float',
+      textureBindingViewDimension: '2d',
+      usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    })
+    .unwrap();
+  const hizTexture = device
+    .createTexture({
+      size: { width: 2, height: 2, depthOrArrayLayers: 1 },
+      mipLevelCount: 1,
+      format: 'r32float',
+      textureBindingViewDimension: '2d',
+      usage: GPU_TEXTURE_USAGE_STORAGE_BINDING | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    })
+    .unwrap();
+  const view = device
+    .createBuffer({
+      size: VIEW_UNIFORM_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const output = device
+    .createBuffer({
+      size: 128,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
+    })
+    .unwrap();
+  const readback = device
+    .createBuffer({
+      size: 128,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  try {
+    const projection = mat4.create();
+    const inverse = mat4.create();
+    mat4.perspective(projection, Math.PI / 2, 1, 1, 10);
+    mat4.invert(inverse, projection);
+    const payload = new Float32Array(VIEW_UNIFORM_BYTES / 4);
+    payload.set(projection, 0);
+    payload.set(inverse, 44);
+    payload.set([1, 10, 0, 0], 228);
+    device.queue.writeBuffer(view, 0, payload).unwrap();
+
+    const depthSeed = createShaderModuleImmediate(device, {
+      code: `
+@vertex fn seed_vertex(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
+  let p = array<vec2<f32>, 3>(vec2<f32>(-1.0, -1.0), vec2<f32>(3.0, -1.0), vec2<f32>(-1.0, 3.0));
+  return vec4<f32>(p[i], 0.0, 1.0);
+}
+@fragment fn seed_depth(@builtin(position) p: vec4<f32>) -> @builtin(frag_depth) f32 {
+  let x = u32(p.x);
+  let y = u32(p.y);
+  // One valid source occupies a different non-center position in every 2x2
+  // full-resolution footprint; the other three positions remain sky.
+  let source = (x == 0u && y == 0u) || (x == 3u && y == 0u) ||
+    (x == 0u && y == 3u) || (x == 2u && y == 2u);
+  return select(1.0, 0.5, source);
+}`,
+    }).unwrap();
+    const depthSeedPipeline = device
+      .createRenderPipeline({
+        layout: 'auto',
+        vertex: { module: depthSeed, entryPoint: 'seed_vertex', buffers: [] },
+        fragment: { module: depthSeed, entryPoint: 'seed_depth', targets: [] },
+        primitive: { topology: 'triangle-list' },
+        depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'always' },
+      })
+      .unwrap();
+
+    const hizSeedModule = createShaderModuleImmediate(device, { code: hiz.value.wgsl }).unwrap();
+    const hizSeedLayout = device
+      .createBindGroupLayout({
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'depth', viewDimension: '2d' },
+          },
+          {
+            binding: 1,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            storageTexture: { access: 'write-only', format: 'r32float', viewDimension: '2d' },
+          },
+          { binding: 2, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'uniform' } },
+        ],
+      })
+      .unwrap();
+    const hizSeedPipeline = device
+      .createComputePipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [hizSeedLayout] }).unwrap(),
+        compute: { module: hizSeedModule, entryPoint: 'ssr_hiz_seed' },
+      })
+      .unwrap();
+
+    const traceModule = createShaderModuleImmediate(device, { code: trace.value.wgsl }).unwrap();
+    const traceInputLayout = device
+      .createBindGroupLayout({
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'depth', viewDimension: '2d' },
+          },
+          {
+            binding: 3,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+          },
+          { binding: 5, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'uniform' } },
+        ],
+      })
+      .unwrap();
+    const traceOutputLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'storage' } },
+        ],
+      })
+      .unwrap();
+    const tracePipeline = device
+      .createComputePipeline({
+        layout: device
+          .createPipelineLayout({ bindGroupLayouts: [traceInputLayout, traceOutputLayout] })
+          .unwrap(),
+        compute: { module: traceModule, entryPoint: 'probe_rescue' },
+      })
+      .unwrap();
+
+    const depthView = device.createTextureView(depth, {}).unwrap();
+    const hizView = device.createTextureView(hizTexture, {}).unwrap();
+    const hizSeedGroup = device
+      .createBindGroup({
+        layout: hizSeedLayout,
+        entries: [
+          { binding: 0, resource: { kind: 'textureView', value: depthView } },
+          { binding: 1, resource: { kind: 'textureView', value: hizView } },
+          { binding: 2, resource: { kind: 'buffer', value: { buffer: view } } },
+        ],
+      })
+      .unwrap();
+    const traceInputGroup = device
+      .createBindGroup({
+        layout: traceInputLayout,
+        entries: [
+          { binding: 0, resource: { kind: 'textureView', value: depthView } },
+          { binding: 3, resource: { kind: 'textureView', value: hizView } },
+          { binding: 5, resource: { kind: 'buffer', value: { buffer: view } } },
+        ],
+      })
+      .unwrap();
+    const traceOutputGroup = device
+      .createBindGroup({
+        layout: traceOutputLayout,
+        entries: [{ binding: 0, resource: { kind: 'buffer', value: { buffer: output } } }],
+      })
+      .unwrap();
+
+    const encoder = device.createCommandEncoder().unwrap();
+    const raster = encoder.beginRenderPass({
+      colorAttachments: [],
+      depthStencilAttachment: {
+        view: depthView,
+        depthClearValue: 1,
+        depthLoadOp: 'clear',
+        depthStoreOp: 'store',
+      },
+    });
+    raster.setPipeline(depthSeedPipeline);
+    raster.draw(3);
+    raster.end();
+    const seedPass = encoder.beginComputePass();
+    seedPass.setPipeline(hizSeedPipeline);
+    seedPass.setBindGroup(0, hizSeedGroup);
+    seedPass.dispatchWorkgroups(1);
+    seedPass.end();
+    const tracePass = encoder.beginComputePass();
+    tracePass.setPipeline(tracePipeline);
+    tracePass.setBindGroup(0, traceInputGroup);
+    tracePass.setBindGroup(1, traceOutputGroup);
+    tracePass.dispatchWorkgroups(1);
+    tracePass.end();
+    encoder.copyBufferToBuffer(output, 0, readback, 0, 128);
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    const mapped = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+    const values = new Float32Array(mapped.getMappedRange().unwrap().slice(0));
+    mapped.unmap();
+
+    // Each result is [valid, source-x, source-y, ray-fraction]. The selected
+    // texel must be the actual seed owner, never the footprint center.
+    expect(Array.from(values).slice(0, 20)).toEqual([
+      1, 0, 0, 0.125, 1, 3, 0, 0.875, 1, 0, 3, 0.125, 1, 2, 2, 0.625, 1, 0, 0, 0,
+    ]);
+  } finally {
+    device.destroyTexture(depth).unwrap();
+    device.destroyTexture(hizTexture).unwrap();
+    for (const buffer of [view, output, readback]) device.destroyBuffer(buffer).unwrap();
+  }
+});

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

@@ -0,0 +1,150 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { describe, expect, it } from 'vitest';
+import { admitSsrSpatial } from '../ssr/admission';
+import { addSsrSpatialPasses } from '../ssr/graph';
+
+const WIDTH = 5;
+const HEIGHT = 3;
+
+type Frame = { readonly encoder: RhiCommandEncoder };
+
+function admittedAdmission() {
+  return admitSsrSpatial({
+    camera: {
+      projection: 'perspective',
+      near: 0.1,
+      far: 100,
+      screenSpaceReflection: { maxDistance: 40, thickness: 0.2, maxRoughness: 0.6 },
+    },
+    environment: {
+      lane: 'deferred',
+      m0: { status: 'admitted' },
+      sceneInputs: true,
+      temporal: true,
+      reflectionFallback: true,
+      capabilities: {
+        compute: true,
+        storageTexture: true,
+        rgba16floatRenderable: true,
+        r32floatSampledStorage: true,
+      },
+    },
+  });
+}
+
+function input(
+  graph: RenderGraphBuilder<Frame>,
+  label: string,
+  format: 'rgba16float' | 'r32float',
+) {
+  const texture = graph
+    .createTexture(label, {
+      format,
+      size: { width: WIDTH, height: HEIGHT },
+    })
+    .unwrap();
+  return graph.view(texture, { label: `${label}.view` }).unwrap();
+}
+
+describe('SSR Hi-Z spatial Browser WebGPU gate', () => {
+  it('probes the real format/BGL chain and submits the odd-size spatial topology', async () => {
+    const adapterResult = await rhi.requestAdapter();
+    expect(adapterResult.ok).toBe(true);
+    if (!adapterResult.ok) return;
+    const deviceResult = await adapterResult.value.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok) return;
+    const device = deviceResult.value;
+
+    const formatReceipt = await device.probeTextureFormatCapability();
+    expect(formatReceipt.ok).toBe(true);
+    if (!formatReceipt.ok) return;
+    expect(formatReceipt.value).toMatchObject({
+      profile: 'r32float-mip-sampled-storage',
+      verdict: 'admitted',
+      evidence: 'real',
+    });
+    expect(formatReceipt.value.stages.map((stage) => stage.stage)).toEqual([
+      'texture-create',
+      'mip-view',
+      'sampled-storage-bind-group',
+      'pipeline-bind',
+      'finish',
+      'submit',
+      'completion',
+      'readback',
+    ]);
+    expect(formatReceipt.value.readback?.byteLength).toBeGreaterThan(0);
+
+    const graph = new RenderGraphBuilder<Frame>();
+    const depth = input(graph, 'scene-depth', 'r32float');
+    const normal = input(graph, 'gbuffer-normal', 'rgba16float');
+    const scene = input(graph, 'scene-color', 'rgba16float');
+    const fallback = input(graph, 'reflection-fallback', 'rgba16float');
+    const currentTemporal = input(graph, 'scene-temporal', 'rgba16float');
+    const seeded = graph.addComputePass('seed-inputs', {
+      accesses: [
+        { resource: depth, usage: 'storage-write' },
+        { resource: normal, usage: 'storage-write' },
+        { resource: scene, usage: 'storage-write' },
+        { resource: fallback, usage: 'storage-write' },
+        { resource: currentTemporal, usage: 'storage-write' },
+      ],
+      encode: () => undefined,
+    });
+    expect(seeded.ok).toBe(true);
+    const projected = addSsrSpatialPasses(graph, {
+      admission: admittedAdmission(),
+      width: WIDTH,
+      height: HEIGHT,
+      depth,
+      normal,
+      scene,
+      fallback,
+      currentTemporal,
+    });
+    expect(projected.ok).toBe(true);
+    if (!projected.ok) return;
+    const compiled = graph.compile({ device, surfaceSize: { width: WIDTH, height: HEIGHT } });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+
+    const encoder = device.createCommandEncoder({ label: 'ssr-spatial-browser-frame' });
+    expect(encoder.ok).toBe(true);
+    if (!encoder.ok) return;
+    expect(compiled.value.execute({ encoder: encoder.value }).ok).toBe(true);
+    const finished = encoder.value.finish();
+    expect(finished.ok).toBe(true);
+    if (!finished.ok) return;
+    expect(device.queue.submit([finished.value]).ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+
+    const info = compiled.value.inspect();
+    expect(info.passes.map((pass) => pass.name)).toEqual([
+      'seed-inputs',
+      'ssr-hiz-seed',
+      'ssr-hiz-reduce-1',
+      'ssr-trace',
+    ]);
+    expect(
+      info.resources.find((resource) => resource.label === 'ssr-hiz')?.descriptor,
+    ).toMatchObject({
+      format: 'r32float',
+      width: Math.floor(WIDTH / 2),
+      height: Math.floor(HEIGHT / 2),
+      mipLevelCount: 2,
+    });
+    console.info(
+      `[ssr-spatial-browser] ${JSON.stringify({
+        backend: device.caps.backendKind,
+        formatProfile: formatReceipt.value.profile,
+        stages: formatReceipt.value.stages.map((stage) => stage.stage),
+        passNames: info.passes.map((pass) => pass.name),
+        structuralOnly: true,
+      })}`,
+    );
+    expect((await compiled.value.retire()).ok).toBe(true);
+  });
+});

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

@@ -0,0 +1,150 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { describe, expect, it } from 'vitest';
+import { admitSsrSpatial } from '../ssr/admission';
+import { addSsrSpatialPasses } from '../ssr/graph';
+
+const WIDTH = 5;
+const HEIGHT = 3;
+
+type Frame = { readonly encoder: RhiCommandEncoder };
+
+function admittedAdmission() {
+  return admitSsrSpatial({
+    camera: {
+      projection: 'perspective',
+      near: 0.1,
+      far: 100,
+      screenSpaceReflection: { maxDistance: 40, thickness: 0.2, maxRoughness: 0.6 },
+    },
+    environment: {
+      lane: 'deferred',
+      m0: { status: 'admitted' },
+      sceneInputs: true,
+      temporal: true,
+      reflectionFallback: true,
+      capabilities: {
+        compute: true,
+        storageTexture: true,
+        rgba16floatRenderable: true,
+        r32floatSampledStorage: true,
+      },
+    },
+  });
+}
+
+function input(
+  graph: RenderGraphBuilder<Frame>,
+  label: string,
+  format: 'rgba16float' | 'r32float',
+) {
+  const texture = graph
+    .createTexture(label, {
+      format,
+      size: { width: WIDTH, height: HEIGHT },
+    })
+    .unwrap();
+  return graph.view(texture, { label: `${label}.view` }).unwrap();
+}
+
+describe('SSR Hi-Z spatial Dawn WebGPU gate', () => {
+  it('probes the real format/BGL chain and submits the odd-size spatial topology', async () => {
+    const adapterResult = await rhi.requestAdapter();
+    expect(adapterResult.ok).toBe(true);
+    if (!adapterResult.ok) return;
+    const deviceResult = await adapterResult.value.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok) return;
+    const device = deviceResult.value;
+
+    const formatReceipt = await device.probeTextureFormatCapability();
+    expect(formatReceipt.ok).toBe(true);
+    if (!formatReceipt.ok) return;
+    expect(formatReceipt.value).toMatchObject({
+      profile: 'r32float-mip-sampled-storage',
+      verdict: 'admitted',
+      evidence: 'real',
+    });
+    expect(formatReceipt.value.stages.map((stage) => stage.stage)).toEqual([
+      'texture-create',
+      'mip-view',
+      'sampled-storage-bind-group',
+      'pipeline-bind',
+      'finish',
+      'submit',
+      'completion',
+      'readback',
+    ]);
+    expect(formatReceipt.value.readback?.values.length).toBeGreaterThan(0);
+
+    const graph = new RenderGraphBuilder<Frame>();
+    const depth = input(graph, 'scene-depth', 'r32float');
+    const normal = input(graph, 'gbuffer-normal', 'rgba16float');
+    const scene = input(graph, 'scene-color', 'rgba16float');
+    const fallback = input(graph, 'reflection-fallback', 'rgba16float');
+    const currentTemporal = input(graph, 'scene-temporal', 'rgba16float');
+    const seeded = graph.addComputePass('seed-inputs', {
+      accesses: [
+        { resource: depth, usage: 'storage-write' },
+        { resource: normal, usage: 'storage-write' },
+        { resource: scene, usage: 'storage-write' },
+        { resource: fallback, usage: 'storage-write' },
+        { resource: currentTemporal, usage: 'storage-write' },
+      ],
+      encode: () => undefined,
+    });
+    expect(seeded.ok).toBe(true);
+    const projected = addSsrSpatialPasses(graph, {
+      admission: admittedAdmission(),
+      width: WIDTH,
+      height: HEIGHT,
+      depth,
+      normal,
+      scene,
+      fallback,
+      currentTemporal,
+    });
+    expect(projected.ok).toBe(true);
+    if (!projected.ok) return;
+    const compiled = graph.compile({ device, surfaceSize: { width: WIDTH, height: HEIGHT } });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+
+    const encoder = device.createCommandEncoder({ label: 'ssr-spatial-dawn-frame' });
+    expect(encoder.ok).toBe(true);
+    if (!encoder.ok) return;
+    expect(compiled.value.execute({ encoder: encoder.value }).ok).toBe(true);
+    const finished = encoder.value.finish();
+    expect(finished.ok).toBe(true);
+    if (!finished.ok) return;
+    expect(device.queue.submit([finished.value]).ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+
+    const info = compiled.value.inspect();
+    expect(info.passes.map((pass) => pass.name)).toEqual([
+      'seed-inputs',
+      'ssr-hiz-seed',
+      'ssr-hiz-reduce-1',
+      'ssr-trace',
+    ]);
+    expect(
+      info.resources.find((resource) => resource.label === 'ssr-hiz')?.descriptor,
+    ).toMatchObject({
+      format: 'r32float',
+      width: Math.floor(WIDTH / 2),
+      height: Math.floor(HEIGHT / 2),
+      mipLevelCount: 2,
+    });
+    console.info(
+      `[ssr-spatial-dawn] ${JSON.stringify({
+        backend: device.caps.backendKind,
+        formatProfile: formatReceipt.value.profile,
+        stages: formatReceipt.value.stages.map((stage) => stage.stage),
+        passNames: info.passes.map((pass) => pass.name),
+        structuralOnly: true,
+      })}`,
+    );
+    expect((await compiled.value.retire()).ok).toBe(true);
+  });
+});

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { buildSsrHiZPlan, reduceSsrHiZLevel } from '../ssr/hiz';
+
+describe('SSR Hi-Z contract', () => {
+  it('derives a complete r32float mip chain for odd and minimum extents', () => {
+    const odd = buildSsrHiZPlan({ width: 5, height: 3 });
+    expect(odd.format).toBe('r32float');
+    expect(odd.mipLevelCount).toBe(3);
+    expect(odd.levels).toEqual([
+      { level: 0, width: 5, height: 3 },
+      { level: 1, width: 2, height: 1 },
+      { level: 2, width: 1, height: 1 },
+    ]);
+
+    const minimum = buildSsrHiZPlan({ width: 1, height: 1 });
+    expect(minimum.levels).toEqual([{ level: 0, width: 1, height: 1 }]);
+  });
+
+  it('preserves positive linear depth and infinity for an empty 2x2 reduction', () => {
+    const reduced = reduceSsrHiZLevel(
+      new Float32Array([
+        Number.POSITIVE_INFINITY,
+        4,
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+      ]),
+      { width: 4, height: 2 },
+    );
+    expect(reduced).toEqual(new Float32Array([4, Number.POSITIVE_INFINITY]));
+    expect(reduced.every((value) => value === Number.POSITIVE_INFINITY || value > 0)).toBe(true);
+  });
+
+  it('retains trailing row and column for an odd source extent without producing NaN', () => {
+    const source = new Float32Array(7 * 3).fill(Number.POSITIVE_INFINITY);
+    // The only finite sample is in the trailing source column and row. The
+    // final destination cell must retain both edges through its footprint.
+    source[2 * 7 + 6] = 7;
+    const reduced = reduceSsrHiZLevel(source, { width: 7, height: 3 });
+    expect(reduced[2]).toBe(7);
+    expect(Array.from(reduced).every(Number.isFinite)).toBe(false);
+    expect(Array.from(reduced).every((value) => Number.isFinite(value) || value === Infinity)).toBe(
+      true,
+    );
+  });
+
+  it('overlaps the normalized 5-to-2 boundary so both cells retain source x=2', () => {
+    const source = new Float32Array(5 * 2).fill(Number.POSITIVE_INFINITY);
+    source[2] = 7;
+    const reduced = reduceSsrHiZLevel(source, { width: 5, height: 2 });
+    expect(Array.from(reduced)).toEqual([7, 7]);
+  });
+});