@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/shader-manifest-fixture.ts

@@ -12,10 +12,12 @@ type FixtureEntry = {
 
 const pbrWgsl = '// fixture marker: f_schlick\n';
 const unlitWgsl = '// fixture marker: default-unlit\n';
+const shadowCasterWgsl = '// fixture marker: shadow-caster\n';
 
 const entries: readonly FixtureEntry[] = [
   { hash: 'fixture-pbr', wgsl: pbrWgsl, glsl: '', bindings: '[]' },
   { hash: 'fixture-unlit', wgsl: unlitWgsl, glsl: '', bindings: '[]' },
+  { hash: 'fixture-shadow-caster', wgsl: shadowCasterWgsl, glsl: '', bindings: '[]' },
   {
     hash: 'fixture-tonemap',
     wgsl: '// fixture marker: TonemapParams\n',
@@ -77,6 +79,36 @@ const standardPbrVariants = (() => {
   return variants;
 })();
 
+const shadowCasterVariants = (() => {
+  const variants = [];
+  for (const storage of [false, true]) {
+    for (const skinningDisabled of [false, true]) {
+      for (const gpuDriven of [false, true]) {
+        for (const explicit of [false, true]) {
+          for (const alphaMask of [false, true]) {
+            if (!storage && gpuDriven) continue;
+            const defines: Record<string, boolean> = {
+              ALPHA_MASK: alphaMask,
+              GPU_DRIVEN_SCENE_INDEX_AVAILABLE: gpuDriven,
+              GPU_DRIVEN_SCENE_INDEX_EXPLICIT: explicit,
+              SKINNING_DISABLED: skinningDisabled,
+              STORAGE_BUFFER_AVAILABLE: storage,
+            };
+            const sortedDefines = Object.entries(defines).sort(([left], [right]) =>
+              left < right ? -1 : left > right ? 1 : 0,
+            );
+            const definesKey = sortedDefines.every(([, value]) => value)
+              ? ''
+              : sortedDefines.map(([key, value]) => `${key}=${value}`).join('+');
+            variants.push({ definesKey, defines, composedWgsl: shadowCasterWgsl });
+          }
+        }
+      }
+    }
+  }
+  return variants;
+})();
+
 const materialShaders = [
   {
     identifier: 'forgeax::default-standard-pbr',
@@ -94,6 +126,13 @@ const materialShaders = [
     variants: [],
     uvSetCount: 1,
   },
+  {
+    identifier: 'forgeax::default-shadow-caster',
+    sourcePath: 'fixture://forgeax/default-shadow-caster.wgsl',
+    composedWgsl: shadowCasterWgsl,
+    paramSchema: JSON.stringify([]),
+    variants: shadowCasterVariants,
+  },
 ] as const;
 
 /**

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

@@ -45,39 +45,6 @@ describe('custom skinned mesh motion consumer contract', () => {
     expect(writes[1]?.data[12]).toBe(0.5);
   });
 
-  it('keeps stable uniform palette slices isolated across frame-pool resets', () => {
-    const device = {
-      limits: { maxUniformBufferBindingSize: 65536 },
-      createBuffer: () => ok({} as Buffer),
-      destroyBuffer: () => undefined,
-      queue: { writeBuffer: () => ok(undefined) },
-    } as unknown as RhiDevice;
-    const allocator = createSkinPaletteAllocator(device, 65536, false);
-    const first = allocator.allocateSliceFor('world:1', 1);
-    allocator.resetForFrame();
-    const second = allocator.allocateSliceFor('world:2', 1);
-
-    expect(second.buffer).not.toBe(first.buffer);
-  });
-
-  it('does not reuse a split storage range beyond its binding window', () => {
-    let bufferId = 0;
-    const device = {
-      limits: { maxStorageBufferBindingSize: 65536 },
-      createBuffer: () => ok({ id: bufferId++ } as unknown as Buffer),
-      queue: { writeBuffer: () => ok(undefined) },
-    } as unknown as RhiDevice;
-    const allocator = createSkinPaletteAllocator(device, 65536, true);
-
-    const full = allocator.allocateSliceFor('world:full', 255);
-    allocator.releaseSliceFor('world:full');
-    const firstSmall = allocator.allocateSliceFor('world:first', 1);
-    const secondSmall = allocator.allocateSliceFor('world:second', 1);
-
-    expect(firstSmall.buffer).toBe(full.buffer);
-    expect(secondSmall.buffer).not.toBe(full.buffer);
-  });
-
   it('prepares both URP and HDRP pbr-skin consumers with the skin-cluster contract', () => {
     const variants = selectSkinPrewarmVariants(
       {

package/src/__tests__/skin-palette-persistent.integration.test.ts

@@ -0,0 +1,28 @@
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { createSkinPaletteOwner } from '../assembly/skin-palette-owner';
+
+describe('skin palette receipt integration', () => {
+  it('shares identity, generation and bounds between storage and uniform receipts', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const bounds = new Float32Array([-1, -1, -1, 1, 1, 1]);
+    const storage = createSkinPaletteOwner(device, true).allocatePersistentSlice({
+      identity: 'shared',
+      generation: 11,
+      jointCount: 2,
+      bounds,
+    });
+    const uniform = createSkinPaletteOwner(device, false).allocatePersistentSlice({
+      identity: 'shared',
+      generation: 11,
+      jointCount: 2,
+      bounds,
+    });
+    expect(storage.identity).toBe(uniform.identity);
+    expect(storage.generation).toBe(uniform.generation);
+    expect(storage.bounds).toEqual(uniform.bounds);
+    expect(storage.customDataStart).toBe(storage.byteOffset);
+    expect(uniform.customDataStart).toBe(uniform.byteOffset);
+  });
+});

package/src/__tests__/skin-palette-persistent.unit.test.ts

@@ -0,0 +1,247 @@
+import { mat4 } from '@forgeax/engine-math';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { createSkinPaletteOwner } from '../assembly/skin-palette-owner';
+
+const bounds = new Float32Array([-1, -2, -3, 1, 2, 3]);
+
+describe('persistent skin palette owner', () => {
+  it('advances content revision only after a GPU palette write', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const receipt = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 1,
+    });
+    const initial = allocator.contentRevision;
+    allocator.writePersistentJointPalette(receipt, [mat4.create()], [mat4.create()]);
+    expect(allocator.contentRevision).toBe(initial + 1);
+    allocator.beginFrame();
+    const stable = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 1,
+    });
+    allocator.writePersistentJointPalette(stable, [mat4.create()], [mat4.create()]);
+    expect(allocator.contentRevision).toBe(initial + 1);
+    allocator.dispose();
+  });
+
+  it('keeps a stable range for an unchanged skeleton and reports zero upload', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const first = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 7,
+      jointCount: 2,
+      bounds,
+    });
+    allocator.beginFrame();
+    const stable = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 7,
+      jointCount: 2,
+      bounds,
+    });
+    expect(stable.byteOffset).toBe(first.byteOffset);
+    expect(stable.generation).toBe(7);
+    expect(stable.uploadBytes).toBe(0);
+    expect(stable.bounds).toEqual(bounds);
+  });
+
+  it('merges dirty joints into aligned ranges and retires stale generations', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const first = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 8,
+      bounds,
+    });
+    allocator.markDirtyJoints('hero', [1, 2, 5]);
+    allocator.beginFrame();
+    const changed = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 2,
+      jointCount: 8,
+      bounds,
+    });
+    expect(changed.byteOffset).not.toBe(first.byteOffset);
+    expect(changed.retiredByteOffset).toBe(first.byteOffset);
+    // A replacement generation owns a fresh address. It must upload every
+    // joint even when the producer pose is unchanged; carrying only the old
+    // dirty set would publish an uninitialized palette slice.
+    expect(changed.dirtyRanges).toEqual([{ startJoint: 0, jointCount: 8 }]);
+    expect(changed.uploadBytes).toBe(8 * 16 * 4);
+  });
+
+  it('observes a changed pose and uploads only its merged dirty joint range', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const ibms = [
+      mat4.identity(mat4.create()),
+      mat4.identity(mat4.create()),
+      mat4.identity(mat4.create()),
+    ];
+    const pose = ibms.map(() => mat4.identity(mat4.create()));
+
+    allocator.observePersistentJoints('hero', ibms, pose);
+    allocator.allocatePersistentSlice({ identity: 'hero', generation: 1, jointCount: 3, bounds });
+    allocator.beginFrame();
+    allocator.observePersistentJoints('hero', ibms, pose);
+    const stable = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 3,
+      bounds,
+    });
+    expect(stable.dirtyRanges).toEqual([]);
+    expect(stable.uploadBytes).toBe(0);
+
+    const changedPose = pose.map((matrix) => mat4.clone(matrix));
+    changedPose[1]?.set([1, 0, 0, 0.25], 12);
+    changedPose[2]?.set([1, 0, 0, 0.5], 12);
+    allocator.observePersistentJoints('hero', ibms, changedPose);
+    const changed = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 3,
+      bounds,
+    });
+    expect(changed.dirtyRanges).toEqual([{ startJoint: 1, jointCount: 2 }]);
+    expect(changed.uploadBytes).toBe(2 * 16 * 4);
+  });
+
+  it('uploads an unchanged pose when a skeleton generation is replaced', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 2,
+      bounds,
+    });
+    allocator.beginFrame();
+    const replacement = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 2,
+      jointCount: 2,
+      bounds,
+    });
+    expect(replacement.dirtyRanges).toEqual([{ startJoint: 0, jointCount: 2 }]);
+    expect(replacement.uploadBytes).toBe(2 * 16 * 4);
+  });
+
+  it('recycles a retired storage range only after the queue fence', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const first = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 2,
+    });
+    allocator.beginFrame();
+    const replacement = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 2,
+      jointCount: 2,
+    });
+    expect(replacement.byteOffset).not.toBe(first.byteOffset);
+    allocator.beginFrame();
+    const beforeFence = allocator.allocatePersistentSlice({
+      identity: 'other',
+      generation: 1,
+      jointCount: 2,
+    });
+    expect(beforeFence.byteOffset).not.toBe(first.byteOffset);
+    await device.queue.onSubmittedWorkDone();
+    allocator.beginFrame();
+    const afterFence = allocator.allocatePersistentSlice({
+      identity: 'third',
+      generation: 1,
+      jointCount: 2,
+    });
+    expect(afterFence.byteOffset).toBe(first.byteOffset);
+  });
+
+  it('releases a detached identity and makes its range recyclable', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const first = allocator.allocatePersistentSlice({
+      identity: 'detached',
+      generation: 1,
+      jointCount: 2,
+    });
+    allocator.releasePersistentSlice('detached');
+    await device.queue.onSubmittedWorkDone();
+    allocator.beginFrame();
+    const replacement = allocator.allocatePersistentSlice({
+      identity: 'replacement',
+      generation: 1,
+      jointCount: 2,
+    });
+    expect(replacement.byteOffset).toBe(first.byteOffset);
+    allocator.dispose();
+    allocator.dispose();
+  });
+
+  it('uses the same receipt shape for uniform projection', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, false);
+    const receipt = allocator.allocatePersistentSlice({
+      identity: 'npc',
+      generation: 3,
+      jointCount: 1,
+      bounds,
+    });
+    expect(receipt.byteOffset).toBe(0);
+    expect(receipt.buffer).toBeDefined();
+    expect(receipt.storageOrUniform).toBe('uniform');
+    expect(receipt.customDataStart).toBe(0);
+  });
+
+  it('rebases earlier same-frame receipts when the storage arena grows', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const first = allocator.allocatePersistentSlice({
+      identity: 'first',
+      generation: 1,
+      jointCount: 2,
+    });
+    const firstBufferBeforeGrow = first.buffer;
+    const second = allocator.allocatePersistentSlice({
+      identity: 'second',
+      generation: 1,
+      jointCount: 255,
+    });
+    expect(second.buffer).not.toBe(firstBufferBeforeGrow);
+    expect(first.buffer).toBe(second.buffer);
+    expect(first.byteOffset).toBe(0);
+    expect(second.byteOffset).toBe(256);
+  });
+
+  it('retains the producer bounds instead of inventing an expanded AABB', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const receipt = allocator.allocatePersistentSlice({
+      identity: 'hero',
+      generation: 1,
+      jointCount: 1,
+      bounds,
+    });
+    expect(Array.from(receipt.bounds ?? [])).toEqual(Array.from(bounds));
+    const identity = mat4.identity(mat4.create());
+    expect(identity[0]).toBe(1);
+  });
+});

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

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
-import { resolveMaterialShaderVariantSet } from '../assembly/factory';
+import { resolveMaterialShaderVariantSet } from '../assembly/material-shader-policy';
 import {
   createPbrSkinMeshBindGroupEntries,
   isSkinnedShadowCasterVariant,
@@ -13,24 +13,26 @@ import { shadowShaderMap } from '../record/shadow-pass.js';
 
 describe('skinned shadow caster', () => {
   it('derives closed capability variants without changing the shader identity', () => {
-    expect(shadowCasterVariantSet(true, false)).toBe('');
+    expect(shadowCasterVariantSet(true, false)).toBe(
+      'ALPHA_MASK=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=false+GPU_DRIVEN_SCENE_INDEX_EXPLICIT=false+SKINNING_DISABLED=true+STORAGE_BUFFER_AVAILABLE=true',
+    );
     expect(shadowCasterVariantSet(false, true)).toBe(
-      'SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false',
+      'ALPHA_MASK=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=false+GPU_DRIVEN_SCENE_INDEX_EXPLICIT=false+SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false',
     );
     expect(shadowCasterVariantSet(true, true)).toBe(
-      'SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=true',
+      'ALPHA_MASK=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=false+GPU_DRIVEN_SCENE_INDEX_EXPLICIT=false+SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=true',
     );
     expect(isSkinnedShadowCasterVariant(SHADOW_CASTER_SHADER_ID, '')).toBe(false);
     expect(
       isSkinnedShadowCasterVariant(
         SHADOW_CASTER_SHADER_ID,
-        'SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false',
+        'ALPHA_MASK=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=false+GPU_DRIVEN_SCENE_INDEX_EXPLICIT=false+SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false',
       ),
     ).toBe(true);
     expect(
       isSkinnedShadowCasterVariant(
         SHADOW_CASTER_SHADER_ID,
-        'SKINNING_DISABLED=true+STORAGE_BUFFER_AVAILABLE=false',
+        'ALPHA_MASK=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=false+GPU_DRIVEN_SCENE_INDEX_EXPLICIT=false+SKINNING_DISABLED=true+STORAGE_BUFFER_AVAILABLE=false',
       ),
     ).toBe(false);
   });
@@ -49,6 +51,12 @@ describe('skinned shadow caster', () => {
       'utf8',
     );
     expect(shader).toContain('#pragma variant_axis SKINNING_DISABLED');
+    expect(shader).toContain('#pragma variant_axis ALPHA_MASK');
+    expect(shader).toContain('#pragma material_slot surface');
+    expect(shader).toContain('#import forgeax_material::parameters::{material}');
+    expect(shader).toContain('@group(1) @binding(46)');
+    expect(shader).toContain('evaluate_standard_surface(input, sceneMaterials[in.materialIndex])');
+    expect(shader).toContain('discard;');
     expect(shader).toContain('@group(2) @binding(1)');
     expect(shader).toContain('let skinMatrix = palette[');
     expect(record).toContain('entry.source.skin.byteOffset');
@@ -56,6 +64,25 @@ describe('skinned shadow caster', () => {
     expect(builder).toContain('buffers: [...ctx.vertexBuffers]');
   });
 
+  it('keeps the optional scene-material binding out of the WebGL2 shadow singleton', () => {
+    const record = readFileSync(
+      fileURLToPath(new URL('../record/shadow-pass.ts', import.meta.url)),
+      'utf8',
+    );
+    const singleton = record.slice(
+      record.indexOf('function ensureSpotShadowMaterialBg'),
+      record.indexOf('function ensureGpuDrivenAlphaMaskMaterialBg'),
+    );
+    expect(singleton).toContain('if (runtime.device.caps.storageBuffer)');
+    expect(singleton).toContain('binding: 46');
+    const sceneMaterialEntry = singleton.slice(singleton.lastIndexOf('binding: 46'));
+    expect(sceneMaterialEntry).toContain('pipelineState.meshStorageBuffer.buffer');
+    expect(sceneMaterialEntry).not.toContain('pipelineState.materialUniformBuffer.buffer');
+    expect(singleton.indexOf('if (runtime.device.caps.storageBuffer)')).toBeLessThan(
+      singleton.indexOf('binding: 46'),
+    );
+  });
+
   it('keeps mixed static and skinned shadow draws on matching variants and bindings', () => {
     const recordSource = readFileSync(
       fileURLToPath(new URL('../record/shadow-pass.ts', import.meta.url)),
@@ -92,12 +119,8 @@ describe('skinned shadow caster', () => {
     expect(skinnedVariant).toBe('SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false');
     expect(isSkinnedShadowCasterVariant(SHADOW_CASTER_SHADER_ID, staticVariant)).toBe(false);
     expect(isSkinnedShadowCasterVariant(SHADOW_CASTER_SHADER_ID, skinnedVariant)).toBe(true);
-    expect(recordSource).toContain(
-      'shadowCasterVariantSet(c.runtime.device.caps.storageBuffer, false)',
-    );
-    expect(recordSource).toContain(
-      "'shadow-caster',\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      'pbr'",
-    );
+    expect(recordSource).toContain('entry.mesh.layoutProjection');
+    expect(recordSource).toContain("skinned ? 'pbr-skin' : 'pbr'");
     expect(recordSource).toContain('createPbrSkinMeshBindGroupEntries(');
     expect(recordSource).toContain('pbrSkinMeshDynamicOffsets(');
 
@@ -130,6 +153,87 @@ describe('skinned shadow caster', () => {
     expect(recordSource).toContain('binding: 12');
   });
 
+  it('uses the visible scene index for multi-batch capable shadows', () => {
+    const shader = readFileSync(
+      fileURLToPath(new URL('../../../shader/src/shadow_caster.wgsl', import.meta.url)),
+      'utf8',
+    );
+    const recordSource = readFileSync(
+      fileURLToPath(new URL('../record/shadow-pass.ts', import.meta.url)),
+      'utf8',
+    );
+    expect(shadowCasterVariantSet(true, false, true)).toBe(
+      'ALPHA_MASK=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=true+GPU_DRIVEN_SCENE_INDEX_EXPLICIT=false+SKINNING_DISABLED=true+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(shader).toContain('@group(3) @binding(1) var<storage, read> visibleItems');
+    expect(shader).toContain('#pragma variant_axis GPU_DRIVEN_SCENE_INDEX_EXPLICIT');
+    expect(shader).toContain('GPU_DRIVEN_SCENE_INDEX_EXPLICIT == false');
+    expect(shader).toContain('meshIndex = visible.x;');
+    expect(shader).toContain('meshes[meshIndex].worldFromLocal');
+    expect(recordSource).toContain('gpuDrivenShadowBatchProjections?.get');
+    expect(recordSource).toContain('for (const batch of viewSubmission.plan.batches)');
+    const capableRecord = recordSource.slice(
+      recordSource.indexOf('function recordGpuDrivenShadowIfPublished'),
+      recordSource.indexOf('export function encodeDirectionalShadowPass'),
+    );
+    expect(capableRecord).not.toContain('validatedOrdered');
+    expect(recordSource).toContain('drawIndexedIndirect(indirect, batch.indirectOffset)');
+    expect(recordSource).toContain("batch.key.admission === 'alpha-mask'");
+    expect(recordSource).toContain('ensureGpuDrivenAlphaMaskMaterialBg');
+    const shadowBootVariants = [
+      {
+        defines: {
+          ALPHA_MASK: false,
+          GPU_DRIVEN_SCENE_INDEX_AVAILABLE: false,
+          GPU_DRIVEN_SCENE_INDEX_EXPLICIT: false,
+          SKINNING_DISABLED: true,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+      },
+      {
+        defines: {
+          ALPHA_MASK: true,
+          GPU_DRIVEN_SCENE_INDEX_AVAILABLE: false,
+          GPU_DRIVEN_SCENE_INDEX_EXPLICIT: false,
+          SKINNING_DISABLED: true,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+      },
+    ];
+    expect(
+      resolveMaterialShaderVariantSet(undefined, shadowBootVariants, 'wgpu-webgl2', false, 0),
+    ).toBe(
+      'ALPHA_MASK=false+GPU_DRIVEN_SCENE_INDEX_AVAILABLE=false+GPU_DRIVEN_SCENE_INDEX_EXPLICIT=false+SKINNING_DISABLED=true+STORAGE_BUFFER_AVAILABLE=false',
+    );
+  });
+
+  it('keeps the dispatch material handle, snapshot, and frame slot together', () => {
+    const paramSnapshot = { alphaClipThreshold: 0.4 };
+    const context = {
+      dispatch: [
+        {
+          renderableIndex: 4,
+          materialHandle: 42,
+          materialShaderId: 'forgeax::default-standard-pbr',
+          paramSnapshot,
+          tags: { LightMode: 'ShadowCaster' },
+        },
+      ],
+      validatedOrdered: [{ renderableIndex: 4 }],
+      materialSlotIndices: [[3, 7]],
+      materialSlots: Array.from({ length: 8 }, (_, slot) => ({
+        materialHandle: slot === 7 ? 42 : 11,
+      })),
+    } as never;
+    const bindings = shadowShaderMap(context);
+    expect(bindings.get(4)?.get(42)?.[0]).toMatchObject({
+      materialHandle: 42,
+      materialShaderId: SHADOW_CASTER_SHADER_ID,
+      materialSlot: 7,
+      paramSnapshot,
+    });
+  });
+
   it('keeps each submesh material associated with its selected shadow program and entries', () => {
     const context = {
       dispatch: [
@@ -150,8 +254,8 @@ describe('skinned shadow caster', () => {
       ],
     } as never;
     const bindings = shadowShaderMap(context);
-    expect(bindings.get(4)?.get(42)?.materialShaderId).toBe(SHADOW_CASTER_SHADER_ID);
-    expect(bindings.get(4)?.get(43)).toMatchObject({
+    expect(bindings.get(4)?.get(42)?.[0]?.materialShaderId).toBe(SHADOW_CASTER_SHADER_ID);
+    expect(bindings.get(4)?.get(43)?.[0]).toMatchObject({
       materialShaderId: 'custom::cutout',
       vertexEntry: 'vs_displaced',
       fragmentEntry: 'fs_cutout',