@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

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

@@ -0,0 +1,360 @@
+// render-system-extract.unit.test.ts
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch M3 / w8.
+//
+// TDD-RED tests for the `SpriteInstances` extract entry. The plan-strategy
+// §2 D-6 contract:
+//
+//   When the render-system extract walks the MeshRenderer query, an entity
+//   carrying `SpriteInstances` must fire one of three structured `EcsError`
+//   codes (declared at packages/ecs/src/errors.ts, M1 / w2) and skip the
+//   renderable (no dispatch entry):
+//
+//     'sprite-instances-mutually-exclusive-with-instances'
+//       — same entity has both Instances and SpriteInstances.
+//     'sprite-instances-requires-sprite-shader'
+//       — MaterialAsset's first-pass materialShaderId resolved by the extract
+//         pipeline is not 'forgeax::sprite'.
+//     'sprite-instances-count-mismatch'
+//       — transforms.length / 16 !== regions.length / 4 (stride pair).
+//
+//   The zero-instance case (transforms.length === 0 && regions.length === 0)
+//   is the explicit non-fire boundary from requirements (Edge Cases) — the entity
+//   passes extract validation (no error) but produces no draw call.
+//
+// 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).
+//
+// Anchors:
+//   - requirements AC-03 (3 sprite-instances error codes fire at extract)
+//   - requirements (Edge Cases) (transforms.length === 0 lawful — non-fire)
+//   - plan-strategy §2 D-6 (3 fires at extract entry, not at spawn)
+//   - plan-strategy §3.2 sequence (extract: snap + validate + skip)
+//   - research §Q-R-2.5 (extract-stage SpriteInstances sniff + validate)
+
+import { readFile } from 'node:fs/promises';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import {
+  Camera,
+  DirectionalLight,
+  Instances,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry, type ShaderRegistryDevice } from '@forgeax/engine-shader';
+import type { Handle, MaterialAsset, MaterialPass, MeshAsset } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { SpriteInstances } from '../../../render/src/components';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+
+interface CollectedError {
+  readonly code: string;
+  readonly detail: unknown;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function identityTransform(): {
+  pos: number[];
+  quat: number[];
+  scale: number[];
+} {
+  return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+}
+
+function makeShaderRegistryWithSpriteAndPbr(): ShaderRegistry {
+  const mockDevice: ShaderRegistryDevice = {
+    createShaderModule() {
+      return {
+        ok: true,
+        value: undefined,
+        unwrap: () => undefined,
+        unwrapOr: (d: unknown) => d,
+      } as unknown as ReturnType<ShaderRegistryDevice['createShaderModule']>;
+    },
+  };
+  const sr = new ShaderRegistry({ device: mockDevice, manifestUrl: undefined });
+  sr.installMaterialArtifact('forgeax::sprite', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+      { name: 'region', type: 'vec4', default: [0.0, 0.0, 1.0, 1.0] },
+      { name: 'pivot', type: 'vec2', default: [0.5, 0.5] },
+      { name: 'flipX', type: 'f32', default: 0.0 },
+      { name: 'flipY', type: 'f32', default: 0.0 },
+      { name: 'slices', type: 'vec4', default: [0.0, 0.0, 0.0, 0.0] },
+      { name: 'sliceMode', type: 'f32', default: 0.0 },
+    ],
+  });
+  sr.installMaterialArtifact('forgeax::default-unlit', {
+    source: 'fn main() {}',
+    paramSchema: [{ name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] }],
+  });
+  return sr;
+}
+
+const SPRITE_PASS: MaterialPass = {
+  name: 'Sprite',
+  program: { module: 'forgeax::sprite' },
+  renderState: { queue: 3000 },
+};
+
+const UNLIT_PASS: MaterialPass = { name: 'Forward', program: { module: 'forgeax::default-unlit' } };
+
+function registerSpriteMesh(world: World): Handle<'MeshAsset', 'shared'> {
+  return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', {
+    kind: 'mesh',
+    vertices: new Float32Array([
+      0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
+      1, 0, 0, 0, 0,
+    ]),
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]) },
+    aabb: new Float32Array([0, 0, 0, 1, 1, 1]),
+    submeshes: [
+      { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  });
+}
+
+function spawnCameraAndLight(world: World): void {
+  world
+    .spawn({
+      component: Camera,
+      data: {
+        fov: 1.0,
+        aspect: 1.0,
+        near: 0.1,
+        far: 100.0,
+        projection: 0,
+        left: -1,
+        right: 1,
+        bottom: -1,
+        top: 1,
+      },
+    })
+    .unwrap();
+  world
+    .spawn({
+      component: DirectionalLight,
+      data: {
+        direction: [0, -1, 0],
+        color: [1, 1, 1],
+        intensity: 1,
+      },
+    })
+    .unwrap();
+}
+
+function makeScene(): {
+  world: World;
+  assets: AssetRegistry;
+  collected: CollectedError[];
+  mesh: Handle<'MeshAsset', 'shared'>;
+  spriteMat: Handle<'MaterialAsset', 'shared'>;
+  unlitMat: Handle<'MaterialAsset', 'shared'>;
+} {
+  const collected: CollectedError[] = [];
+  const world = new World();
+  const assets = new AssetRegistry(makeShaderRegistryWithSpriteAndPbr());
+  vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+    const e = args[args.length - 1] as { code?: string; detail?: unknown };
+    if (e.code !== undefined) collected.push({ code: e.code, detail: e.detail });
+  });
+  spawnCameraAndLight(world);
+  const mesh = registerSpriteMesh(world);
+  const spriteMat = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [SPRITE_PASS],
+    values: {},
+  } as MaterialAsset);
+  const unlitMat = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [UNLIT_PASS],
+    values: {},
+  } as MaterialAsset);
+  return { world, assets, collected, mesh, spriteMat, unlitMat };
+}
+
+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 transforms = new Float32Array(16);
+    const regions = new Float32Array(4);
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [spriteMat] } },
+        { component: Instances, data: { transforms } },
+        { component: SpriteInstances, data: { transforms, regions } },
+      )
+      .unwrap();
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    const fired = collected.filter(
+      (c) => c.code === 'sprite-instances-mutually-exclusive-with-instances',
+    );
+    expect(fired.length).toBe(1);
+    const detail = fired[0]?.detail as { entityId: number };
+    expect(typeof detail.entityId).toBe('number');
+    expect(detail.entityId).toBeGreaterThan(0);
+    // entity skipped: zero renderables (camera/light do not produce a renderable)
+    expect(frame.renderables.length).toBe(0);
+  });
+
+  it('(b) SpriteInstances on non-sprite materialShaderId -> fires sprite-instances-requires-sprite-shader + entity skipped', () => {
+    const { world, assets, collected, mesh, unlitMat } = makeScene();
+    const transforms = new Float32Array(16);
+    const regions = new Float32Array(4);
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [unlitMat] } },
+        { component: SpriteInstances, data: { transforms, regions } },
+      )
+      .unwrap();
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    const fired = collected.filter((c) => c.code === 'sprite-instances-requires-sprite-shader');
+    expect(fired.length).toBe(1);
+    const detail = fired[0]?.detail as { entityId: number; observedMaterialShaderId: string };
+    expect(typeof detail.entityId).toBe('number');
+    expect(detail.entityId).toBeGreaterThan(0);
+    // observedMaterialShaderId surfaces the actual resolved shader id string
+    // for the AI user's debug; the unlit material resolves to
+    // 'forgeax::default-unlit', which is != 'forgeax::sprite'.
+    expect(typeof detail.observedMaterialShaderId).toBe('string');
+    expect(detail.observedMaterialShaderId).not.toBe('forgeax::sprite');
+    expect(frame.renderables.length).toBe(0);
+  });
+
+  it('(c) transforms.length=320, regions.length=40 (20 vs 10 instance count) -> fires sprite-instances-count-mismatch with detail + entity skipped', () => {
+    const { world, assets, collected, mesh, spriteMat } = makeScene();
+    const transforms = new Float32Array(320);
+    const regions = new Float32Array(40);
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [spriteMat] } },
+        { component: SpriteInstances, data: { transforms, regions } },
+      )
+      .unwrap();
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    const fired = collected.filter((c) => c.code === 'sprite-instances-count-mismatch');
+    expect(fired.length).toBe(1);
+    const detail = fired[0]?.detail as {
+      transformsLength: number;
+      regionsLength: number;
+      expectedStride: { transforms: 16; regions: 4 };
+    };
+    expect(detail.transformsLength).toBe(320);
+    expect(detail.regionsLength).toBe(40);
+    expect(detail.expectedStride.transforms).toBe(16);
+    expect(detail.expectedStride.regions).toBe(4);
+    expect(frame.renderables.length).toBe(0);
+  });
+
+  it('(d) zero-instance lawful: transforms.length=0 + regions.length=0 -> no fire + entity NOT skipped on validation grounds', () => {
+    // requirements (Edge Cases): the zero-instance shape is the explicit
+    // non-fire boundary. The entity passes extract validation; no draw call
+    // is produced downstream because the instance count is zero.
+    const { world, assets, collected, mesh, spriteMat } = makeScene();
+    const transforms = new Float32Array(0);
+    const regions = new Float32Array(0);
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [spriteMat] } },
+        { component: SpriteInstances, data: { transforms, regions } },
+      )
+      .unwrap();
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    // No sprite-instances error fires. (Note: the count-mismatch path must
+    // NOT fire for 0/0 — `0/16 === 0/4 === 0` is the equality the validator
+    // honours; the count-mismatch fire requires unequal derived counts.)
+    expect(collected.filter((c) => String(c.code).startsWith('sprite-instances-')).length).toBe(0);
+    // Renderable still surfaces (extract does not skip the entity on
+    // validation grounds); whether the draw call is emitted is downstream
+    // record-stage concern (instance count = 0 -> drawIndexed(..., 0, ...) skip).
+    expect(frame.renderables.length).toBe(1);
+  });
+});
+
+describe('render-system-extract material color boundary', () => {
+  it('decodes default-sRGB asset colors exactly once into the runtime snapshot', () => {
+    const { world, assets, mesh } = makeScene();
+    const authored = [0.5, 0.25, 0.75, 0.4] as const;
+    const material = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+      kind: 'material',
+      passes: [UNLIT_PASS],
+      values: { baseColor: authored },
+    });
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [material] } },
+      )
+      .unwrap();
+
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    const runtime = frame.renderables[0]?.material;
+    // MaterialSnapshot stores baseColor in f32 engine vectors.
+    expect(runtime?.baseColor[0]).toBeCloseTo(0.2140411405, 6);
+    expect(runtime?.baseColor[1]).toBeCloseTo(0.0508760882, 6);
+    expect(runtime?.baseColor[2]).toBeCloseTo(0.5225215539, 6);
+    expect(runtime?.paramSnapshot?.baseColor).toEqual([
+      expect.closeTo(0.2140411405, 9),
+      expect.closeTo(0.0508760882, 9),
+      expect.closeTo(0.5225215539, 9),
+      0.4,
+    ]);
+    expect(authored).toEqual([0.5, 0.25, 0.75, 0.4]);
+  });
+
+  it('passes explicitly-linear asset colors through unchanged', () => {
+    const { world, assets, mesh } = makeScene();
+    const material = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+      kind: 'material',
+      colorSpace: 'linear',
+      passes: [UNLIT_PASS],
+      values: { baseColor: [0.5, 0.25, 0.75, 0.4] },
+    });
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [material] } },
+      )
+      .unwrap();
+
+    const runtime = extractFrame(world, prepareExtractContext(world, { assets })).renderables[0]
+      ?.material;
+    expect(Array.from(runtime?.baseColor ?? [])).toEqual([0.5, 0.25, 0.75]);
+    expect(runtime?.paramSnapshot?.baseColor).toEqual([0.5, 0.25, 0.75, 0.4]);
+  });
+});
+
+describe('render-system-extract spot direction owner', () => {
+  it('normalizes one spot snapshot in extract and keeps one spot query', async () => {
+    const source = await readFile(
+      new URL('../../../render/src/render-system-extract.ts', import.meta.url),
+      'utf8',
+    );
+
+    expect(source.match(/\.query\(\{\s*read: \[SpotLight\]/g)?.length).toBe(1);
+    expect(source).toContain('const dirN = vec3.create(');
+    expect(source).toContain('direction: dirN');
+  });
+});

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

@@ -0,0 +1,286 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w1 — fold-bucket basics.
+//
+// Drives the pure fold helper `foldDispatchBuckets(entries, mode, renderables)`
+// for mode-0 (LAYER_Z) basic paths:
+//   (1) single material, N consecutive DispatchEntry sharing (layer, posZ,
+//       materialHandle) -> 1 fold bucket with bucketSize=N.
+//   (2) empty input -> 0 buckets.
+//   (3) chunkSize=1 (each entry has its own (layer, posZ, material)) ->
+//       N buckets each with bucketSize=1 (degenerate single-instance path).
+//   (4) Float32Array layout: assembled transforms is a Float32Array with
+//       stride=16 (16 f32 per instance, column-major mat4), length=N*16.
+//
+// Constraints from plan-tasks.json w1:
+//   - mode 0 (LAYER_Z) only (mode 1/2/3 in w3)
+//   - Instances schema not touched (stride=16)
+//   - no new file in packages/runtime/src/scene-instances/ (AC-08)
+
+import { RenderQueue } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { foldDispatchBuckets } from '../../../render/src/record/mesh-ssbo';
+import type { DispatchEntry } from '../../../render/src/render-system-extract';
+import { TRANSPARENT_SORT_MODE_LAYER_Z } from '../../../render/src/systems/transparent-sort-config';
+
+// Minimal mock DispatchEntry — only the fields the fold helper reads:
+// materialHandle, renderableIndex, layer, queue. Other fields are
+// `undefined` / placeholder; the helper does not consult them.
+function mockEntry(opts: {
+  renderableIndex: number;
+  materialHandle: number;
+  layer: number;
+}): DispatchEntry {
+  return {
+    entityIndex: opts.renderableIndex,
+    materialHandle: opts.materialHandle,
+    renderableIndex: opts.renderableIndex,
+    passIndex: 0,
+    queue: RenderQueue.Transparent,
+    layer: opts.layer,
+    tags: {},
+    renderState: undefined,
+    defines: undefined,
+    vertexEntry: undefined,
+    fragmentEntry: undefined,
+    materialShaderId: undefined,
+    paramSnapshot: undefined,
+  };
+}
+
+// Minimal renderable snapshot — only the world mat4 is consulted (for posZ
+// and for assembled transforms). Build an identity mat4 with a chosen tz.
+// PR #502 fix + feat-20260625 R2 fix-up: foldDispatchBuckets gates fold to
+// transparent entries (the M3 ablation collapsed `shadingModel === 'sprite'`
+// into `transparent === true` as the LDR-split-sub-pass discriminator). The
+// `transparent` parameter is a 3-arity optional flag: omitted (arity=1)
+// defaults to `true` so legacy basic-paths tests keep their fold-eligible
+// behavior; explicit values may pass `undefined` (non-transparent /
+// geometry-pass) which must land as undefined in the renderable (do NOT
+// collapse to default via arity-2 default-parameter substitution).
+function mockRenderable(
+  tz: number,
+  ...rest: [true | undefined] | []
+): {
+  transform: { world: Float32Array };
+  material: { transparent?: true | undefined };
+} {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[14] = tz; // posZ
+  const transparent = rest.length === 0 ? true : rest[0];
+  return { transform: { world }, material: { transparent } };
+}
+
+describe('foldDispatchBuckets — mode 0 basic paths (w1)', () => {
+  it('empty entries produces 0 buckets', () => {
+    const buckets = foldDispatchBuckets([], TRANSPARENT_SORT_MODE_LAYER_Z, []);
+    expect(buckets).toHaveLength(0);
+  });
+
+  it('single material N consecutive entries with same (layer, posZ, materialHandle) -> 1 bucket, bucketSize=N', () => {
+    const N = 5;
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 42, layer: 7 }));
+      renderables.push(mockRenderable(1.5));
+    }
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(1);
+    const bucket = buckets[0];
+    expect(bucket).toBeDefined();
+    if (bucket === undefined) return;
+    expect(bucket.bucketSize).toBe(N);
+    expect(bucket.materialHandle).toBe(42);
+    expect(bucket.layer).toBe(7);
+    expect(bucket.sortKey).toBeCloseTo(1.5);
+    expect(bucket.entries).toHaveLength(N);
+  });
+
+  it('assembled transforms Float32Array stride=16 (N*16 floats, column-major mat4)', () => {
+    const N = 4;
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      // Distinct tz per entry so we can verify per-instance slot ordering.
+      renderables.push(mockRenderable(2.0));
+    }
+    // Force distinct world mat4 contents while keeping posZ equal (posZ
+    // is at index 14; we mutate index 12 / 13 to assert per-instance copy
+    // semantics in the assembled buffer).
+    for (let i = 0; i < N; i++) {
+      const w = renderables[i]?.transform.world;
+      if (w === undefined) continue;
+      w[12] = i * 10; // distinct posX
+      w[13] = i * 100; // distinct posY
+    }
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+    expect(buckets).toHaveLength(1);
+    const bucket = buckets[0];
+    expect(bucket).toBeDefined();
+    if (bucket === undefined) return;
+
+    expect(bucket.transforms).toBeInstanceOf(Float32Array);
+    expect(bucket.transforms.length).toBe(N * 16);
+    // Verify each instance slot holds its renderable's world mat4 contents:
+    // slot i posX (index 12) === i * 10; slot i posY (index 13) === i * 100;
+    // slot i posZ (index 14) === 2.0.
+    for (let i = 0; i < N; i++) {
+      expect(bucket.transforms[i * 16 + 12]).toBeCloseTo(i * 10);
+      expect(bucket.transforms[i * 16 + 13]).toBeCloseTo(i * 100);
+      expect(bucket.transforms[i * 16 + 14]).toBeCloseTo(2.0);
+      // Identity diagonal preserved
+      expect(bucket.transforms[i * 16 + 0]).toBeCloseTo(1);
+      expect(bucket.transforms[i * 16 + 5]).toBeCloseTo(1);
+      expect(bucket.transforms[i * 16 + 10]).toBeCloseTo(1);
+      expect(bucket.transforms[i * 16 + 15]).toBeCloseTo(1);
+    }
+  });
+
+  it('chunkSize=1 degenerate path: each entry distinct -> N singleton buckets', () => {
+    // Distinct posZ per entry -> each becomes its own bucket (no fold).
+    const N = 3;
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      renderables.push(mockRenderable(i + 0.5)); // distinct posZ
+    }
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+    expect(buckets).toHaveLength(N);
+    for (let i = 0; i < N; i++) {
+      const b = buckets[i];
+      expect(b).toBeDefined();
+      if (b === undefined) continue;
+      expect(b.bucketSize).toBe(1);
+      expect(b.transforms.length).toBe(16);
+    }
+  });
+});
+
+// PR #502 hello-room CI red regression + feat-20260625 R2 fix-up:
+// geometry-pass entries (non-transparent: standard-PBR / unlit / skin) were
+// folded into multi-entry buckets when they shared (layer, posZ,
+// materialHandle). The mesh-SSBO upload loop then overwrote their slot
+// with identity (because `headBuckets.has(i)` was true), but the
+// geometry-pass dispatch loop does NOT branch on `headBuckets` — it kept
+// emitting per-entity drawIndexed which then read identity and rendered
+// the 3D geometry at the world origin, collapsing the frame to black.
+//
+// The fix gates fold to transparent entries at the bucket-key level
+// (`foldDispatchBuckets` itself), so non-transparent entries always
+// produce singleton buckets that `buildFoldDispatchPlan` filters out from
+// `headBuckets` / `skipIndices`. The mesh-SSBO upload loop then keeps
+// writing the entity's real world matrix for those slots, and both
+// dispatch loops behave byte-identically to the pre-fold path.
+//
+// feat-20260625 R2 fix-up: the gate migrated from `shadingModel ===
+// '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('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
+    // gate they MUST each be their own singleton.
+    const N = 4;
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 7, layer: 0 }));
+      renderables.push(mockRenderable(1.0, undefined)); // <-- not transparent
+    }
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(N);
+    for (const b of buckets) {
+      expect(b.bucketSize).toBe(1);
+    }
+  });
+
+  it('standard-PBR (non-transparent) entries never form multi-entry buckets', () => {
+    // Standard / PBR materials carry shadingModel=undefined + materialShaderId
+    // (feat-20260523-shader-template-instance-split M4-T05). They must also
+    // stay singleton — same hello-room CI red root cause (sphereChild +
+    // planeChild use Standard, geometry-pass collapsed them to (0,0,0)).
+    const N = 3;
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 9, layer: 0 }));
+      renderables.push(mockRenderable(2.0, undefined)); // <-- not transparent
+    }
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(N);
+    for (const b of buckets) {
+      expect(b.bucketSize).toBe(1);
+    }
+  });
+
+  it('mixed transparent + non-transparent entries: transparent run folds, non-transparent stays singleton', () => {
+    // Three transparent entries (fold-eligible) followed by three non-
+    // transparent. Result: 1 bucket of size 3 (the transparent run) + 3
+    // singletons (one per non-transparent entry).
+    const entries: DispatchEntry[] = [
+      mockEntry({ renderableIndex: 0, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 1, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 2, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 3, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 4, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 5, materialHandle: 11, layer: 0 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(1.0, true),
+      mockRenderable(1.0, true),
+      mockRenderable(1.0, true),
+      mockRenderable(1.0, undefined),
+      mockRenderable(1.0, undefined),
+      mockRenderable(1.0, undefined),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(4);
+    expect(buckets[0]?.bucketSize).toBe(3); // transparent run
+    expect(buckets[1]?.bucketSize).toBe(1); // non-transparent singletons
+    expect(buckets[2]?.bucketSize).toBe(1);
+    expect(buckets[3]?.bucketSize).toBe(1);
+  });
+
+  it('transparent run interrupted by non-transparent breaks fold even with matching key', () => {
+    // transparent, transparent, non-transparent, transparent — pre-fix the
+    // (layer, posZ, material) equality would have folded all four; the gate
+    // now splits at the non-transparent entry (forcing it singleton) and
+    // the trailing transparent starts a fresh head (which becomes a
+    // singleton bucket since the run ends immediately — no further matching
+    // entry follows in this fixture).
+    const entries: DispatchEntry[] = [
+      mockEntry({ renderableIndex: 0, materialHandle: 2, layer: 0 }),
+      mockEntry({ renderableIndex: 1, materialHandle: 2, layer: 0 }),
+      mockEntry({ renderableIndex: 2, materialHandle: 2, layer: 0 }),
+      mockEntry({ renderableIndex: 3, materialHandle: 2, layer: 0 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(0.5, true),
+      mockRenderable(0.5, true),
+      mockRenderable(0.5, undefined), // breaks the run
+      mockRenderable(0.5, true),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(3);
+    expect(buckets[0]?.bucketSize).toBe(2); // transparent run [0,1]
+    expect(buckets[1]?.bucketSize).toBe(1); // non-transparent singleton [2]
+    expect(buckets[2]?.bucketSize).toBe(1); // transparent singleton [3]
+  });
+});