@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/standard-cluster-capability.integration.test.ts

@@ -0,0 +1,63 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  prepareStandardLighting,
+  type StandardLightFrame,
+} from '../pipeline/standard-lighting/prepare';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
+
+function prepared(localCount: number) {
+  const frame: StandardLightFrame = {
+    directional: undefined,
+    local: Array.from({ length: localCount }, (_, index) => ({
+      kind: index % 2 === 0 ? ('point' as const) : ('spot' as const),
+      shadowed: false,
+      position: vec3.create((index % 4) - 1.5, 0, -4 - (index % 8)),
+      range: 2,
+    })),
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: 256,
+    renderPath: 'forward',
+  };
+  const result = prepareStandardLighting(frame);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('Standard Cluster capability admission', () => {
+  it('keeps the same requested/admitted corpus across proven storage lanes', () => {
+    const cpu = prepared(33);
+    const compute = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: true },
+      cpu,
+    );
+    const storage = selectStandardClusterTransport(
+      { compute: false, storageBuffer: true, membershipPipelineReady: false },
+      cpu,
+    );
+    expect(compute.ok && storage.ok).toBe(true);
+    if (!compute.ok || !storage.ok) return;
+    expect(compute.value.requestedLightCount).toBe(33);
+    expect(storage.value.requestedLightCount).toBe(33);
+    expect(compute.value.admittedLightCount).toBe(storage.value.admittedLightCount);
+    expect(compute.value.membershipEntryCount).toBe(storage.value.membershipEntryCount);
+    expect(compute.value.lightBoundsBytes).toBe(storage.value.lightBoundsBytes);
+  });
+
+  it('never advertises a four-light fallback for WebGL2-like capabilities', () => {
+    const result = selectStandardClusterTransport(
+      { compute: false, storageBuffer: false, membershipPipelineReady: false },
+      prepared(33),
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    if (result.error.code !== 'standard-cluster-transport-unavailable') return;
+    expect(result.error.detail).toEqual({ requested: 33, admitted: 0 });
+    expect(JSON.stringify(result.error)).not.toContain('four');
+  });
+});

package/src/__tests__/standard-cluster-transport.unit.test.ts

@@ -0,0 +1,121 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  type PreparedStandardLighting,
+  prepareStandardLighting,
+  type StandardLightFrame,
+} from '../pipeline/standard-lighting/prepare';
+import {
+  type StandardClusterCapabilities,
+  selectStandardClusterTransport,
+} from '../pipeline/standard-lighting/transport';
+
+function frame(localCount: number): StandardLightFrame {
+  return {
+    directional: undefined,
+    local: Array.from({ length: localCount }, (_, index) => ({
+      kind: index % 2 === 0 ? ('point' as const) : ('spot' as const),
+      shadowed: false,
+      position: vec3.create((index % 4) - 1.5, 0, -4 - (index % 8)),
+      range: 2,
+    })),
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: 256,
+    renderPath: 'forward',
+  };
+}
+
+function prepared(localCount: number): PreparedStandardLighting {
+  const result = prepareStandardLighting(frame(localCount));
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+const STORAGE_FIXTURES: readonly [string, StandardClusterCapabilities, 'cpu' | 'gpu'][] = [
+  [
+    'compute + storage',
+    { compute: true, storageBuffer: true, membershipPipelineReady: true },
+    'gpu',
+  ],
+  [
+    'storage without compute',
+    { compute: false, storageBuffer: true, membershipPipelineReady: false },
+    'cpu',
+  ],
+];
+
+describe('Standard Cluster transport capability closure', () => {
+  it.each(STORAGE_FIXTURES)('selects %s from the prepared corpus', (_name, caps, producer) => {
+    const preparedFrame = prepared(33);
+    const selected = selectStandardClusterTransport(caps, preparedFrame);
+
+    expect(selected.ok).toBe(true);
+    if (!selected.ok) return;
+    expect(selected.value.requestedLightCount).toBe(33);
+    expect(selected.value.admittedLightCount).toBe(33);
+    expect(selected.value.membershipEntryCount).toBe(preparedFrame.membershipEntryCount);
+    expect(selected.value.lightBoundsBytes).toBe(preparedFrame.lightBounds.byteLength);
+    expect(selected.value.layout).toBe(preparedFrame.layout);
+    expect(selected.value.kind).toBe(producer === 'gpu' ? 'compute-storage' : 'cpu-storage');
+    expect(selected.value.producer).toBe(producer);
+  });
+
+  it('keeps CPU and GPU preparation on the same cluster corpus', () => {
+    const canonical = prepared(33);
+    const cpuTransport = selectStandardClusterTransport(
+      { compute: false, storageBuffer: true, membershipPipelineReady: false },
+      canonical,
+    );
+    const gpuTransport = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: true },
+      canonical,
+    );
+    expect(cpuTransport.ok && gpuTransport.ok).toBe(true);
+    if (!cpuTransport.ok || !gpuTransport.ok) return;
+    expect(Array.from(canonical.clusterGrid)).not.toEqual([]);
+    expect(Array.from(canonical.lightBounds)).not.toEqual([]);
+    expect(canonical.membershipEntryCount).toBeGreaterThan(0);
+    expect(cpuTransport.value.membershipEntryCount).toBe(gpuTransport.value.membershipEntryCount);
+    expect(cpuTransport.value.requestedLightCount).toBe(gpuTransport.value.requestedLightCount);
+  });
+
+  it('does not forge a GPU producer when the membership pipeline is not ready', () => {
+    const result = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: false },
+      prepared(33),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.producer).toBe('cpu');
+    expect(result.value.kind).toBe('cpu-storage');
+  });
+
+  it('fails closed when no proven storage transport exists', () => {
+    const result = selectStandardClusterTransport(
+      { compute: true, storageBuffer: false, membershipPipelineReady: false },
+      prepared(33),
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    if (result.error.code !== 'standard-cluster-transport-unavailable') return;
+    expect(result.error.detail).toEqual({ requested: 33, admitted: 0 });
+    expect(result.error.hint).toContain('storage');
+    expect(JSON.stringify(result.error)).not.toContain('four');
+  });
+
+  it('rejects even an empty frame without storage so no second cluster ABI exists', () => {
+    const result = selectStandardClusterTransport(
+      { compute: false, storageBuffer: false, membershipPipelineReady: false },
+      prepared(0),
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    if (result.error.code !== 'standard-cluster-transport-unavailable') return;
+    expect(result.error.detail).toEqual({ requested: 0, admitted: 0 });
+  });
+});

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

@@ -0,0 +1,299 @@
+import { mat4 } from '@forgeax/engine-math';
+import { RhiNullAdapter } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { resolveMaterialShaderVariantSet, selectNoColorPbrVariant } from '../assembly/factory';
+import { createClusterBinScratch } from '../cluster-binner';
+import { createHdrpClusterMembershipBindGroupLayoutDescriptor } from '../hdrp-buffers';
+import { RhiErrorListenerRegistry } from '../lifecycle';
+import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
+import { deriveStandardTopologyInput } from '../pipeline/standard-lighting/topology';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
+import {
+  standardCapabilityVariantSet,
+  standardStorageVariantSet,
+  standardTopologyBindGroupReady,
+  standardTopologyVariantSet,
+} from '../pipeline-spec';
+import { writeHdrpClusterAndSsaoBuffers } from '../record/frame-lighting';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
+import type { RenderSystemInternals } from '../record/render-context';
+
+const standardVariants = [
+  { defines: { CLUSTER_FORWARD_AVAILABLE: true, STORAGE_BUFFER_AVAILABLE: true } },
+  { defines: { CLUSTER_FORWARD_AVAILABLE: false, STORAGE_BUFFER_AVAILABLE: true } },
+];
+
+const noColorVariants = [
+  {
+    defines: {
+      CLUSTER_FORWARD_AVAILABLE: true,
+      STORAGE_BUFFER_AVAILABLE: true,
+      VERTEX_COLOR_AVAILABLE: false,
+    },
+  },
+  {
+    defines: {
+      CLUSTER_FORWARD_AVAILABLE: false,
+      STORAGE_BUFFER_AVAILABLE: true,
+      VERTEX_COLOR_AVAILABLE: false,
+    },
+  },
+] as never;
+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, false)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(standardCapabilityVariantSet(false, true, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(standardCapabilityVariantSet(false, false, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false',
+    );
+  });
+
+  it('derives PBR, skin, and sprite-lit variants from the frame topology', () => {
+    const noLocalForward = { kind: 'no-local-lights' as const, renderPath: 'forward' as const };
+    const clusteredForward = { kind: 'clustered' as const, renderPath: 'forward' as const };
+    const clusteredDeferred = { kind: 'clustered' as const, renderPath: 'deferred' as const };
+
+    expect(standardTopologyVariantSet(noLocalForward, true, false)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(standardTopologyVariantSet(clusteredForward, true, false)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(standardTopologyVariantSet(clusteredDeferred, true, false)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+    );
+  });
+
+  it('expands the clustered base before requesting the object-level probe ABI', () => {
+    const noLocalForward = { kind: 'no-local-lights' as const };
+    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',
+    );
+    expect(standardTopologyVariantSet(clusteredForward, true, false, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+    );
+    expect(standardTopologyVariantSet(clusteredForward, true, true, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+    );
+    expect(standardTopologyVariantSet(clusteredForward, false, false, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=false',
+    );
+  });
+
+  it('fails closed when a clustered frame is missing its unified group', () => {
+    expect(standardTopologyBindGroupReady({ kind: 'no-local-lights' }, null)).toBe(true);
+    expect(standardTopologyBindGroupReady({ kind: 'clustered' }, {})).toBe(true);
+    expect(standardTopologyBindGroupReady({ kind: 'clustered' }, null)).toBe(false);
+    expect(standardTopologyBindGroupReady({ kind: 'clustered' }, undefined)).toBe(false);
+  });
+
+  it('derives storage-only keys for unlit material consumers', () => {
+    expect(standardStorageVariantSet(true, true)).toBe('');
+    expect(standardStorageVariantSet(true, false)).toBe(
+      'STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+    );
+    expect(standardStorageVariantSet(false, true)).toBe(
+      'STORAGE_BUFFER_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=true',
+    );
+  });
+
+  it('normalizes an explicit all-true capability request to the canonical empty key', () => {
+    expect(
+      resolveMaterialShaderVariantSet(
+        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+        standardVariants,
+        'webgpu',
+        true,
+      ),
+    ).toBe('');
+  });
+
+  it('normalizes an absent request to the explicit URP false key', () => {
+    expect(resolveMaterialShaderVariantSet(undefined, standardVariants, 'webgpu', true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(
+      resolveMaterialShaderVariantSet(
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+        standardVariants,
+        'webgpu',
+        true,
+      ),
+    ).toBe('CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true');
+  });
+
+  it('keeps a zero-local storage frame on the clustered ABI', () => {
+    const prepared = prepareStandardLighting({
+      directional: undefined,
+      local: [],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 32,
+      renderPath: 'forward',
+    });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const transport = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: true },
+      prepared.value,
+    );
+    expect(transport.ok).toBe(true);
+    if (!transport.ok) return;
+    expect(transport.value.requestedLightCount).toBe(0);
+    expect(transport.value.membershipEntryCount).toBe(0);
+    const topology = deriveStandardTopologyInput({
+      kind: 'clustered',
+      prepared: prepared.value,
+      transport: transport.value,
+    });
+    expect(topology.ok).toBe(true);
+    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',
+    );
+  });
+
+  it('selects no-color HDRP for empty and expanded true keys', () => {
+    expect(selectNoColorPbrVariant(noColorManifest, true, '')).toBe(noColorVariants[0]);
+    expect(
+      selectNoColorPbrVariant(
+        noColorManifest,
+        true,
+        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      ),
+    ).toBe(noColorVariants[0]);
+  });
+
+  it('selects no-color URP for an expanded false key', () => {
+    expect(
+      selectNoColorPbrVariant(
+        noColorManifest,
+        true,
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      ),
+    ).toBe(noColorVariants[1]);
+  });
+
+  it('keeps fallback PBR layout selection aligned with the requested probe ABI', () => {
+    const noProbeUrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: false,
+        PROBE_BLEND_AVAILABLE: false,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'no-probe-urp',
+    };
+    const probeUrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: false,
+        PROBE_BLEND_AVAILABLE: true,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'probe-urp',
+    };
+    const noProbeHdrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: true,
+        PROBE_BLEND_AVAILABLE: false,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'no-probe-hdrp',
+    };
+    const probeHdrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: true,
+        PROBE_BLEND_AVAILABLE: true,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'probe-hdrp',
+    };
+    const manifest = { variants: [probeUrp, noProbeUrp, probeHdrp, noProbeHdrp] } as never;
+
+    expect(selectNoColorPbrVariant(manifest, true, undefined)).toBe(noProbeUrp);
+    expect(
+      selectNoColorPbrVariant(
+        manifest,
+        true,
+        'CLUSTER_FORWARD_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+      ),
+    ).toBe(probeHdrp);
+  });
+
+  it('rebuilds membership in write after a device and layout generation change', async () => {
+    const adapter = new RhiNullAdapter();
+    const deviceAResult = await adapter.requestDevice();
+    const deviceBResult = await adapter.requestDevice();
+    expect(deviceAResult.ok).toBe(true);
+    expect(deviceBResult.ok).toBe(true);
+    if (!deviceAResult.ok || !deviceBResult.ok) return;
+    const deviceA = deviceAResult.value;
+    const deviceB = deviceBResult.value;
+    const layoutA = deviceA.createBindGroupLayout({ entries: [] }).unwrap();
+    const layoutB = deviceB
+      .createBindGroupLayout(createHdrpClusterMembershipBindGroupLayoutDescriptor())
+      .unwrap();
+    const staleBindGroup = deviceA.createBindGroup({ layout: layoutA, entries: [] }).unwrap();
+    const frameState = {
+      clusteredLighting: true,
+      installedPipelineConfig: undefined,
+      standardOncePerFrameFired: new Set(),
+      hdrpClusterMembership: { device: deviceA, layout: layoutA, bindGroup: staleBindGroup },
+      hdrpClusterGridScratch: null,
+      hdrpLightIndexListScratch: null,
+      hdrpClusterBinScratch: createClusterBinScratch(),
+    } as unknown as RenderFrameState;
+    const internals = {
+      device: deviceB,
+      errorRegistry: new RhiErrorListenerRegistry(),
+    } as unknown as RenderSystemInternals;
+    const prepared = prepareStandardLighting({
+      directional: undefined,
+      local: [],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 1,
+      renderPath: 'forward',
+    });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const transport = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: true },
+      prepared.value,
+    );
+    expect(transport.ok).toBe(true);
+    if (!transport.ok) return;
+    writeHdrpClusterAndSsaoBuffers(
+      internals,
+      frameState,
+      makeZeroCameraFallbackSnapshot(),
+      prepared.value,
+      transport.value,
+      undefined,
+      true,
+      layoutB,
+    );
+    expect(frameState.hdrpClusterMembership?.device).toBe(deviceB);
+    expect(frameState.hdrpClusterMembership?.layout).toBe(layoutB);
+    expect(frameState.hdrpClusterMembership?.bindGroup).not.toBe(staleBindGroup);
+  });
+});

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

@@ -6,11 +6,15 @@ const clusteredSource = readFileSync(
   new URL('../pipeline/standard-pipeline.ts', import.meta.url),
   'utf8',
 );
-const frameSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
+const clusterGraphSource = readFileSync(
+  new URL('../pipeline/standard-lighting/graph.ts', import.meta.url),
+  'utf8',
+);
 const forwardSource = readFileSync(
   new URL('../pipeline/standard-forward-lane.ts', import.meta.url),
   'utf8',
 );
+const recordSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
 
 describe('Standard clustered post color-domain order', () => {
   it('keeps transparent and bloom work in linear HDR before tone output', () => {
@@ -27,9 +31,9 @@ describe('Standard clustered post color-domain order', () => {
   });
 
   it('keeps the real Standard producer and record owner as one provenance chain', () => {
-    expect(clusteredSource).toContain("graph.addComputePass('cluster-membership-producer'");
-    expect(frameSource).toContain('internals.device.caps?.compute === true,');
-    expect(clusteredSource).toContain('pass.dispatchWorkgroups(');
+    expect(clusterGraphSource).toContain("graph.addComputePass('cluster-membership-producer'");
+    expect(clusterGraphSource).toContain("buffers.lightIndexList, usage: 'storage-write'");
+    expect(clusterGraphSource).toContain('pass.dispatchWorkgroups(');
   });
 
   it('routes both Standard lanes through the one shared post-chain owner', () => {
@@ -44,6 +48,12 @@ describe('Standard clustered post color-domain order', () => {
     expect(result).toContainEqual(['bloom', 'linear-hdr', 'linear-hdr']);
     expect(clusteredSource).toContain('spotShadow: shadows.value.spot');
     expect(clusteredSource).toContain('shadows.value.spot,');
-    expect(clusteredSource).toContain("'hdrp-light-index-list'");
+    expect(clusterGraphSource).toContain("'hdrp-light-index-list'");
+  });
+
+  it('routes clustered direct-light recording through the Spot modifier uploader', () => {
+    expect(recordSource).toContain(
+      'writeSpotModifierTextures(internals, pipelineState, lights.spot);',
+    );
   });
 });

package/src/__tests__/standard-lighting-inspection.integration.test.ts

@@ -0,0 +1,138 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  inspectStandardClusterTransport,
+  inspectStandardLighting,
+} from '../pipeline/standard-lighting/inspection';
+import {
+  prepareStandardLighting,
+  type StandardLightFrame,
+} from '../pipeline/standard-lighting/prepare';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
+
+function prepared(localCount: number) {
+  const frame: StandardLightFrame = {
+    directional: undefined,
+    local: Array.from({ length: localCount }, (_, index) => ({
+      kind: index % 2 === 0 ? ('point' as const) : ('spot' as const),
+      shadowed: false,
+      position: vec3.create((index % 4) - 1.5, 0, -4 - (index % 8)),
+      range: 2,
+    })),
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: 256,
+    renderPath: 'forward',
+  };
+  const result = prepareStandardLighting(frame);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('Standard lighting inspection provenance', () => {
+  it('reports facts from the selected prepared transport, not a profile constant', () => {
+    const preparedFrame = prepared(33);
+    const selected = selectStandardClusterTransport(
+      { compute: false, storageBuffer: true, membershipPipelineReady: false },
+      preparedFrame,
+    );
+    expect(selected.ok).toBe(true);
+    if (!selected.ok) return;
+
+    expect(inspectStandardClusterTransport(selected.value, preparedFrame)).toEqual({
+      renderPath: 'forward',
+      transport: 'cpu-storage',
+      producer: 'cpu',
+      requested: 33,
+      admitted: 33,
+      shadowed: 0,
+      maxLights: 256,
+      indexCount: preparedFrame.membershipEntryCount,
+      occupied: selected.value.occupiedClusterCount,
+      clusterGridBytes: preparedFrame.layout.clusterGridU32Length * 4,
+      lightIndexListBytes: preparedFrame.membershipEntryCount * 4,
+      lightDataBytes: 33 * 80,
+      lightBoundsBytes: preparedFrame.lightBounds.byteLength,
+      grid: preparedFrame.layout.grid,
+    });
+  });
+
+  it('publishes an explicit not-required inspection for a successful zero-local frame', () => {
+    const result = prepareStandardLighting({
+      directional: undefined,
+      local: [],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 1,
+      renderPath: 'forward',
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const inspection = inspectStandardLighting({ kind: 'no-local-lights', prepared: result.value });
+    expect(inspection).toEqual({
+      renderPath: 'forward',
+      transport: 'not-required',
+      producer: 'none',
+      requested: 0,
+      admitted: 0,
+      shadowed: 0,
+      maxLights: 1,
+      indexCount: 0,
+      occupied: 0,
+      clusterGridBytes: 0,
+      lightIndexListBytes: 0,
+      lightDataBytes: 0,
+      lightBoundsBytes: 0,
+      grid: result.value.layout.grid,
+    });
+  });
+
+  it('preserves deferred path, shadow admission, and profile light budget', () => {
+    const frame: StandardLightFrame = {
+      directional: undefined,
+      local: [
+        {
+          kind: 'point',
+          shadowed: true,
+          position: vec3.create(0, 0, -4),
+          range: 2,
+        },
+      ],
+      view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+      projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 32,
+      renderPath: 'deferred',
+    };
+    const preparedFrame = prepareStandardLighting(frame);
+    expect(preparedFrame.ok).toBe(true);
+    if (!preparedFrame.ok) return;
+    const selected = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: true },
+      preparedFrame.value,
+    );
+    expect(selected.ok).toBe(true);
+    if (!selected.ok) return;
+    expect(
+      inspectStandardLighting({
+        kind: 'clustered',
+        prepared: preparedFrame.value,
+        transport: selected.value,
+      }),
+    ).toMatchObject({
+      renderPath: 'deferred',
+      transport: 'compute-storage',
+      producer: 'gpu',
+      shadowed: 1,
+      maxLights: 32,
+    });
+  });
+});

package/src/__tests__/standard-lighting-ssot.unit.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { STANDARD_CLUSTER_LAYOUT } from '../pipeline/standard-lighting/layout';
+import { CLUSTER_GRID_STRIDE_U32, LIGHT_INDEX_LIST_CAPACITY } from '../pipeline/standard-profile';
+
+describe('Standard lighting layout SSOT', () => {
+  it('derives the transport storage sizes from one cluster layout', () => {
+    expect(STANDARD_CLUSTER_LAYOUT.clusterGridStrideU32).toBe(CLUSTER_GRID_STRIDE_U32);
+    expect(STANDARD_CLUSTER_LAYOUT.lightIndexListCapacity).toBe(LIGHT_INDEX_LIST_CAPACITY);
+    expect(STANDARD_CLUSTER_LAYOUT.clusterGridU32Length).toBe(
+      STANDARD_CLUSTER_LAYOUT.clusterCount * STANDARD_CLUSTER_LAYOUT.clusterGridStrideU32,
+    );
+  });
+
+  it('does not introduce a second light-index budget', () => {
+    expect(Object.keys(STANDARD_CLUSTER_LAYOUT)).not.toContain('maxLightIndexListCapacity');
+    expect(STANDARD_CLUSTER_LAYOUT.lightIndexListCapacity).toBe(LIGHT_INDEX_LIST_CAPACITY);
+  });
+});