@forgeax/engine-runtime 0.1.7 → 0.1.20

package/src/__tests__/fullscreen-post-process-pass.dawn.test.ts

@@ -4,8 +4,8 @@
 // Dawn integration tests for FullscreenPostProcessPass:
 // (a) AC-06: the typed fullscreen pass samples input texture and writes to target,
 //     producing visible pixel output (non-black readback).
-// (b) AC-09: FXAA OFF/ON dual-pass pixel readback byte-identical to
-//     pre-refactor baseline (epsilon <= 0.05).
+// (b) AC-09: FXAA OFF/ON dual-pass readback with independent byte and
+//     affected-pixel diagnostics.
 // (c) R-COLORSPACE falsify: a variant that writes the swap-chain through the
 //     srgb view confirms the dual-pass comparison has discriminability
 //     (the sRGB-pass variant produces different bytes).
@@ -22,10 +22,19 @@ import type { Renderer } from '@forgeax/engine-render';
 import {
   ANTIALIAS_FXAA,
   ANTIALIAS_NONE,
+  ANTIALIAS_TAA,
   Camera,
+  Materials,
   MeshFilter,
   MeshRenderer,
+  MotionBlur,
 } from '@forgeax/engine-render';
+import { validateGraphTargetCaptureReadback } from '@forgeax/engine-render/internal';
+import type {
+  RendererHostAssembly,
+  RendererLegacyHostAdapter,
+} from '@forgeax/engine-render/internal/construct-renderer';
+import type { Buffer } from '@forgeax/engine-rhi';
 import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
 import { constructRuntimeRendererHost } from '../renderer-host';
@@ -42,6 +51,13 @@ const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
 const BUFFER_USAGE_MAP_READ = 0x0001;
 const BUFFER_USAGE_COPY_DST = 0x0008;
 const MAP_MODE_READ = 0x0001;
+const BUFFER_USAGE_MAP_READ_RHI = 0x0001;
+const BUFFER_USAGE_COPY_DST_RHI = 0x0008;
+type DebugDrawHost = RendererHostAssembly['debugDrawHost'] &
+  Pick<
+    RendererLegacyHostAdapter,
+    'getCurrentGraphTarget' | 'requestGraphTargetCapture' | 'onError'
+  >;
 
 const ENGINE_MANIFEST = await (async () => {
   const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
@@ -75,6 +91,140 @@ async function doReadPixels(device: GPUDevice, renderTarget: GPUTexture): Promis
   return bytes;
 }
 
+function pixelHash(pixels: Uint8Array): string {
+  let hash = 2166136261;
+  for (const byte of pixels) hash = Math.imul(hash ^ byte, 16777619);
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+function pixelDiffSummary(none: Uint8Array, fxaa: Uint8Array): string {
+  const channelDiffs = [0, 0, 0, 0];
+  const channelDelta = [0, 0, 0, 0];
+  let differingPixels = 0;
+  for (let offset = 0; offset < none.length; offset += 4) {
+    let pixelDiffers = false;
+    for (let channel = 0; channel < 4; channel += 1) {
+      const delta = Math.abs((none[offset + channel] ?? 0) - (fxaa[offset + channel] ?? 0));
+      if (delta !== 0) {
+        pixelDiffers = true;
+        channelDiffs[channel] = (channelDiffs[channel] ?? 0) + 1;
+        channelDelta[channel] = (channelDelta[channel] ?? 0) + delta;
+      }
+    }
+    if (pixelDiffers) differingPixels += 1;
+  }
+  const centerOffset = ((HEIGHT >> 1) * WIDTH + (WIDTH >> 1)) * 4;
+  const channels = (pixels: Uint8Array, offset: number) =>
+    Array.from(pixels.subarray(offset, offset + 4));
+  return JSON.stringify({
+    noneHash: pixelHash(none),
+    fxaaHash: pixelHash(fxaa),
+    differingPixels,
+    channelDiffs,
+    channelDelta,
+    center: { none: channels(none, centerOffset), fxaa: channels(fxaa, centerOffset) },
+    background: { none: channels(none, 4), fxaa: channels(fxaa, 4) },
+  });
+}
+
+function decodeFloat16(lo: number, hi: number): number {
+  const bits = lo | (hi << 8);
+  const sign = (bits & 0x8000) === 0 ? 1 : -1;
+  const exponent = (bits >>> 10) & 0x1f;
+  const fraction = bits & 0x03ff;
+  if (exponent === 0) return sign * 2 ** -14 * (fraction / 1024);
+  if (exponent === 0x1f) return fraction === 0 ? sign * Infinity : Number.NaN;
+  return sign * 2 ** (exponent - 15) * (1 + fraction / 1024);
+}
+
+function prepareOutputTransformCapture(host: DebugDrawHost):
+  | {
+      readonly buffer: Buffer;
+      readonly bytesPerRow: number;
+      readonly width: number;
+      readonly height: number;
+    }
+  | undefined {
+  const bytesPerRow = Math.ceil((WIDTH * 8) / 256) * 256;
+  const buffer = host.device.createBuffer({
+    size: bytesPerRow * HEIGHT,
+    usage: BUFFER_USAGE_MAP_READ_RHI | BUFFER_USAGE_COPY_DST_RHI,
+  });
+  if (!buffer.ok) return undefined;
+  const sentinel = new Uint8Array(16).fill(0xa5);
+  const initialized = host.device.queue.writeBuffer(buffer.value, 0, sentinel);
+  if (!initialized.ok) return undefined;
+  host.requestGraphTargetCapture({
+    name: 'standard-output-color',
+    buffer: buffer.value,
+    bytesPerRow,
+    width: WIDTH,
+    height: HEIGHT,
+    expected: {
+      format: 'rgba16float',
+      width: WIDTH,
+      height: HEIGHT,
+      usage: TEXTURE_USAGE_COPY_SRC,
+    },
+  });
+  return { buffer: buffer.value, bytesPerRow, width: WIDTH, height: HEIGHT };
+}
+
+async function readOutputTransformCapture(
+  host: DebugDrawHost,
+  capture: ReturnType<typeof prepareOutputTransformCapture>,
+  receiptFrameId: number,
+): Promise<
+  | {
+      readonly graphFrameId: number;
+      readonly graphGeneration: number;
+      readonly targetName: string;
+      readonly textureIdentity: number;
+      readonly receiptFrameId: number;
+      readonly format: string;
+      readonly size: { readonly width: number; readonly height: number };
+      readonly usage: number;
+      readonly center: readonly number[];
+      readonly captureWritten: boolean;
+    }
+  | undefined
+> {
+  const target = host.getCurrentGraphTarget('standard-output-color');
+  if (target === undefined || capture === undefined) return undefined;
+  await host.device.queue.onSubmittedWorkDone();
+  const mapped = await capture.buffer.mapAsync(MAP_MODE_READ);
+  if (!mapped.ok) return undefined;
+  const range = mapped.value.getMappedRange();
+  if (!range.ok) return undefined;
+  const bytes = new Uint8Array(range.value.slice(0));
+  mapped.value.unmap();
+  host.device.destroyBuffer(capture.buffer);
+  const { width, height } = capture;
+  const { bytesPerRow } = capture;
+  const validation = validateGraphTargetCaptureReadback({
+    bytes,
+    expectedByteLength: bytesPerRow * height,
+    sentinel: new Uint8Array(16).fill(0xa5),
+  });
+  if (!validation.ok) throw new Error(`graph-target-capture:${validation.code}`);
+  const centerOffset = (height >> 1) * bytesPerRow + (width >> 1) * 8;
+  return {
+    graphFrameId: target.frameId,
+    graphGeneration: target.graphGeneration,
+    targetName: target.name,
+    textureIdentity: target.textureIdentity,
+    receiptFrameId,
+    format: target.descriptor.format,
+    size: { width, height },
+    usage: target.descriptor.usage,
+    center: [0, 1, 2, 3].map((channel) => {
+      const offset = centerOffset + channel * 2;
+      return decodeFloat16(bytes[offset] ?? 0, bytes[offset + 1] ?? 0);
+    }),
+    captureWritten: bytes.some((byte, index) => index < 16 && byte !== 0xa5),
+  };
+}
+
 function spawnCubeScene(world: World, antialias: number): void {
   world.spawn(
     {
@@ -111,6 +261,73 @@ function spawnCubeScene(world: World, antialias: number): void {
   );
 }
 
+function spawnTemporalCubeScene(world: World) {
+  const material = world.allocSharedRef('MaterialAsset', Materials.unlit([0.9, 0.3, 0.25, 1]));
+  const cube = world
+    .spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [material] } },
+    )
+    .unwrap();
+  world
+    .spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 4],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      {
+        component: Camera,
+        data: {
+          fov: Math.PI / 3,
+          aspect: WIDTH / HEIGHT,
+          near: 0.1,
+          far: 100,
+          antialias: ANTIALIAS_TAA,
+          clearColor: [0, 0, 0, 1],
+        } as Record<string, unknown> as never,
+      },
+      { component: MotionBlur, data: { shutterAngle: 180, maxRadiusPixels: 32, sampleCount: 8 } },
+    )
+    .unwrap();
+  return cube;
+}
+
+function spawnLinearClearScene(world: World, antialias: number, linear: number): void {
+  world.spawn(
+    {
+      component: Transform,
+      data: {
+        pos: [0, 0, 3],
+        quat: [0, 0, 0, 1],
+        scale: [1, 1, 1],
+      },
+    },
+    {
+      component: Camera,
+      data: {
+        fov: Math.PI / 4,
+        aspect: 1,
+        near: 0.1,
+        far: 100,
+        antialias,
+        clearColor: [linear, linear, linear, 1],
+      } as Record<string, unknown> as never,
+    },
+  );
+}
+
 /**
  * Build a renderer with a mock canvas + offscreen render target, following the
  * fxaa-pixel-diff.dawn.test.ts pattern. Returns the renderer, captured device,
@@ -120,6 +337,7 @@ async function setupRenderer(): Promise<{
   renderer: Renderer;
   device: GPUDevice;
   renderTarget: GPUTexture;
+  debugDrawHost: DebugDrawHost;
 }> {
   if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') {
     throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
@@ -193,7 +411,8 @@ async function setupRenderer(): Promise<{
   // Create render target eagerly after capturing the shared device.
   const rt = getOrCreateRt(device);
 
-  return { renderer, device, renderTarget: rt };
+  const debugDrawHost = host.value.debugDrawHost as DebugDrawHost;
+  return { renderer, device, renderTarget: rt, debugDrawHost };
 }
 
 describe('feat-20260604 M2 w10: FullscreenPostProcessPass dawn tests', () => {
@@ -233,15 +452,18 @@ describe('feat-20260604 M2 w10: FullscreenPostProcessPass dawn tests', () => {
     expect(r + g + b, 'center pixel must not be black — cube should render').toBeGreaterThan(0);
   });
 
-  it('AC-09: FXAA OFF/ON dual-pass produces byte-consistent output (epsilon <= 0.05)', async () => {
-    // AC-09: The FXAA OFF/ON dual-state pixel readback must be byte-identical
-    // to the pre-refactor baseline (epsilon <= 0.05 = at most 5% of pixels
-    // differ). This confirms zero visual change from the M1 anchor.
+  it('AC-09: FXAA OFF/ON dual-pass preserves paired readback diagnostics', async () => {
+    // AC-09 keeps the paired readback and surface-path evidence. The old
+    // repair-local byte/pixel epsilon gate was dimensionally invalid: RGB byte
+    // differences cannot be compared with a pixel count. Keep both quantities
+    // as independent diagnostics while the fixture owns visual acceptance.
     //
     // NOTE: There is no reference PNG. The assertion is that two distinct
     // render passes produce measurable differences (proving FXAA is active)
     // while both produce visible geometry (proving nothing is broken).
-    const { renderer, device, renderTarget } = await setupRenderer();
+    const { renderer, device, renderTarget, debugDrawHost } = await setupRenderer();
+    const renderErrors: unknown[] = [];
+    const removeErrorListener = debugDrawHost.onError((error) => renderErrors.push(error));
 
     // Pass 1: antialias='none' baseline.
     const worldNone = new World();
@@ -256,8 +478,14 @@ describe('feat-20260604 M2 w10: FullscreenPostProcessPass dawn tests', () => {
       environment: { lease: attachmentNone.value },
     });
     expect(drawnNone.ok).toBe(true);
+    if (!drawnNone.ok) throw drawnNone.error;
     await device.queue.onSubmittedWorkDone();
+    const standardOutputNone = {
+      receiptFrameId: drawnNone.value.frameId,
+      target: 'not-present-on-no-fxaa-fast-path',
+    } as const;
     const pixelsNone = await doReadPixels(device, renderTarget);
+    const inspectionNone = renderer.inspect();
 
     // Pass 2: antialias='fxaa'.
     const worldFxaa = new World();
@@ -266,14 +494,38 @@ describe('feat-20260604 M2 w10: FullscreenPostProcessPass dawn tests', () => {
     expect(attachmentFxaa.ok).toBe(true);
     if (!attachmentFxaa.ok) throw attachmentFxaa.error;
     worldFxaa.update(1 / 60).unwrap();
+    const outputCapture = prepareOutputTransformCapture(debugDrawHost);
     const drawnFxaa = renderer.draw({
       leases: [attachmentFxaa.value],
       camera: { lease: attachmentFxaa.value },
       environment: { lease: attachmentFxaa.value },
     });
-    expect(drawnFxaa.ok).toBe(true);
+    expect(
+      drawnFxaa.ok,
+      drawnFxaa.ok
+        ? undefined
+        : `FXAA draw failed: ${JSON.stringify({ error: drawnFxaa.error, renderErrors })}`,
+    ).toBe(true);
+    if (!drawnFxaa.ok) throw drawnFxaa.error;
     await device.queue.onSubmittedWorkDone();
+    const standardOutputFxaa = await readOutputTransformCapture(
+      debugDrawHost,
+      outputCapture,
+      drawnFxaa.value.frameId,
+    );
     const pixelsFxaa = await doReadPixels(device, renderTarget);
+    const inspectionFxaa = renderer.inspect();
+    expect(standardOutputFxaa).toEqual(
+      expect.objectContaining({
+        graphFrameId: drawnFxaa.value.frameId - 1,
+        graphGeneration: expect.any(Number),
+        textureIdentity: expect.any(Number),
+        receiptFrameId: drawnFxaa.value.frameId,
+        format: 'rgba16float',
+        size: { width: WIDTH, height: HEIGHT },
+      }),
+    );
+    expect(standardOutputFxaa?.captureWritten).toBe(true);
 
     expect(pixelsNone.length).toBe(pixelsFxaa.length);
     expect(pixelsNone.length).toBeGreaterThan(0);
@@ -297,18 +549,99 @@ describe('feat-20260604 M2 w10: FullscreenPostProcessPass dawn tests', () => {
     }
     expect(nonBlackFxaa, 'fxaa pass must render at least one non-black pixel').toBeGreaterThan(0);
 
-    // AC-09: Byte-level pixel diff between OFF and ON — epsilon <= 0.05.
-    let diffCount = 0;
-    for (let i = 0; i < pixelsNone.length; i++) {
-      if (pixelsNone[i] !== pixelsFxaa[i]) diffCount++;
+    let rgbByteDiffCount = 0;
+    let affectedPixels = 0;
+    for (let i = 0; i < pixelsNone.length; i += 4) {
+      let pixelAffected = false;
+      for (let channel = 0; channel < 3; channel++) {
+        if (pixelsNone[i + channel] !== pixelsFxaa[i + channel]) {
+          rgbByteDiffCount++;
+          pixelAffected = true;
+        }
+      }
+      if (pixelAffected) affectedPixels++;
     }
     const totalPixels = WIDTH * HEIGHT;
-    const epsilon = 0.05;
-    const maxDiffPixels = Math.floor(totalPixels * epsilon);
+    const affectedPixelRatio = affectedPixels / totalPixels;
+    const diagnostics = {
+      rgbByteDiffCount,
+      affectedPixels,
+      affectedPixelRatio,
+      pixelDiff: pixelDiffSummary(pixelsNone, pixelsFxaa),
+      standardOutputNone,
+      standardOutputFxaa,
+    };
+    // biome-ignore lint/suspicious/noConsole: AC-09 retains a bounded portability diagnostic for paired readback evidence.
+    console.info(`AC-09 paired readback diagnostics: ${JSON.stringify(diagnostics)}`);
     expect(
-      diffCount,
-      `pixel diff ${diffCount} must be <= ${maxDiffPixels} (epsilon=${epsilon} of ${totalPixels} pixels)`,
-    ).toBeLessThanOrEqual(maxDiffPixels);
+      rgbByteDiffCount,
+      `paired readback must expose the existing FXAA difference; diagnostics=${JSON.stringify(diagnostics)}; ` +
+        `noneSurface=${JSON.stringify({
+          displayEncoded: inspectionNone.displayEncoded,
+          intermediateFormat: inspectionNone.intermediateFormat,
+          surfaceStorage: inspectionNone.surfaceStorage,
+          surfaceDisplay: inspectionNone.surfaceDisplay,
+          endpoint: inspectionNone.endpoint,
+          capability: inspectionNone.capability,
+          error: inspectionNone.error,
+        })}; fxaaSurface=${JSON.stringify({
+          displayEncoded: inspectionFxaa.displayEncoded,
+          intermediateFormat: inspectionFxaa.intermediateFormat,
+          surfaceStorage: inspectionFxaa.surfaceStorage,
+          surfaceDisplay: inspectionFxaa.surfaceDisplay,
+          endpoint: inspectionFxaa.endpoint,
+          capability: inspectionFxaa.capability,
+          error: inspectionFxaa.error,
+          standardOutputNone,
+          standardOutputFxaa,
+        })}`,
+    ).toBeGreaterThan(0);
+    removeErrorListener();
+  });
+
+  it('keeps TAA + MotionBlur visible on the first no-yield Dawn draw', async () => {
+    const { renderer, device, renderTarget } = await setupRenderer();
+    const world = new World();
+    const cube = spawnTemporalCubeScene(world);
+    const attachment = renderer.attach(world);
+    expect(attachment.ok).toBe(true);
+    if (!attachment.ok) throw attachment.error;
+
+    // Do not await between draws: temporal fullscreen PSOs must be seeded by
+    // renderer initialization, not by an accidental event-loop yield.
+    for (let frame = 0; frame < 2; frame += 1) {
+      world.set(cube, Transform, { pos: [Math.sin(frame * 0.08) * 0.2, 0, 0] }).unwrap();
+      world.update(1 / 60).unwrap();
+      const drawn = renderer.draw({
+        leases: [attachment.value],
+        camera: { lease: attachment.value },
+        environment: { lease: attachment.value },
+      });
+      expect(drawn.ok).toBe(true);
+    }
+    await device.queue.onSubmittedWorkDone();
+    const pixels = await doReadPixels(device, renderTarget);
+    let nonBlack = 0;
+    for (let index = 0; index < pixels.length; index += 4) {
+      const red = pixels[index + 0] ?? 0;
+      const green = pixels[index + 1] ?? 0;
+      const blue = pixels[index + 2] ?? 0;
+      if (red + green + blue > 0) nonBlack += 1;
+    }
+    expect(nonBlack, 'TAA + MotionBlur must write the declared output target').toBeGreaterThan(0);
+
+    const inspection = renderer.inspect();
+    expect(inspection.perFramePassNames).toEqual(
+      expect.arrayContaining([
+        'standard-scene-data',
+        'taa-resolve',
+        'motion-blur',
+        'output-transform',
+      ]),
+    );
+    expect(inspection.temporal).toMatchObject({ status: 'stable', historyValid: true });
+    expect(inspection.motionBlur).toMatchObject({ status: 'active', historyWrites: 0 });
+    await renderer.dispose();
   });
 
   it('R-COLORSPACE falsify: writing through srgb view changes pixel output (discriminability guard)', () => {
@@ -333,4 +666,114 @@ describe('feat-20260604 M2 w10: FullscreenPostProcessPass dawn tests', () => {
     // The sRGB-encoded value should be larger (gamma curve brightens).
     expect(srgbGammaOutput).toBeGreaterThan(nonSrgbOutput);
   });
+
+  it('records the GPU half-cell/raw-unorm divergence without software quantization', async () => {
+    const { renderer, device, renderTarget, debugDrawHost } = await setupRenderer();
+    const linearInputs = [0.49989, 0.49992] as const;
+    const directPixels: Uint8Array[] = [];
+    const fxaaPixels: Uint8Array[] = [];
+    const fxaaCaptures: Array<NonNullable<Awaited<ReturnType<typeof readOutputTransformCapture>>>> =
+      [];
+
+    for (const linear of linearInputs) {
+      const directWorld = new World();
+      spawnLinearClearScene(directWorld, ANTIALIAS_NONE, linear);
+      const directAttachment = renderer.attach(directWorld);
+      expect(directAttachment.ok).toBe(true);
+      if (!directAttachment.ok) throw directAttachment.error;
+      directWorld.update(1 / 60).unwrap();
+      const directDraw = renderer.draw({
+        leases: [directAttachment.value],
+        camera: { lease: directAttachment.value },
+        environment: { lease: directAttachment.value },
+      });
+      expect(directDraw.ok).toBe(true);
+      await device.queue.onSubmittedWorkDone();
+      directPixels.push(await doReadPixels(device, renderTarget));
+
+      const fxaaWorld = new World();
+      spawnLinearClearScene(fxaaWorld, ANTIALIAS_FXAA, linear);
+      const fxaaAttachment = renderer.attach(fxaaWorld);
+      expect(fxaaAttachment.ok).toBe(true);
+      if (!fxaaAttachment.ok) throw fxaaAttachment.error;
+      fxaaWorld.update(1 / 60).unwrap();
+      const capture = prepareOutputTransformCapture(debugDrawHost);
+      const fxaaDraw = renderer.draw({
+        leases: [fxaaAttachment.value],
+        camera: { lease: fxaaAttachment.value },
+        environment: { lease: fxaaAttachment.value },
+      });
+      expect(fxaaDraw.ok).toBe(true);
+      if (!fxaaDraw.ok) throw fxaaDraw.error;
+      await device.queue.onSubmittedWorkDone();
+      const output = await readOutputTransformCapture(
+        debugDrawHost,
+        capture,
+        fxaaDraw.value.frameId,
+      );
+      expect(output?.captureWritten).toBe(true);
+      expect(output?.center.every(Number.isFinite)).toBe(true);
+      if (output === undefined) continue;
+      fxaaCaptures.push(output);
+      fxaaPixels.push(await doReadPixels(device, renderTarget));
+    }
+
+    const centerOffset = ((HEIGHT >> 1) * WIDTH + (WIDTH >> 1)) * 4;
+    const rawCenters = [
+      ...directPixels.map((pixels) => pixels[centerOffset] ?? Number.NaN),
+      ...fxaaPixels.map((pixels) => pixels[centerOffset] ?? Number.NaN),
+    ];
+    expect(rawCenters.every((value) => Number.isInteger(value) && value >= 0 && value <= 255)).toBe(
+      true,
+    );
+    expect(fxaaCaptures).toHaveLength(linearInputs.length);
+    for (const output of fxaaCaptures) {
+      expect(output).toMatchObject({
+        targetName: 'standard-output-color',
+        format: 'rgba16float',
+        size: { width: WIDTH, height: HEIGHT },
+        captureWritten: true,
+      });
+      expect(output.graphFrameId).toBeGreaterThan(0);
+      expect(output.receiptFrameId).toBeGreaterThan(0);
+      expect(output.graphGeneration).toBeGreaterThan(0);
+      expect(output.textureIdentity).toBeGreaterThan(0);
+      expect(output.usage & TEXTURE_USAGE_COPY_SRC).toBe(TEXTURE_USAGE_COPY_SRC);
+      expect(output.center.every(Number.isFinite)).toBe(true);
+    }
+    expect(fxaaCaptures[0]?.center).toEqual(fxaaCaptures[1]?.center);
+  });
+
+  it('keeps Output Transform boundary inputs finite on the GPU', async () => {
+    const { renderer, device, debugDrawHost } = await setupRenderer();
+    const linearInputs = [0, 2 ** -24, 2 ** -14, 1] as const;
+    const outputs: number[] = [];
+
+    for (const linear of linearInputs) {
+      const world = new World();
+      spawnLinearClearScene(world, ANTIALIAS_FXAA, linear);
+      const attachment = renderer.attach(world);
+      expect(attachment.ok).toBe(true);
+      if (!attachment.ok) throw attachment.error;
+      world.update(1 / 60).unwrap();
+      const capture = prepareOutputTransformCapture(debugDrawHost);
+      const drawn = renderer.draw({
+        leases: [attachment.value],
+        camera: { lease: attachment.value },
+        environment: { lease: attachment.value },
+      });
+      expect(drawn.ok).toBe(true);
+      if (!drawn.ok) throw drawn.error;
+      await device.queue.onSubmittedWorkDone();
+      const output = await readOutputTransformCapture(debugDrawHost, capture, drawn.value.frameId);
+      expect(output?.captureWritten).toBe(true);
+      expect(output?.center.every(Number.isFinite)).toBe(true);
+      outputs.push(output?.center[0] ?? Number.NaN);
+    }
+
+    expect(outputs[0]).toBe(0);
+    expect(outputs[3]).toBeGreaterThan(0.99);
+    expect(outputs[3]).toBeLessThanOrEqual(1);
+    expect(outputs.every(Number.isFinite)).toBe(true);
+  });
 });

package/src/__tests__/geometry.unit.test.ts

@@ -64,6 +64,7 @@ import {
 import type { ExtractedFrame } from '../../../render/src/render-system-extract';
 import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 import { drawWithOwners } from './renderer-test-utils';
 
 type RendererErrorObservation = {
@@ -2135,7 +2136,8 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const manifest = {
       schemaVersion: '1.0.0',

package/src/__tests__/gpu-resource-cow-survivor.test.ts

@@ -144,12 +144,11 @@ function configuredStore(probe: CowProbe): GpuResidencyCache {
 function texturePod(w = 2, h = 2): TextureAsset {
   return {
     kind: 'texture',
-    width: w,
-    height: h,
+    shape: { viewDimension: '2d', extent: { width: w, height: h } },
     format: 'rgba8unorm-srgb',
     data: new Uint8Array(w * h * 4).fill(188),
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
   };
 }
 

package/src/__tests__/helpers/standard-material-manifest.ts

@@ -0,0 +1,45 @@
+export interface StandardMaterialShaderVariant {
+  readonly definesKey: string;
+  readonly defines: {
+    readonly CLUSTER_FORWARD_AVAILABLE: boolean;
+    readonly STORAGE_BUFFER_AVAILABLE: boolean;
+    readonly TRANSMISSION_AVAILABLE: boolean;
+    readonly VERTEX_COLOR_AVAILABLE: boolean;
+  };
+  readonly composedWgsl: string;
+}
+
+function variantKey(defines: StandardMaterialShaderVariant['defines']): string {
+  const entries = Object.entries(defines).sort(([left], [right]) =>
+    left < right ? -1 : left > right ? 1 : 0,
+  );
+  return entries.every(([, value]) => value)
+    ? ''
+    : entries.map(([key, value]) => `${key}=${value}`).join('+');
+}
+
+export function standardMaterialShaderVariants(
+  composedWgsl = '/* stub */',
+): readonly StandardMaterialShaderVariant[] {
+  const variants: StandardMaterialShaderVariant[] = [];
+  for (const cluster of [false, true]) {
+    for (const storage of [false, true]) {
+      for (const transmission of [false, true]) {
+        for (const vertexColor of [false, true]) {
+          const defines = {
+            CLUSTER_FORWARD_AVAILABLE: cluster,
+            STORAGE_BUFFER_AVAILABLE: storage,
+            TRANSMISSION_AVAILABLE: transmission,
+            VERTEX_COLOR_AVAILABLE: vertexColor,
+          } as const;
+          variants.push({
+            definesKey: variantKey(defines),
+            defines,
+            composedWgsl,
+          });
+        }
+      }
+    }
+  }
+  return variants;
+}

package/src/__tests__/helpers/tilemap-assets.ts

@@ -6,12 +6,11 @@ export const TEST_ATLAS_GUID = 'test/atlas';
 export function makeTestTexture(seed = 0): TextureAsset {
   return {
     kind: 'texture',
-    width: 32,
-    height: 32,
-    format: 'rgba8unorm',
+    shape: { viewDimension: '2d', extent: { width: 32, height: 32 } },
+    format: 'rgba8unorm-srgb',
     data: new Uint8Array(32 * 32 * 4).fill(seed),
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
   };
 }