@forgeax/engine-render 0.1.33 → 0.1.34

package/src/__tests__/single-layer-medium-passes.unit.test.ts

@@ -0,0 +1,275 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiDevice, TextureFormat } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL } from '@forgeax/engine-shader';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import {
+  addSingleLayerMediumMsaaPairProducer,
+  addSingleLayerMediumPasses,
+  addSingleLayerMediumRawDepthProducer,
+  SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID,
+  type SingleLayerMediumPassInput,
+} from '../pipeline/single-layer-medium-passes';
+import type {
+  RenderPipelineFrame,
+  RenderPipelineSurfaceMediumPair,
+  RenderPipelineTarget,
+} from '../render-pipeline';
+
+let device: RhiDevice;
+
+beforeAll(async () => {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw adapter.error;
+  const created = await adapter.value.requestDevice();
+  if (!created.ok) throw created.error;
+  device = created.value;
+});
+
+function target(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  label: string,
+  format: TextureFormat,
+): RenderPipelineTarget {
+  const texture = graph.createTexture(label, {
+    format,
+    size: { width: 1, height: 1 },
+    sampleCount: 1,
+  });
+  if (!texture.ok) throw texture.error;
+  const view = graph.view(texture.value, { label: `${label}.view` });
+  if (!view.ok) throw view.error;
+  return { texture: texture.value, view: view.value, format, sampleCount: 1 };
+}
+
+function mediumInput(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  surfacePair: RenderPipelineSurfaceMediumPair,
+): SingleLayerMediumPassInput {
+  return {
+    graph,
+    size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+    nearestLayer: target(graph, 'medium-nearest-layer', 'rgba8unorm'),
+    nearestDepth: target(graph, 'medium-nearest-depth', 'depth24plus-stencil8'),
+    color: target(graph, 'medium-color', 'rgba8unorm'),
+    depth: target(graph, 'scene-depth', 'depth24plus-stencil8'),
+    surfacePair,
+  };
+}
+
+function addColorProducer(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  output: RenderPipelineTarget,
+  name: string,
+): void {
+  const result = graph.addRasterPass(name, {
+    accesses: [{ resource: output.view, usage: 'color-attachment' }],
+    colorAttachments: [
+      {
+        view: output.view,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+      },
+    ],
+    encode: () => undefined,
+  });
+  if (!result.ok) throw result.error;
+}
+
+function addDepthProducer(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  output: RenderPipelineTarget,
+  name: string,
+): void {
+  const result = graph.addRasterPass(name, {
+    accesses: [{ resource: output.view, usage: 'depth-stencil-write' }],
+    colorAttachments: [],
+    depthStencilAttachment: {
+      view: output.view,
+      depthClearValue: 1,
+      depthLoadOp: 'clear',
+      depthStoreOp: 'store',
+      stencilClearValue: 0,
+      stencilLoadOp: 'clear',
+      stencilStoreOp: 'store',
+    },
+    encode: () => undefined,
+  });
+  if (!result.ok) throw result.error;
+}
+
+describe('single-layer medium graph producer pair', () => {
+  it('fails closed from the producer unavailable fact without adding passes', () => {
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const backdrop = target(graph, 'medium-backdrop', 'rgba8unorm');
+    addColorProducer(graph, backdrop, 'medium-backdrop-producer');
+    const result = addSingleLayerMediumPasses(
+      mediumInput(graph, {
+        opaqueColor: backdrop.view,
+        rawDepth: { status: 'unavailable', reason: 'depth-copy-unavailable' },
+      }),
+    );
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'resource-descriptor-invalid',
+        detail: {
+          field: 'surfacePair.rawDepth',
+          actual: 'depth-copy-unavailable',
+        },
+      },
+    });
+  });
+
+  it('routes an available producer pair into both typed medium passes', async () => {
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const backdrop = target(graph, 'medium-backdrop', 'rgba8unorm');
+    addColorProducer(graph, backdrop, 'medium-backdrop-producer');
+    const input = mediumInput(graph, {
+      opaqueColor: backdrop.view,
+      rawDepth: { status: 'unavailable', reason: 'depth-copy-unavailable' },
+    });
+    addColorProducer(graph, input.color, 'medium-color-producer');
+    addDepthProducer(graph, input.depth, 'scene-depth-producer');
+
+    const rawDepth = addSingleLayerMediumRawDepthProducer({
+      graph,
+      sourceColor: backdrop,
+      sourceDepth: input.depth,
+      size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+    });
+    expect(rawDepth.ok).toBe(true);
+    if (!rawDepth.ok) return;
+    const availableInput: SingleLayerMediumPassInput = {
+      ...input,
+      surfacePair: {
+        opaqueColor: backdrop.view,
+        rawDepth: { status: 'available', view: rawDepth.value.view },
+      },
+    };
+
+    const result = addSingleLayerMediumPasses(availableInput);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const createTextureView = vi.spyOn(device, 'createTextureView');
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } });
+    const viewCalls = createTextureView.mock.calls;
+    createTextureView.mockRestore();
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    expect(viewCalls).toContainEqual([
+      expect.anything(),
+      expect.objectContaining({ label: 'single-layer-medium-nearest-depth-sampled.view' }),
+    ]);
+    const passes = compiled.value
+      .inspect()
+      .passes.filter(
+        (pass) =>
+          pass.name === 'single-layer-medium-nearest-layer' ||
+          pass.name === 'single-layer-medium-color',
+      );
+    expect(passes.map((pass) => pass.name)).toEqual([
+      'single-layer-medium-nearest-layer',
+      'single-layer-medium-color',
+    ]);
+    for (const pass of passes) {
+      expect(pass.accesses).toContainEqual({
+        resource: 'single-layer-medium-raw-depth',
+        usage: 'sampled-read',
+      });
+    }
+    expect(compiled.value.inspect().passes).toContainEqual(
+      expect.objectContaining({ name: 'single-layer-medium-nearest-depth-sampled-producer' }),
+    );
+  });
+
+  it('encodes the registered raw-depth producer through the Null RHI', async () => {
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const sourceColor = target(graph, 'raw-depth-source-color', 'rgba8unorm');
+    const sourceDepth = target(graph, 'raw-depth-source-depth', 'depth24plus-stencil8');
+    addColorProducer(graph, sourceColor, 'raw-depth-color-producer');
+    addDepthProducer(graph, sourceDepth, 'raw-depth-depth-producer');
+    const producer = addSingleLayerMediumRawDepthProducer({
+      graph,
+      sourceColor,
+      sourceDepth,
+      size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+    });
+    expect(producer.ok).toBe(true);
+    if (!producer.ok) return;
+    expect(producer.value.format).toBe('r32float');
+    expect(producer.value.view).toBeDefined();
+
+    const createBindGroup = vi.spyOn(device, 'createBindGroup');
+    const errors: unknown[] = [];
+    const encoder = device.createCommandEncoder({ label: 'raw-depth-producer-encode' }).unwrap();
+    const frame = {
+      encoder,
+      runtime: {
+        device,
+        errorRegistry: { fire: (error: unknown) => errors.push(error) },
+        lookupPostProcess: (id: string) =>
+          id === SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID
+            ? {
+                source: SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL,
+                reads: ['input', { key: 'scene-depth', sampleType: 'depth' as const }],
+              }
+            : undefined,
+        getPostProcessPipeline: () => ({}) as never,
+      },
+      pipelineState: { colorAttachmentFormat: 'r32float', format: 'rgba8unorm' },
+      frameState: { perFrameGraph: undefined },
+      bindGroupCounts: {},
+      geometryDepthKey: 'scene-depth',
+      postProcessParams: new Map(),
+      msaaActive: false,
+      targetW: 1,
+      targetH: 1,
+      view: undefined,
+      currentTexture: undefined,
+      clear: [0, 0, 0, 1],
+      geometryColorResolveView: null,
+      ldrSpriteColorView: null,
+    } as unknown as RenderPipelineFrame;
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const executed = compiled.value.execute(frame);
+    expect(executed.ok).toBe(true);
+    expect(errors).toEqual([]);
+    expect(createBindGroup).toHaveBeenCalled();
+    const entries = createBindGroup.mock.calls.at(-1)?.[0].entries as readonly {
+      binding: number;
+    }[];
+    expect(entries.map((entry) => entry.binding)).toEqual([0, 1, 3, 4]);
+    expect(encoder.finish().ok).toBe(true);
+    createBindGroup.mockRestore();
+  });
+
+  it('rejects a non-4x input at the paired resolver boundary', () => {
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const sourceColor = target(graph, 'paired-source-color', 'rgba16float');
+    const sourceDepth = target(graph, 'paired-source-depth', 'depth24plus-stencil8');
+    const result = addSingleLayerMediumMsaaPairProducer({
+      graph,
+      label: 'paired-invalid',
+      sourceColor,
+      sourceDepth,
+      size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+    });
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'resource-descriptor-invalid',
+        detail: {
+          field: 'source.sampleCount',
+          expected: 'color=4,depth=4',
+          actual: 'color=1,depth=1',
+        },
+      },
+    });
+  });
+});

package/src/__tests__/skin-motion-regression.unit.test.ts

@@ -1,7 +1,8 @@
 import type { Mat4 } from '@forgeax/engine-math';
 import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
 import { ok } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it, vi } from 'vitest';
 import {
   selectHdrpPbrPrewarmVariants,
   selectPipelineLayoutForVariant,
@@ -45,6 +46,74 @@ describe('custom skinned mesh motion consumer contract', () => {
     expect(writes[1]?.data[12]).toBe(0.5);
   });
 
+  it('keeps persistent uniform palettes isolated across frame-pool resets', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteAllocator(device, 65536, false);
+    try {
+      const first = allocator.allocatePersistentSlice({
+        identity: 'world:1',
+        generation: 1,
+        jointCount: 1,
+      });
+      allocator.resetForFrame();
+      const second = allocator.allocatePersistentSlice({
+        identity: 'world:2',
+        generation: 1,
+        jointCount: 1,
+      });
+      expect(second.buffer).not.toBe(first.buffer);
+      expect(
+        allocator.allocatePersistentSlice({ identity: 'world:1', generation: 1, jointCount: 1 })
+          .buffer,
+      ).toBe(first.buffer);
+    } finally {
+      allocator.dispose();
+    }
+  });
+
+  it('keeps recycled storage slices inside their dynamic binding windows', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const sizes = new Map<Buffer, number>();
+    const createBuffer = device.createBuffer.bind(device);
+    vi.spyOn(device, 'createBuffer').mockImplementation((descriptor) => {
+      const result = createBuffer(descriptor);
+      if (result.ok && descriptor.size !== undefined) sizes.set(result.value, descriptor.size);
+      return result;
+    });
+    const allocator = createSkinPaletteAllocator(device, 65536, true);
+    try {
+      const full = allocator.allocatePersistentSlice({
+        identity: 'world:full',
+        generation: 1,
+        jointCount: 255,
+      });
+      allocator.releasePersistentSlice('world:full');
+      await device.queue.onSubmittedWorkDone();
+      const first = allocator.allocatePersistentSlice({
+        identity: 'world:first',
+        generation: 1,
+        jointCount: 1,
+      });
+      const second = allocator.allocatePersistentSlice({
+        identity: 'world:second',
+        generation: 1,
+        jointCount: 1,
+      });
+      expect(first.byteOffset).toBe(full.byteOffset);
+      expect(second.byteOffset).not.toBe(first.byteOffset);
+      for (const slice of [first, second]) {
+        const bufferSize = sizes.get(slice.buffer);
+        if (bufferSize === undefined) throw new Error('palette buffer has no allocation size');
+        expect(slice.byteOffset % 256).toBe(0);
+        expect(slice.byteOffset + allocator.bindingWindowBytes).toBeLessThanOrEqual(bufferSize);
+      }
+    } finally {
+      allocator.dispose();
+    }
+  });
+
   it('prepares both URP and HDRP pbr-skin consumers with the skin-cluster contract', () => {
     const variants = selectSkinPrewarmVariants(
       {

package/src/__tests__/skin-palette-recycling.dawn.test.ts

@@ -0,0 +1,97 @@
+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_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+} from '../gpu-usage';
+import { createSkinPaletteAllocator } from '../systems/skin-palette-allocator';
+
+it('submits recycled persistent palettes with complete dynamic binding windows', async () => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const allocator = createSkinPaletteAllocator(device, 65536, true);
+  const output = device
+    .createBuffer({ size: 16, usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC })
+    .unwrap();
+  const readback = device
+    .createBuffer({ size: 16, usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST })
+    .unwrap();
+  try {
+    allocator.allocatePersistentSlice({ identity: 'full', generation: 1, jointCount: 255 });
+    allocator.releasePersistentSlice('full');
+    await device.queue.onSubmittedWorkDone();
+    allocator.allocatePersistentSlice({ identity: 'first', generation: 1, jointCount: 1 });
+    const second = allocator.allocatePersistentSlice({
+      identity: 'second',
+      generation: 1,
+      jointCount: 1,
+    });
+    expect(second.byteOffset).toBeGreaterThan(0);
+    const identity = mat4.create();
+    mat4.identity(identity);
+    const pose = mat4.create();
+    mat4.identity(pose);
+    pose[12] = 7;
+    allocator.writePersistentJointPalette(second, [identity], [pose]);
+    const module = createShaderModuleImmediate(device, {
+      code: `@group(0) @binding(0) var<storage, read> palette: array<mat4x4<f32>, 255>;
+@group(0) @binding(1) var<storage, read_write> result: vec4<f32>;
+@compute @workgroup_size(1) fn probe() { result = palette[0][3]; }`,
+    }).unwrap();
+    const groupLayout = device
+      .createBindGroupLayout({
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            buffer: {
+              type: 'read-only-storage',
+              hasDynamicOffset: true,
+              minBindingSize: allocator.bindingWindowBytes,
+            },
+          },
+          { binding: 1, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'storage' } },
+        ],
+      })
+      .unwrap();
+    const layout = device.createPipelineLayout({ bindGroupLayouts: [groupLayout] }).unwrap();
+    const pipeline = device
+      .createComputePipeline({ layout, compute: { module, entryPoint: 'probe' } })
+      .unwrap();
+    const group = device
+      .createBindGroup({
+        layout: groupLayout,
+        entries: [
+          {
+            binding: 0,
+            resource: {
+              kind: 'buffer',
+              value: { buffer: second.buffer, offset: 0, size: allocator.bindingWindowBytes },
+            },
+          },
+          { binding: 1, resource: { kind: 'buffer', value: { buffer: output } } },
+        ],
+      })
+      .unwrap();
+    const encoder = device.createCommandEncoder().unwrap();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, group, [second.byteOffset]);
+    pass.dispatchWorkgroups(1);
+    pass.end();
+    encoder.copyBufferToBuffer(output, 0, readback, 0, 16);
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    const mapped = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+    const result = new Float32Array(mapped.getMappedRange().unwrap().slice(0));
+    mapped.unmap();
+    expect(Array.from(result)).toEqual([7, 0, 0, 1]);
+  } finally {
+    await device.queue.onSubmittedWorkDone();
+    allocator.dispose();
+    device.destroyBuffer(output).unwrap();
+    device.destroyBuffer(readback).unwrap();
+  }
+});

package/src/__tests__/skinned-shadow-caster.test.ts

@@ -159,6 +159,21 @@ describe('skinned shadow caster', () => {
     expect(recordSource).toContain('binding: 12');
   });
 
+  it('keeps shadow view bind groups complete when cloud transport extends the shared layout', () => {
+    const recordSource = readFileSync(
+      fileURLToPath(new URL('../record/shadow-pass.ts', import.meta.url)),
+      'utf8',
+    );
+    const shadowViewHelper = recordSource.slice(
+      recordSource.indexOf('function ensureTypedShadowViewBg'),
+      recordSource.indexOf('interface ShadowDispatch'),
+    );
+    expect(shadowViewHelper).toContain('binding: 16');
+    expect(shadowViewHelper).toContain('binding: 17');
+    expect(shadowViewHelper).toContain('pipelineState.defaultWhiteTextureView');
+    expect(shadowViewHelper).toContain('pipelineState.defaultSampler');
+  });
+
   it('uses the visible scene index for multi-batch capable shadows', () => {
     const shader = readFileSync(
       fileURLToPath(new URL('../../../shader/src/shadow_caster.wgsl', import.meta.url)),

package/src/__tests__/ssr-carrier-public-contract.unit.test.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const carrierScripts = [
+  new URL('../../../../apps/hello/ssr/scripts/smoke-dawn.mjs', import.meta.url),
+  new URL(
+    '../../../../apps/learn-render/6.pbr/4.render-target-reflection/scripts/smoke-dawn.mjs',
+    import.meta.url,
+  ),
+];
+
+describe('SSR carrier public receipt contract', () => {
+  it('uses public receipt completion instead of private inspection completion', () => {
+    for (const scriptUrl of carrierScripts) {
+      const source = readFileSync(scriptUrl, 'utf8');
+      expect(source).not.toContain('reflectionFallbackCompletion');
+      expect(source).toContain('.completed');
+      expect(source).toContain('renderer.inspect()');
+    }
+  });
+});

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

@@ -25,7 +25,7 @@ describe('SSR GPU dispatch Browser WebGPU probe', () => {
     device = (await adapter.requestDevice()).unwrap();
   });
 
-  // Independent cases identify the failing invariant. The 300-frame case
+  // Independent cases identify the failing invariant. The 60-frame case
   // also includes cold software-driver compilation and completed readbacks;
   // its bounded 30-second execution allowance is not a frame-performance gate.
   it('reprojects history and reconstructs perspective and orthographic view distance', async () => {
@@ -40,8 +40,8 @@ describe('SSR GPU dispatch Browser WebGPU probe', () => {
     }
   });
 
-  it('executes 300 stable Hi-Z, trace and temporal frames with finite visible hits', async () => {
-    const hit = await runSsrGpuDispatch(device, sources, 300);
+  it('executes 60 stable Hi-Z, trace and temporal frames with finite visible hits', async () => {
+    const hit = await runSsrGpuDispatch(device, sources, 60);
     expect(hit.passNames.filter((name) => name.startsWith('ssr-hiz-reduce'))).toHaveLength(1);
     expect(hit.passNames.filter((name) => name.startsWith('ssr-reflection-mip'))).toHaveLength(1);
     expect(hit.passNames).toContain('ssr-hiz-seed');
@@ -49,7 +49,7 @@ describe('SSR GPU dispatch Browser WebGPU probe', () => {
     expect(hit.passNames).toContain('ssr-temporal');
     expect(hit.passNames.filter((name) => name === 'ssr-compose')).toHaveLength(1);
     expect(hit.resourceNames).toContain('ssr-resolved');
-    expect(hit.pixels).toHaveLength(300);
+    expect(hit.pixels).toHaveLength(60);
     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] ?? [];

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

@@ -38,7 +38,7 @@ describe('SSR GPU dispatch Dawn probe', () => {
       expect(distances[0]).toBeCloseTo(6.58, 4);
       expect(distances[1]).toBeCloseTo(12, 4);
     }
-    const hit = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 300);
+    const hit = await runSsrGpuDispatch(device, sourcesFromManifest(manifest), 60);
     // Mip count must not grow CPU pass recording: ordered dispatches share
     // one compute pass per pyramid, with every level still produced below.
     expect(hit.passNames.filter((name) => name.startsWith('ssr-hiz-reduce'))).toHaveLength(1);
@@ -49,7 +49,7 @@ describe('SSR GPU dispatch Dawn probe', () => {
     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(hit.pixels).toHaveLength(60);
     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

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

@@ -889,7 +889,7 @@ export async function runSsrGpuDispatch(
     await device.queue.onSubmittedWorkDone();
     // These independent copies share one completed submission. Request all
     // mappings together instead of paying three browser/driver round trips
-    // for each of the 300 frames; every buffer is still read and validated.
+    // for each of the 60 frames; every buffer is still read and validated.
     const [mapped, traceMapped, hizMapped] = await Promise.all([
       readbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ),
       traceReadbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ),

package/src/__tests__/ssr-receiver-coverage.dawn.test.ts

@@ -16,6 +16,7 @@ import {
   GPU_BUFFER_USAGE_MAP_READ,
   GPU_BUFFER_USAGE_UNIFORM,
 } from '../gpu-usage';
+import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
 
 async function composePixels(
   width: number,
@@ -85,9 +86,12 @@ async function composePixels(
     upload(width, height, normals),
   ];
   const view = device
-    .createBuffer({ size: 960, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST })
+    .createBuffer({
+      size: VIEW_UNIFORM_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    })
     .unwrap();
-  const viewData = new Float32Array(240);
+  const viewData = new Float32Array(VIEW_UNIFORM_BYTES / Float32Array.BYTES_PER_ELEMENT);
   viewData[238] = options.roughnessLimit ?? 1;
   viewData[239] = options.enabled ?? 1;
   device.queue.writeBuffer(view, 0, viewData).unwrap();

package/src/__tests__/standard-output-chain-contract.unit.test.ts

@@ -68,6 +68,34 @@ describe('Standard output chain contract', () => {
     expect(validateStandardOutputPlan(plan).ok).toBe(true);
   });
 
+  it('places barrel distortion in linear-LDR after LUT and before edge AA', () => {
+    const plan = createStandardOutputPlan({
+      ...fullRequest,
+      barrelDistortion: true,
+    });
+
+    expect(plan.logicalStages).toEqual([
+      'temporal',
+      'meter',
+      'bloom',
+      'exposure-white-balance',
+      'tone',
+      'lut',
+      'barrel-distortion',
+      'fxaa',
+      'output-encoding',
+    ]);
+    expect(plan.physicalStages.at(6)).toEqual({
+      name: 'barrel-distortion',
+      input: 'linear-ldr',
+      output: 'linear-ldr',
+    });
+    expect(plan.incrementalResources).toContain('standard-barrel-distortion');
+    expect(plan.incrementalBindings).toBeGreaterThan(0);
+    expect(plan.physicalStages.at(8)?.output).toBe('display-encoded');
+    expect(validateStandardOutputPlan(plan).ok).toBe(true);
+  });
+
   it.each([
     [
       'swaps meter and bloom',

package/src/__tests__/standard-pbr-artifact-assembly.unit.test.ts

@@ -160,6 +160,48 @@ describe('Standard PBR artifact assembly', () => {
     expect(custom?.receipt).toEqual(colored);
   });
 
+  it('resolves a topology projection against the producer complete variant key', () => {
+    const receipt = createStandardPbrArtifactReceipt();
+    const shader = {
+      findMaterialArtifact: () => ({
+        ok: true as const,
+        value: { source: 'boot-direct', paramSchema: [], receipt },
+      }),
+      materialShaderManifestEntries: () => [
+        {
+          identifier: 'forgeax::default-standard-pbr',
+          sourcePath: 'default-standard-pbr.wgsl',
+          composedWgsl: 'boot-direct',
+          paramSchema: '[]',
+          variants: [
+            {
+              definesKey:
+                'CLUSTER_FORWARD_AVAILABLE=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=true+PROBE_BLEND_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+              defines: {
+                CLUSTER_FORWARD_AVAILABLE: false,
+                GPU_DRIVEN_SCENE_INDEX_AVAILABLE: true,
+                PROBE_BLEND_AVAILABLE: false,
+                STORAGE_BUFFER_AVAILABLE: true,
+                VERTEX_COLOR_AVAILABLE: false,
+              },
+              composedWgsl: 'scene-index',
+              receipt,
+            },
+          ],
+        },
+      ],
+    } as unknown as Parameters<typeof resolveMaterialShaderArtifact>[1];
+    const artifact = resolveMaterialShaderArtifact('forgeax::default-standard-pbr', shader, {
+      address: 'scene-index',
+      pass: 'forward',
+      vertexColorAvailable: false,
+      variantSet:
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+    });
+    expect(artifact?.wgsl).toBe('scene-index');
+    expect(artifact?.receipt).toEqual(receipt);
+  });
+
   it('routes built-in Standard shadow requests through the shadow-caster artifact', () => {
     const rigidPlain = createStandardPbrArtifactReceipt();
     const rigidColor = createStandardPbrArtifactReceipt(false, true);
@@ -251,7 +293,10 @@ describe('Standard PBR artifact assembly', () => {
     };
     const registry = {
       findMaterialArtifact: () => ({ ok: true, value: entry }),
-      materialShaderManifestEntries: () => [manifest].values(),
+      *materialShaderManifestEntries() {
+        yield manifest;
+        throw new Error('manifest search must stop at the first matching publication');
+      },
     } as unknown as Parameters<typeof resolveMaterialShaderArtifact>[1];
     const resolve = () =>
       resolveMaterialShaderArtifact('game::surface', registry, { address: 'scene-index' });