@forgeax/engine-runtime 0.1.28 → 0.1.29

package/src/__tests__/record-worldid-isolation.test.ts

@@ -2,7 +2,8 @@
 //
 // Verifies that every cache write/read site in the record stage that was
 // identified in plan-strategy D-1a as needing worldEntityKey compositing
-// actually uses worldEntityKey (not bare entityKey / cacheKey).
+// actually uses a world-aware key (worldEntityKey or
+// instanceCollectionCacheKey), not a bare entityKey / cacheKey.
 //
 // Anchors:
 //   plan-tasks.json m2 (patch assignment)
@@ -15,7 +16,7 @@
 // part of the contract and must not make this gate stale after extraction.
 //
 // Each site check uses a line-range window: we read the source file and verify
-// that within the line range, a `worldEntityKey(...)` call appears on a line
+// that within the line range, a world-aware key call appears on a line
 // that contains the target key expression. This directly falsifies the bug
 // "site uses bare key" — when a site uses a bare key, the worldEntityKey
 // check will fail.
@@ -27,12 +28,12 @@ import { describe, expect, it } from 'vitest';
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
 /**
- * Verify that a cache site uses a worldEntityKey composite key.
+ * Verify that a cache site uses a world-aware composite key.
  * Scans the source file around the given line (within a window) for both
  * `worldEntityKey` and the cache operation (`targetPattern` such as
  * `instanceBuffers.get`, etc.).
  */
-function expectWorldEntityKeyAt(
+function expectWorldAwareCacheKeyAt(
   filePath: string,
   line: number,
   description: string,
@@ -56,7 +57,7 @@ function expectWorldEntityKeyAt(
     nearby.push(`  ${i + 1}: ${lines[i]}`);
   }
   expect.fail(
-    `${description}: worldEntityKey NOT found near line ${line} in ${filePath}\nNearby lines:\n${nearby.join('\n')}`,
+    `${description}: world-aware cache key NOT found near line ${line} in ${filePath}\nNearby lines:\n${nearby.join('\n')}`,
   );
 }
 
@@ -74,21 +75,21 @@ function findLine(filePath: string, needle: string, occurrence = 0): number {
 
 // ── Geometry pass instanceBuffers (D-1a #1) ────────────────────────────────
 
-describe('production-path geometry instanceBuffers worldEntityKey', () => {
+describe('production-path geometry instanceBuffers world-aware key', () => {
   const FILE = fileURLToPath(
     new URL('../../../render/src/record/main-pass-geometry.ts', import.meta.url),
   );
 
-  it('inst.cacheKey get uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
+  it('inst.cacheKey get uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
       FILE,
       findLine(FILE, 'frameState.instanceBuffers.get('),
       'main-pass-geometry instanceBuffers.get',
     );
   });
 
-  it('inst.cacheKey set uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
+  it('inst.cacheKey set uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
       FILE,
       findLine(FILE, 'frameState.instanceBuffers.set('),
       'main-pass-geometry instanceBuffers.set',
@@ -110,17 +111,17 @@ describe('production-path shared instance bind-group resolver', () => {
 
 // ── Sprite Instances instanceBuffers (D-1a #1) ─────────────────────────────
 
-describe('production-path sprite Instances instanceBuffers worldEntityKey', () => {
-  it('spriteInst.cacheKey get uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
+describe('production-path sprite Instances instanceBuffers world-aware key', () => {
+  it('spriteInst.cacheKey get uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
       SPRITE_FILE,
       findLine(SPRITE_FILE, 'frameState.instanceBuffers.get(', 1),
       'main-pass-sprite-draws sprite instanceBuffers.get',
     );
   });
 
-  it('spriteInst.cacheKey set uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
+  it('spriteInst.cacheKey set uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
       SPRITE_FILE,
       findLine(SPRITE_FILE, 'frameState.instanceBuffers.set(', 1),
       'main-pass-sprite-draws sprite instanceBuffers.set',
@@ -130,17 +131,17 @@ describe('production-path sprite Instances instanceBuffers worldEntityKey', () =
 
 // ── SpriteInstances instanceBuffers (D-1a #1) ──────────────────────────────
 
-describe('production-path SpriteInstances instanceBuffers worldEntityKey', () => {
-  it('spriteInstancesSnap.cacheKey get uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
+describe('production-path SpriteInstances instanceBuffers world-aware key', () => {
+  it('spriteInstancesSnap.cacheKey get uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
       SPRITE_FILE,
       findLine(SPRITE_FILE, 'frameState.instanceBuffers.get(', 2),
       'main-pass-sprite-draws spriteInstances instanceBuffers.get',
     );
   });
 
-  it('spriteInstancesSnap.cacheKey set uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
+  it('spriteInstancesSnap.cacheKey set uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
       SPRITE_FILE,
       findLine(SPRITE_FILE, 'frameState.instanceBuffers.set(', 2),
       'main-pass-sprite-draws spriteInstances instanceBuffers.set',
@@ -154,12 +155,21 @@ const SHADOW_FILE = fileURLToPath(
   new URL('../../../render/src/record/shadow-pass.ts', import.meta.url),
 );
 
-describe('production-path shadow instanceBuffers worldEntityKey', () => {
-  it('shares the world-aware geometry instance residency owner', () => {
-    const src = readFileSync(SHADOW_FILE, 'utf8');
-    expect(src).toMatch(/resolveGeometryInstanceBuffer\(\s*c,\s*entry,/);
-    expect(src).not.toContain('instanceBuffers.get(');
-    expect(src).not.toContain('instanceBuffers.set(');
+describe('production-path shadow instanceBuffers world-aware key', () => {
+  it('shadowInst.cacheKey get uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, 'c.frameState.instanceBuffers.get(', 0),
+      'shadow-pass instanceBuffers.get',
+    );
+  });
+
+  it('shadowInst.cacheKey set uses a world-aware key', () => {
+    expectWorldAwareCacheKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, 'c.frameState.instanceBuffers.set('),
+      'shadow-pass instanceBuffers.set',
+    );
   });
 
   it('spot shadow uses the shared world-aware caster recorder', () => {
@@ -167,9 +177,18 @@ describe('production-path shadow instanceBuffers worldEntityKey', () => {
     const start = src.indexOf('export function encodeSpotShadowPass(');
     expect(start).toBeGreaterThanOrEqual(0);
     expect(src.slice(start)).toContain('recordShadowCasterDraws(');
-    expect(src.slice(start)).toContain(
-      "buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] })",
+    expect(src.slice(start)).toContain('buildMatchedRenderableIndices(');
+    expect(src.slice(start)).toContain("{ LightMode: ['ShadowCaster'] }");
+  });
+});
+
+describe('production-path shadow shared instance bind-group resolver', () => {
+  it('shadow pass resolves the bind group from the world-aware buffer cache', () => {
+    const src = readFileSync(SHADOW_FILE, 'utf8');
+    expect(src).toContain(
+      'const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, instanceDraw.buffer);',
     );
+    expect(src).toContain('instanceCollectionCacheKey(entry.source.worldId, shadowInst)');
   });
 });
 

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -14,6 +14,14 @@ import type { RenderError, RenderErrorCode } from '@forgeax/engine-render';
 
 function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
   switch (code) {
+    case 'auto-exposure-invalid-parameter':
+      return code;
+    case 'auto-exposure-capability-unavailable':
+      return code;
+    case 'auto-exposure-stale-generation':
+      return code;
+    case 'auto-exposure-stage-failed':
+      return code;
     case 'lifecycle-construction-failed':
       return code;
     case 'world-lease-invalid':
@@ -148,6 +156,22 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
 
 function narrowRenderError(err: RenderError): void {
   switch (err.code) {
+    case 'auto-exposure-invalid-parameter':
+      void err.detail.field;
+      void err.detail.value;
+      break;
+    case 'auto-exposure-capability-unavailable':
+      void err.detail.capability;
+      void err.detail.generation;
+      break;
+    case 'auto-exposure-stale-generation':
+      void err.detail.expectedGeneration;
+      void err.detail.actualGeneration;
+      break;
+    case 'auto-exposure-stage-failed':
+      void err.detail.stage;
+      void err.detail.operation;
+      break;
     case 'lifecycle-construction-failed':
       void err.detail.owner;
       void err.detail.generation;

package/src/__tests__/render-system-extract-dispatch-ordering.test.ts

@@ -51,7 +51,13 @@
 
 import { AssetRegistry, HANDLE_QUAD } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { Camera, Instances, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import {
+  Camera,
+  InstanceCollectionStore,
+  Instances,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render';
 import { propagateTransforms, Transform } from '@forgeax/engine-scene';
 import type { MaterialAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
@@ -245,13 +251,15 @@ describe('render-system-extract M2.5 dispatch/renderable slot pairing (AC-06)',
       instanceTransforms[n * 16 + 10] = 1;
       instanceTransforms[n * 16 + 15] = 1;
     }
+    const instanceCollections = new InstanceCollectionStore();
+    const collection = instanceCollections.create({ transforms: instanceTransforms }).unwrap();
 
     world
       .spawn(
         { component: Transform, data: transformAtZ(100) },
         { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
         { component: MeshRenderer, data: { materials: [matBlue] } },
-        { component: Instances, data: { transforms: instanceTransforms } },
+        { component: Instances, data: { collectionId: collection.collectionId } },
       )
       .unwrap();
     world
@@ -259,12 +267,15 @@ describe('render-system-extract M2.5 dispatch/renderable slot pairing (AC-06)',
         { component: Transform, data: identityTransform() },
         { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
         { component: MeshRenderer, data: { materials: [matYellow] } },
-        { component: Instances, data: { transforms: instanceTransforms } },
+        { component: Instances, data: { collectionId: collection.collectionId } },
       )
       .unwrap();
 
     expect(propagateTransforms(world).ok).toBe(true);
-    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    const frame = extractFrame(
+      world,
+      prepareExtractContext(world, { assets, instanceCollections }),
+    );
 
     expect(frame.renderables).toHaveLength(1);
     expect(frame.renderables[0]?.instances).toBeDefined();

package/src/__tests__/render-system-extract.test.ts

@@ -17,6 +17,7 @@ import {
   MeshFilter,
   MeshRenderer,
   PointLight,
+  PointLightShadow,
   SpotLight,
 } from '@forgeax/engine-render';
 import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
@@ -35,6 +36,7 @@ import {
   extractFrames,
   prepareExtractContext,
 } from '../../../render/src/render-system-extract';
+import { PersistentRenderScene } from '../../../render/src/scene/render-scene';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 
 // ─── from render-system-extract.test.ts ───
@@ -539,6 +541,65 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       expect(frame.frustumStats).toEqual({ culled: 1, total: 1 });
     });
 
+    it('retains off-camera casters only for shadow dispatch and only inside a light frustum', () => {
+      const world = new World();
+      spawnCamera(world);
+      world
+        .spawn(
+          { component: Transform, data: { ...identity(), pos: [0, 0, 2] } },
+          { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+          { component: MeshRenderer, data: {} },
+        )
+        .unwrap();
+      const light = world
+        .spawn(
+          { component: Transform, data: { ...identity(), pos: [0, 0, 5] } },
+          { component: PointLight, data: { intensity: 10, range: 10 } },
+          { component: PointLightShadow, data: { nearPlane: 0.1, farPlane: 10 } },
+        )
+        .unwrap();
+      propagateTransforms(world).unwrap();
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.frustumStats).toEqual({ culled: 1, total: 1 });
+      expect(frame.renderables).toHaveLength(1);
+      expect(frame.dispatch.map((entry) => entry.tags.LightMode)).toEqual(['ShadowCaster']);
+      expect(frame.dispatch.every((entry) => entry.renderableIndex === 0)).toBe(true);
+      world.set(light, PointLightShadow, { farPlane: 1 }).unwrap();
+      expect(extractFrame(world, prepareExtractContext(world)).renderables).toHaveLength(0);
+      world.despawn(light).unwrap();
+      expect(extractFrame(world, prepareExtractContext(world)).renderables).toHaveLength(0);
+    });
+
+    it('persistent composition retains shadow-only casters lit from another World', () => {
+      const sceneWorld = new World();
+      spawnCamera(sceneWorld);
+      sceneWorld
+        .spawn(
+          { component: Transform, data: { ...identity(), pos: [0, 0, 2] } },
+          { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+          { component: MeshRenderer, data: {} },
+        )
+        .unwrap();
+      const lightWorld = new World();
+      lightWorld
+        .spawn(
+          { component: Transform, data: { ...identity(), pos: [0, 0, 5] } },
+          { component: PointLight, data: { intensity: 10, range: 10 } },
+          { component: PointLightShadow, data: { nearPlane: 0.1, farPlane: 10 } },
+        )
+        .unwrap();
+      for (const world of [sceneWorld, lightWorld]) propagateTransforms(world).unwrap();
+      const worlds = [sceneWorld, lightWorld];
+      const owner = { cameraOwner: 0, resourceOwner: 0 };
+      const scene = new PersistentRenderScene();
+      const frame = scene.extractComposition(worlds, owner, 0, () =>
+        extractFrames(worlds, owner, undefined, undefined, undefined, { cull: 'none' }),
+      );
+      expect(frame.frustumStats).toEqual({ culled: 1, total: 1 });
+      expect(frame.renderables).toHaveLength(1);
+      expect(frame.dispatch.map((entry) => entry.tags.LightMode)).toEqual(['ShadowCaster']);
+    });
+
     it('cross-world extract keeps frustum culling against the surfaced camera-owner camera', () => {
       const cameraWorld = new World();
       cameraWorld

package/src/__tests__/render-system-extract.unit.test.ts

@@ -24,9 +24,9 @@
 // The 4 sub-assertions below RED before w10 lands the 3 _routeError fires
 // + SpriteInstancesSnapshot population in `render-system-extract.ts`. They
 // GO GREEN once w10 wires the validation into the QueryRow loop at the
-// same layer as the existing 'instance-transforms-stride-mismatch' fail-fast
-// (see packages/runtime/src/__tests__/render-system-mega.test.ts §w14 for
-// the structural sibling).
+// same extract boundary as renderer-owned InstanceCollectionError validation
+// (see packages/runtime/src/__tests__/render-system-mega.test.ts for the
+// collection association coverage).
 //
 // Anchors:
 //   - requirements AC-03 (3 sprite-instances error codes fire at extract)
@@ -41,6 +41,7 @@ import { World } from '@forgeax/engine-ecs';
 import {
   Camera,
   DirectionalLight,
+  InstanceCollectionStore,
   Instances,
   MeshFilter,
   MeshRenderer,
@@ -162,6 +163,7 @@ function makeScene(): {
   mesh: Handle<'MeshAsset', 'shared'>;
   spriteMat: Handle<'MaterialAsset', 'shared'>;
   unlitMat: Handle<'MaterialAsset', 'shared'>;
+  instanceCollections: InstanceCollectionStore;
 } {
   const collected: CollectedError[] = [];
   const world = new World();
@@ -182,24 +184,36 @@ function makeScene(): {
     passes: [UNLIT_PASS],
     values: {},
   } as MaterialAsset);
-  return { world, assets, collected, mesh, spriteMat, unlitMat };
+  return {
+    world,
+    assets,
+    collected,
+    mesh,
+    spriteMat,
+    unlitMat,
+    instanceCollections: new InstanceCollectionStore(),
+  };
 }
 
 describe('render-system-extract SpriteInstances validation (w8, AC-03 + Edge Cases)', () => {
   it('(a) entity carries both Instances + SpriteInstances -> fires sprite-instances-mutually-exclusive-with-instances + entity skipped', () => {
-    const { world, assets, collected, mesh, spriteMat } = makeScene();
+    const { world, assets, collected, mesh, spriteMat, instanceCollections } = makeScene();
     const transforms = new Float32Array(16);
     const regions = new Float32Array(4);
+    const collection = instanceCollections.create({ transforms }).unwrap();
     world
       .spawn(
         { component: Transform, data: identityTransform() },
         { component: MeshFilter, data: { assetHandle: mesh } },
         { component: MeshRenderer, data: { materials: [spriteMat] } },
-        { component: Instances, data: { transforms } },
+        { component: Instances, data: { collectionId: collection.collectionId } },
         { component: SpriteInstances, data: { transforms, regions } },
       )
       .unwrap();
-    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    const frame = extractFrame(
+      world,
+      prepareExtractContext(world, { assets, instanceCollections }),
+    );
     const fired = collected.filter(
       (c) => c.code === 'sprite-instances-mutually-exclusive-with-instances',
     );

package/src/__tests__/render-system-fold-bucket.unit.test.ts

@@ -28,6 +28,7 @@ function mockEntry(opts: {
   renderableIndex: number;
   materialHandle: number;
   layer: number;
+  materialShaderId?: string;
 }): DispatchEntry {
   return {
     entityIndex: opts.renderableIndex,
@@ -41,7 +42,7 @@ function mockEntry(opts: {
     defines: undefined,
     vertexEntry: undefined,
     fragmentEntry: undefined,
-    materialShaderId: undefined,
+    materialShaderId: opts.materialShaderId ?? 'forgeax::sprite',
     paramSnapshot: undefined,
   };
 }
@@ -185,6 +186,37 @@ describe('foldDispatchBuckets — mode 0 basic paths (w1)', () => {
 // 'sprite'` to `transparent === true` (the M3 ablation collapsed the
 // sprite discriminator into the generic transparent flag).
 describe('foldDispatchBuckets — transparent-only gate (PR #502 fix + feat-20260625 R2 fix-up)', () => {
+  it('transparent Standard PBR entries remain singleton while sprite shaders fold', () => {
+    const standardEntries = [0, 1].map((renderableIndex) =>
+      mockEntry({
+        renderableIndex,
+        materialHandle: 13,
+        layer: 0,
+        materialShaderId: 'forgeax::default-standard-pbr',
+      }),
+    );
+    const standardRenderables = standardEntries.map(() => mockRenderable(1.0, true));
+    const standardBuckets = foldDispatchBuckets(
+      standardEntries,
+      TRANSPARENT_SORT_MODE_LAYER_Z,
+      standardRenderables,
+    );
+    expect(standardBuckets.map((bucket) => bucket.bucketSize)).toEqual([1, 1]);
+
+    for (const materialShaderId of ['forgeax::sprite', 'forgeax::sprite-lit']) {
+      const spriteEntries = [0, 1].map((renderableIndex) =>
+        mockEntry({ renderableIndex, materialHandle: 13, layer: 0, materialShaderId }),
+      );
+      const spriteBuckets = foldDispatchBuckets(
+        spriteEntries,
+        TRANSPARENT_SORT_MODE_LAYER_Z,
+        standardRenderables,
+      );
+      expect(spriteBuckets).toHaveLength(1);
+      expect(spriteBuckets[0]?.bucketSize).toBe(2);
+    }
+  });
+
   it('non-transparent (unlit-shading) entries never form multi-entry buckets', () => {
     // 4 entries sharing (layer, posZ, materialHandle) — pre-fix would have
     // folded into a single bucketSize=4 bucket. With the transparent-only

package/src/__tests__/render-system-fold-material.unit.test.ts

@@ -19,6 +19,7 @@ function mockEntry(opts: {
   renderableIndex: number;
   materialHandle: number;
   layer: number;
+  materialShaderId?: string;
 }): DispatchEntry {
   return {
     entityIndex: opts.renderableIndex,
@@ -32,7 +33,7 @@ function mockEntry(opts: {
     defines: undefined,
     vertexEntry: undefined,
     fragmentEntry: undefined,
-    materialShaderId: undefined,
+    materialShaderId: opts.materialShaderId,
     paramSnapshot: undefined,
   };
 }
@@ -60,11 +61,36 @@ describe('foldDispatchBuckets — AC-10 multi-material boundary (w2)', () => {
     // [M1, M1, M1, M2, M2] — 3 entries with materialHandle=11 followed by
     // 2 with materialHandle=22, all same layer=5 and same posZ=3.0.
     const entries: DispatchEntry[] = [
-      mockEntry({ renderableIndex: 0, materialHandle: 11, layer: 5 }),
-      mockEntry({ renderableIndex: 1, materialHandle: 11, layer: 5 }),
-      mockEntry({ renderableIndex: 2, materialHandle: 11, layer: 5 }),
-      mockEntry({ renderableIndex: 3, materialHandle: 22, layer: 5 }),
-      mockEntry({ renderableIndex: 4, materialHandle: 22, layer: 5 }),
+      mockEntry({
+        renderableIndex: 0,
+        materialHandle: 11,
+        layer: 5,
+        materialShaderId: 'forgeax::sprite',
+      }),
+      mockEntry({
+        renderableIndex: 1,
+        materialHandle: 11,
+        layer: 5,
+        materialShaderId: 'forgeax::sprite',
+      }),
+      mockEntry({
+        renderableIndex: 2,
+        materialHandle: 11,
+        layer: 5,
+        materialShaderId: 'forgeax::sprite',
+      }),
+      mockEntry({
+        renderableIndex: 3,
+        materialHandle: 22,
+        layer: 5,
+        materialShaderId: 'forgeax::sprite',
+      }),
+      mockEntry({
+        renderableIndex: 4,
+        materialHandle: 22,
+        layer: 5,
+        materialShaderId: 'forgeax::sprite',
+      }),
     ];
     const renderables: ReturnType<typeof mockRenderable>[] = [
       mockRenderable(3.0),

package/src/__tests__/render-system-fold-modegate.unit.test.ts

@@ -30,6 +30,7 @@ function mockEntry(opts: {
   renderableIndex: number;
   materialHandle: number;
   layer: number;
+  materialShaderId?: string;
 }): DispatchEntry {
   return {
     entityIndex: opts.renderableIndex,
@@ -43,7 +44,7 @@ function mockEntry(opts: {
     defines: undefined,
     vertexEntry: undefined,
     fragmentEntry: undefined,
-    materialShaderId: undefined,
+    materialShaderId: opts.materialShaderId,
     paramSnapshot: undefined,
   };
 }
@@ -80,7 +81,14 @@ describe('foldDispatchBuckets — mode-gate (D-5, w3)', () => {
     const entries: DispatchEntry[] = [];
     const renderables: ReturnType<typeof mockRenderable>[] = [];
     for (let i = 0; i < N; i++) {
-      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      entries.push(
+        mockEntry({
+          renderableIndex: i,
+          materialHandle: 1,
+          layer: 0,
+          materialShaderId: 'forgeax::sprite',
+        }),
+      );
       renderables.push(mockRenderable(0, 0));
     }
     return { entries, renderables };
@@ -113,7 +121,14 @@ describe('foldDispatchBuckets — mode-gate (D-5, w3)', () => {
     const entries: DispatchEntry[] = [];
     const renderables: ReturnType<typeof mockRenderable>[] = [];
     for (let i = 0; i < N; i++) {
-      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      entries.push(
+        mockEntry({
+          renderableIndex: i,
+          materialHandle: 1,
+          layer: 0,
+          materialShaderId: 'forgeax::sprite',
+        }),
+      );
       renderables.push(mockRenderable(0, i * 16)); // posY = 0, 16, 32, 48
     }
     const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Y, renderables);
@@ -127,7 +142,14 @@ describe('foldDispatchBuckets — mode-gate (D-5, w3)', () => {
     const entries: DispatchEntry[] = [];
     const renderables: ReturnType<typeof mockRenderable>[] = [];
     for (let i = 0; i < N; i++) {
-      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      entries.push(
+        mockEntry({
+          renderableIndex: i,
+          materialHandle: 1,
+          layer: 0,
+          materialShaderId: 'forgeax::sprite',
+        }),
+      );
       renderables.push(mockRenderable(0, 3.0));
     }
     const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Y, renderables);

package/src/__tests__/render-system-fold.dawn.test.ts

@@ -71,7 +71,10 @@ function mockDispatchEntry(opts: {
     defines: undefined,
     vertexEntry: undefined,
     fragmentEntry: undefined,
-    materialShaderId: undefined,
+    // Fold admission is intentionally limited to the transparent sprite
+    // owners; these fixtures model sprite/tilemap draws rather than generic
+    // transparent Standard PBR geometry.
+    materialShaderId: 'forgeax::sprite',
     paramSnapshot: undefined,
   };
 }