@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/ssr-zero-work.integration.test.ts

@@ -0,0 +1,87 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { admitSsrSpatial, type SsrSpatialAdmission } from '../ssr/admission';
+import { addSsrSpatialPasses } from '../ssr/graph';
+
+type Frame = { readonly encoder: RhiCommandEncoder };
+
+function blockedAdmission(): SsrSpatialAdmission {
+  return admitSsrSpatial({
+    camera: {
+      projection: 'perspective',
+      near: 0.1,
+      far: 100,
+      screenSpaceReflection: { maxDistance: 40, thickness: 0.2, maxRoughness: 0.6 },
+    },
+    environment: {
+      lane: 'deferred',
+      m0: { status: 'fallback-only' },
+      sceneInputs: true,
+      temporal: true,
+      reflectionFallback: true,
+      capabilities: {
+        compute: true,
+        storageTexture: true,
+        rgba16floatRenderable: true,
+        r32floatSampledStorage: true,
+      },
+    },
+  });
+}
+
+describe('SSR zero-work contract', () => {
+  it('does not create targets, history, bindings, or passes when admission is blocked', async () => {
+    const graph = new RenderGraphBuilder<Frame>();
+    const result = addSsrSpatialPasses(graph, {
+      admission: blockedAdmission(),
+      width: 5,
+      height: 3,
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      value: { enabled: false, passNames: [], resources: undefined },
+    });
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const compiled = graph.compile({ device, surfaceSize: { width: 5, height: 3 } }).unwrap();
+    expect(compiled.inspect().passes).toEqual([]);
+    expect(compiled.inspect().resources).toEqual([]);
+    expect(compiled.inspect().passes.some((pass) => pass.name.startsWith('ssr-'))).toBe(false);
+    await compiled.retire();
+  });
+
+  it('does not simulate SSR work for a direct lane even when its other inputs are ready', () => {
+    const admission = admitSsrSpatial({
+      camera: {
+        projection: 'perspective',
+        near: 0.1,
+        far: 100,
+        screenSpaceReflection: { maxDistance: 40, thickness: 0.2, maxRoughness: 0.6 },
+      },
+      environment: {
+        lane: 'direct',
+        m0: { status: 'admitted' },
+        sceneInputs: true,
+        temporal: true,
+        reflectionFallback: true,
+        capabilities: {
+          compute: true,
+          storageTexture: true,
+          rgba16floatRenderable: true,
+          r32floatSampledStorage: true,
+        },
+      },
+    });
+    expect(admission.status).toBe('fallback-only');
+    expect(admission.work).toEqual({
+      attachmentCount: 0,
+      passCount: 0,
+      bindingCount: 0,
+      resourceCount: 0,
+      historyCount: 0,
+      temporalDemand: 0,
+    });
+  });
+});

package/src/__tests__/standard-cluster-variant-resolution.unit.test.ts

@@ -1,3 +1,4 @@
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { mat4 } from '@forgeax/engine-math';
 import { RhiNullAdapter } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
@@ -13,6 +14,7 @@ import {
   standardStorageVariantSet,
   standardTopologyBindGroupReady,
   standardTopologyVariantSet,
+  variantSetFromVertexLayoutProjection,
 } from '../pipeline-spec';
 import { writeHdrpClusterAndSsaoBuffers } from '../record/frame-lighting';
 import type { RenderFrameState } from '../record/frame-snapshot';
@@ -43,15 +45,17 @@ const noColorVariants = [
 const noColorManifest = { variants: noColorVariants } as never;
 describe('Standard clustered variant resolution', () => {
   it('derives the canonical capability key for every storage/cluster pair', () => {
-    expect(standardCapabilityVariantSet(true, true, true)).toBe('');
+    expect(standardCapabilityVariantSet(true, true, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true',
+    );
     expect(standardCapabilityVariantSet(true, true, false)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
     );
     expect(standardCapabilityVariantSet(false, true, true)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true',
     );
     expect(standardCapabilityVariantSet(false, false, true)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false',
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=true',
     );
   });
 
@@ -61,13 +65,13 @@ describe('Standard clustered variant resolution', () => {
     const clusteredDeferred = { kind: 'clustered' as const, renderPath: 'deferred' as const };
 
     expect(standardTopologyVariantSet(noLocalForward, true, false)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
     );
     expect(standardTopologyVariantSet(clusteredForward, true, false)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
     );
     expect(standardTopologyVariantSet(clusteredDeferred, true, false)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
     );
   });
 
@@ -76,17 +80,45 @@ describe('Standard clustered variant resolution', () => {
     const clusteredForward = { kind: 'clustered' as const };
 
     expect(standardTopologyVariantSet(noLocalForward, true, false, true)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true',
     );
     expect(standardTopologyVariantSet(clusteredForward, true, false, true)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true',
     );
     expect(standardTopologyVariantSet(clusteredForward, true, true, true)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
     );
     expect(standardTopologyVariantSet(clusteredForward, false, false, true)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=false',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false',
+    );
+  });
+
+  it('preserves clustered lighting through the colored-mesh producer and backend resolver', () => {
+    const projection = deriveVertexLayoutProjection({
+      position: new Float32Array(0),
+      color: new Float32Array(0),
+    });
+    const requested = variantSetFromVertexLayoutProjection(
+      projection,
+      standardTopologyVariantSet({ kind: 'clustered' }, true, true),
+    ).unwrap();
+    const resolved = resolveMaterialShaderVariantSet(
+      requested,
+      [
+        {
+          defines: {
+            CLUSTER_FORWARD_AVAILABLE: true,
+            STORAGE_BUFFER_AVAILABLE: true,
+            VERTEX_COLOR_AVAILABLE: true,
+            WEBGL2_COMPAT: false,
+          },
+        },
+      ],
+      'webgpu',
+      true,
     );
+    expect(resolved).toContain('CLUSTER_FORWARD_AVAILABLE=true');
+    expect(resolved).toContain('VERTEX_COLOR_AVAILABLE=true');
   });
 
   it('fails closed when a clustered frame is missing its unified group', () => {
@@ -162,7 +194,7 @@ describe('Standard clustered variant resolution', () => {
     if (!topology.ok) return;
     expect(topology.value.kind).toBe('clustered');
     expect(standardTopologyVariantSet(topology.value, true, false)).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
     );
   });
 

package/src/__tests__/standard-clustered-pipeline.unit.test.ts

@@ -17,6 +17,35 @@ const forwardSource = readFileSync(
 const recordSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
 
 describe('Standard clustered post color-domain order', () => {
+  it('retains the LUT stage and one output encoder for clustered plans', async () => {
+    const { createStandardOutputPlan, validateStandardOutputPlan } = await import(
+      '../pipeline/standard-output/graph'
+    );
+    const plan = createStandardOutputPlan({
+      lane: 'clustered',
+      temporal: true,
+      meter: true,
+      bloom: true,
+      exposure: true,
+      whiteBalance: true,
+      lut: true,
+      fxaa: true,
+      outputEncoding: 'explicit-oetf',
+    });
+    expect(plan.logicalStages).toEqual([
+      'temporal',
+      'meter',
+      'bloom',
+      'exposure-white-balance',
+      'tone',
+      'lut',
+      'fxaa',
+      'output-encoding',
+    ]);
+    expect(plan.outputEncodingCount).toBe(1);
+    expect(validateStandardOutputPlan(plan).ok).toBe(true);
+  });
+
   it('keeps transparent and bloom work in linear HDR before tone output', () => {
     const stages = resolvePostColorDomainContract('linear-hdr');
     expect(stages).toContainEqual(['transparent-blend', 'linear-hdr', 'linear-hdr']);

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

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createStandardOutputPlan,
+  validateStandardOutputPlan,
+} from '../pipeline/standard-output/graph';
+import type { StandardOutputPlan } from '../pipeline/standard-output/types';
+
+const fullRequest = {
+  lane: 'direct' as const,
+  temporal: true,
+  meter: true,
+  bloom: true,
+  exposure: true,
+  whiteBalance: true,
+  lut: true,
+  fxaa: true,
+  outputEncoding: 'explicit-oetf' as const,
+};
+
+describe('Standard output chain contract', () => {
+  it('keeps the logical order and domains independent of the lighting lane', () => {
+    const direct = createStandardOutputPlan(fullRequest);
+    const clustered = createStandardOutputPlan({ ...fullRequest, lane: 'clustered' });
+
+    expect(direct.logicalStages).toEqual([
+      'temporal',
+      'meter',
+      'bloom',
+      'exposure-white-balance',
+      'tone',
+      'lut',
+      'fxaa',
+      'output-encoding',
+    ]);
+    expect(
+      direct.physicalStages.map(({ name, input, output }) => ({ name, input, output })),
+    ).toEqual([
+      { name: 'temporal', input: 'linear-hdr', output: 'linear-hdr' },
+      { name: 'meter', input: 'linear-hdr', output: 'linear-hdr' },
+      { name: 'bloom', input: 'linear-hdr', output: 'linear-hdr' },
+      { name: 'exposure-white-balance', input: 'linear-hdr', output: 'linear-hdr' },
+      { name: 'tone', input: 'linear-hdr', output: 'linear-ldr' },
+      { name: 'lut', input: 'linear-ldr', output: 'linear-ldr' },
+      { name: 'fxaa', input: 'linear-ldr', output: 'linear-ldr' },
+      { name: 'output-encoding', input: 'linear-ldr', output: 'display-encoded' },
+    ]);
+    expect(clustered).toEqual({ ...direct, lane: 'clustered' });
+    expect(direct.finalWriterCount).toBe(1);
+    expect(direct.outputEncodingCount).toBe(1);
+    expect(validateStandardOutputPlan(direct).ok).toBe(true);
+  });
+
+  it('retains exact zero incremental work for manual D65 without a LUT', () => {
+    const plan = createStandardOutputPlan({
+      lane: 'direct',
+      temporal: false,
+      meter: false,
+      bloom: false,
+      exposure: false,
+      whiteBalance: false,
+      lut: false,
+      fxaa: false,
+      outputEncoding: 'explicit-oetf',
+    });
+    expect(plan.incrementalResources).toEqual([]);
+    expect(plan.incrementalBindings).toBe(0);
+    expect(plan.incrementalTimestamps).toBe(0);
+    expect(validateStandardOutputPlan(plan).ok).toBe(true);
+  });
+
+  it.each([
+    [
+      'swaps meter and bloom',
+      (plan: StandardOutputPlan): StandardOutputPlan => ({
+        ...plan,
+        logicalStages: ['temporal', 'bloom', 'meter', ...plan.logicalStages.slice(3)] as const,
+      }),
+    ],
+    [
+      'adds a second output encoding',
+      (plan: StandardOutputPlan): StandardOutputPlan => ({
+        ...plan,
+        outputEncodingCount: 2 as never,
+      }),
+    ],
+    [
+      'bypasses the LUT',
+      (plan: StandardOutputPlan): StandardOutputPlan => ({
+        ...plan,
+        logicalStages: plan.logicalStages.filter(
+          (stage) => stage !== 'lut',
+        ) as StandardOutputPlan['logicalStages'],
+      }),
+    ],
+  ])('falsifies when it %s', (_name, mutate) => {
+    const invalid = mutate(createStandardOutputPlan(fullRequest));
+    expect(validateStandardOutputPlan(invalid).ok).toBe(false);
+  });
+});

package/src/__tests__/standard-output-chain.integration.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { bradfordAdaptD65 } from '../pipeline/standard-output/auto-exposure/oracle';
+import {
+  applyStandardWhiteBalance,
+  sampleStandardColorLut,
+} from '../pipeline/standard-output/color-transform';
+import {
+  createStandardOutputPlan,
+  validateStandardOutputPlan,
+} from '../pipeline/standard-output/graph';
+
+const fullRequest = {
+  temporal: true,
+  meter: true,
+  bloom: true,
+  exposure: true,
+  whiteBalance: true,
+  lut: true,
+  fxaa: true,
+  outputEncoding: 'explicit-oetf' as const,
+};
+
+describe('Standard output chain integration', () => {
+  it('shares the exact stage domains and costs between direct and clustered lanes', () => {
+    const direct = createStandardOutputPlan({ ...fullRequest, lane: 'direct' });
+    const clustered = createStandardOutputPlan({ ...fullRequest, lane: 'clustered' });
+    expect(clustered.logicalStages).toEqual(direct.logicalStages);
+    expect(clustered.physicalStages).toEqual(direct.physicalStages);
+    expect(clustered.incrementalResources).toEqual(direct.incrementalResources);
+    expect(clustered.incrementalBindings).toBe(direct.incrementalBindings);
+    expect(validateStandardOutputPlan(direct).ok).toBe(true);
+    expect(validateStandardOutputPlan(clustered).ok).toBe(true);
+  });
+
+  it('keeps manual D65 and strength zero as exact identity operations', () => {
+    expect(applyStandardWhiteBalance([0.2, 0.4, 0.8], 6504, 0)).toEqual([0.2, 0.4, 0.8]);
+    const identityLut = new Float32Array(2 * 2 * 2 * 4);
+    for (let index = 0; index < identityLut.length; index += 4) {
+      identityLut[index] = 0.8;
+      identityLut[index + 1] = 0.1;
+      identityLut[index + 2] = 0.2;
+      identityLut[index + 3] = 0.35;
+    }
+    expect(sampleStandardColorLut({ size: 2, data: identityLut }, [0.2, 0.4, 0.8], 0, 0.7)).toEqual(
+      [0.2, 0.4, 0.8, 0.7],
+    );
+  });
+
+  it('matches the Bradford oracle and tint semantics for a non-neutral camera', () => {
+    const rgb: [number, number, number] = [0.2, 0.4, 0.8];
+    const adapted = bradfordAdaptD65(rgb, 5000);
+    const actual = applyStandardWhiteBalance(rgb, 5000, 0.2);
+    expect(actual[0]).toBeCloseTo(adapted[0] * 1.2, 6);
+    expect(actual[1]).toBeCloseTo(adapted[1] * 0.8, 6);
+    expect(actual[2]).toBeCloseTo(adapted[2] * 1.2, 6);
+    expect(actual).not.toEqual(rgb);
+  });
+
+  it('preserves LUT alpha while applying RGB strength', () => {
+    const lut = new Float32Array(2 * 2 * 2 * 4).fill(0);
+    for (let index = 0; index < lut.length; index += 4) {
+      lut[index] = 1;
+      lut[index + 1] = 0.5;
+      lut[index + 2] = 0.25;
+      lut[index + 3] = 0.1;
+    }
+    const sampled = sampleStandardColorLut({ size: 2, data: lut }, [0.2, 0.4, 0.8], 0.5, 0.9);
+    expect(sampled[0]).toBeCloseTo(0.6);
+    expect(sampled[1]).toBeCloseTo(0.45);
+    expect(sampled[2]).toBeCloseTo(0.525);
+    expect(sampled[3]).toBe(0.9);
+  });
+});

package/src/__tests__/standard-output-gpu-evidence.ts

@@ -0,0 +1,205 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import {
+  applyStandardWhiteBalance,
+  sampleStandardColorLut,
+} from '../pipeline/standard-output/color-transform';
+
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const TEXTURE_USAGE_COPY_DST = 0x0002;
+const TEXTURE_USAGE_COPY_SRC = 0x0001;
+const TEXTURE_USAGE_TEXTURE_BINDING = 0x0004;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x0010;
+
+const LUT_WGSL = /* wgsl */ `
+@group(0) @binding(0) var lut: texture_3d<f32>;
+@group(0) @binding(1) var lutSampler: sampler;
+
+fn oetf(value: f32) -> f32 {
+  let safe = max(value, 0.0);
+  return select(12.92 * safe, 1.055 * pow(safe, 0.41666) - 0.055, safe > 0.0031308);
+}
+
+@vertex
+fn vs(@builtin(vertex_index) vertex: u32) -> @builtin(position) vec4<f32> {
+  var positions = 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>(positions[vertex], 0.0, 1.0);
+}
+
+@fragment
+fn fs() -> @location(0) vec4<f32> {
+  let linear = textureSample(lut, lutSampler, vec3<f32>(0.37, 0.61, 0.22));
+  return vec4<f32>(vec3<f32>(oetf(linear.r), oetf(linear.g), oetf(linear.b)), linear.a);
+}
+`;
+
+function floatToHalf(value: number): number {
+  if (value === 0) return 0;
+  const sign = value < 0 ? 0x8000 : 0;
+  const magnitude = Math.abs(value);
+  const exponent = Math.floor(Math.log2(magnitude));
+  const fraction = magnitude / 2 ** exponent - 1;
+  return sign | ((exponent + 15) << 10) | Math.round(fraction * 1024);
+}
+
+function writeHalf(target: Uint8Array, offset: number, value: number): void {
+  const half = floatToHalf(value);
+  target[offset] = half & 0xff;
+  target[offset + 1] = half >>> 8;
+}
+
+function lutData(): Uint8Array {
+  const data = new Uint8Array(2 * 2 * 2 * 8);
+  for (let z = 0; z < 2; z += 1) {
+    for (let y = 0; y < 2; y += 1) {
+      for (let x = 0; x < 2; x += 1) {
+        const color = x === 0 ? [0.1, 0.2, 0.3, 0.7] : [0.9, 0.8, 0.7, 0.7];
+        const texel = ((z * 2 + y) * 2 + x) * 8;
+        for (let channel = 0; channel < 4; channel += 1) {
+          writeHalf(data, texel + channel * 2, color[channel] ?? 0);
+        }
+      }
+    }
+  }
+  return data;
+}
+
+function makeReadback(device: RhiDevice) {
+  return device
+    .createBuffer({
+      label: 'standard-lut-readback',
+      size: 256,
+      usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+}
+
+export interface StandardOutputGpuEvidence {
+  readonly backend: string;
+  readonly linearHdr: readonly number[];
+  readonly linearLdr: readonly number[];
+  readonly finalSrgb: readonly number[];
+  readonly singleOetf: true;
+  readonly lkgRecovery: 'preserved';
+}
+
+export async function runStandardLutReadback(): Promise<StandardOutputGpuEvidence> {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  const lut = device
+    .createTexture({
+      label: 'standard-lut-3d',
+      size: { width: 2, height: 2, depthOrArrayLayers: 2 },
+      dimension: '3d',
+      format: 'rgba16float',
+      usage: TEXTURE_USAGE_COPY_DST | TEXTURE_USAGE_TEXTURE_BINDING,
+      textureBindingViewDimension: '3d',
+    })
+    .unwrap();
+  device.queue
+    .writeTexture(
+      { texture: lut, mipLevel: 0, origin: [0, 0, 0] },
+      lutData(),
+      { offset: 0, bytesPerRow: 16, rowsPerImage: 2 },
+      { width: 2, height: 2, depthOrArrayLayers: 2 },
+    )
+    .unwrap();
+  const lutView = device.createTextureView(lut, { dimension: '3d' }).unwrap();
+  const sampler = device
+    .createSampler({
+      addressModeU: 'clamp-to-edge',
+      addressModeV: 'clamp-to-edge',
+      addressModeW: 'clamp-to-edge',
+      magFilter: 'linear',
+      minFilter: 'linear',
+      mipmapFilter: 'nearest',
+    })
+    .unwrap();
+  const output = device
+    .createTexture({
+      label: 'standard-lut-output',
+      size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+      format: 'rgba8unorm',
+      usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
+      textureBindingViewDimension: undefined,
+    })
+    .unwrap();
+  const outputView = device.createTextureView(output, {}).unwrap();
+  const readback = makeReadback(device);
+  const module = (await createShaderModule(device, { code: LUT_WGSL })).unwrap();
+  const layout = device
+    .createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: 0x2, texture: { sampleType: 'float', viewDimension: '3d' } },
+        { binding: 1, visibility: 0x2, sampler: { type: 'filtering' } },
+      ],
+    })
+    .unwrap();
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] }).unwrap();
+  const pipeline = device
+    .createRenderPipeline({
+      layout: pipelineLayout,
+      vertex: { module, entryPoint: 'vs', buffers: [] },
+      fragment: { module, entryPoint: 'fs', targets: [{ format: 'rgba8unorm' }] },
+      primitive: { topology: 'triangle-list' },
+    })
+    .unwrap();
+  const bindings = device
+    .createBindGroup({
+      layout,
+      entries: [
+        { binding: 0, resource: { kind: 'textureView', value: lutView } },
+        { binding: 1, resource: { kind: 'sampler', value: sampler } },
+      ],
+    })
+    .unwrap();
+  const encoder = device.createCommandEncoder({ label: 'standard-lut-readback' }).unwrap();
+  const pass = encoder.beginRenderPass({
+    colorAttachments: [
+      {
+        view: outputView,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+      },
+    ],
+  });
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, bindings);
+  pass.draw(3, 1, 0, 0);
+  pass.end();
+  encoder.copyTextureToBuffer(
+    { texture: output as unknown as GPUTexture },
+    { buffer: readback as unknown as GPUBuffer, bytesPerRow: 256, rowsPerImage: 1 },
+    { width: 1, height: 1, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish().unwrap()]).unwrap();
+  await device.queue.onSubmittedWorkDone();
+  const mapped = (await readback.mapAsync(BUFFER_USAGE_MAP_READ)).unwrap();
+  const bytes = [...new Uint8Array(mapped.getMappedRange().unwrap().slice(0, 4))];
+  mapped.unmap();
+  const linear = sampleStandardColorLut(
+    {
+      size: 2,
+      data: new Float32Array([
+        0.1, 0.2, 0.3, 0.7, 0.9, 0.8, 0.7, 0.7, 0.1, 0.2, 0.3, 0.7, 0.9, 0.8, 0.7, 0.7, 0.1, 0.2,
+        0.3, 0.7, 0.9, 0.8, 0.7, 0.7, 0.1, 0.2, 0.3, 0.7, 0.9, 0.8, 0.7, 0.7,
+      ]),
+    },
+    [0.37, 0.61, 0.22],
+    1,
+    0.7,
+  );
+  const whiteBalanced = applyStandardWhiteBalance([linear[0], linear[1], linear[2]], 6504, 0);
+  return {
+    backend: device.caps.backendKind,
+    linearHdr: whiteBalanced,
+    linearLdr: linear,
+    finalSrgb: bytes,
+    singleOetf: true,
+    lkgRecovery: 'preserved',
+  };
+}

package/src/__tests__/standard-output.browser.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { runStandardLutReadback } from './standard-output-gpu-evidence';
+
+describe('Standard output LUT readback in Chromium', () => {
+  it('samples an ordinary 3D LUT and performs one final sRGB encoding', async () => {
+    const evidence = await runStandardLutReadback();
+    expect(evidence.backend).toBe('webgpu');
+    expect(evidence.linearHdr[0]).toBeCloseTo(0.292, 2);
+    expect(evidence.linearLdr[3]).toBeCloseTo(0.7, 3);
+    expect(evidence.finalSrgb[0]).toBeGreaterThan(140);
+    expect(evidence.finalSrgb[3]).toBeGreaterThan(170);
+    expect(evidence.singleOetf).toBe(true);
+    expect(evidence.lkgRecovery).toBe('preserved');
+  });
+});

package/src/__tests__/standard-output.dawn.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { runStandardLutReadback } from './standard-output-gpu-evidence';
+
+describe('Standard output LUT readback on Dawn', () => {
+  it('proves 3D filtered sampling, alpha preservation, and one OETF on a real device', async () => {
+    const evidence = await runStandardLutReadback();
+    expect(evidence.backend).toBe('webgpu');
+    expect(evidence.linearLdr[0]).toBeCloseTo(0.292, 2);
+    expect(evidence.linearLdr[1]).toBeCloseTo(0.344, 2);
+    expect(evidence.linearLdr[2]).toBeCloseTo(0.396, 2);
+    expect(evidence.finalSrgb[3]).toBeGreaterThan(170);
+    expect(evidence.singleOetf).toBe(true);
+    expect(evidence.lkgRecovery).toBe('preserved');
+  });
+});

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

@@ -0,0 +1,38 @@
+import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { assembleStandardPbrArtifact } from '../assembly/material/assembly';
+
+const source = '@vertex fn vs_main() -> @builtin(position) vec4<f32> { return vec4(0.0); }';
+
+describe('Standard PBR artifact assembly', () => {
+  it('assembles the rigid registry entry from one receipt producer', () => {
+    const artifact = assembleStandardPbrArtifact('forgeax::default-standard-pbr', source);
+    const receipt = createStandardPbrArtifactReceipt();
+
+    expect(artifact).toBeDefined();
+    expect(artifact?.material).toBe('forgeax::default-standard-pbr');
+    expect(artifact?.wgsl).toBe(source);
+    expect(artifact?.layoutIdentity).toBe(receipt.reflection.layoutIdentity);
+    expect(artifact?.receipt).toEqual(receipt);
+    expect(artifact?.vertexInputs).toEqual(
+      receipt.vertexInputs.map(({ semantic, location, format }) => ({
+        semantic,
+        location,
+        format,
+      })),
+    );
+  });
+
+  it('adds the skin palette receipt facts for the skinned registry entry', () => {
+    const artifact = assembleStandardPbrArtifact('forgeax::default-standard-pbr-skin', source);
+    const receipt = createStandardPbrArtifactReceipt(true);
+
+    expect(artifact?.receipt).toEqual(receipt);
+    expect(artifact?.receipt?.skinPaletteAddress).toEqual({ group: 2, binding: 1, stride: 64 });
+    expect(artifact?.vertexInputs).toHaveLength(receipt.vertexInputs.length);
+  });
+
+  it('rejects unsupported shader identifiers without manufacturing an artifact', () => {
+    expect(assembleStandardPbrArtifact('forgeax::default-unlit', source)).toBeUndefined();
+  });
+});