@forgeax/engine-runtime 0.1.2

package/src/__tests__/bind-group-cache-keying.test.ts

@@ -0,0 +1,295 @@
+// feat-20260622-handle-to-id-allocator-elimination M2 / w4 + w5:
+// TDD tests for WeakMap chain determinism, cleanup new shape, AC-08 export,
+// and AC-06 two-helper existence. Replaces the old string-key dedup +
+// sentinel-survival tests (buildBindGroupCacheKey / Number.isNaN / D-6 rescue).
+//
+// w4: chain determinism (getOrCreateFromChain — red until w7 implements it).
+// w5: cleanup eviction (cleanPerEntityCache — red until w8 rewrites it)
+//     + getOrCreatePerEntity existence (red until w8 implements it).
+
+import {
+  type BindGroupCounts,
+  cleanPerEntityCache,
+  getOrCreateFromChain,
+  getOrCreatePerEntity,
+} from '@forgeax/engine-render/internal';
+import type { BindGroup } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function h(): object {
+  return {};
+}
+
+function stubBindGroup(): BindGroup {
+  return {} as unknown as BindGroup;
+}
+
+function stubCounts(): BindGroupCounts {
+  return { createBindGroup: 0, keys: [] };
+}
+
+function factory(): BindGroup {
+  return stubBindGroup();
+}
+
+// ─── w4: WeakMap chain determinism (no id allocator, no NaN, no string key) ──
+//
+// The old buildBindGroupCacheKey walked a WeakMap<object,number> counter to
+// produce string keys for a flat Map<string,BG>. The new design uses handle
+// objects directly as WeakMap chain nodes — same object identity → same leaf,
+// different objects → different leaf. No Number.isNaN rescue branch exists
+// because there is no string parsing.
+//
+// These tests are RED until w7 implements getOrCreateFromChain (D-2 / AC-06).
+
+describe('w4 — WeakMap chain determinism', () => {
+  it('same handles + same variant produces the same BG leaf (deterministic)', () => {
+    const root = new WeakMap<object, unknown>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bg1 = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+    const bg2 = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+    expect(bg1).toBe(bg2);
+  });
+
+  it('different handle set produces a different BG leaf', () => {
+    const root = new WeakMap<object, unknown>();
+    const handlesA = [h(), h()];
+    const handlesB = [h(), h()];
+    const counts = stubCounts();
+    const bgA = getOrCreateFromChain(root, handlesA, 'view-main', factory, counts);
+    const bgB = getOrCreateFromChain(root, handlesB, 'view-main', factory, counts);
+    expect(bgA).not.toBe(bgB);
+  });
+
+  it('same handles + different variant produces different BG leaf', () => {
+    const root = new WeakMap<object, unknown>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bgMain = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+    const bgShadow = getOrCreateFromChain(root, handles, 'view-shadow', factory, counts);
+    expect(bgMain).not.toBe(bgShadow);
+  });
+
+  it('chain lookup is idempotent — createBindGroup stays at 1 across N calls', () => {
+    const root = new WeakMap<object, unknown>();
+    const handles = [h(), h(), h(), h(), h(), h(), h()]; // 7 deep like view-main
+    const counts = stubCounts();
+    for (let i = 0; i < 100; i++) {
+      const bg = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+      expect(bg).toBeDefined();
+    }
+    expect(counts.createBindGroup).toBe(1);
+  });
+});
+
+// ─── w5a: cleanPerEntityCache new shape (AC-02 / AC-08) ─────────────────────
+//
+// The old cleanPerEntityCache parsed entityKey from string keys via
+// indexOf('-') + Number(slice) and used Number.isNaN(ek) to rescue
+// sentinel / material-shared keys. The new design uses Map<number, WeakMap>
+// where entityKey is already a number — eviction is a simple delete loop:
+//   for (const ek of cache.keys())
+//     if (!validatedEntityKeys.has(ek)) cache.delete(ek)
+//
+// No string parsing, no Number.isNaN, no indexOf / Number calls.
+// cleanPerEntityCache remains an @internal export (AC-08).
+//
+// These tests are RED until w8 rewrites cleanPerEntityCache (RD4 / AC-02).
+
+describe('w5a — cleanPerEntityCache new shape (AC-02, AC-08)', () => {
+  it('deletes entityKeys not in the validated set', () => {
+    const bg1 = stubBindGroup();
+    const bg2 = stubBindGroup();
+    const inner1 = new WeakMap<object, BindGroup>();
+    inner1.set(h(), bg1);
+    const inner2 = new WeakMap<object, BindGroup>();
+    inner2.set(h(), bg2);
+    const cache = new Map<number, WeakMap<object, BindGroup>>();
+    cache.set(123, inner1);
+    cache.set(456, inner2);
+
+    const validated = new Set<number>([123]);
+
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.has(123)).toBe(true); // validated -> kept
+    expect(cache.has(456)).toBe(false); // stale -> deleted
+  });
+
+  it('deletes all entityKeys when validated set is empty', () => {
+    const inner = new WeakMap<object, BindGroup>();
+    inner.set(h(), stubBindGroup());
+    const cache = new Map<number, WeakMap<object, BindGroup>>();
+    cache.set(42, inner);
+
+    cleanPerEntityCache(cache, new Set());
+
+    expect(cache.size).toBe(0);
+  });
+
+  it('keeps all entityKeys when all are validated', () => {
+    const inner1 = new WeakMap<object, BindGroup>();
+    inner1.set(h(), stubBindGroup());
+    const inner2 = new WeakMap<object, BindGroup>();
+    inner2.set(h(), stubBindGroup());
+    const cache = new Map<number, WeakMap<object, BindGroup>>();
+    cache.set(1, inner1);
+    cache.set(2, inner2);
+
+    const validated = new Set<number>([1, 2]);
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.size).toBe(2);
+    expect(cache.has(1)).toBe(true);
+    expect(cache.has(2)).toBe(true);
+  });
+
+  it('has no string parsing, no Number.isNaN, no Number calls in function body', () => {
+    // AC-02: the function body must not contain indexOf, Number, or Number.isNaN.
+    const fnSrc = cleanPerEntityCache.toString();
+    expect(fnSrc).not.toContain('indexOf');
+    expect(fnSrc).not.toContain('Number.isNaN');
+    expect(fnSrc).not.toContain('Number(');
+  });
+});
+
+// ─── w5b: getOrCreatePerEntity existence (AC-06) ────────────────────────────
+//
+// The new per-entity helper `getOrCreatePerEntity` takes an outer
+// Map<string|number, WeakMap<...>> and an outerKey, then walks the
+// inner WeakMap chain. No branch-on-cache-type inside a single generic
+// helper (AC-06: two distinct helpers exist, no unified one).
+//
+// These tests are RED until w8 implements getOrCreatePerEntity (D-2 / AC-06).
+
+describe('w5b — getOrCreatePerEntity existence and behavior (AC-06)', () => {
+  it('getOrCreatePerEntity is a distinct named export (no branch-on-cache-type)', () => {
+    // AC-06: Two named helpers exist, no unified generic helper with
+    // branch-on-cache-type. These imports would fail at load time if either
+    // symbol is missing (the file-level import already validates this).
+    expect(typeof getOrCreateFromChain).toBe('function');
+    expect(typeof getOrCreatePerEntity).toBe('function');
+  });
+
+  it('getOrCreatePerEntity with outerKey=number hits same leaf on second call', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bg1 = getOrCreatePerEntity(outer, 42, handles, 'material', factory, counts);
+    const bg2 = getOrCreatePerEntity(outer, 42, handles, 'material', factory, counts);
+    expect(bg1).toBe(bg2);
+    expect(counts.createBindGroup).toBe(1);
+  });
+
+  it('getOrCreatePerEntity with outerKey=string hits same leaf on second call', () => {
+    // material-shared uses string outerKey (shaderId) — OQ-1 / D-1.
+    const outer = new Map<string, WeakMap<object, unknown>>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bg1 = getOrCreatePerEntity(
+      outer,
+      'pbr-standard',
+      handles,
+      'material-shared',
+      factory,
+      counts,
+    );
+    const bg2 = getOrCreatePerEntity(
+      outer,
+      'pbr-standard',
+      handles,
+      'material-shared',
+      factory,
+      counts,
+    );
+    expect(bg1).toBe(bg2);
+    expect(counts.createBindGroup).toBe(1);
+  });
+
+  it('getOrCreatePerEntity: different outerKey produces different leaf', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bgA = getOrCreatePerEntity(outer, 1, handles, 'material', factory, counts);
+    const bgB = getOrCreatePerEntity(outer, 2, handles, 'material', factory, counts);
+    expect(bgA).not.toBe(bgB);
+  });
+});
+
+// ─── w20: HDRP shadow-instances cross-function producer/consumer pair (D-4) ──
+//
+// recordShadowPass writes the shadow-instances BG at render-system-record.ts
+// :3438 via getOrCreatePerEntity(instancesBgPerEntity, entityKey,
+// [instBuffer], 'shadow-instances', ...). The HDRP main pass reads it back at
+// :3825 NOT through the helper, but with a manual two-step lookup:
+//   instancesBgPerEntity.get(entityKey)?.get(instBuffer) as Map<string, BG>
+//   leaf?.get('shadow-instances')
+// If the read end used a different outerKey or handle than the write end, the
+// lookup would miss, the main pass would `continue`, and instanced shadows
+// would silently vanish. HDRP shadow pass has no dawn smoke and the HDRP
+// browser tests only assert BGL slots / gbuffer formats (not shadow-instance
+// draws), so this invariant is otherwise untested (research OQ-2). These tests
+// fixate the D-4 contract: the manual read shape must find the helper write.
+
+describe('w20 — HDRP shadow-instances cross-function read finds helper write (D-4)', () => {
+  const SHADOW_INSTANCES_VARIANT = 'shadow-instances';
+
+  // Mirrors the :3825 read end: two WeakMap hops + variant leaf lookup.
+  function readShadowInstancesBg(
+    outer: Map<number, WeakMap<object, unknown>>,
+    entityKey: number,
+    instBuffer: object,
+  ): BindGroup | undefined {
+    const leaf = outer.get(entityKey)?.get(instBuffer) as Map<string, BindGroup> | undefined;
+    return leaf?.get(SHADOW_INSTANCES_VARIANT);
+  }
+
+  it('read end finds the leaf the write end stored under the same (entityKey, instBuffer)', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const entityKey = 7;
+    const instBuffer = h(); // the shared instance buffer handle (single-handle chain)
+    const counts = stubCounts();
+
+    // Write end (:3438): recordShadowPass populates the per-entity leaf.
+    const written = getOrCreatePerEntity(
+      outer,
+      entityKey,
+      [instBuffer],
+      SHADOW_INSTANCES_VARIANT,
+      factory,
+      counts,
+    );
+
+    // Read end (:3825): HDRP main pass resolves it with the same pair.
+    const read = readShadowInstancesBg(outer, entityKey, instBuffer);
+
+    expect(read).toBeDefined();
+    expect(read).toBe(written);
+    expect(counts.createBindGroup).toBe(1); // single create, then a hit on read
+  });
+
+  it('read end misses when the entityKey differs (per-entity isolation)', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const instBuffer = h();
+    const counts = stubCounts();
+
+    getOrCreatePerEntity(outer, 7, [instBuffer], SHADOW_INSTANCES_VARIANT, factory, counts);
+
+    // Different entity, same buffer handle -> no outer-Map entry -> miss.
+    expect(readShadowInstancesBg(outer, 8, instBuffer)).toBeUndefined();
+  });
+
+  it('read end misses when the instance buffer handle differs (chain identity)', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const entityKey = 7;
+    const counts = stubCounts();
+
+    getOrCreatePerEntity(outer, entityKey, [h()], SHADOW_INSTANCES_VARIANT, factory, counts);
+
+    // Same entity, a fresh (grown) instance buffer object -> inner WeakMap miss.
+    expect(readShadowInstancesBg(outer, entityKey, h())).toBeUndefined();
+  });
+});

package/src/__tests__/block-upload-math.unit.test.ts

@@ -0,0 +1,192 @@
+// w29 -- block-aware upload math unit tests (AC-08).
+//
+// Table-driven coverage of `deriveMipUploadLayout` (render-data.ts, landed by
+// w35): the per-mip GPU-upload layout for block-compressed textures. Each mip
+// level's `bytesPerRow` pads the pixel width up to a full block
+// (`ceil(width / blockW) * bytesPerBlock`) and `rowsPerImage` counts block rows
+// (`ceil(height / blockH)`); `byteOffset` accumulates the prior levels' byte
+// lengths (mip-major layout). The GPU samples only the valid texel region, so
+// non-4-multiple sizes and the 1x1 / 2x2 mip tails pad up to a block without
+// corrupting the image (t5).
+//
+// This is TDD-RED before w35 -- `deriveMipUploadLayout` does not exist yet.
+//
+// Constraints (plan-tasks w29):
+//   - no real GPU writeTexture call (browser e2e AC-15 owns that)
+//   - no re-test of the block table contents (codec w9 owns that)
+//   - pure node unit, no browser / dawn dependency
+
+import {
+  deriveMipUploadLayout,
+  deriveTextureExtent,
+  type MipUploadLevel,
+} from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+/** Sum of every level's byte length -- the total block-byte buffer size. */
+function totalBytes(layout: readonly MipUploadLevel[]): number {
+  return layout.reduce((acc, l) => acc + l.byteLength, 0);
+}
+
+describe('deriveMipUploadLayout -- single-level block sizing (w29)', () => {
+  // BC7 = 4x4 block, 16 bytes/block. bytesPerRow = ceil(w/4)*16.
+  it.each([
+    // [width, height, expectedBytesPerRow, expectedRowsPerImage]
+    [4, 4, 16, 1], // exact single block
+    [8, 8, 32, 2], // 2x2 blocks
+    [7, 7, 32, 2], // non-4-multiple: ceil(7/4)=2 both axes
+    [1, 1, 16, 1], // 1x1 tail pads to a full block
+    [2, 2, 16, 1], // 2x2 tail pads to a full block
+    [5, 3, 32, 1], // ceil(5/4)=2 -> 32 wide, ceil(3/4)=1 tall
+    [16, 1, 64, 1], // wide sliver
+  ])('bc7 %ix%i -> bytesPerRow=%i rowsPerImage=%i', (w, h, bpr, rpi) => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', w, h, 1);
+    expect(layout).toHaveLength(1);
+    const l = layout[0] as MipUploadLevel;
+    expect(l.level).toBe(0);
+    expect(l.width).toBe(w);
+    expect(l.height).toBe(h);
+    expect(l.bytesPerRow).toBe(bpr);
+    expect(l.rowsPerImage).toBe(rpi);
+    expect(l.byteOffset).toBe(0);
+    expect(l.byteLength).toBe(bpr * rpi);
+  });
+
+  // BC1 / BC4 / ETC2-rgb8 / EAC-r11 = 4x4 block, 8 bytes/block (0.5 bpp).
+  it.each([
+    ['bc1-rgba-unorm', 8, 8, 16, 2],
+    ['bc4-r-unorm', 4, 4, 8, 1],
+    ['etc2-rgb8unorm', 16, 16, 32, 4],
+    ['eac-r11unorm', 7, 5, 16, 2],
+  ] as const)('%s %ix%i -> bytesPerRow=%i rowsPerImage=%i', (fmt, w, h, bpr, rpi) => {
+    const l = deriveMipUploadLayout(fmt, w, h, 1)[0] as MipUploadLevel;
+    expect(l.bytesPerRow).toBe(bpr);
+    expect(l.rowsPerImage).toBe(rpi);
+  });
+
+  // ASTC block dims come from the format name; all 16 bytes/block.
+  it.each([
+    ['astc-4x4-unorm', 8, 8, 32, 2],
+    ['astc-6x6-unorm', 12, 12, 32, 2], // ceil(12/6)=2 -> 32, ceil(12/6)=2
+    ['astc-8x8-unorm', 9, 9, 32, 2], // ceil(9/8)=2 both axes
+    ['astc-5x4-unorm', 5, 4, 16, 1], // one 5-wide x 4-tall block
+  ] as const)('%s %ix%i -> bytesPerRow=%i rowsPerImage=%i', (fmt, w, h, bpr, rpi) => {
+    const l = deriveMipUploadLayout(fmt, w, h, 1)[0] as MipUploadLevel;
+    expect(l.bytesPerRow).toBe(bpr);
+    expect(l.rowsPerImage).toBe(rpi);
+  });
+
+  // BC6H (HDR) = 4x4 block, 16 bytes/block -- the equirect HDR upload path.
+  it('bc6h-rgb-ufloat 4x4 -> one 16-byte block', () => {
+    const l = deriveMipUploadLayout('bc6h-rgb-ufloat', 4, 4, 1)[0] as MipUploadLevel;
+    expect(l.bytesPerRow).toBe(16);
+    expect(l.rowsPerImage).toBe(1);
+    expect(l.byteLength).toBe(16);
+  });
+});
+
+describe('deriveMipUploadLayout -- mip-major offset accumulation (w29)', () => {
+  it('bc7 8x8 4-level chain accumulates offsets with block-padded tails', () => {
+    // levels: 8x8, 4x4, 2x2, 1x1 (2x2 and 1x1 pad up to a full 4x4 block)
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 8, 8, 4);
+    expect(layout).toHaveLength(4);
+
+    const expected: readonly Pick<
+      MipUploadLevel,
+      'width' | 'height' | 'bytesPerRow' | 'rowsPerImage' | 'byteOffset' | 'byteLength'
+    >[] = [
+      { width: 8, height: 8, bytesPerRow: 32, rowsPerImage: 2, byteOffset: 0, byteLength: 64 },
+      { width: 4, height: 4, bytesPerRow: 16, rowsPerImage: 1, byteOffset: 64, byteLength: 16 },
+      { width: 2, height: 2, bytesPerRow: 16, rowsPerImage: 1, byteOffset: 80, byteLength: 16 },
+      { width: 1, height: 1, bytesPerRow: 16, rowsPerImage: 1, byteOffset: 96, byteLength: 16 },
+    ];
+    for (let i = 0; i < expected.length; i++) {
+      const l = layout[i] as MipUploadLevel;
+      expect(l.level).toBe(i);
+      expect({
+        width: l.width,
+        height: l.height,
+        bytesPerRow: l.bytesPerRow,
+        rowsPerImage: l.rowsPerImage,
+        byteOffset: l.byteOffset,
+        byteLength: l.byteLength,
+      }).toEqual(expected[i]);
+    }
+    expect(totalBytes(layout)).toBe(112);
+  });
+
+  it('bc1 non-square 12x6 3-level chain (0.5bpp) offsets are contiguous', () => {
+    // 12x6 -> 6x3 -> 3x1  (bc1 = 8 bytes/block, 4x4)
+    const layout = deriveMipUploadLayout('bc1-rgba-unorm', 12, 6, 3);
+    // level0 12x6: bpr=ceil(12/4)*8=24, rpi=ceil(6/4)=2, len=48, off=0
+    // level1 6x3:  bpr=ceil(6/4)*8=16, rpi=ceil(3/4)=1, len=16, off=48
+    // level2 3x1:  bpr=ceil(3/4)*8=8,  rpi=1,           len=8,  off=64
+    expect(layout.map((l) => l.byteOffset)).toEqual([0, 48, 64]);
+    expect(layout.map((l) => l.byteLength)).toEqual([48, 16, 8]);
+    expect(totalBytes(layout)).toBe(72);
+  });
+
+  it('single-level (no mip chain) returns one entry at offset 0', () => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 256, 256, 1);
+    expect(layout).toHaveLength(1);
+    expect(layout[0]?.byteOffset).toBe(0);
+  });
+});
+
+describe('deriveMipUploadLayout -- physical full-subresource copy extents', () => {
+  it('aligns non-block-aligned BC7 copies to physical storage', () => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 7, 5, 1);
+    expect(layout[0]?.copyWidth).toBe(8);
+    expect(layout[0]?.copyHeight).toBe(8);
+  });
+
+  it('aligns sub-block tail mip copies independently', () => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 8, 8, 4);
+    expect(layout[2]?.width).toBe(2);
+    expect(layout[2]?.copyWidth).toBe(4);
+    expect(layout[2]?.copyHeight).toBe(4);
+    expect(layout[3]?.width).toBe(1);
+    expect(layout[3]?.copyWidth).toBe(4);
+    expect(layout[3]?.copyHeight).toBe(4);
+  });
+
+  it('aligns non-square ASTC copies with its own block dimensions', () => {
+    const layout = deriveMipUploadLayout('astc-8x5-unorm', 5, 3, 1);
+    expect(layout[0]?.copyWidth).toBe(8);
+    expect(layout[0]?.copyHeight).toBe(5);
+  });
+});
+
+describe('deriveTextureExtent -- logical asset extent to physical storage extent (w35)', () => {
+  it('derives BC7 physical storage and a logical UV scale without changing logical metadata', () => {
+    expect(deriveTextureExtent('bc7-rgba-unorm', 2085, 1573)).toEqual({
+      logicalExtent: { width: 2085, height: 1573 },
+      physicalExtent: { width: 2088, height: 1576 },
+      uvScale: [2085 / 2088, 1573 / 1576],
+    });
+  });
+
+  it('derives each 4x4 tail mip independently', () => {
+    expect(deriveTextureExtent('bc7-rgba-unorm', 2, 1)).toEqual({
+      logicalExtent: { width: 2, height: 1 },
+      physicalExtent: { width: 4, height: 4 },
+      uvScale: [0.5, 0.25],
+    });
+  });
+
+  it('uses the codec block-format table for a non-4x4 format', () => {
+    expect(deriveTextureExtent('astc-6x6-unorm', 7, 8)).toEqual({
+      logicalExtent: { width: 7, height: 8 },
+      physicalExtent: { width: 12, height: 12 },
+      uvScale: [7 / 12, 8 / 12],
+    });
+  });
+
+  it('keeps uncompressed textures at identity extent and scale', () => {
+    expect(deriveTextureExtent('rgba8unorm', 17, 9)).toEqual({
+      logicalExtent: { width: 17, height: 9 },
+      physicalExtent: { width: 17, height: 9 },
+      uvScale: [1, 1],
+    });
+  });
+});

package/src/__tests__/builtin-shader-register-e2e.test.ts

@@ -0,0 +1,151 @@
+// 5 built-in shader register-time e2e (feat-20260613-material-paramschema-
+// driven-binding M4 / w25).
+//
+// Walks the post-w18/w19/w20 sidecar paramSchemas through derive() and
+// asserts that the BGL shape lines up with plan-strategy §3.4 + the
+// orchestrator Q3 reading (3-texture user region; emissive + occlusion
+// appended via appendInjection(bgl, 'lightmap')).
+//
+// Coverage matrix:
+//   - default-standard-pbr     : userRegionBindingEnd === 7
+//   - default-standard-pbr-skin: userRegionBindingEnd === 7
+//   - default-unlit            : userRegionBindingEnd === 3
+//   - sprite                   : userRegionBindingEnd === 3
+//   - shadow-caster (empty)    : userRegionBindingEnd === 0
+//
+// The fixtures mirror the engine sidecar files exactly — any drift between
+// this test and packages/shader/src/*.material.json surfaces immediately
+// (charter F2: structural, falsifiable).
+
+import { appendInjection } from '@forgeax/engine-render/internal';
+import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+// ─── post-w18 default-standard-pbr sidecar ──────────────────────────────────
+const STANDARD_PBR_SIDECAR: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+  { name: 'metallic', type: 'f32', default: 0.0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'metallicChannel', type: 'f32', default: 2.0 },
+  { name: 'roughnessChannel', type: 'f32', default: 1.0 },
+  { name: 'aoChannel', type: 'f32', default: 0.0 },
+  { name: 'extraChannel', type: 'f32', default: 0.0 },
+  { name: 'emissive', type: 'vec3', default: [0.0, 0.0, 0.0] },
+  { name: 'emissiveIntensity', type: 'f32', default: 0.0 },
+  { name: 'occlusionStrength', type: 'f32', default: 1.0 },
+  { name: 'alphaCutoff', type: 'f32', default: 0.0 },
+  { name: 'clearcoat', type: 'f32', default: 0.0 },
+  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'metallicRoughnessTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+];
+
+// ─── post-w19 default-standard-pbr-skin sidecar ────────────────────────────
+const PBR_SKIN_SIDECAR: readonly ParamSchemaEntry[] = STANDARD_PBR_SIDECAR;
+
+// ─── post-w20 default-unlit sidecar ──────────────────────────────────────────
+const UNLIT_SIDECAR: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color' },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];
+
+// ─── post-w20 sprite sidecar ─────────────────────────────────────────────────
+const SPRITE_SIDECAR: readonly ParamSchemaEntry[] = [
+  { 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 },
+  { name: 'texture', type: 'texture2d' },
+];
+
+// ─── shadow-caster (vertex-only depth pass; no per-material params) ──────────
+const SHADOW_CASTER_SIDECAR: readonly ParamSchemaEntry[] = [];
+
+describe('5 built-in shader register-time e2e (M4 / w25)', () => {
+  it('default-standard-pbr derives 1 UBO + 3 sampler/texture pairs', () => {
+    const out = derive(STANDARD_PBR_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(7);
+    expect(out.bglEntries.length).toBe(7);
+    expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
+    // Sampler-first (§D-4): odd bindings are samplers, even bindings
+    // (after the UBO) are textures.
+    expect(out.bglEntries[1]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[2]?.texture?.viewDimension).toBe('2d');
+    expect(out.bglEntries[3]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[4]?.texture?.viewDimension).toBe('2d');
+    expect(out.bglEntries[5]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[6]?.texture?.viewDimension).toBe('2d');
+    // Texture field names exposed for the loader's missing-handle gate.
+    expect([...out.textureFieldNames].sort()).toEqual(
+      ['baseColorTexture', 'metallicRoughnessTexture', 'normalTexture'].sort(),
+    );
+  });
+
+  it('default-standard-pbr-skin matches the standard-pbr layout (skinned vertex stream lives elsewhere)', () => {
+    const out = derive(PBR_SKIN_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(7);
+    expect(out.bglEntries.length).toBe(7);
+  });
+
+  it('default-unlit derives 1 UBO + 1 sampler/texture pair (userRegionBindingEnd=3)', () => {
+    const out = derive(UNLIT_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(3);
+    expect(out.bglEntries.map((e) => e.binding)).toEqual([0, 1, 2]);
+    expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
+    expect(out.bglEntries[1]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[2]?.texture?.sampleType).toBe('float');
+  });
+
+  it('sprite derives one merged UBO (numerics packed std140) + 1 sampler/texture pair', () => {
+    const out = derive(SPRITE_SIDECAR);
+    // Numerics: baseColor(16) + region(16) + pivot(8 align 8) + flipX(4)
+    //         + flipY(4) + slices(16) + sliceMode(4) collapse onto one UBO
+    // entry; texture+sampler pair follow.
+    expect(out.userRegionBindingEnd).toBe(3);
+    expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
+    expect(out.bglEntries[1]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[2]?.texture?.viewDimension).toBe('2d');
+    expect(out.uboLayout.entries.find((e) => e.name === 'baseColor')?.offset).toBe(0);
+    expect(out.uboLayout.entries.find((e) => e.name === 'region')?.offset).toBe(16);
+  });
+
+  it('shadow-caster empty schema derives empty BGL (graceful per D-12)', () => {
+    const out = derive(SHADOW_CASTER_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(0);
+    expect(out.bglEntries.length).toBe(0);
+    expect(out.uboLayout.totalBytes).toBe(0);
+  });
+
+  it('appendInjection threads userRegionBindingEnd for each shader', () => {
+    // appendInjection consumes the WebGPU-native GPUBindGroupLayoutEntry
+    // shape; derive returns the structurally compatible engine-types
+    // BindGroupLayoutEntry. The cast is structural — both share the same
+    // four resource-layout members (buffer / sampler / texture / storage
+    // texture) and the only nominal divergence is exactOptionalPropertyTypes
+    // narrowing on the @webgpu/types side.
+    type LayoutEntry = readonly GPUBindGroupLayoutEntry[];
+
+    // standard-pbr: 7 + lightmap(4) -> bindings 7..10; +ibl(7) -> 11..17
+    const pbrOut = derive(STANDARD_PBR_SIDECAR);
+    const lightmap = appendInjection(pbrOut.bglEntries as unknown as LayoutEntry, 'lightmap');
+    expect(lightmap.map((e) => e.binding)).toEqual([7, 8, 9, 10]);
+    const merged = [...(pbrOut.bglEntries as unknown as LayoutEntry), ...lightmap];
+    const ibl = appendInjection(merged, 'ibl');
+    expect(ibl.map((e) => e.binding)).toEqual([11, 12, 13, 14, 15, 16, 17]);
+
+    // unlit: 3 + shadow(2) -> bindings 3..4
+    const unlitOut = derive(UNLIT_SIDECAR);
+    const unlitShadow = appendInjection(unlitOut.bglEntries as unknown as LayoutEntry, 'shadow');
+    expect(unlitShadow.map((e) => e.binding)).toEqual([3, 4]);
+
+    // shadow-caster: 0 + shadow(2) -> bindings 0..1
+    const scOut = derive(SHADOW_CASTER_SIDECAR);
+    const scShadow = appendInjection(scOut.bglEntries as unknown as LayoutEntry, 'shadow');
+    expect(scShadow.map((e) => e.binding)).toEqual([0, 1]);
+  });
+});