@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,288 @@
+// 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 type { DispatchEntry } from '@forgeax/engine-render/internal';
+import {
+  foldDispatchBuckets,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '@forgeax/engine-render/internal';
+import { RenderQueue } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+// 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]
+  });
+});

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

@@ -0,0 +1,148 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M2 / w9 — fold-bucket
+// uniform-cap fallback functional unit tests.
+//
+// AC-05 (b) runtime behaviour: when caps.storageBuffer===false and a fold
+// bucket carries more than 128 instances, the engine fires a structured
+// `RhiError(code='instancing-exceeds-uniform-cap')` AND falls the bucket
+// back to per-entity drawIndexed (no identity-buffer collapse — see
+// research F-4 / R-4 + plan-decisions D-9).
+//
+// Boundary matrix (plan-strategy 4 R-4):
+//   storageBuffer=false, count=129 (just over cap)         -> error + fallback
+//   storageBuffer=false, count=128 (at cap)                -> no error, fold
+//   storageBuffer=false, count=129 scope='tilemap-chunk'   -> error + fallback
+//   storageBuffer=true,  count=10000                       -> no error, fold
+//   storageBuffer=false, singleton bucket (count=1)        -> no error path
+//
+// The fallback path is exposed as the pure helper
+// `evaluateFoldBucketUniformCap(bucket, caps, scope)` co-located with
+// `foldDispatchBuckets` in render-system-fold.ts: keeping it next to the
+// bucket type definition lets the record-stage dispatch site (w11) call
+// one branch instead of inlining the cap arithmetic, and lets this unit
+// test drive the decision without booting recordFrame (D-9: shared
+// fallback exit with the mode-gate bypass means the helper output is
+// the SSOT for "should this bucket fold or fall back?").
+
+import type { DispatchEntry } from '@forgeax/engine-render/internal';
+import { evaluateFoldBucketUniformCap, type FoldBucket } from '@forgeax/engine-render/internal';
+import { RhiError } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+
+const FOLD_UNIFORM_CAP = 128;
+
+function mockBucket(count: number, materialHandle = 7, layer = 0): FoldBucket {
+  const transforms = new Float32Array(count * 16);
+  // Each instance: identity mat4 (only matters for runtime stride; assertion
+  // is on bucket count, not transform values).
+  for (let i = 0; i < count; i++) {
+    transforms[i * 16 + 0] = 1;
+    transforms[i * 16 + 5] = 1;
+    transforms[i * 16 + 10] = 1;
+    transforms[i * 16 + 15] = 1;
+  }
+  const entries: DispatchEntry[] = [];
+  for (let i = 0; i < count; i++) {
+    entries.push({
+      entityIndex: i,
+      materialHandle,
+      renderableIndex: i,
+      passIndex: 0,
+      queue: 3000,
+      layer,
+      tags: {},
+      renderState: undefined,
+      defines: undefined,
+      vertexEntry: undefined,
+      fragmentEntry: undefined,
+      materialShaderId: undefined,
+      paramSnapshot: undefined,
+    });
+  }
+  return {
+    entries,
+    bucketSize: count,
+    transforms,
+    materialHandle,
+    layer,
+    sortKey: 0,
+  };
+}
+
+describe('M2 / w9 — fold-bucket uniform-cap fallback decision', () => {
+  it('storageBuffer=false + count > 128 -> fallback=true with RhiError carrying detail', () => {
+    const bucket = mockBucket(200);
+    const decision = evaluateFoldBucketUniformCap(bucket, { storageBuffer: false }, 'sprite');
+    expect(decision.fallback).toBe(true);
+    expect(decision.error).toBeInstanceOf(RhiError);
+    expect(decision.error?.code).toBe('instancing-exceeds-uniform-cap');
+    if (decision.error?.code === 'instancing-exceeds-uniform-cap') {
+      const d = decision.error.detail as
+        | { requested: number; limit: 128; scope: 'sprite' | 'tilemap-chunk' }
+        | undefined;
+      expect(d?.requested).toBe(200);
+      expect(d?.limit).toBe(FOLD_UNIFORM_CAP);
+      expect(d?.scope).toBe('sprite');
+    }
+    expect(decision.error?.expected.length).toBeGreaterThan(0);
+    expect(decision.error?.hint.length).toBeGreaterThan(0);
+  });
+
+  it('storageBuffer=false + count = 128 -> no fallback, no error (cap inclusive)', () => {
+    const bucket = mockBucket(128);
+    const decision = evaluateFoldBucketUniformCap(bucket, { storageBuffer: false }, 'sprite');
+    expect(decision.fallback).toBe(false);
+    expect(decision.error).toBeUndefined();
+  });
+
+  it('storageBuffer=false + count = 129 -> fallback fires (boundary just above cap)', () => {
+    const bucket = mockBucket(129);
+    const decision = evaluateFoldBucketUniformCap(
+      bucket,
+      { storageBuffer: false },
+      'tilemap-chunk',
+    );
+    expect(decision.fallback).toBe(true);
+    expect(decision.error?.code).toBe('instancing-exceeds-uniform-cap');
+    if (decision.error?.code === 'instancing-exceeds-uniform-cap') {
+      const d = decision.error.detail as
+        | { requested: number; limit: 128; scope: 'sprite' | 'tilemap-chunk' }
+        | undefined;
+      expect(d?.scope).toBe('tilemap-chunk');
+      expect(d?.requested).toBe(129);
+    }
+  });
+
+  it('storageBuffer=true + count = 10_000 -> no fallback (WebGPU has no UBO cap)', () => {
+    const bucket = mockBucket(10000);
+    const decision = evaluateFoldBucketUniformCap(bucket, { storageBuffer: true }, 'sprite');
+    expect(decision.fallback).toBe(false);
+    expect(decision.error).toBeUndefined();
+  });
+
+  it('singleton bucket (bucketSize=1) -> no fallback regardless of caps', () => {
+    const bucket = mockBucket(1);
+    const decisionFalse = evaluateFoldBucketUniformCap(bucket, { storageBuffer: false }, 'sprite');
+    const decisionTrue = evaluateFoldBucketUniformCap(bucket, { storageBuffer: true }, 'sprite');
+    expect(decisionFalse.fallback).toBe(false);
+    expect(decisionFalse.error).toBeUndefined();
+    expect(decisionTrue.fallback).toBe(false);
+    expect(decisionTrue.error).toBeUndefined();
+  });
+
+  it('scope is reflected verbatim in detail (no remapping)', () => {
+    const bucketSprite = mockBucket(200);
+    const bucketTilemap = mockBucket(200);
+    const dSprite = evaluateFoldBucketUniformCap(bucketSprite, { storageBuffer: false }, 'sprite');
+    const dTilemap = evaluateFoldBucketUniformCap(
+      bucketTilemap,
+      { storageBuffer: false },
+      'tilemap-chunk',
+    );
+    if (dSprite.error?.code === 'instancing-exceeds-uniform-cap') {
+      expect((dSprite.error.detail as { scope: string }).scope).toBe('sprite');
+    }
+    if (dTilemap.error?.code === 'instancing-exceeds-uniform-cap') {
+      expect((dTilemap.error.detail as { scope: string }).scope).toBe('tilemap-chunk');
+    }
+  });
+});

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

@@ -0,0 +1,145 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w2 — AC-10 multi-material.
+//
+// Drives the pure fold helper for the AC-10 boundary: a single chunk
+// spanning multiple atlas/material handles. Same Layer.value + same posZ +
+// 2 different materialHandle values must produce 2 separate buckets — the
+// fold must NOT merge them into one bucket (would render with the wrong
+// texture, requirements AC-10).
+//
+// Bucket key is the three-tuple (Layer.value, posZ, materialHandle). The
+// fold's correctness on the materialHandle leg is what this test pins.
+
+import type { DispatchEntry } from '@forgeax/engine-render/internal';
+import {
+  foldDispatchBuckets,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '@forgeax/engine-render/internal';
+import { RenderQueue } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+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,
+  };
+}
+
+function mockRenderable(tz: number): {
+  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;
+  // PR #502 fix + feat-20260625 R2 fix-up: `transparent: true` preserves the
+  // fold-eligible behavior these material-keyed tests exercise. The
+  // discriminator migrated from `shadingModel === 'sprite'` to
+  // `transparent === true` (M3 / w15 collapsed the sprite union member).
+  return { transform: { world }, material: { transparent: true } };
+}
+
+describe('foldDispatchBuckets — AC-10 multi-material boundary (w2)', () => {
+  it('2 different materialHandle values with same (layer, posZ) -> 2 separate buckets', () => {
+    // Layout (ordered by mode-0 sort which is stable within (layer, posZ)):
+    // [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 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(2);
+    const b0 = buckets[0];
+    const b1 = buckets[1];
+    expect(b0).toBeDefined();
+    expect(b1).toBeDefined();
+    if (b0 === undefined || b1 === undefined) return;
+    expect(b0.materialHandle).toBe(11);
+    expect(b0.bucketSize).toBe(3);
+    expect(b1.materialHandle).toBe(22);
+    expect(b1.bucketSize).toBe(2);
+  });
+
+  it('2 material runs interleaved (M1, M2, M1, M2) -> 4 separate singleton buckets (no string-bucket bug)', () => {
+    // The fold operator walks consecutive runs only; non-consecutive
+    // entries of the same material must NOT be merged into one bucket
+    // (would re-order draws, breaking transparent-sort stability).
+    const entries: DispatchEntry[] = [
+      mockEntry({ renderableIndex: 0, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 1, materialHandle: 22, layer: 0 }),
+      mockEntry({ renderableIndex: 2, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 3, materialHandle: 22, layer: 0 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(0),
+      mockRenderable(0),
+      mockRenderable(0),
+      mockRenderable(0),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    // 4 singleton buckets — consecutive-run fold preserves stable ordering.
+    expect(buckets).toHaveLength(4);
+    for (const b of buckets) {
+      expect(b.bucketSize).toBe(1);
+    }
+  });
+
+  it('two-material run with material key as bucket discriminator: distinct material -> never merged', () => {
+    // Edge: same layer + same posZ + different materialHandle. Even if
+    // (layer, posZ) match, materialHandle is the third key dimension and
+    // must split the bucket. This is the AC-10 essence (multi-atlas chunk).
+    const entries: DispatchEntry[] = [
+      mockEntry({ renderableIndex: 0, materialHandle: 100, layer: 9 }),
+      mockEntry({ renderableIndex: 1, materialHandle: 200, layer: 9 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(4.0),
+      mockRenderable(4.0),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(2);
+    const b0 = buckets[0];
+    const b1 = buckets[1];
+    expect(b0).toBeDefined();
+    expect(b1).toBeDefined();
+    if (b0 === undefined || b1 === undefined) return;
+    expect(b0.materialHandle).toBe(100);
+    expect(b1.materialHandle).toBe(200);
+    expect(b0.bucketSize).toBe(1);
+    expect(b1.bucketSize).toBe(1);
+  });
+});