@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/gpu-driven-production.integration.test.ts

@@ -3,20 +3,22 @@ import { World } from '@forgeax/engine-ecs';
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { vec3 } from '@forgeax/engine-math';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
-import type { BindGroup } from '@forgeax/engine-rhi';
+import { type BindGroup, RhiError, type RhiRenderPassEncoder } from '@forgeax/engine-rhi';
 import { type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
-import { Transform } from '@forgeax/engine-scene';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
 import {
   createStandardPbrArtifactReceipt,
   DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
 } from '@forgeax/engine-shader';
 import { ok } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { createRenderer as constructRenderer } from '../assembly/factory';
 import { Camera, MeshFilter, MeshRenderer, PointLight } from '../components';
 import type { MeshGpuHandles } from '../device/gpu-residency';
+import { gpuDrivenDrawKey, gpuDrivenShadowDrawKey } from '../extract/gpu-driven';
 import { BatchTopology } from '../gpu-driven/batch-topology';
+import { standardPbrProgramKey } from '../gpu-driven/pbr-program';
 import {
   adaptStandardPbrFrameResources,
   GpuDrivenProduction,
@@ -31,10 +33,28 @@ import {
   GPU_BUFFER_USAGE_UNIFORM,
   GPU_BUFFER_USAGE_VERTEX,
 } from '../gpu-usage';
+import { buildDispatchPlan } from '../record/frame';
 import { makeZeroCameraFallbackSnapshot, worldEntityKey } from '../record/frame-snapshot';
+import {
+  encodeDirectionalShadowPass,
+  encodePointShadowPass,
+  encodeSpotShadowPass,
+  recordShadowCasterDraws,
+  shadowShaderMap,
+} from '../record/shadow-pass';
 import type { RenderPipelineFrame } from '../render-pipeline';
-import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
-import { RenderScene } from '../scene/render-scene';
+import type {
+  DispatchEntry,
+  MaterialSnapshot,
+  RenderableSnapshot,
+  ShadowCasterMembership,
+} from '../render-system-extract';
+import { shadowCasterCpuReason } from '../render-system-extract';
+import { PersistentRenderScene, RenderScene } from '../scene/render-scene';
+import {
+  preparedPbrSnapshot as preparedPbrFixture,
+  standardPbrInputs,
+} from './gpu-driven-production-fixture';
 
 const STANDARD_PBR_RECEIPT = createStandardPbrArtifactReceipt();
 
@@ -136,6 +156,27 @@ function snapshot(entityKey: number, assetHandle: number): RenderableSnapshot {
   };
 }
 
+function preparedSnapshot(entityKey: number, assetHandle: number): RenderableSnapshot {
+  return preparedPbrFixture(snapshot(entityKey, assetHandle));
+}
+
+function withoutPrepared(
+  draw: NonNullable<RenderableSnapshot['gpuDrivenDraws']>[number],
+): Omit<typeof draw, 'prepared'> {
+  const { prepared, ...rest } = draw;
+  void prepared;
+  return rest;
+}
+
+function updateSnapshot(value: RenderableSnapshot) {
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    snapshot: value,
+  };
+}
+
 function mesh(device: RhiNullDevice, indexed = true, withLod = false): MeshGpuHandles {
   const vertex = device
     .createBuffer({
@@ -158,7 +199,6 @@ function mesh(device: RhiNullDevice, indexed = true, withLod = false): MeshGpuHa
     iboBytes: indexed ? 8 : 0,
     indexCount: indexed ? 3 : 0,
     indexFormat: 'uint16',
-    layout: '12F',
     layoutProjection: deriveVertexLayoutProjection({
       position: new Float32Array(9),
       normal: new Float32Array(9),
@@ -199,10 +239,11 @@ describe('GPU-driven production projection', () => {
         entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
       })
       .unwrap();
+    const pbrInputs = standardPbrInputs(device, shader, viewLayout);
     const projection = new RenderScene();
     const lodMeshGuid = '00000000-0000-7000-8000-000000000001' as never;
     const makeLodSnapshot = (entityKey: number): RenderableSnapshot => {
-      const base = snapshot(entityKey, 3);
+      const base = preparedPbrFixture(snapshot(entityKey, 3));
       const draw = base.gpuDrivenDraws?.[0];
       if (draw === undefined) throw new Error('LOD test snapshot has no draw');
       return {
@@ -212,8 +253,8 @@ describe('GPU-driven production projection', () => {
       };
     };
     const delta = projection.apply([
-      { kind: 'create', snapshot: makeLodSnapshot(1) },
-      { kind: 'create', snapshot: makeLodSnapshot(2) },
+      updateSnapshot(makeLodSnapshot(1)),
+      updateSnapshot(makeLodSnapshot(2)),
     ]);
     const availability = GpuScene.create(device, 2).unwrap();
     expect(availability.status).toBe('available');
@@ -224,23 +265,28 @@ describe('GPU-driven production projection', () => {
     const production = new GpuDrivenProduction(device, {
       createShaderModule: () => ok(shader),
     });
+    const lodGpuMesh = mesh(device, true, true);
     const prepared = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes: new Map([[3, mesh(device, true, true)]]),
+        meshBySlot: new Map([
+          [0, lodGpuMesh],
+          [1, lodGpuMesh],
+        ]),
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
+
         activeEntityKeys: new Set([worldEntityKey(0, 1)]),
         activeEntityRevision: 1,
       })
       .unwrap();
-    expect(prepared?.entityKeys).toEqual(new Set([worldEntityKey(0, 1)]));
+    expect(prepared?.drawKeys).toEqual(new Set(['1:-1:0', '2:-1:0']));
     // Both candidates are uploaded to the selector (2 * 304 bytes), while
     // only the active entity is admitted into the compacted draw stream.
     expect(production.inspect()).toMatchObject({
@@ -254,7 +300,7 @@ describe('GPU-driven production projection', () => {
       .unwrap();
     expect(projected.accesses.length).toBeGreaterThan(0);
     expect(production.inspect()).toMatchObject({
-      batchBindGroupCreates: 1,
+      batchBindGroupCreates: 0,
       indirectDrawCount: 1,
     });
     expect(production.inspect().indirectDrawCount).toBeGreaterThan(0);
@@ -262,18 +308,50 @@ describe('GPU-driven production projection', () => {
       production.inspect().batchCount,
     );
 
+    // The scene/view buffers and visible range are unchanged on a warm
+    // projection. The raster owner must reuse the physical batch bind group;
+    // a new group is only valid after one of those handles or the range
+    // changes (resize/recovery/LOD admission).
+    const warm = production
+      .prepare({
+        ...pbrInputs,
+        scene: {
+          scene: availability.scene,
+          plan: topology.plan(),
+          slots: projection.slotsSnapshot(),
+        },
+        camera: makeZeroCameraFallbackSnapshot(),
+        meshBySlot: new Map([
+          [0, lodGpuMesh],
+          [1, lodGpuMesh],
+        ]),
+        viewBindGroupLayout: viewLayout,
+        meshResidencyEpoch: 1,
+
+        activeEntityKeys: new Set([worldEntityKey(0, 1)]),
+        activeEntityRevision: 1,
+      })
+      .unwrap();
+    expect(warm?.topologySignature).toBe(prepared.topologySignature);
+    warm?.project(new RenderGraphBuilder<RenderPipelineFrame>(), 'rgba8unorm', 1).unwrap();
+    expect(production.inspect()).toMatchObject({ batchBindGroupCreates: 0 });
+
     const suppressed = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes: new Map([[3, mesh(device, true, true)]]),
+        meshBySlot: new Map([
+          [0, lodGpuMesh],
+          [1, lodGpuMesh],
+        ]),
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
+
         activeEntityKeys: new Set(),
         activeEntityRevision: 2,
       })
@@ -286,16 +364,20 @@ describe('GPU-driven production projection', () => {
 
     const restored = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes: new Map([[3, mesh(device, true, true)]]),
+        meshBySlot: new Map([
+          [0, lodGpuMesh],
+          [1, lodGpuMesh],
+        ]),
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
+
         activeEntityKeys: new Set([worldEntityKey(0, 1)]),
         activeEntityRevision: 3,
       })
@@ -306,16 +388,18 @@ describe('GPU-driven production projection', () => {
       indirectDrawCount: 1,
     });
     expect(GPU_DRIVEN_VIEW_WGSL.indexOf('atomicAdd(&counters[lodCounterIndex')).toBeLessThan(
-      GPU_DRIVEN_VIEW_WGSL.indexOf('if (candidate.submitAdmission == 0u)'),
+      GPU_DRIVEN_VIEW_WGSL.indexOf('if ((candidate.submitAdmission & 1u) == 0u)'),
     );
-    expect(GPU_DRIVEN_VIEW_WGSL.indexOf('if (candidate.submitAdmission == 0u)')).toBeLessThan(
+    expect(
+      GPU_DRIVEN_VIEW_WGSL.indexOf('if ((candidate.submitAdmission & 1u) == 0u)'),
+    ).toBeLessThan(
       GPU_DRIVEN_VIEW_WGSL.indexOf('atomicAdd(&counters[counterIndex(candidate.batchIndex)], 1u)'),
     );
     production.dispose();
     availability.scene.dispose();
   });
 
-  it('keeps a suppressed-only batch in selector telemetry without raster resources', async () => {
+  it('keeps an all-suppressed candidate out of the GPU raster frame', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
     const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
@@ -324,9 +408,10 @@ describe('GPU-driven production projection', () => {
         entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
       })
       .unwrap();
+    const pbrInputs = standardPbrInputs(device, shader, viewLayout);
     const projection = new RenderScene();
-    const candidate = snapshot(1, 3);
-    const delta = projection.apply([{ kind: 'create', snapshot: candidate }]);
+    const candidate = preparedPbrFixture(snapshot(1, 3));
+    const delta = projection.apply([updateSnapshot(candidate)]);
     const availability = GpuScene.create(device, 1).unwrap();
     expect(availability.status).toBe('available');
     if (availability.status !== 'available') return;
@@ -338,31 +423,29 @@ describe('GPU-driven production projection', () => {
     });
     const prepared = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes: new Map([[3, mesh(device)]]),
+        meshBySlot: new Map([[0, mesh(device)]]),
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
+
         activeEntityKeys: new Set(),
         activeEntityRevision: 1,
       })
       .unwrap();
-    expect(prepared).toBeDefined();
-    expect(production.requiresSceneRows()).toBe(true);
+    expect(prepared).toBeUndefined();
     expect(production.inspect()).toMatchObject({
-      batchCount: 1,
+      batchCount: 0,
       indirectDrawCount: 0,
       batchBindGroupCreates: 0,
     });
-    if (prepared === undefined) return;
-    prepared.project(new RenderGraphBuilder<RenderPipelineFrame>(), 'rgba8unorm', 1).unwrap();
     expect(production.inspect()).toMatchObject({
-      batchCount: 1,
+      batchCount: 0,
       indirectDrawCount: 0,
       batchBindGroupCreates: 0,
     });
@@ -379,13 +462,11 @@ describe('GPU-driven production projection', () => {
         entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
       })
       .unwrap();
+    const pbrInputs = standardPbrInputs(device, shader, viewLayout);
     const projection = new RenderScene();
-    const first = snapshot(1, 3);
-    const second = { ...snapshot(2, 3), worldId: 1 };
-    const delta = projection.apply([
-      { kind: 'create', snapshot: first },
-      { kind: 'create', snapshot: second },
-    ]);
+    const first = preparedPbrFixture(snapshot(1, 3));
+    const second = { ...preparedPbrFixture(snapshot(2, 3)), worldId: 1 };
+    const delta = projection.apply([updateSnapshot(first), updateSnapshot(second)]);
     const availability = GpuScene.create(device, 2).unwrap();
     expect(availability.status).toBe('available');
     if (availability.status !== 'available') return;
@@ -397,16 +478,19 @@ describe('GPU-driven production projection', () => {
     });
     const prepared = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes: new Map([[3, mesh(device)]]),
+        meshBySlot: new Map([
+          [0, mesh(device)],
+          [1, mesh(device)],
+        ]),
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(prepared).toBeDefined();
@@ -415,7 +499,7 @@ describe('GPU-driven production projection', () => {
     availability.scene.dispose();
   });
 
-  it('uses renderer-local World keys for CPU validation telemetry', async () => {
+  it('uses concrete draw keys for CPU validation telemetry', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
     const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
@@ -428,24 +512,24 @@ describe('GPU-driven production projection', () => {
       lods: [{ mesh: '00000000-0000-7000-8000-000000000001' as never, screenCoverage: 0.5 }],
     };
     const plainFallbackRow = { ...snapshot(2, 3), worldId: 0 };
-    const gpuOwned = new Set([worldEntityKey(101, gpuLodRow.entityKey)]);
-    const worldKeys = [202, 101];
+    const gpuOwned = new Set([
+      gpuDrivenDrawKey(worldEntityKey(gpuLodRow.worldId, gpuLodRow.entityKey), -1, 0),
+    ]);
 
     // A GPU-owned row is removed from validation before this telemetry hook;
     // the remaining plain row must still be counted as the one CPU fallback.
-    production.recordCpuValidation([{ source: plainFallbackRow }], gpuOwned, worldKeys);
+    production.recordCpuValidation([{ source: plainFallbackRow }], gpuOwned);
     expect(production.inspect()).toMatchObject({
       cpuFallbackDrawItems: 1,
       validatedGpuOwnedRows: 0,
     });
 
-    // Prove the same renderer-local namespace recognizes the GPU row when a
-    // diagnostic caller supplies it directly, even though its extracted
-    // RenderableSnapshot still carries the reordered array index.
-    production.recordCpuValidation([{ source: gpuLodRow }], gpuOwned, worldKeys);
+    // A GPU-only row contributes ownership telemetry without inflating the
+    // CPU residual row count.
+    production.recordCpuValidation([{ source: gpuLodRow }], gpuOwned);
     expect(production.inspect()).toMatchObject({
-      cpuFallbackDrawItems: 1,
-      validatedGpuOwnedRows: 1,
+      cpuFallbackDrawItems: 0,
+      validatedGpuOwnedRows: 0,
     });
     production.dispose();
   });
@@ -459,10 +543,11 @@ describe('GPU-driven production projection', () => {
         entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
       })
       .unwrap();
+    const pbrInputs = standardPbrInputs(device, shader, viewLayout);
     const projection = new RenderScene();
     const lodMeshGuid = '00000000-0000-7000-8000-000000000001' as never;
     const makeLodSnapshot = (entityKey: number): RenderableSnapshot => {
-      const base = snapshot(entityKey, 3);
+      const base = preparedPbrFixture(snapshot(entityKey, 3));
       const draw = base.gpuDrivenDraws?.[0];
       if (draw === undefined) throw new Error('LOD test snapshot has no draw');
       return {
@@ -472,8 +557,8 @@ describe('GPU-driven production projection', () => {
       };
     };
     const delta = projection.apply([
-      { kind: 'create', snapshot: makeLodSnapshot(1) },
-      { kind: 'create', snapshot: makeLodSnapshot(2) },
+      updateSnapshot(makeLodSnapshot(1)),
+      updateSnapshot(makeLodSnapshot(2)),
     ]);
     const availability = GpuScene.create(device, 2).unwrap();
     expect(availability.status).toBe('available');
@@ -484,18 +569,22 @@ describe('GPU-driven production projection', () => {
     const production = new GpuDrivenProduction(device, {
       createShaderModule: () => ok(shader),
     });
+    const lodGpuMesh = mesh(device, true, true);
     const prepared = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: { ...makeZeroCameraFallbackSnapshot(), position: vec3.create(0, 0, 5) },
-        meshes: new Map([[3, mesh(device, true, true)]]),
+        meshBySlot: new Map([
+          [0, lodGpuMesh],
+          [1, lodGpuMesh],
+        ]),
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(prepared).toBeDefined();
@@ -582,6 +671,7 @@ describe('GPU-driven production projection', () => {
         entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
       })
       .unwrap();
+    const pbrInputs = standardPbrInputs(device, shader, viewLayout);
     const viewUniform = device
       .createBuffer({ size: 784, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST })
       .unwrap();
@@ -591,11 +681,11 @@ describe('GPU-driven production projection', () => {
         entries: [{ binding: 0, resource: { kind: 'buffer', value: { buffer: viewUniform } } }],
       })
       .unwrap();
-    const first = snapshot(1, 3);
+    const first = preparedPbrFixture(snapshot(1, 3));
     const firstDraw = first.gpuDrivenDraws?.[0];
     expect(firstDraw).toBeDefined();
     if (firstDraw === undefined) return;
-    const second = { ...snapshot(2, 4), worldId: 1 };
+    const second = { ...preparedPbrFixture(snapshot(2, 4)), worldId: 1 };
     const secondDraw = second.gpuDrivenDraws?.[0];
     expect(secondDraw).toBeDefined();
     if (secondDraw === undefined) return;
@@ -621,9 +711,7 @@ describe('GPU-driven production projection', () => {
       },
     ];
     const projection = new RenderScene();
-    const delta = projection.apply(
-      renderables.map((renderable) => ({ kind: 'create' as const, snapshot: renderable })),
-    );
+    const delta = projection.apply(renderables.map((renderable) => updateSnapshot(renderable)));
     const availability = GpuScene.create(device, 2).unwrap();
     expect(availability.status).toBe('available');
     if (availability.status !== 'available') return;
@@ -632,53 +720,59 @@ describe('GPU-driven production projection', () => {
     topology.rebuild(projection.slotsSnapshot());
     expect(topology.plan()).toMatchObject({
       candidateCount: 3,
-      visibleCapacity: 129,
-      batches: [{ visibleBase: 0 }, { visibleBase: 64 }, { visibleBase: 128 }],
+      visibleCapacity: 65,
+      batches: [{ visibleBase: 0 }, { visibleBase: 64 }],
     });
     const production = new GpuDrivenProduction(device, {
       createShaderModule: () => ok(shader),
     });
     const meshes = new Map([
-      [3, mesh(device)],
-      [4, mesh(device, false)],
+      [0, mesh(device)],
+      [1, mesh(device, false)],
     ]);
     const prepared = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes,
+        meshBySlot: meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(prepared).toBeDefined();
     if (prepared === undefined) return;
-    expect([...prepared.entityKeys]).toEqual([worldEntityKey(0, 1), worldEntityKey(1, 2)]);
+    expect(prepared.drawKeys).toEqual(
+      new Set([
+        gpuDrivenDrawKey(worldEntityKey(0, 1), -1, 0),
+        gpuDrivenDrawKey(worldEntityKey(0, 1), -1, 1),
+        gpuDrivenDrawKey(worldEntityKey(1, 2), 42, 0),
+      ]),
+    );
     expect(production.inspect()).toMatchObject({
       gpuOwnedSnapshotsMaterialized: 2,
       filteredPlanBuilds: 1,
       candidateUploadBytes: 912,
-      batchUploadBytes: 96,
+      batchUploadBytes: 64,
       viewBindGroupCreates: 1,
     });
 
     const stable = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes,
+        meshBySlot: meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(stable?.topologySignature).toBe(prepared.topologySignature);
@@ -690,40 +784,46 @@ describe('GPU-driven production projection', () => {
       viewConstantsUploadBytes: 112,
       viewBindGroupCreates: 0,
       batchBindGroupCreates: 0,
-      indirectDrawCount: 3,
+      indirectDrawCount: 2,
     });
 
-    // The scene topology is unchanged, but projectedHeight is camera-owned
-    // input to the GPU LOD selector. A moved camera must rebuild the filtered
-    // candidate plan instead of reusing the previous view's heights.
+    // This mixed batch has no LOD relation. Camera movement updates view
+    // constants while retaining the scene topology and candidate uploads.
     const movedCamera = {
       ...makeZeroCameraFallbackSnapshot(),
       position: vec3.create(0, 0, 6),
     };
     const moved = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: movedCamera,
-        meshes,
+        meshBySlot: meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(moved).toBeDefined();
     expect(production.inspect()).toMatchObject({
-      filteredPlanBuilds: 1,
-      candidateUploadBytes: 912,
-      batchUploadBytes: 96,
+      filteredPlanBuilds: 0,
+      candidateUploadBytes: 0,
+      batchUploadBytes: 0,
     });
     if (moved === undefined) return;
 
     const graph = new RenderGraphBuilder<RenderPipelineFrame>();
     const gpu = moved.project(graph, 'rgba8unorm', 1).unwrap();
+    const materialBindGroup = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const frameResources = {
+      ...moved.standardPbrFrameResources,
+      materialBindGroups: [
+        device.createBindGroup({ layout: materialBindGroup, entries: [] }).unwrap(),
+      ],
+    };
     const color = graph
       .createTexture('gpu-driven-production-color', {
         format: 'rgba8unorm',
@@ -742,7 +842,7 @@ describe('GPU-driven production projection', () => {
             clearValue: { r: 0, g: 0, b: 0, a: 1 },
           },
         ],
-        encode: ({ pass, resources }) => gpu.encode(viewBindGroup, pass, resources),
+        encode: ({ pass, resources }) => gpu.encode(viewBindGroup, pass, resources, frameResources),
       })
       .unwrap();
     const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
@@ -751,7 +851,13 @@ describe('GPU-driven production projection', () => {
       dependencies: ['gpu-driven.frustum-compact', 'gpu-driven.finalize-indirect'],
     });
     const encoder = device.createCommandEncoder({ label: 'gpu-driven-production' }).unwrap();
-    compiled.execute({ viewBindGroup, encoder } as unknown as RenderPipelineFrame).unwrap();
+    compiled
+      .execute({
+        viewBindGroup,
+        encoder,
+        gpuDrivenStandardPbrFrameResources: frameResources,
+      } as unknown as RenderPipelineFrame)
+      .unwrap();
     encoder.finish().unwrap();
     expect(device.framePassNames).toEqual([
       'gpu-driven.view-reset',
@@ -760,8 +866,8 @@ describe('GPU-driven production projection', () => {
       'main',
     ]);
     expect(device.totalDispatchCount).toBe(3);
-    expect(device.totalDrawCount).toBe(3);
-    expect(production.inspect().indirectDrawCount).toBe(3);
+    expect(device.totalDrawCount).toBe(2);
+    expect(production.inspect().indirectDrawCount).toBe(2);
     expect(production.inspect().indirectDrawCount).toBeLessThanOrEqual(
       production.inspect().batchCount,
     );
@@ -771,40 +877,42 @@ describe('GPU-driven production projection', () => {
     // plan without making the remaining entity fall back to CPU validation.
     const activeOnly = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: movedCamera,
-        meshes,
+        meshBySlot: meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
+
         activeEntityKeys: new Set([worldEntityKey(0, 1)]),
         activeEntityRevision: 1,
       })
       .unwrap();
-    expect(activeOnly?.entityKeys).toEqual(new Set([1]));
-    expect(activeOnly?.ownsAllRenderables).toBe(true);
+    expect(activeOnly?.drawKeys?.size).toBe(3);
+    expect(activeOnly?.ownsAllDrawItems).toBe(true);
 
     const changedActive = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: availability.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: movedCamera,
-        meshes,
+        meshBySlot: meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
+
         activeEntityKeys: new Set([worldEntityKey(1, 2)]),
         activeEntityRevision: 2,
       })
       .unwrap();
-    expect(changedActive?.entityKeys).toEqual(new Set([worldEntityKey(1, 2)]));
+    expect(changedActive?.drawKeys?.size).toBe(3);
     // Production inspection counters are per-prepare-frame facts. The changed
     // revision must trigger exactly one rebuild for this frame, not accumulate
     // the prior frame's count.
@@ -816,16 +924,16 @@ describe('GPU-driven production projection', () => {
     replacement.scene.sync(delta).unwrap();
     const replacementPrepared = production
       .prepare({
+        ...pbrInputs,
         scene: {
           scene: replacement.scene,
           plan: topology.plan(),
           slots: projection.slotsSnapshot(),
         },
         camera: makeZeroCameraFallbackSnapshot(),
-        meshes,
+        meshBySlot: meshes,
         viewBindGroupLayout: viewLayout,
         meshResidencyEpoch: 1,
-        hdrp: false,
       })
       .unwrap();
     expect(replacementPrepared?.topologySignature).not.toBe(prepared.topologySignature);
@@ -850,9 +958,7 @@ describe('GPU-driven production projection', () => {
       materialShaderId: 'forgeax::default-standard-pbr',
     };
     const projection = new RenderScene();
-    const delta = projection.apply([
-      { kind: 'create', snapshot: { ...base, material, materials: [material] } },
-    ]);
+    const delta = projection.apply([updateSnapshot({ ...base, material, materials: [material] })]);
     const availability = GpuScene.create(device, 1).unwrap();
     expect(availability.status).toBe('available');
     if (availability.status !== 'available') return;
@@ -868,9 +974,8 @@ describe('GPU-driven production projection', () => {
         plan: topology.plan(),
         slots: projection.slotsSnapshot(),
       },
-      meshes: new Map([[3, mesh(device)]]),
+      meshBySlot: new Map([[0, mesh(device)]]),
       viewBindGroupLayout: viewLayout,
-      hdrp: false,
     } as const;
 
     expect(
@@ -882,8 +987,7 @@ describe('GPU-driven production projection', () => {
         })
         .unwrap(),
     ).toBeUndefined();
-    expect(production.requiresSceneRows()).toBe(false);
-    expect(production.inspect().filteredPlanBuilds).toBe(1);
+    expect(production.inspect().filteredPlanBuilds).toBe(0);
     expect(
       production
         .prepare({
@@ -893,7 +997,6 @@ describe('GPU-driven production projection', () => {
         })
         .unwrap(),
     ).toBeUndefined();
-    expect(production.requiresSceneRows()).toBe(false);
     expect(production.inspect()).toMatchObject({
       filteredPlanBuilds: 0,
       gpuOwnedSnapshotsMaterialized: 0,
@@ -904,7 +1007,7 @@ describe('GPU-driven production projection', () => {
     availability.scene.dispose();
   });
 
-  it('activates inside the renderer-owned clustered Standard graph and removes the CPU draw', async () => {
+  it('keeps an ordinary mesh on the common CPU residual while the Standard graph stays active', async () => {
     const canvas = {
       width: 1,
       height: 1,
@@ -954,11 +1057,9 @@ describe('GPU-driven production projection', () => {
     );
     expect(renderer.perFramePassNames).toContain('output-transform');
     // Storage-buffer LDR frames keep the scene linear until the one output
-    // transform writes the encoded surface; the GPU-driven indirect raster
-    // draw and that fullscreen pass are the only draws in this topology.
-    // A plain mesh has no LOD relation, so it stays on the CPU visibility
-    // path for occlusion while GPU-driven raster + output-transform remain
-    // the only draws in this graph.
+    // transform writes the encoded surface. The ordinary unprepared mesh
+    // remains the CPU residual under common visibility projection, while the
+    // clustered Standard graph and output transform stay active.
     expect(device.totalDrawCount).toBe(2);
     expect(renderer.inspect().lodOcclusion).toMatchObject({
       fallback: { active: false },
@@ -979,7 +1080,7 @@ describe('GPU-driven production projection', () => {
         batchBindGroupCreates: 0,
         viewBindGroupCreates: 0,
         validatedGpuOwnedRows: 0,
-        cpuFallbackDrawItems: 0,
+        cpuFallbackDrawItems: 1,
       },
     });
     renderer.dispose();
@@ -1030,7 +1131,7 @@ describe('GPU-driven production projection', () => {
       projectionRecords: 1,
       topology: { batchCount: 1, candidateCount: 1 },
       gpu: { status: 'resident' },
-      gpuDriven: { cpuFallbackDrawItems: 0, validatedGpuOwnedRows: 0 },
+      gpuDriven: { cpuFallbackDrawItems: 1, validatedGpuOwnedRows: 0 },
     });
 
     sceneWorld.set(rendered, Transform, { pos: [1, 0, 0] }).unwrap();
@@ -1047,4 +1148,873 @@ describe('GPU-driven production projection', () => {
     });
     renderer.dispose();
   });
+
+  it('routes mixed ordinary camera and light edits through common visibility projection', async () => {
+    const canvas = {
+      width: 1,
+      height: 1,
+      getContext: () => null,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    } as unknown as HTMLCanvasElement;
+    const renderer = await constructRenderer(
+      canvas,
+      { rhi },
+      { shaderManifestUrl: manifestDataUrl() },
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    const world = new World();
+    expect(renderer.attach(world).ok).toBe(true);
+    const camera = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 5] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: {} },
+      )
+      .unwrap();
+    const lamp = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 1] } },
+        { component: PointLight, data: { intensity: 1, range: 10 } },
+      )
+      .unwrap();
+    const updateVisibility = vi.spyOn(PersistentRenderScene.prototype, 'updateVisibilityFacet');
+    const projectVisibility = vi.spyOn(PersistentRenderScene.prototype, 'projectVisibility');
+    try {
+      world.update(1 / 60).unwrap();
+      expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+      const warmUpdateCalls = updateVisibility.mock.calls.length;
+      const warmProjectCalls = projectVisibility.mock.calls.length;
+      const before = renderer.inspect().renderScene;
+
+      world.set(camera, Transform, { pos: [0, 1, 5] }).unwrap();
+      world.set(lamp, PointLight, { intensity: 3, range: 8 }).unwrap();
+      propagateTransforms(world).unwrap();
+      world.update(1 / 60).unwrap();
+      expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+
+      expect(updateVisibility.mock.calls.length).toBeGreaterThan(warmUpdateCalls);
+      expect(projectVisibility.mock.calls.length).toBeGreaterThan(warmProjectCalls);
+      const after = renderer.inspect().renderScene;
+      expect(after).toMatchObject({
+        fullRebuilds: 1,
+        projectionRecords: before.projectionRecords,
+      });
+      expect(after.topology.revision).toBe(before.topology.revision);
+    } finally {
+      updateVisibility.mockRestore();
+      projectVisibility.mockRestore();
+      renderer.dispose();
+    }
+  });
+
+  it('admits prepared Alpha Mask draws to the GPU shadow lane', () => {
+    const source = preparedSnapshot(10, 3);
+    const alphaMaterial = {
+      ...source.material,
+      paramSnapshot: { alphaCutoff: 0.5 },
+      textureHandles: new Map([['baseColorTexture', 1]]) as never,
+      samplerHandles: new Map([['baseColorTexture', 2]]) as never,
+    } as MaterialSnapshot;
+    const draw = source.gpuDrivenDraws?.[0];
+    expect(draw?.prepared).toBeDefined();
+    if (draw === undefined || draw.prepared === undefined) return;
+
+    // Alpha Mask is a prepared material fact: it keeps the opaque depth
+    // state, carries an authored cutoff, and owns the base-color resource
+    // needed by the shadow fragment discard. Alpha Blend is covered by the
+    // adjacent residual-lane regression and must remain CPU-owned.
+    expect(
+      shadowCasterCpuReason(
+        alphaMaterial,
+        draw,
+        [{ materialShaderId: 'forgeax::default-shadow-caster' } as DispatchEntry],
+        undefined,
+        undefined,
+      ),
+    ).toBeUndefined();
+
+    const projection = new RenderScene();
+    projection.apply([
+      updateSnapshot({ ...source, material: alphaMaterial, materials: [alphaMaterial] }),
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.plan()).toMatchObject({
+      candidateCount: 1,
+      batches: [{ key: { admission: 'alpha-mask' } }],
+    });
+  });
+
+  it('does not admit Alpha Blend or CPU transmission draw plans as GPU-owned', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const viewLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
+      })
+      .unwrap();
+    const materialLayout = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const meshLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'read-only-storage' } }],
+      })
+      .unwrap();
+    const instancesLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 0x1, buffer: { type: 'read-only-storage' } },
+          { binding: 1, visibility: 0x1, buffer: { type: 'read-only-storage' } },
+        ],
+      })
+      .unwrap();
+    const pbrPipelineLayout = device
+      .createPipelineLayout({
+        bindGroupLayouts: [viewLayout, materialLayout, meshLayout, instancesLayout],
+      })
+      .unwrap();
+    const opaque = preparedSnapshot(1, 3);
+    const blendState = {
+      color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+      alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    } as const;
+    const alphaMaterial = {
+      ...opaque.material,
+      renderState: { cullMode: 'none' as const, blend: blendState, depthWriteEnabled: false },
+    } as MaterialSnapshot;
+    const alphaSnapshots = [2, 3].map(
+      (entityKey): RenderableSnapshot => ({
+        ...preparedSnapshot(entityKey, 3),
+        material: alphaMaterial,
+        materials: [alphaMaterial],
+        gpuDrivenDraws: [],
+      }),
+    );
+    const transmissionMaterial = {
+      ...opaque.material,
+      paramSnapshot: { transmission: 0.5 },
+    } as MaterialSnapshot;
+    const transmissionSnapshot: RenderableSnapshot = {
+      ...preparedSnapshot(4, 3),
+      material: transmissionMaterial,
+      materials: [transmissionMaterial],
+    };
+    const sceneProjection = new RenderScene();
+    const delta = sceneProjection.apply([
+      updateSnapshot(opaque),
+      ...alphaSnapshots.map((snapshot) => updateSnapshot(snapshot)),
+      updateSnapshot(transmissionSnapshot),
+    ]);
+    const availability = GpuScene.create(device, 3).unwrap();
+    expect(availability.status).toBe('available');
+    if (availability.status !== 'available') return;
+    availability.scene.sync(delta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(sceneProjection.slotsSnapshot());
+    const production = new GpuDrivenProduction(device, {
+      createShaderModule: () => ok(shader),
+    });
+    const artifact = {
+      material: 'forgeax::default-standard-pbr',
+      pass: 'forward',
+      wgsl: 'synthetic',
+      layoutIdentity: STANDARD_PBR_RECEIPT.reflection.layoutIdentity,
+      bindings: [],
+      deps: [],
+      vertexInputs: STANDARD_PBR_RECEIPT.vertexInputs as unknown as readonly Readonly<
+        Record<string, unknown>
+      >[],
+      receipt: STANDARD_PBR_RECEIPT,
+    };
+    const programKey = standardPbrProgramKey(artifact.material);
+    expect(programKey).toBeDefined();
+    if (programKey === undefined) return;
+    const prepared = production.prepare({
+      scene: {
+        scene: availability.scene,
+        plan: topology.plan(),
+        slots: sceneProjection.slotsSnapshot(),
+      },
+      camera: makeZeroCameraFallbackSnapshot(),
+      meshBySlot: new Map([[0, mesh(device)]]),
+      viewBindGroupLayout: viewLayout,
+      meshResidencyEpoch: 1,
+
+      standardPbrArtifact: artifact,
+      standardPbrPipelineState: {
+        pbrPipelineLayout,
+        meshBindGroupLayout: meshLayout,
+        instancesBindGroupLayout: instancesLayout,
+        gpuDrivenInstancesBindGroupLayout: instancesLayout,
+        gpuDrivenPbrPipelineLayout: pbrPipelineLayout,
+        standardPbrShaderModule: shader,
+        gpuDrivenPbrPrograms: new Map([[programKey, { module: shader, artifact }]]),
+      } as never,
+    });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    expect(prepared.value?.drawKeys).toEqual(new Set(['1:-1:0']));
+    expect(prepared.value?.ownsAllDrawItems).toBe(false);
+    production.dispose();
+    availability.scene.dispose();
+  });
+
+  it('projects concrete ShadowCaster candidates and leaves the CPU residual disjoint', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const viewLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
+      })
+      .unwrap();
+    const materialLayout = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const meshLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'read-only-storage' } }],
+      })
+      .unwrap();
+    const instancesLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 0x1, buffer: { type: 'read-only-storage' } },
+          { binding: 1, visibility: 0x1, buffer: { type: 'read-only-storage' } },
+        ],
+      })
+      .unwrap();
+    const pbrPipelineLayout = device
+      .createPipelineLayout({
+        bindGroupLayouts: [viewLayout, materialLayout, meshLayout, instancesLayout],
+      })
+      .unwrap();
+    const source = preparedSnapshot(1, 3);
+    const firstDraw = source.gpuDrivenDraws?.[0];
+    expect(firstDraw).toBeDefined();
+    if (firstDraw === undefined) return;
+    const firstPrepared = firstDraw.prepared;
+    expect(firstPrepared).toBeDefined();
+    if (firstPrepared === undefined) return;
+    const blendState = {
+      color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+      alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    } as const;
+    const residualMaterial = {
+      ...source.material,
+      materialHandle: 22,
+      transparent: true,
+      renderState: { cullMode: 'none' as const, blend: blendState, depthWriteEnabled: false },
+    } as MaterialSnapshot;
+    const residualDraw = {
+      ...firstDraw,
+      first: 3,
+      materialSlot: 1,
+      materialResourceClass: 'alpha-blend',
+      prepared: { ...firstPrepared, first: 3 },
+    };
+    const mixed = {
+      ...source,
+      materials: [source.material, residualMaterial],
+      gpuDrivenDraws: [firstDraw, residualDraw],
+    } as RenderableSnapshot;
+    const projection = new RenderScene();
+    const delta = projection.apply([updateSnapshot(mixed)]);
+    const availability = GpuScene.create(device, 1).unwrap();
+    expect(availability.status).toBe('available');
+    if (availability.status !== 'available') return;
+    availability.scene.sync(delta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.plan()).toMatchObject({ candidateCount: 1 });
+    const production = new GpuDrivenProduction(device, {
+      createShaderModule: () => ok(shader),
+    });
+    const artifact = {
+      material: 'forgeax::default-standard-pbr',
+      pass: 'forward',
+      wgsl: 'synthetic',
+      layoutIdentity: STANDARD_PBR_RECEIPT.reflection.layoutIdentity,
+      bindings: [],
+      deps: [],
+      vertexInputs: STANDARD_PBR_RECEIPT.vertexInputs as unknown as readonly Readonly<
+        Record<string, unknown>
+      >[],
+      receipt: STANDARD_PBR_RECEIPT,
+    };
+    const programKey = standardPbrProgramKey(artifact.material);
+    expect(programKey).toBeDefined();
+    if (programKey === undefined) return;
+    const entity = worldEntityKey(mixed.worldId, mixed.entityKey);
+    const gpuKey = gpuDrivenShadowDrawKey(entity, -1, 0, 0);
+    const residualKey = gpuDrivenShadowDrawKey(entity, 22, 1, 0);
+    const allShadowKeys = new Set([gpuKey, residualKey]);
+    const prepareFrame = () =>
+      production
+        .prepare({
+          scene: {
+            scene: availability.scene,
+            plan: topology.plan(),
+            slots: projection.slotsSnapshot(),
+          },
+          camera: makeZeroCameraFallbackSnapshot(),
+          meshBySlot: new Map([[0, mesh(device)]]),
+          viewBindGroupLayout: viewLayout,
+          meshResidencyEpoch: 1,
+          standardPbrArtifact: artifact,
+          standardPbrPipelineState: {
+            pbrPipelineLayout,
+            meshBindGroupLayout: meshLayout,
+            instancesBindGroupLayout: instancesLayout,
+            gpuDrivenInstancesBindGroupLayout: instancesLayout,
+            gpuDrivenPbrPipelineLayout: pbrPipelineLayout,
+            standardPbrShaderModule: shader,
+            gpuDrivenPbrPrograms: new Map([[programKey, { module: shader, artifact }]]),
+          } as never,
+          shadowCasterDrawKeys: allShadowKeys,
+        })
+        .unwrap();
+    const prepared = prepareFrame();
+    expect(prepared).toBeDefined();
+    if (prepared === undefined) return;
+    const claimed = new Set(prepared.shadowDrawKeys ?? []);
+    expect([...claimed]).toEqual([gpuKey]);
+    expect(prepared.ownsAllShadowCasters).toBe(false);
+    const residual = [...allShadowKeys].filter((key) => !claimed.has(key));
+    expect(residual).toEqual([residualKey]);
+    expect([...new Set([...claimed, ...residual])].sort()).toEqual([...allShadowKeys].sort());
+    const identity = { kind: 'directional' as const, index: 0 };
+    const updated = prepared.updateShadowViews?.([
+      { identity, planes: new Float32Array(24), cacheToken: 'mixed-candidates' },
+    ]);
+    expect(updated?.ok).toBe(true);
+    expect(production.inspect().channels).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          viewPass: 'directional-shadow',
+          lane: 'blocked',
+          reason: 'shadow-ownership',
+          drawCount: 1,
+          failure: expect.objectContaining({
+            code: 'shadow-ownership',
+            detail: expect.objectContaining({
+              owner: 'shadow',
+              reason: 'shadow-ownership-missing',
+              recovery: 'route-cpu-lane',
+            }),
+          }),
+        }),
+      ]),
+    );
+    const submission = prepared.shadowViewPool?.submission(identity);
+    expect(submission?.plan.candidateCount).toBe(1);
+    const resumed = prepareFrame();
+    expect(
+      resumed?.updateShadowViews?.([
+        { identity, planes: new Float32Array(24), cacheToken: 'mixed-candidates' },
+      ]).ok,
+    ).toBe(true);
+    expect(
+      production.inspect().channels.some((channel) => channel.viewPass === 'directional-shadow'),
+    ).toBe(true);
+    production.dispose();
+    availability.scene.dispose();
+  });
+
+  it('claims exact ShadowCaster passes without swallowing residual or custom passes', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const viewLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
+      })
+      .unwrap();
+    const materialLayout = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const meshLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'read-only-storage' } }],
+      })
+      .unwrap();
+    const instancesLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 0x1, buffer: { type: 'read-only-storage' } },
+          { binding: 1, visibility: 0x1, buffer: { type: 'read-only-storage' } },
+        ],
+      })
+      .unwrap();
+    const pbrPipelineLayout = device
+      .createPipelineLayout({
+        bindGroupLayouts: [viewLayout, materialLayout, meshLayout, instancesLayout],
+      })
+      .unwrap();
+    const source = preparedSnapshot(7, 3);
+    const firstDraw = source.gpuDrivenDraws?.[0];
+    expect(firstDraw?.prepared).toBeDefined();
+    if (firstDraw === undefined || firstDraw.prepared === undefined) return;
+    const materials = [0, 1, 2].map((handle) => ({
+      ...source.material,
+      materialHandle: handle + 10,
+    })) as MaterialSnapshot[];
+    const draws = [
+      { ...firstDraw, drawItemIndex: 0, materialSlot: 0, first: 0, count: 3 },
+      {
+        ...withoutPrepared(firstDraw),
+        drawItemIndex: 1,
+        materialSlot: 1,
+        first: 3,
+        count: 3,
+      },
+      { ...firstDraw, drawItemIndex: 2, materialSlot: 2, first: 6, count: 3 },
+    ];
+    const mixed: RenderableSnapshot = {
+      ...source,
+      material: materials[0] as MaterialSnapshot,
+      materials,
+      gpuDrivenDraws: draws,
+    };
+    const projection = new RenderScene();
+    const delta = projection.apply([updateSnapshot(mixed)]);
+    const availability = GpuScene.create(device, 1).unwrap();
+    expect(availability.status).toBe('available');
+    if (availability.status !== 'available') return;
+    availability.scene.sync(delta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.plan().candidateCount).toBe(3);
+    const entity = worldEntityKey(mixed.worldId, mixed.entityKey);
+    const membership: ShadowCasterMembership[] = [
+      {
+        worldEntity: entity,
+        renderableIndex: 0,
+        drawItemIndex: 0,
+        materialHandle: 10,
+        passIndex: 0,
+        materialShaderId: 'forgeax::default-shadow-caster',
+      },
+      {
+        worldEntity: entity,
+        renderableIndex: 0,
+        drawItemIndex: 1,
+        materialHandle: 11,
+        passIndex: 0,
+        materialShaderId: 'forgeax::default-shadow-caster',
+      },
+      {
+        worldEntity: entity,
+        renderableIndex: 0,
+        drawItemIndex: 2,
+        materialHandle: 12,
+        passIndex: 0,
+        materialShaderId: 'forgeax::default-shadow-caster',
+      },
+      {
+        worldEntity: entity,
+        renderableIndex: 0,
+        drawItemIndex: 2,
+        materialHandle: 12,
+        passIndex: 7,
+        materialShaderId: 'custom-shadow-caster',
+      },
+    ];
+    const allKeys = new Set(
+      membership.map((entry) =>
+        gpuDrivenShadowDrawKey(
+          entry.worldEntity,
+          entry.materialHandle,
+          entry.drawItemIndex,
+          entry.passIndex,
+        ),
+      ),
+    );
+    const production = new GpuDrivenProduction(device, {
+      createShaderModule: () => ok(shader),
+    });
+    const artifact = {
+      material: 'forgeax::default-standard-pbr',
+      pass: 'forward',
+      wgsl: 'synthetic',
+      layoutIdentity: STANDARD_PBR_RECEIPT.reflection.layoutIdentity,
+      bindings: [],
+      deps: [],
+      vertexInputs: STANDARD_PBR_RECEIPT.vertexInputs as unknown as readonly Readonly<
+        Record<string, unknown>
+      >[],
+      receipt: STANDARD_PBR_RECEIPT,
+    };
+    const programKey = standardPbrProgramKey(artifact.material);
+    expect(programKey).toBeDefined();
+    if (programKey === undefined) return;
+    const multiMesh = {
+      ...mesh(device),
+      submeshes: [0, 1, 2].map((materialSlot) => ({
+        indexOffset: materialSlot * 3,
+        indexCount: 3,
+        vertexCount: 3,
+        materialSlot,
+        topology: 'triangle-list' as const,
+      })),
+    };
+    const prepared = production
+      .prepare({
+        scene: {
+          scene: availability.scene,
+          plan: topology.plan(),
+          slots: projection.slotsSnapshot(),
+        },
+        camera: makeZeroCameraFallbackSnapshot(),
+        meshBySlot: new Map([[0, multiMesh]]),
+        viewBindGroupLayout: viewLayout,
+        meshResidencyEpoch: 1,
+
+        standardPbrArtifact: artifact,
+        standardPbrPipelineState: {
+          pbrPipelineLayout,
+          meshBindGroupLayout: meshLayout,
+          instancesBindGroupLayout: instancesLayout,
+          gpuDrivenInstancesBindGroupLayout: instancesLayout,
+          gpuDrivenPbrPipelineLayout: pbrPipelineLayout,
+          standardPbrShaderModule: shader,
+          gpuDrivenPbrPrograms: new Map([[programKey, { module: shader, artifact }]]),
+        } as never,
+        shadowCasterDrawKeys: allKeys,
+        shadowCasterMembership: membership,
+      })
+      .unwrap();
+    expect(prepared).toBeDefined();
+    if (prepared === undefined) return;
+    const gpuKey = gpuDrivenShadowDrawKey(entity, 10, 0, 0);
+    expect([...(prepared.shadowDrawKeys ?? [])]).toEqual([gpuKey]);
+    expect(prepared.ownsAllShadowCasters).toBe(false);
+    const residual = [...allKeys].filter((key) => !prepared.shadowDrawKeys?.has(key));
+    expect(residual).toHaveLength(3);
+    expect(new Set([...(prepared.shadowDrawKeys ?? []), ...residual])).toEqual(allKeys);
+    const identity = { kind: 'directional' as const, index: 0 };
+    expect(
+      prepared.updateShadowViews?.([
+        { identity, planes: new Float32Array(24), cacheToken: 'exact-shadow-membership' },
+      ]).ok,
+    ).toBe(true);
+    expect(prepared.shadowViewPool?.submission(identity)?.plan.candidateCount).toBe(1);
+    expect(prepared.shadowDrawKeysByView?.get('directional:0:')).toEqual(new Set([gpuKey]));
+    production.dispose();
+    availability.scene.dispose();
+  });
+
+  it.each([false, true])('prepares off-camera CPU shadow materials (main rows=%s)', (withMain) => {
+    const material = { ...preparedSnapshot(1, 3).material, materialHandle: 42 };
+    const shadow = {
+      source: { ...preparedSnapshot(1, 3), material, materials: [material] },
+      renderableIndex: 0,
+    } as never;
+    const main = { source: preparedSnapshot(2, 3), renderableIndex: 0 } as never;
+    const plan = buildDispatchPlan({} as never, withMain ? [main] : [], [], [], [shadow]);
+    expect(plan.shadowValidatedOrdered).toEqual([shadow]);
+    const slot = plan.materialSlots.indexOf(material);
+    expect(slot).toBeGreaterThanOrEqual(0);
+    expect(plan.materialSlotOwners[slot]).toBe(shadow);
+    const dispatch = {
+      renderableIndex: 0,
+      materialHandle: 42,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      tags: { LightMode: 'ShadowCaster' },
+    };
+    const map = shadowShaderMap({ ...plan, shadowDispatch: [dispatch] } as never);
+    expect(map.get(0)?.get(42)?.[0]?.materialSlot).toBe(slot);
+  });
+
+  it.each([
+    false,
+    true,
+  ])('records exact CPU residuals with authored state (skinned=%s)', async (skinned) => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
+    const source = preparedSnapshot(8, 3);
+    const firstDraw = source.gpuDrivenDraws?.[0];
+    expect(firstDraw?.prepared).toBeDefined();
+    if (firstDraw === undefined || firstDraw.prepared === undefined) return;
+    const materials = [0, 1, 2].map((handle) => ({
+      ...source.material,
+      materialHandle: handle + 20,
+    })) as MaterialSnapshot[];
+    const draws = [
+      { ...firstDraw, drawItemIndex: 0, materialSlot: 0, first: 0, count: 3 },
+      { ...firstDraw, drawItemIndex: 1, materialSlot: 1, first: 3, count: 3 },
+      { ...firstDraw, drawItemIndex: 2, materialSlot: 2, first: 6, count: 3 },
+    ];
+    const sourceForRecord: RenderableSnapshot = {
+      ...source,
+      ...(skinned ? { skin: { buffer: {} as never, byteOffset: 0 } as never } : {}),
+      material: materials[0] as MaterialSnapshot,
+      materials,
+      gpuDrivenDraws: draws,
+    };
+    const geometry = {
+      ...mesh(device),
+      submeshes: [0, 1, 2].map((materialSlot) => ({
+        indexOffset: materialSlot * 3,
+        indexCount: 3,
+        vertexCount: 3,
+        materialSlot,
+        topology: 'triangle-list' as const,
+      })),
+    };
+    const identityInstanceBuffer = device
+      .createBuffer({ size: 64, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST })
+      .unwrap();
+    const instancesBindGroupLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 0x1, buffer: { type: 'uniform' } },
+          { binding: 1, visibility: 0x1, buffer: { type: 'uniform' } },
+        ],
+      })
+      .unwrap();
+    const worldEntity = worldEntityKey(sourceForRecord.worldId, sourceForRecord.entityKey);
+    const claimedKey = gpuDrivenShadowDrawKey(worldEntity, 20, 0, 0);
+    const residualKeys = new Set([
+      gpuDrivenShadowDrawKey(worldEntity, 21, 1, 0),
+      gpuDrivenShadowDrawKey(worldEntity, 22, 2, 0),
+      gpuDrivenShadowDrawKey(worldEntity, 22, 2, 7),
+    ]);
+    const shadowDispatches = new Map([
+      [
+        0,
+        new Map([
+          [
+            20,
+            [
+              {
+                passIndex: 0,
+                materialHandle: 20,
+                vertexEntry: undefined,
+                fragmentEntry: undefined,
+                materialShaderId: 'forgeax::default-shadow-caster',
+                renderState: undefined,
+                materialSlot: 0,
+                paramSnapshot: materials[0]?.paramSnapshot,
+              },
+            ],
+          ],
+          [
+            21,
+            [
+              {
+                passIndex: 0,
+                materialHandle: 21,
+                vertexEntry: undefined,
+                fragmentEntry: undefined,
+                materialShaderId: 'forgeax::default-shadow-caster',
+                renderState: undefined,
+                materialSlot: 1,
+                paramSnapshot: materials[1]?.paramSnapshot,
+              },
+            ],
+          ],
+          [
+            22,
+            [
+              {
+                passIndex: 0,
+                materialHandle: 22,
+                vertexEntry: undefined,
+                fragmentEntry: undefined,
+                materialShaderId: 'forgeax::default-shadow-caster',
+                renderState: undefined,
+                materialSlot: 2,
+                paramSnapshot: materials[2]?.paramSnapshot,
+              },
+              {
+                passIndex: 7,
+                materialHandle: 22,
+                vertexEntry: undefined,
+                fragmentEntry: undefined,
+                materialShaderId: 'custom-shadow-caster',
+                renderState: { cullMode: 'none' as const, frontFace: 'cw' as const },
+                materialSlot: 2,
+                paramSnapshot: materials[2]?.paramSnapshot,
+              },
+            ],
+          ],
+        ]),
+      ],
+    ]);
+    const indexedDraws: number[][] = [];
+    const pipelineRequests: unknown[][] = [];
+    const pass = {
+      setPipeline: () => undefined,
+      setVertexBuffer: () => undefined,
+      setIndexBuffer: () => undefined,
+      setBindGroup: () => undefined,
+      drawIndexed: (...args: number[]) => indexedDraws.push(args),
+      draw: () => undefined,
+    } as unknown as RhiRenderPassEncoder;
+    const context = {
+      runtime: {
+        device,
+        getMaterialShaderPipeline: (...args: unknown[]) => {
+          pipelineRequests.push(args);
+          return {} as never;
+        },
+      },
+      pipelineState: {
+        identityInstanceBuffer,
+        pbrSkinMeshBindGroupLayout: {} as never,
+        skinPaletteAllocator: { bindingWindowBytes: 256 },
+        instancesBindGroupLayout,
+        materialBindGroupLayout: {} as never,
+        materialUniformBuffer: { buffer: {} as never, sizeInBytes: 256 },
+        meshStorageBuffer: { buffer: {} as never, sizeInBytes: 256 },
+        defaultSampler: {} as never,
+        fallbackTextureView: {} as never,
+        defaultNormalTextureView: {} as never,
+        defaultWhiteTextureView: {} as never,
+        skylightFallback: {
+          irradianceView: {} as never,
+          prefilterView: {} as never,
+          brdfLutView: {} as never,
+          sampler: {} as never,
+          intensityBuffer: {} as never,
+        },
+      },
+      validatedOrdered: [
+        {
+          source: sourceForRecord,
+          mesh: geometry,
+          renderableIndex: 0,
+        },
+      ],
+      frameState: {
+        instanceBuffers: new Map(),
+        meshBindGroupCache: new Map(),
+        instancesBgPerEntity: new Map(),
+        shadowMaterialBindGroups: new WeakMap(),
+        materialBgShared: new Map(),
+      },
+      materialBgAssemblyCache: new Map(),
+      store: { materialResourceEpoch: 0 } as never,
+      world: new World(),
+      bindGroupCounts: { createBindGroup: 0, keys: [] },
+      dispatch: [],
+    } as never;
+    const recorded = recordShadowCasterDraws(
+      context,
+      pass,
+      {} as never,
+      {} as never,
+      new Set([0]),
+      new Map([[0, new Set([20, 21, 22])]]),
+      shadowDispatches,
+      new Set([claimedKey]),
+    );
+    expect(indexedDraws).toHaveLength(3);
+    expect(recorded).toEqual(residualKeys);
+    expect(recorded.has(claimedKey)).toBe(false);
+    const authored = pipelineRequests.find((args) => args[0] === 'custom-shadow-caster');
+    expect(authored).toBeDefined();
+    expect(authored?.[2]).toEqual({ cullMode: 'none', frontFace: 'cw' });
+    expect(authored?.[15]).toBe(skinned ? 'pbr-skin' : 'pbr');
+    if (skinned) expect(authored?.[5]).toContain('SKINNING_DISABLED=false');
+  });
+
+  it('fails closed at every shadow front door when expected casters lack bind groups', () => {
+    const membership: ShadowCasterMembership[] = [
+      {
+        worldEntity: 1,
+        renderableIndex: 0,
+        drawItemIndex: 0,
+        materialHandle: 20,
+        passIndex: 0,
+        materialShaderId: 'forgeax::default-shadow-caster',
+        cpuReason: 'unprepared',
+      },
+    ];
+    const context = {
+      runtime: {
+        device: { caps: { storageBuffer: false } },
+        getMaterialShaderPipeline: () => null,
+      },
+      pipelineState: { perPassResources: { shadowSampler: null } },
+      frameState: {
+        pointShadowSnapshots: [{ shadowAtlasLayer: 0 }],
+        spotShadowSnapshots: [{ shadowAtlasTile: 0, lightViewProj: new Float32Array(16) }],
+      },
+      dispatch: [],
+      shadowCasterMembership: membership,
+    } as never;
+    const pass = {} as RhiRenderPassEncoder;
+    const calls = [
+      () =>
+        encodeDirectionalShadowPass(context, pass, 0, {
+          x: 0,
+          y: 0,
+          w: 1,
+          h: 1,
+        }),
+      () => encodePointShadowPass(context, pass, 0, 0),
+      () => encodeSpotShadowPass(context, pass, 0),
+    ];
+    for (const call of calls) {
+      expect(call).toThrowError(RhiError);
+      try {
+        call();
+      } catch (error) {
+        expect(error).toBeInstanceOf(RhiError);
+        expect((error as RhiError).code).toBe('rhi-not-available');
+      }
+    }
+  });
+
+  it('labels a prepared-contract admission rejection for the CPU residual', () => {
+    const source = preparedSnapshot(9, 3);
+    const draw = source.gpuDrivenDraws?.[0];
+    expect(draw?.prepared).toBeDefined();
+    if (draw === undefined || draw.prepared === undefined) return;
+    const mismatched = {
+      ...draw,
+      prepared: {
+        ...draw.prepared,
+        identity: {
+          ...draw.prepared.identity,
+          material: 'forgeax::pbr-skin' as const,
+          deformation: 'skin' as const,
+        },
+      },
+    };
+    const material = {
+      ...source.material,
+      materialShaderId: 'forgeax::default-standard-pbr',
+    } as MaterialSnapshot;
+    expect(
+      shadowCasterCpuReason(
+        material,
+        mismatched,
+        [
+          {
+            entityIndex: source.entityKey,
+            materialHandle: material.materialHandle ?? -1,
+            renderableIndex: 0,
+            passIndex: 0,
+            queue: 2000,
+            layer: 0,
+            tags: { LightMode: 'ShadowCaster' },
+            renderState: undefined,
+            defines: undefined,
+            vertexEntry: undefined,
+            fragmentEntry: undefined,
+            materialShaderId: 'forgeax::default-shadow-caster',
+            paramSnapshot: undefined,
+          } as DispatchEntry,
+        ],
+        undefined,
+        undefined,
+      ),
+    ).toBe('prepared-contract');
+  });
 });