@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/reflection-probe-box.dawn.test.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { expect, it } from 'vitest';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+} from '../gpu-usage';
+
+it('projects only interior probe rays and preserves the sign of nearly parallel axes', async () => {
+  const source = readFileSync('packages/shader/src/ibl-sampling.wgsl', 'utf8');
+  const helper = source.slice(
+    source.indexOf('fn box_project('),
+    source.indexOf('// Split-sum probe sample.'),
+  );
+  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 output = device.createBuffer({
+    size: 48,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
+  });
+  const readback = device.createBuffer({
+    size: 48,
+    usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
+  });
+  try {
+    const module = device.createShaderModule({
+      code: `${helper}
+      @group(0) @binding(0) var<storage, read_write> result: array<vec4f>;
+      @compute @workgroup_size(1) fn main() {
+        result[0] = vec4f(box_project(vec3f(4,-1,3),vec3f(0,1,0),vec3f(0),vec3f(1)),0);
+        result[1] = vec4f(box_project(vec3f(4,-1,3),vec3f(0,-1,0),vec3f(0),vec3f(1)),0);
+        result[2] = vec4f(box_project(vec3f(0.5,0.25,-0.2),vec3f(-0.000001,0.6,0.8),vec3f(0),vec3f(1)),0);
+      }`,
+    });
+    const pipeline = await device.createComputePipelineAsync({
+      layout: 'auto',
+      compute: { module, entryPoint: 'main' },
+    });
+    const group = device.createBindGroup({
+      layout: pipeline.getBindGroupLayout(0),
+      entries: [{ binding: 0, resource: { buffer: output } }],
+    });
+    const encoder = device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, group);
+    pass.dispatchWorkgroups(1);
+    pass.end();
+    encoder.copyBufferToBuffer(output, 0, readback, 0, 48);
+    device.queue.submit([encoder.finish()]);
+    await readback.mapAsync(1);
+    const values = new Float32Array(readback.getMappedRange()).slice();
+    readback.unmap();
+    expect(Array.from(values.slice(0, 3))).toEqual([0, 1, 0]);
+    expect(Array.from(values.slice(4, 7))).toEqual([0, -1, 0]);
+    // The finite ray exits the y=1 face at t=1.25, independently of its tiny x component.
+    const intersection = [0.5 - 0.000001 * 1.25, 1, 0.8] as const;
+    const length = Math.hypot(...intersection);
+    for (const axis of [0, 1, 2] as const)
+      expect(values[8 + axis]).toBeCloseTo(intersection[axis] / length, 5);
+    expect(errors).toEqual([]);
+  } finally {
+    readback.destroy();
+    output.destroy();
+    device.destroy();
+  }
+});

package/src/__tests__/reflection-probe-filter.unit.test.ts

@@ -43,6 +43,15 @@ describe('ReflectionProbe bounded filtering and table projection', () => {
     expect(table.cpuIndexByPrimitive('0:9')).toBe(1);
   });
 
+  it('does not turn an outside ray into a direction from the box center', () => {
+    expect(boxProjectReflectionDirection([0, 1, 0], [0, 0, 0], [1, 1, 1], [4, -1, 3])).toEqual([
+      0, 1, 0,
+    ]);
+    expect(boxProjectReflectionDirection([0, -1, 0], [0, 0, 0], [1, 1, 1], [4, -1, 3])).toEqual([
+      0, -1, 0,
+    ]);
+  });
+
   it('projects a reflection direction from inside and outside the box', () => {
     expect(boxProjectReflectionDirection([1, 0, 0], [0, 0, 0], [2, 2, 2], [0, 0, 0])).toEqual([
       1, 0, 0,

package/src/__tests__/reflection-probe-orientation.dawn.test.ts

@@ -0,0 +1,294 @@
+import { readFileSync } from 'node:fs';
+import { mat4 } from '@forgeax/engine-math';
+import { expect, it } from 'vitest';
+import { buildCubeCameraFaceViews } from '../capture/cube-views';
+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,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
+import { CAPTURE_VIEW_PROJS, CUBEMAP_FACE_VERTICES } from '../ibl/IblPipelineCache';
+
+// Independent WebGPU cube lookup coordinates, sampled away from face seams.
+function direction(face: number, x: number, y: number, size: number) {
+  const u = ((x + 0.5) * 2) / size - 1;
+  const v = ((y + 0.5) * 2) / size - 1;
+  const vector =
+    [
+      [1, -v, -u],
+      [-1, -v, u],
+      [u, 1, v],
+      [u, -1, -v],
+      [u, -v, 1],
+      [-u, -v, -1],
+    ][face] ?? [];
+  const length = Math.hypot(...vector);
+  return vector.map((value) => value / length);
+}
+
+function shader(file: string) {
+  return readFileSync(`packages/shader/src/${file}`, 'utf8').replace(
+    /^#(?:define_import_path|import).*$/gm,
+    '',
+  );
+}
+
+function half(bits: number) {
+  const exponent = (bits >>> 10) & 31;
+  const fraction = bits & 1023;
+  return (
+    (bits & 32768 ? -1 : 1) *
+    (exponent === 0 ? fraction * 2 ** -24 : (1 + fraction / 1024) * 2 ** (exponent - 15))
+  );
+}
+
+it('preserves asymmetric world directions through cube capture, PMREM and probe lookup', async () => {
+  const adapter = await navigator.gpu.requestAdapter();
+  if (adapter === null) 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 = 16;
+  const cube = (format: GPUTextureFormat, usage: number) =>
+    device.createTexture({ size: [size, size, 6], format, usage });
+  const source = cube('rgba8unorm', GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING);
+  const raw = cube(
+    'rgba16float',
+    GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+  );
+  const filtered = cube(
+    'rgba16float',
+    GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_COPY_SRC,
+  );
+  const depth = device.createTexture({
+    size: [size, size],
+    format: 'depth24plus-stencil8',
+    usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  });
+  const readback = device.createBuffer({
+    size: 256 * size * 6,
+    usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
+  });
+  const captureUniforms = device.createBuffer({
+    size: 256 * 6,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const faceUniforms = device.createBuffer({
+    size: 256 * 6,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const filterUniforms = device.createBuffer({
+    size: 16,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const vertices = device.createBuffer({
+    size: CUBEMAP_FACE_VERTICES.byteLength,
+    usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  try {
+    const shared = shader('ibl-shared.wgsl');
+    const background = device.createShaderModule({
+      code: shared + shader('ibl-probe-background.wgsl'),
+    });
+    const prefilter = device.createShaderModule({ code: shared + shader('ibl-prefilter.wgsl') });
+    const capturePipeline = await device.createRenderPipelineAsync({
+      layout: 'auto',
+      vertex: { module: background, entryPoint: 'probe_background_vs' },
+      fragment: {
+        module: background,
+        entryPoint: 'probe_background_fs',
+        targets: [{ format: 'rgba16float' }],
+      },
+      depthStencil: {
+        format: 'depth24plus-stencil8',
+        depthWriteEnabled: false,
+        depthCompare: 'less-equal',
+      },
+    });
+    const filterPipeline = await device.createRenderPipelineAsync({
+      layout: 'auto',
+      vertex: {
+        module: prefilter,
+        entryPoint: 'cubemap_vs',
+        buffers: [
+          { arrayStride: 12, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] },
+        ],
+      },
+      fragment: {
+        module: prefilter,
+        entryPoint: 'prefilterEnv_fs',
+        targets: [{ format: 'rgba16float' }],
+      },
+      primitive: { cullMode: 'none' },
+    });
+    const sampler = device.createSampler({
+      magFilter: 'linear',
+      minFilter: 'linear',
+      addressModeU: 'clamp-to-edge',
+      addressModeV: 'clamp-to-edge',
+    });
+    const sourceView = source.createView({ dimension: 'cube' });
+    const rawView = raw.createView({ dimension: 'cube' });
+    const filterGroup = device.createBindGroup({
+      layout: filterPipeline.getBindGroupLayout(1),
+      entries: [
+        { binding: 0, resource: rawView },
+        { binding: 1, resource: sampler },
+      ],
+    });
+    device.queue.writeBuffer(vertices, 0, CUBEMAP_FACE_VERTICES);
+    device.queue.writeBuffer(filterUniforms, 0, new Float32Array([0, size, 1, 1]));
+    const views = buildCubeCameraFaceViews({ position: [3, 5, -7], near: 0.1, far: 100 });
+    const encoder = device.createCommandEncoder();
+    for (let face = 0; face < 6; face++) {
+      const pixels = new Uint8Array(size * size * 4);
+      for (let y = 0; y < size; y++)
+        for (let x = 0; x < size; x++) {
+          const d = direction(face, x, y, size);
+          pixels.set(
+            [
+              Math.round((0.5 + 0.4 * (d[0] ?? 0)) * 255),
+              Math.round((0.5 - 0.4 * (d[1] ?? 0)) * 255),
+              Math.round((0.5 + 0.4 * (d[2] ?? 0)) * 255),
+              255,
+            ],
+            (y * size + x) * 4,
+          );
+        }
+      device.queue.writeTexture(
+        { texture: source, origin: [0, 0, face] },
+        pixels,
+        { bytesPerRow: size * 4 },
+        [size, size],
+      );
+      const pose = mat4.invert(mat4.create(), views[face]?.view ?? mat4.create());
+      device.queue.writeBuffer(
+        captureUniforms,
+        face * 256,
+        new Float32Array([
+          ...pose.slice(0, 3),
+          0,
+          ...pose.slice(4, 7),
+          0,
+          ...pose.slice(8, 11),
+          0,
+          0,
+          0,
+          0,
+          1,
+          1,
+          1,
+          1,
+          0,
+        ]),
+      );
+      device.queue.writeBuffer(faceUniforms, face * 256, CAPTURE_VIEW_PROJS[face] ?? mat4.create());
+      const group = device.createBindGroup({
+        layout: capturePipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: sourceView },
+          { binding: 1, resource: sampler },
+          { binding: 2, resource: { buffer: captureUniforms, offset: face * 256, size: 80 } },
+        ],
+      });
+      const pass = encoder.beginRenderPass({
+        colorAttachments: [
+          {
+            view: raw.createView({ dimension: '2d', baseArrayLayer: face, arrayLayerCount: 1 }),
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: [0, 0, 0, 1],
+          },
+        ],
+        depthStencilAttachment: {
+          view: depth.createView(),
+          depthClearValue: 1,
+          depthLoadOp: 'clear',
+          depthStoreOp: 'discard',
+          stencilClearValue: 0,
+          stencilLoadOp: 'clear',
+          stencilStoreOp: 'discard',
+        },
+      });
+      pass.setPipeline(capturePipeline);
+      pass.setBindGroup(0, group);
+      pass.draw(3);
+      pass.end();
+    }
+    for (let face = 0; face < 6; face++) {
+      const group = device.createBindGroup({
+        layout: filterPipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: { buffer: faceUniforms, offset: face * 256, size: 64 } },
+          { binding: 1, resource: { buffer: filterUniforms } },
+        ],
+      });
+      const pass = encoder.beginRenderPass({
+        colorAttachments: [
+          {
+            view: filtered.createView({
+              dimension: '2d',
+              baseArrayLayer: face,
+              arrayLayerCount: 1,
+            }),
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: [0, 0, 0, 1],
+          },
+        ],
+      });
+      pass.setPipeline(filterPipeline);
+      pass.setBindGroup(0, group);
+      pass.setBindGroup(1, filterGroup);
+      pass.setVertexBuffer(0, vertices);
+      pass.draw(6, 1, face * 6);
+      pass.end();
+    }
+    encoder.copyTextureToBuffer(
+      { texture: filtered },
+      { buffer: readback, bytesPerRow: 256, rowsPerImage: size },
+      [size, size, 6],
+    );
+    device.queue.submit([encoder.finish()]);
+    await readback.mapAsync(1);
+    const data = new DataView(readback.getMappedRange());
+    let maximum = 0;
+    for (let face = 0; face < 6; face++)
+      for (let y = 2; y < size - 2; y++)
+        for (let x = 2; x < size - 2; x++) {
+          const d = direction(face, x, y, size);
+          for (let channel = 0; channel < 3; channel++)
+            maximum = Math.max(
+              maximum,
+              Math.abs(
+                half(data.getUint16((face * size + y) * 256 + x * 8 + channel * 2, true)) -
+                  (0.5 + 0.4 * (d[channel] ?? 0)),
+              ),
+            );
+        }
+    expect(errors).toEqual([]);
+    expect(maximum).toBeLessThan(0.04);
+    readback.unmap();
+  } finally {
+    for (const resource of [
+      source,
+      raw,
+      filtered,
+      depth,
+      readback,
+      captureUniforms,
+      faceUniforms,
+      filterUniforms,
+      vertices,
+    ])
+      resource.destroy();
+    device.destroy();
+  }
+});

package/src/__tests__/reflection-probe-record-owner.characterization.unit.test.ts

@@ -28,7 +28,7 @@ describe('ReflectionProbeRecordOwner characterization', () => {
     expect(ownerContractsSource).toContain('active: ProbeCubeSet | undefined;');
     expect(ownerContractsSource).toContain('candidate: ProbeCubeSet;');
     expect(ownerContractsSource).toContain('spare: ProbeCubeSet | undefined;');
-    expect(ownerSource).toContain('const active = resource.active;');
+    expect(ownerSource).toContain('const active = resource.activeFact?.center.every');
     expect(ownerSource).toContain('if (active === undefined) return undefined;');
     expect(ownerSource).toContain('filteredView: active.cubeView');
   });
@@ -51,7 +51,9 @@ describe('ReflectionProbeRecordOwner characterization', () => {
 
   it('discards failed completion and preserves incremental filter state', () => {
     expect(ownerSource).toContain('fallbackRequested,');
-    expect(ownerSource).toContain('if (!fallbackRequested)');
+    expect(ownerSource).toMatch(
+      /if \(fallbackRequested\)\s+await this\.completeFallbackSubmission\(/,
+    );
     expect(ownerSource).toContain('if (pending.step === undefined) continue;');
     expect(ownerSource).toContain('if (resource.pending !== undefined) continue;');
 
@@ -70,7 +72,7 @@ describe('ReflectionProbeRecordOwner characterization', () => {
   });
 
   it('resets capture work on revision changes while retaining active generation identity', () => {
-    expect(ownerSource).toContain('if (existing.fact.revision !== fact.revision)');
+    expect(ownerSource).toContain('existing.captureFact.revision !== fact.revision');
     expect(ownerSource).toContain('activeGeneration: existing.filter.activeGeneration');
     expect(ownerSource).toContain('existing.rawFaceCursor = 0;');
     expect(ownerSource).toContain('this.resources.clear();');
@@ -98,17 +100,6 @@ describe('ReflectionProbeRecordOwner characterization', () => {
     expect(ownerSource).toContain("pending.projection.source === 'neutral'");
   });
 
-  it('does not publish an active receipt from a descriptor without readback', () => {
-    expect(ownerSource).toContain('fallbackOutput?.readback === undefined');
-    expect(ownerSource).toContain('this.fallbackReadback = Object.freeze');
-    expect(ownerSource).toContain("readbackStatus: 'complete'");
-    expect(ownerSource).not.toContain("readbackStatus: 'scheduled'");
-    expect(ownerSource).toContain('readbackHash: readback.hash');
-    expect(ownerSource).not.toContain('linearHdr: readback.linearHdr');
-    expect(ownerSource).toContain('const staged = this.pendingFallback.get(pending.ticket);');
-    expect(ownerSource).toContain('latestFallbackTickets');
-  });
-
   it('keeps fallback capability and recovery facts on the same owner', () => {
     expect(ownerSource).toContain('private fallbackFormatAvailable: boolean;');
     expect(ownerSource).toContain('this.refreshFallbackCapabilities(frameId);');

package/src/__tests__/reflection-probe-updates.unit.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderSystemInternals } from '../record/render-context';
+import { createProbeFilterState } from '../reflection/filter';
+import type { ReflectionProbeFact } from '../reflection/projection';
+import { ReflectionProbeRecordOwner } from '../reflection/record-owner';
+
+// Tests exercise the existing owner without widening its production API.
+type ProbeOwnerFixture = {
+  resources: ReflectionProbeRecordOwner['resources'];
+  resourceFor: ReflectionProbeRecordOwner['resourceFor'];
+  completeSubmission: ReflectionProbeRecordOwner['completeSubmission'];
+};
+
+function fixture(intent: 'once' | 'on-change' | 'continuous') {
+  const owner = new ReflectionProbeRecordOwner({
+    device: { caps: { rgba16floatRenderable: true }, queue: { writeBuffer: () => ({ ok: true }) } },
+    deviceScope: { generation: 1 },
+  } as unknown as RenderSystemInternals) as unknown as ProbeOwnerFixture;
+  const fact: ReflectionProbeFact = {
+    worldId: 0,
+    entityKey: 1,
+    center: [0, 0, 0],
+    halfExtents: [2, 2, 2],
+    intensity: 1,
+    priority: 0,
+    resolution: 64,
+    revision: 1,
+    updateIntent: intent,
+  };
+  const resource = {
+    fact,
+    captureFact: fact,
+    diffusePayload: [0, 0, 0, 0, 0, 0, 0, 1],
+    captureSceneRevision: '1',
+    index: 0,
+    filter: {
+      ...createProbeFilterState({ probeIndex: 0, mipCount: 5, activeGeneration: 1 }),
+      cursor: 30,
+    },
+    rawFaceCursor: 6,
+    raw: { size: 64, faceViews: new Array(6) },
+    active: {},
+    candidate: {},
+    spare: undefined,
+  } as unknown as NonNullable<ReturnType<(typeof owner)['resourceFor']>>;
+  owner.resources.set('0:1', resource);
+  return { owner, fact, resource };
+}
+
+describe('ReflectionProbe real resource update ownership', () => {
+  it.each([
+    'continuous',
+    'on-change',
+  ] as const)('starts another bounded capture for %s', (intent) => {
+    const { owner, fact, resource } = fixture(intent);
+    owner.resourceFor('0:1', fact, 0, '2');
+    expect(resource.rawFaceCursor).toBe(0);
+    expect(resource.filter.cursor).toBe(0);
+    expect(resource.filter.activeGeneration).toBe(1);
+  });
+  it('keeps once probes steady across ordinary scene changes', () => {
+    const { owner, fact, resource } = fixture('once');
+    owner.resourceFor('0:1', fact, 0, '2');
+    expect(resource.rawFaceCursor).toBe(6);
+    expect(resource.filter.cursor).toBe(30);
+  });
+  it('coalesces a changing scene without starving an in-progress capture', () => {
+    const { owner, fact, resource } = fixture('on-change');
+    resource.rawFaceCursor = 3;
+    resource.filter = { ...resource.filter, cursor: 0 };
+    owner.resourceFor('0:1', { ...fact, revision: 2 }, 0, '2');
+    expect(resource.rawFaceCursor).toBe(3);
+  });
+  it('commits capture tickets even when no fallback MRT was requested', async () => {
+    const { owner, resource } = fixture('once');
+    resource.rawFaceCursor = 2;
+    const pending = { rawCaptureFace: 2, step: undefined };
+    resource.pending = pending;
+    await owner.completeSubmission(
+      true,
+      new Map(),
+      Promise.resolve(),
+      undefined,
+      false,
+      [{ resource, pending }],
+      1,
+      37,
+    );
+    expect(resource.rawFaceCursor).toBe(3);
+    expect(resource.pending).toBeUndefined();
+  });
+  it('failed submissions retry the same face', async () => {
+    const { owner, resource } = fixture('once');
+    resource.rawFaceCursor = 2;
+    const pending = { rawCaptureFace: 2, step: undefined };
+    resource.pending = pending;
+    await owner.completeSubmission(
+      false,
+      new Map(),
+      undefined,
+      undefined,
+      false,
+      [{ resource, pending }],
+      1,
+      37,
+    );
+    expect(resource.rawFaceCursor).toBe(2);
+    expect(resource.pending).toBeUndefined();
+  });
+  it('a stale completion cannot advance a replaced pending ticket', async () => {
+    const { owner, resource } = fixture('once');
+    resource.rawFaceCursor = 2;
+    const old = { rawCaptureFace: 2, step: undefined };
+    const current = { rawCaptureFace: 2, step: undefined };
+    resource.pending = current;
+    await owner.completeSubmission(
+      true,
+      new Map(),
+      undefined,
+      undefined,
+      false,
+      [{ resource, pending: old }],
+      1,
+      37,
+    );
+    expect(resource.rawFaceCursor).toBe(2);
+    expect(resource.pending).toBe(current);
+  });
+});

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -15,6 +15,10 @@ import type {
 } from '../index';
 
 const expectedCodes = [
+  'auto-exposure-invalid-parameter',
+  'auto-exposure-capability-unavailable',
+  'auto-exposure-stale-generation',
+  'auto-exposure-stage-failed',
   'lifecycle-construction-failed',
   'world-lease-invalid',
   'frame-input-invalid',
@@ -32,6 +36,9 @@ const expectedCodes = [
   'observation-unavailable',
   'scene-data-unavailable',
   'taa-unavailable',
+  'dynamic-resolution-invalid-parameter',
+  'dynamic-resolution-requires-taa',
+  'dynamic-resolution-timing-unavailable',
   'shadow-invalid-config',
   'equirect-projection-failed',
   'standard-light-budget-exceeded',

package/src/__tests__/render-error-detail-ssot.test-d.ts

@@ -1,5 +1,10 @@
 import { describe, expectTypeOf, it } from 'vitest';
 import type { RenderError } from '../errors/render';
+import type {
+  AutoExposureError,
+  AutoExposureErrorCode,
+  AutoExposureErrorDetail,
+} from '../pipeline/standard-output/auto-exposure/inspection';
 import type {
   FullscreenInputNotFoundDetail,
   PostProcessErrorCode,
@@ -15,12 +20,23 @@ import type {
 } from '../post-process-errors';
 import { PostProcessError } from '../post-process-errors';
 
+type ExpectedAutoExposureCodes =
+  | 'auto-exposure-invalid-parameter'
+  | 'auto-exposure-capability-unavailable'
+  | 'auto-exposure-stale-generation'
+  | 'auto-exposure-stage-failed';
+type AutoExposureDetailFor<C extends AutoExposureErrorCode> = Extract<
+  AutoExposureError,
+  { readonly code: C }
+>['detail'];
+
 type ExpectedPostProcessDetails = {
   readonly 'post-process-already-registered': PostProcessPreviouslyRegisteredDetail;
   readonly 'post-process-not-found': PostProcessNotFoundDetail;
   readonly 'fullscreen-input-not-found': FullscreenInputNotFoundDetail;
   readonly 'ssao-radius-non-positive': SsaoRadiusNonPositiveDetail;
   readonly 'ssao-bias-negative': SsaoBiasNegativeDetail;
+  readonly 'ssao-parameter-invalid': { readonly paramName: string; readonly value: unknown };
   readonly 'params-size-mismatch': PostProcessParamsSizeMismatchDetail;
   readonly 'params-update-size-mismatch': PostProcessParamsUpdateSizeMismatchDetail;
 };
@@ -32,13 +48,20 @@ type DetailFor<C extends PostProcessErrorCode> = Extract<
 >['detail'];
 
 describe('render error detail aliases derive from their code resolvers', () => {
+  it('keeps auto-exposure error codes and code/detail correlation closed', () => {
+    expectTypeOf<AutoExposureErrorCode>().toEqualTypeOf<ExpectedAutoExposureCodes>();
+    expectTypeOf<AutoExposureErrorCode>().toEqualTypeOf<AutoExposureError['code']>();
+    expectTypeOf<AutoExposureErrorDetail>().toEqualTypeOf<
+      AutoExposureDetailFor<AutoExposureErrorCode>
+    >();
+  });
   it('preserves the complete post-process detail union', () => {
     expectTypeOf<PostProcessErrorDetail>().toEqualTypeOf<
       PostProcessErrorDetailFor<PostProcessErrorCode>
     >();
   });
 
-  it('keeps the exact seven-code vocabulary and derives the public code view', () => {
+  it('keeps the closed parameter-validation vocabulary and derives the public code view', () => {
     expectTypeOf<PostProcessErrorCode>().toEqualTypeOf<ExpectedPostProcessCodes>();
     expectTypeOf<ExpectedPostProcessCodes>().toEqualTypeOf<PostProcessErrorCode>();
     expectTypeOf<PostProcessErrorType['code']>().toEqualTypeOf<PostProcessErrorCode>();
@@ -118,6 +141,9 @@ describe('render error detail aliases derive from their code resolvers', () => {
           expectTypeOf(error.detail.paramName).toEqualTypeOf<string>();
           expectTypeOf(error.detail.value).toEqualTypeOf<number>();
           return `${error.detail.paramName}:${error.detail.value}`;
+        case 'ssao-parameter-invalid':
+          expectTypeOf(error.detail.value).toEqualTypeOf<unknown>();
+          return error.detail.paramName;
         case 'ssao-bias-negative':
           expectTypeOf(error.detail.paramName).toEqualTypeOf<string>();
           expectTypeOf(error.detail.value).toEqualTypeOf<number>();

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -11,6 +11,20 @@ import type {
   VertexColorVariantConflictError,
 } from '../errors/render';
 import type { RenderFeatureErrorCode } from '../features/types';
+import type { AutoExposureErrorCode } from '../pipeline/standard-output/auto-exposure/inspection';
+
+function autoExposureCodeLabel(code: AutoExposureErrorCode): string {
+  switch (code) {
+    case 'auto-exposure-invalid-parameter':
+      return code;
+    case 'auto-exposure-capability-unavailable':
+      return code;
+    case 'auto-exposure-stale-generation':
+      return code;
+    case 'auto-exposure-stage-failed':
+      return code;
+  }
+}
 
 function renderFeatureCodeLabel(code: RenderFeatureErrorCode): string {
   switch (code) {
@@ -111,3 +125,4 @@ const taaErrorCode: RenderErrorCode = 'taa-unavailable';
 void taaErrorCode;
 void renderCodeLabel;
 void renderFeatureErrorLabel;
+void autoExposureCodeLabel;