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

package/src/__tests__/dawn/zero-manifest-ready.dawn.test.ts

@@ -0,0 +1,98 @@
+// zero-manifest-ready.dawn.test.ts -- bug-20260519 AC-02 dual-impl mirror.
+//
+// This is the dawn-side counterpart of the browser AC-02 case in
+// `renderer-ready.test.ts`. The browser case uses a vitest mock GPUDevice
+// with a recorded `order[]` log to spy on `createShaderModule`; the dawn
+// project drives the real wgpu-wasm + naga binding through `rhi-wgpu`.
+// Asserting `ready.ok === true` is sufficient for the dual-impl regression
+// gate: pre-fix the unconditional Step 2 entry-scan would reject because
+// the empty manifest carries neither the `f_schlick` PBR entry nor the
+// unlit entry; post-fix the gate skips Step 2 outright, the registry
+// yields zero entries, and host construction reaches the ready state.
+//
+// AC: requirements section 4 AC-02 (Camera-only world reaches `ready ok`
+// without forcing shader compilation) projected onto the dawn / rhi-wgpu
+// path per OOS-4 dual-impl behaviour parity. plan-strategy D-1 + D-4 (test
+// matrix migration: dawn project mirror) + charter P4 (consistent
+// abstraction across rhi-webgpu / rhi-wgpu).
+
+import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../../renderer-host';
+
+const WIDTH = 64;
+const HEIGHT = 64;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+
+describe('bug-20260519 AC-02 dawn mirror: zero manifest -> ready state', () => {
+  it('runtime host without shaderManifestUrl reaches ready state on dawn', async () => {
+    const dawnAvailable = typeof globalThis.navigator?.gpu?.requestAdapter === 'function';
+    if (!dawnAvailable) {
+      throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
+    }
+
+    let sharedDevice: GPUDevice | undefined;
+    const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
+      globalThis.navigator.gpu,
+    );
+    globalThis.navigator.gpu.requestAdapter = async (opts) => {
+      const rawAdapter = await originalRequestAdapter(opts);
+      if (rawAdapter === null) return rawAdapter;
+      const originalRequestDevice = rawAdapter.requestDevice.bind(rawAdapter);
+      rawAdapter.requestDevice = async (desc) => {
+        const dev = await originalRequestDevice(desc);
+        if (sharedDevice === undefined) sharedDevice = dev;
+        return dev;
+      };
+      return rawAdapter;
+    };
+
+    let renderTarget: GPUTexture | undefined;
+    const ensureRenderTarget = (device: GPUDevice, format: GPUTextureFormat): GPUTexture => {
+      if (renderTarget !== undefined) return renderTarget;
+      renderTarget = device.createTexture({
+        size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+        format,
+        usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
+        viewFormats: ['rgba8unorm-srgb'],
+      });
+      return renderTarget;
+    };
+    const mockCanvas = {
+      width: WIDTH,
+      height: HEIGHT,
+      getContext(kind: string): unknown {
+        if (kind !== 'webgpu') return null;
+        return {
+          configure(desc: { device: GPUDevice; format?: GPUTextureFormat }) {
+            ensureRenderTarget(desc.device, desc.format ?? 'rgba8unorm');
+          },
+          unconfigure() {},
+          getCurrentTexture(): GPUTexture {
+            if (renderTarget === undefined) {
+              if (sharedDevice === undefined)
+                throw new Error('render target requested before device captured');
+              return ensureRenderTarget(sharedDevice, 'rgba8unorm');
+            }
+            return renderTarget;
+          },
+        };
+      },
+      addEventListener() {},
+      removeEventListener() {},
+    } as unknown as HTMLCanvasElement;
+
+    let host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
+    try {
+      // Explicit `shaderManifestUrl: undefined` opts into zero-entry mode.
+      // ShaderRegistry returns empty entries without issuing any fetch;
+      // Runtime host shader compilation is skipped entirely.
+      host = await constructRuntimeRendererHost(mockCanvas, {}, { shaderManifestUrl: undefined });
+    } finally {
+      globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
+    }
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    expect(host.value.renderer.inspect().state).toBe('alive');
+  });
+});

package/src/__tests__/demo-sortscope-migration.unit.test.ts

@@ -0,0 +1,115 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M5 / w15.
+//
+// Round-2 production migration verification: asserts the two affected
+// demos (`apps/hello/tilemap` + `apps/hello/asi-world`) actually use the
+// `sortScope`-named field and do NOT carry the retired `ySort` literal,
+// reading the demo source files directly off disk.
+//
+// What round-2 changes vs round-1:
+//   - round-1 (R-NEW-1 fallback): forward-looking migration table only;
+//     no on-disk demo file reads (target directories didn't exist yet).
+//   - round-2 (R-NEW-1 fallback graduated, D-V-3): upstream + demo
+//     directories landed via PR #502 (2026-06-26T07:24Z), so we read
+//     the actual demo source files and assert (a) `sortScope` is the
+//     spelling used, (b) `ySort` does not reappear anywhere in
+//     `apps/hello/tilemap/src/**` or `apps/hello/asi-world/src/**`
+//     (Change stance "Optimal > compatible" — no shim, no alias).
+//
+// Boundary: reads two `*.ts` source files via `node:fs`. No runtime
+// import (so a future demo bug doesn't bleed into this test failure
+// signal). The asi-world spawn must encode `sortScope: 'per-cell'`
+// (via `encodeSortScope`), the tilemap demo may either omit `sortScope`
+// (default 'layer') or pass `encodeSortScope('layer')` explicitly; both
+// shapes are accepted because the closed union's default arm and the
+// explicit arm both satisfy the migration intent.
+//
+// Anchors:
+//   - requirements.md AC-02: `ySort: 0/1` -> `sortScope: 'layer' |
+//     'per-cell'`, TS compile errors are the only migration gate.
+//   - plan-strategy.md section 7 M5: demo migration boundary, two-demo
+//     scope (hello-tilemap + asi-world).
+//   - verify-decisions D-V-3 (round-2 mandate item 4): "demo migration".
+//   - AGENTS.md Change stance: no `ySort` alias, no parallel field.
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '..', '..', '..', '..');
+
+interface DemoMigrationCase {
+  readonly demo: 'hello-tilemap' | 'hello-asi-world';
+  readonly mainTsPath: string;
+  readonly expectedSpawns: ReadonlyArray<{
+    readonly layerCategory: 'tilemap' | 'terrain' | 'object';
+    // After migration: literal that must appear in main.ts.
+    // 'per-cell' -> demo must call `encodeSortScope('per-cell')` (or
+    //               pass the closed-union literal through TileLayerData);
+    // 'layer'    -> demo may omit `sortScope` (default) or spell 'layer'
+    //               explicitly. Both shapes are acceptable.
+    readonly postMigrationSortScope: 'layer' | 'per-cell';
+  }>;
+}
+
+const DEMO_CASES: readonly DemoMigrationCase[] = [
+  {
+    demo: 'hello-tilemap',
+    mainTsPath: resolve(REPO_ROOT, 'apps', 'hello', 'tilemap', 'src', 'main.ts'),
+    expectedSpawns: [{ layerCategory: 'tilemap', postMigrationSortScope: 'layer' }],
+  },
+  {
+    demo: 'hello-asi-world',
+    mainTsPath: resolve(REPO_ROOT, 'apps', 'hello', 'asi-world', 'src', 'main.ts'),
+    expectedSpawns: [
+      { layerCategory: 'terrain', postMigrationSortScope: 'layer' },
+      { layerCategory: 'object', postMigrationSortScope: 'per-cell' },
+    ],
+  },
+];
+
+describe('demo sortScope migration (w15, round-2 production)', () => {
+  it.each(DEMO_CASES)('$demo main.ts exists and is readable', ({ mainTsPath }) => {
+    // readFileSync throws if absent; reaching the .length read implies success.
+    const src = readFileSync(mainTsPath, 'utf8');
+    expect(src.length).toBeGreaterThan(0);
+  });
+
+  it.each(DEMO_CASES)('$demo main.ts does NOT carry the retired ySort field', ({ mainTsPath }) => {
+    const src = readFileSync(mainTsPath, 'utf8');
+    const ySortFieldRe = /\bySort\s*:/;
+    expect(src).not.toMatch(ySortFieldRe);
+  });
+
+  it('hello-tilemap demo defaults sortScope to layer (no per-cell call)', () => {
+    const tilemapCase = DEMO_CASES.find((c) => c.demo === 'hello-tilemap');
+    if (tilemapCase === undefined) throw new Error('hello-tilemap case missing');
+    const src = readFileSync(tilemapCase.mainTsPath, 'utf8');
+    expect(src).not.toMatch(/TilemapSort\.perCell/);
+  });
+
+  it("asi-world demo encodes sortScope: 'per-cell' for the object TileLayer", () => {
+    const asiCase = DEMO_CASES.find((c) => c.demo === 'hello-asi-world');
+    if (asiCase === undefined) throw new Error('asi-world case missing');
+    const src = readFileSync(asiCase.mainTsPath, 'utf8');
+    expect(src).toMatch(/TilemapSort\.perCell/);
+  });
+
+  it('asi-world demo imports the grouped TilemapSort authoring value', () => {
+    const asiCase = DEMO_CASES.find((c) => c.demo === 'hello-asi-world');
+    if (asiCase === undefined) throw new Error('asi-world case missing');
+    const src = readFileSync(asiCase.mainTsPath, 'utf8');
+    expect(src).toMatch(/TilemapSort/);
+    expect(src).toMatch(/@forgeax\/engine-render\/authoring/);
+  });
+
+  it('migration covers both terrain semantics (layer) and object semantics (per-cell)', () => {
+    const scopes = new Set<string>();
+    for (const c of DEMO_CASES) {
+      for (const s of c.expectedSpawns) scopes.add(s.postMigrationSortScope);
+    }
+    expect(scopes.has('layer')).toBe(true);
+    expect(scopes.has('per-cell')).toBe(true);
+  });
+});

package/src/__tests__/derive-bgl-integration.test.ts

@@ -0,0 +1,388 @@
+// derive-bgl-integration.test.ts -- M3 / w11 integration test for derive(schema)
+// integration into the BGL build path consumed by installMaterialArtifact-like
+// register-time validation.
+//
+// feat-20260613-material-paramschema-driven-binding M3 / w11.
+//
+// Decision anchors (plan-strategy §2):
+//   - D-2  derive(schema) is the pure SSOT for BGL / UBO / loader lookup tables.
+//   - D-3  consecutive numeric entries are run-merged into one UBO entry.
+//   - D-4  texture* family entries auto-pair a filtering sampler at binding+1.
+//   - D-12 empty schema is graceful: bglEntries=[] / totalBytes=0.
+//
+// What this test asserts (M3 scope, narrow):
+//   (a) derive(schema) over each of the 5 built-in shader sidecar shapes
+//       returns a well-formed bglEntries array consistent with the rest of
+//       the derive output (textureFieldNames / samplerForTexture map /
+//       userRegionBindingEnd advances by exactly the entries created).
+//   (b) bglEntries[i].binding values are unique and dense from 0..N-1, so
+//       that a downstream device.createBindGroupLayout({entries}) call would
+//       accept them without renumbering. The assertion runs against synthetic
+//       schemas representative of each built-in shader; the real WGSL @binding
+//       numbers are renumbered to match in M4 (plan-strategy §3.4 table).
+//   (c) record-stage byte packing aligns with derive(...).uboLayout: the
+//       sequence of (offset, size) for the merged-UBO field run is the
+//       std140 walk produced by derive — caller writes scalars at the
+//       reported offsets and the totalBytes is the buffer allocation size.
+
+import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { appendInjection } from '../../../render/src/pbr-pipeline';
+
+// ─── Synthetic schemas (one per built-in shader family) ─────────────────────
+//
+// These mirror the *intended* schemas after M4 sidecar updates. The current
+// .material.json sidecars (research F-1) are misaligned with WGSL @binding
+// numbers; M3 here verifies the derive plumbing works on well-formed schemas
+// — M4 brings the real sidecars into alignment.
+
+const standardPbrSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'metallicChannel', type: 'f32', default: 2 },
+  { name: 'roughnessChannel', type: 'f32', default: 1 },
+  { name: 'aoChannel', type: 'f32', default: 0 },
+  { name: 'extraChannel', type: 'f32', default: 0 },
+  { name: 'emissive', type: 'vec3', default: [0, 0, 0] },
+  { name: 'emissiveIntensity', type: 'f32', default: 0 },
+  { name: 'occlusionStrength', type: 'f32', default: 1 },
+  { name: 'alphaCutoff', type: 'f32', default: 0 },
+  { name: 'clearcoat', type: 'f32', default: 0 },
+  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'metallicRoughnessTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+  { name: 'emissiveTexture', type: 'texture2d' },
+];
+
+const skinSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'metallicRoughnessTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+];
+
+const unlitSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];
+
+const spriteSchema: readonly ParamSchemaEntry[] = [
+  { name: 'tint', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];
+
+const shadowCasterSchema: readonly ParamSchemaEntry[] = [];
+
+const builtinSchemas: ReadonlyArray<{ id: string; schema: readonly ParamSchemaEntry[] }> = [
+  { id: 'forgeax::default-standard-pbr', schema: standardPbrSchema },
+  { id: 'forgeax::pbr-skin', schema: skinSchema },
+  { id: 'forgeax::default-unlit', schema: unlitSchema },
+  { id: 'forgeax::sprite', schema: spriteSchema },
+  { id: 'forgeax::default-shadow-caster', schema: shadowCasterSchema },
+];
+
+describe('derive(schema) integration over 5 built-in shader families (M3 w11)', () => {
+  it('(a) every built-in shader derives a well-formed BGL with consistent userRegionBindingEnd', () => {
+    for (const { id, schema } of builtinSchemas) {
+      const out = derive(schema);
+      // bglEntries length == userRegionBindingEnd (every entry consumes
+      // exactly one binding slot under the run-merging rule of D-3).
+      expect(out.bglEntries.length, `${id}: bglEntries.length === userRegionBindingEnd`).toBe(
+        out.userRegionBindingEnd,
+      );
+      // textureFieldNames is a subset of the schema names.
+      const schemaNames = new Set(schema.map((e) => e.name));
+      for (const tex of out.textureFieldNames) {
+        expect(schemaNames.has(tex), `${id}: textureFieldName '${tex}' is in schema`).toBe(true);
+      }
+      // samplerForTexture maps each texture name to '<tex>_sampler'.
+      for (const [tex, samp] of out.samplerForTexture) {
+        expect(samp).toBe(`${tex}_sampler`);
+      }
+    }
+  });
+
+  it('(b) bglEntries[i].binding values are unique and dense from 0..N-1', () => {
+    for (const { id, schema } of builtinSchemas) {
+      const out = derive(schema);
+      const bindings = out.bglEntries.map((e) => e.binding);
+      // unique
+      expect(new Set(bindings).size, `${id}: binding values unique`).toBe(bindings.length);
+      // dense from 0..N-1
+      for (let i = 0; i < bindings.length; i++) {
+        expect(bindings, `${id}: bglEntries[${i}].binding === ${i}`).toContain(i);
+      }
+    }
+  });
+
+  it('(c) record-stage packing aligns with uboLayout offsets (totalBytes >= last field offset+size)', () => {
+    for (const { id, schema } of builtinSchemas) {
+      const out = derive(schema);
+      const fields = out.uboLayout.entries;
+      // offsets are non-decreasing.
+      for (let i = 1; i < fields.length; i++) {
+        const prev = fields[i - 1];
+        const cur = fields[i];
+        if (prev === undefined || cur === undefined) continue;
+        expect(
+          cur.offset,
+          `${id}: field[${i}].offset >= field[${i - 1}].offset+size`,
+        ).toBeGreaterThanOrEqual(prev.offset + prev.size);
+      }
+      // totalBytes covers the last field exactly (or is 0 when no fields).
+      if (fields.length === 0) {
+        expect(out.uboLayout.totalBytes, `${id}: empty schema totalBytes==0`).toBe(0);
+      } else {
+        const last = fields[fields.length - 1];
+        if (last !== undefined) {
+          expect(
+            out.uboLayout.totalBytes,
+            `${id}: totalBytes >= last.offset+size`,
+          ).toBeGreaterThanOrEqual(last.offset + last.size);
+        }
+      }
+    }
+  });
+
+  it('(d) shadow-caster (empty schema) is graceful (D-12)', () => {
+    const out = derive(shadowCasterSchema);
+    expect(out.bglEntries).toEqual([]);
+    expect(out.uboLayout.totalBytes).toBe(0);
+    expect(out.userRegionBindingEnd).toBe(0);
+    expect(out.textureFieldNames.size).toBe(0);
+  });
+});
+
+// ─── M1 regression fence: built-in standard PBR derive + injection ───────────
+//
+// feat-20260621-learn-render-5-5-parallax-mapping-demo-aligned-wit M1 / w1
+//
+// Characterises today's derived pbr-material-merged layout so M2's
+// refactor (derived BGL replaces fixed base-7) is validated bit-for-bit.
+//
+// Layout (verified against pbr-pipeline.ts + default-standard-pbr.material.json):
+//   user-region:    binding 0 (UBO, 15 numeric run-merged) + 4 sampler/texture pairs
+//                   = 9 entries, userRegionBindingEnd = 9
+//   ibl injection:  binding 9..15 (7 entries: irradiance/prefilter cube + brdfLut 2d +
+//                   3 samplers + intensity uniform)
+//   lightmap inj.:  binding 16..19 (4 entries: emissive sampler+tex + occlusion sampler+tex)
+//   total:          20 entries, bindings 0..19 dense.
+//
+// Invariant: injection start == userRegionBindingEnd (NOT hardcoded 7);
+//           injection order ibl-then-lightmap (D-8).
+
+// Exact paramSchema from packages/shader/src/default-standard-pbr.material.json:68-77
+// (15 numeric entries + 4 texture2d entries).
+const defaultStandardPbrSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'metallicChannel', type: 'f32', default: 2 },
+  { name: 'roughnessChannel', type: 'f32', default: 1 },
+  { name: 'aoChannel', type: 'f32', default: 0 },
+  { name: 'extraChannel', type: 'f32', default: 0 },
+  { name: 'emissive', type: 'vec3', default: [0, 0, 0] },
+  { name: 'emissiveIntensity', type: 'f32', default: 0 },
+  { name: 'occlusionStrength', type: 'f32', default: 1 },
+  { name: 'alphaCutoff', type: 'f32', default: 0 },
+  { name: 'clearcoat', type: 'f32', default: 0 },
+  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
+  { name: 'specularTint', type: 'vec3', default: [1, 1, 1] },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'metallicRoughnessTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+  { name: 'specularTintTexture', type: 'texture2d' },
+];
+
+describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
+  it('w1 user-region: derive produces 9 entries (binding 0 UBO + 4 sampler/texture pairs), userRegionBindingEnd=9', () => {
+    const out = derive(defaultStandardPbrSchema);
+
+    // 15 numeric entries run-merged into binding 0 UBO + 4 textures x 2 = 1 + 8 = 9.
+    expect(out.bglEntries.length).toBe(9);
+    expect(out.userRegionBindingEnd).toBe(9);
+
+    // Bindings 0..6 dense, no gaps.
+    const bindings = out.bglEntries.map((e) => e.binding);
+    expect(new Set(bindings).size).toBe(9);
+    for (let i = 0; i < 9; i++) {
+      expect(bindings).toContain(i);
+    }
+
+    // binding 0 is the UBO (uniform buffer).
+    expect(out.bglEntries[0]?.binding).toBe(0);
+    expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
+
+    // textureFieldNames covers exactly the 4 texture2d entries.
+    expect(out.textureFieldNames.size).toBe(4);
+    expect(out.textureFieldNames.has('baseColorTexture')).toBe(true);
+    expect(out.textureFieldNames.has('metallicRoughnessTexture')).toBe(true);
+    expect(out.textureFieldNames.has('normalTexture')).toBe(true);
+    expect(out.textureFieldNames.has('specularTintTexture')).toBe(true);
+
+    // sampler map: each texture has a paired sampler.
+    expect(out.samplerForTexture.size).toBe(4);
+    expect(out.samplerForTexture.get('baseColorTexture')).toBe('baseColorTexture_sampler');
+    expect(out.samplerForTexture.get('metallicRoughnessTexture')).toBe(
+      'metallicRoughnessTexture_sampler',
+    );
+    expect(out.samplerForTexture.get('normalTexture')).toBe('normalTexture_sampler');
+    expect(out.samplerForTexture.get('specularTintTexture')).toBe('specularTintTexture_sampler');
+  });
+
+  it('w1 full pipeline: derive + ibl injection + lightmap injection = 20 entries dense 0..19', () => {
+    const out = derive(defaultStandardPbrSchema);
+    // Same cast as append-injection.test.ts — forgeax shim → @webgpu/types via
+    // explicit two-step `as unknown as`, exempt from RHI gate j.
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+
+    // Injection start = userRegionBindingEnd (NOT a hardcoded 7 literal).
+    const afterIbl = appendInjection(userBgl, 'ibl');
+    expect(afterIbl.length).toBe(7);
+    expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd); // 9
+
+    const mergedAfterIbl = [...userBgl, ...afterIbl];
+
+    const afterLightmap = appendInjection(mergedAfterIbl, 'lightmap');
+    expect(afterLightmap.length).toBe(4);
+    expect(afterLightmap[0]?.binding).toBe(mergedAfterIbl.length); // 16
+
+    const fullSet = [...mergedAfterIbl, ...afterLightmap];
+    expect(fullSet.length).toBe(20);
+
+    // Bindings 0..17 dense, no gaps.
+    const bindings = fullSet.map((e) => e.binding);
+    expect(new Set(bindings).size).toBe(20);
+    for (let i = 0; i < 20; i++) {
+      expect(bindings).toContain(i);
+    }
+
+    // IBL injection starts at userRegionBindingEnd (the dynamic path, not a constant).
+    // This is the key invariant: if derive produces a different userRegionBindingEnd
+    // (e.g. 9 for a 4-texture schema), injection starts at that value, not at 7.
+    expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd);
+    expect(afterLightmap[0]?.binding).toBe(out.userRegionBindingEnd + afterIbl.length);
+
+    // D-8: injection order is ibl-then-lightmap.
+    // IBL entries (7) precede lightmap entries (4) after the user-region.
+    const iblBindings = afterIbl.map((e) => e.binding);
+    const lightmapBindings = afterLightmap.map((e) => e.binding);
+    for (const b of iblBindings) {
+      for (const lb of lightmapBindings) {
+        expect(b).toBeLessThan(lb as number);
+      }
+    }
+  });
+
+  it('w1 injection start is userRegionBindingEnd, not a hardcoded literal', () => {
+    const out = derive(defaultStandardPbrSchema);
+    // Prove that userRegionBindingEnd (9 today) is what feeds injection, not a
+    // hardcoded constant embedded in test logic. The derive() output IS the SSOT.
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+
+    const afterIbl = appendInjection(userBgl, 'ibl');
+    // The first IBL entry's binding MUST equal out.userRegionBindingEnd.
+    // If someone changes appendInjection to use a hardcoded 7, and
+    // derive later shifts userRegionBindingEnd (e.g. to 9 for 4-texture),
+    // this assertion catches the desync.
+    expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd);
+    // read-back guard: confirm the derive result really is 9 today.
+    expect(out.userRegionBindingEnd).toBe(9);
+  });
+});
+
+// ─── M2 / w2: 5-texture custom schema derive (heightTexture shifts injection) ──
+//
+// feat-20260621-learn-render-5-5-parallax-mapping-demo-aligned-wit M2 / w2
+//
+// A custom parallax shader declares a 5th texture (heightTexture) on top of the
+// 4 standard user-region textures. derive() already handles arbitrary texture
+// counts (it is the SSOT) — this test characterises that the 4th texture earns
+// a distinct sampler/texture binding pair and that the engine-injection region
+// (IBL / lightmap) shifts its start binding by exactly one sampler/texture slot
+// pair relative to the 3-texture baseline. The point of failure is NOT derive()
+// (which is correct today) but the pipeline-layout build path that until M2 did
+// not consume bglEntries — that gap is closed by w5/w6.
+//
+// Layout for the 5-texture schema:
+//   binding 0       : UBO (numeric run-merge)
+//   binding 1/2     : baseColorTexture       (sampler / texture)
+//   binding 3/4     : metallicRoughnessTexture
+//   binding 5/6     : normalTexture
+//   binding 9/10    : heightTexture          (the NEW 5th texture)
+//   userRegionBindingEnd = 11 (4-texture baseline was 9 — shifted +2)
+
+const parallax4TextureSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'heightScale', type: 'f32', default: 0.1 },
+  { name: 'algoMode', type: 'f32', default: 0 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'metallicRoughnessTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+  { name: 'specularTintTexture', type: 'texture2d' },
+  { name: 'heightTexture', type: 'texture2d' },
+];
+
+describe('5-texture custom schema derive: heightTexture binding + injection shift (M2 w2)', () => {
+  it('(a) heightTexture earns a distinct sampler(7)/texture(8) binding pair', () => {
+    const out = derive(parallax4TextureSchema);
+
+    // textureFieldNames covers all 5 declared textures.
+    expect(out.textureFieldNames.size).toBe(5);
+    expect(out.textureFieldNames.has('heightTexture')).toBe(true);
+    expect(out.samplerForTexture.get('heightTexture')).toBe('heightTexture_sampler');
+
+    // 1 UBO + 5 sampler/texture pairs = 11 entries.
+    expect(out.bglEntries.length).toBe(11);
+
+    // heightTexture is the 5th texture: sampler at binding 9, texture at binding 10.
+    // (after baseColor 1/2, MR 3/4, normal 5/6, specular tint 7/8).
+    const heightSampler = out.bglEntries[9];
+    const heightTexture = out.bglEntries[10];
+    expect(heightSampler?.binding).toBe(9);
+    expect(heightSampler?.sampler).toBeDefined();
+    expect(heightTexture?.binding).toBe(10);
+    expect(heightTexture?.texture).toBeDefined();
+  });
+
+  it('(b) userRegionBindingEnd=11 (4-texture baseline 9, shifted +2 by heightTexture)', () => {
+    const baseline = derive(defaultStandardPbrSchema);
+    const parallax = derive(parallax4TextureSchema);
+    expect(baseline.userRegionBindingEnd).toBe(9);
+    expect(parallax.userRegionBindingEnd).toBe(11);
+    // Exactly one sampler/texture pair (2 bindings) of shift.
+    expect(parallax.userRegionBindingEnd - baseline.userRegionBindingEnd).toBe(2);
+  });
+
+  it('(c) ibl injection start = userRegionBindingEnd (11), shifted +2 vs 4-texture baseline (9)', () => {
+    const out = derive(parallax4TextureSchema);
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+
+    const afterIbl = appendInjection(userBgl, 'ibl');
+    // Injection start follows derive().userRegionBindingEnd dynamically — for a
+    // 5-texture schema that is 11, not the 4-texture baseline's 9.
+    expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd);
+    expect(afterIbl[0]?.binding).toBe(11);
+
+    const mergedAfterIbl = [...userBgl, ...afterIbl];
+    const afterLightmap = appendInjection(mergedAfterIbl, 'lightmap');
+    // Lightmap follows IBL: 11 + 7 = 18.
+    expect(afterLightmap[0]?.binding).toBe(18);
+
+    // Full set: 11 user-region + 7 ibl + 4 lightmap = 22 entries, dense 0..21.
+    const fullSet = [...mergedAfterIbl, ...afterLightmap];
+    expect(fullSet.length).toBe(22);
+    const bindings = fullSet.map((e) => e.binding);
+    expect(new Set(bindings).size).toBe(22);
+    for (let i = 0; i < 22; i++) {
+      expect(bindings).toContain(i);
+    }
+  });
+});