@forgeax/engine-runtime 0.1.2

package/src/__tests__/pipeline-cache-keying.unit.test.ts

@@ -0,0 +1,316 @@
+import {
+  cacheKeyOf,
+  type PipelineSpec,
+  SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET,
+} from '@forgeax/engine-render/internal';
+import { KNOWN_PASS_KINDS, type PassKind, type VertexAttributeMap } from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+/*
+ * feat-20260615-pipeline-spec-ssot M2-T2: cache key axis tests migrated from
+ * materialShaderPipelineCacheKey to cacheKeyOf(spec).
+ *
+ * Post-migration: cacheKeyOf covers all 4 PipelineSpec axes (shader /
+ * attachments / geometry / renderState). The old 8-segment string construction
+ * is deleted. These tests verify equivalent cache-key semantics.
+ */
+
+const DEFAULT_VERTEX_LAYOUT: VertexAttributeMap = {
+  position: new Float32Array(0),
+  normal: new Float32Array(0),
+  uv: new Float32Array(0),
+  tangent: new Float32Array(0),
+};
+
+function specOf(
+  id: string,
+  isHdr: boolean,
+  passKind: string = 'forward',
+  topology = 'triangle-list' as const,
+  variantSet?: string,
+  sampleCount: 1 | 4 = 1,
+): PipelineSpec {
+  const colorFormat: GPUTextureFormat = isHdr
+    ? ('rgba16float' as unknown as GPUTextureFormat)
+    : ('bgra8unorm-srgb' as unknown as GPUTextureFormat);
+  const depthFormat: GPUTextureFormat =
+    passKind === 'shadow-caster'
+      ? ('depth32float' as unknown as GPUTextureFormat)
+      : ('depth24plus-stencil8' as unknown as GPUTextureFormat);
+
+  return {
+    shader: { id, passKind, variantSet },
+    attachments: {
+      colorFormats: passKind === 'shadow-caster' ? [] : [colorFormat],
+      depthFormat,
+      sampleCount,
+    },
+    geometry: {
+      topology,
+      vertexLayout: DEFAULT_VERTEX_LAYOUT,
+    },
+    renderState: undefined,
+  };
+}
+
+describe('cacheKeyOf passKind dimension', () => {
+  const SHADER_ID = 'forgeax::default-unlit';
+
+  it('same shaderId + entries produce different keys for forward vs shadow-caster', () => {
+    const forwardKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward'));
+    const shadowKey = cacheKeyOf(specOf(SHADER_ID, false, 'shadow-caster'));
+
+    expect(forwardKey).not.toBe(shadowKey);
+  });
+
+  it('same passKind + entries produce identical keys', () => {
+    const key1 = cacheKeyOf(specOf(SHADER_ID, true, 'forward'));
+    const key2 = cacheKeyOf(specOf(SHADER_ID, true, 'forward'));
+
+    expect(key1).toBe(key2);
+  });
+
+  it('default passKind is forward (backward compatibility)', () => {
+    const explicitKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward'));
+    const defaultKey = cacheKeyOf(specOf(SHADER_ID, false));
+
+    expect(defaultKey).toBe(explicitKey);
+  });
+
+  it('HDR variant + passKind both distinguish keys', () => {
+    const ldrForward = cacheKeyOf(specOf(SHADER_ID, false, 'forward'));
+    const hdrForward = cacheKeyOf(specOf(SHADER_ID, true, 'forward'));
+    const ldrShadow = cacheKeyOf(specOf(SHADER_ID, false, 'shadow-caster'));
+
+    const unique = new Set([ldrForward, hdrForward, ldrShadow]);
+    expect(unique.size).toBe(3);
+  });
+
+  it('different shaderId + same passKind produce different keys', () => {
+    const key1 = cacheKeyOf(specOf('forgeax::default-unlit', false, 'forward'));
+    const key2 = cacheKeyOf(specOf('forgeax::default-standard-pbr', false, 'forward'));
+
+    expect(key1).not.toBe(key2);
+  });
+
+  it('variantSet and passKind are orthogonal cache dimensions', () => {
+    const urpForward = cacheKeyOf(
+      specOf(
+        SHADER_ID,
+        false,
+        'forward',
+        'triangle-list',
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      ),
+    );
+    const hdrpForward = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', ''));
+    const urpShadow = cacheKeyOf(
+      specOf(
+        SHADER_ID,
+        false,
+        'shadow-caster',
+        'triangle-list',
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      ),
+    );
+    const hdrpShadow = cacheKeyOf(specOf(SHADER_ID, false, 'shadow-caster', 'triangle-list', ''));
+    const unique = new Set([urpForward, hdrpForward, urpShadow, hdrpShadow]);
+    expect(unique.size).toBe(4);
+  });
+});
+
+/*
+ * feat-20260612-hdrp-deferred-shading-learn-render-5-8 M1 / w1:
+ * PassKind 4-value closed union narrow test.
+ *
+ * AC-03: PassKind = 'forward' | 'deferred' | 'lighting' | 'shadow-caster'.
+ * The union is closed; TS exhaustive-switch without default must compile.
+ * The pre-rename value 'shadow-depth-only' must NOT be a member of the union (backwards-assert).
+ */
+describe('PassKind open string + KNOWN_PASS_KINDS (feat-20260615 D-10)', () => {
+  // M2-T4 expanded KNOWN_PASS_KINDS from 4 to 6 entries by adding 'post-process'
+  // and 'skybox' so fullscreen-post + skybox passes can route through
+  // SPEC_CONST_TABLE / getOrBuildPipeline rather than raw createRenderPipeline.
+  it('KNOWN_PASS_KINDS has exactly 7 entries', () => {
+    expect(KNOWN_PASS_KINDS).toHaveLength(7);
+  });
+
+  it('KNOWN_PASS_KINDS contains the 6 engine-shipped pass kinds', () => {
+    expect(KNOWN_PASS_KINDS).toContain('forward');
+    expect(KNOWN_PASS_KINDS).toContain('deferred');
+    expect(KNOWN_PASS_KINDS).toContain('temporal');
+    expect(KNOWN_PASS_KINDS).toContain('lighting');
+    expect(KNOWN_PASS_KINDS).toContain('shadow-caster');
+    expect(KNOWN_PASS_KINDS).toContain('post-process');
+    expect(KNOWN_PASS_KINDS).toContain('skybox');
+  });
+
+  it('shadow-caster is a valid PassKind value', () => {
+    const pk: PassKind = 'shadow-caster';
+    expect(pk).toBe('shadow-caster');
+  });
+
+  it('deferred and lighting are valid PassKind values', () => {
+    const pk1: PassKind = 'deferred';
+    const pk2: PassKind = 'lighting';
+    expect(pk1).toBe('deferred');
+    expect(pk2).toBe('lighting');
+  });
+
+  it('PassKind is an open string (assignable from any string)', () => {
+    expectTypeOf<PassKind>().toEqualTypeOf<string>();
+  });
+
+  it('PassKind accepts unknown custom strings', () => {
+    const pk: PassKind = 'custom-user-pass';
+    expect(typeof pk).toBe('string');
+  });
+});
+
+/*
+ * bug-20260615-msaa-silently-disables-custom-material-shaders M1 + M2 / m2-1:
+ * sampleCount cache-key axis (migrated to cacheKeyOf).
+ *
+ * sampleCount is part of the attachments axis in PipelineSpec.
+ * spec.sampleCount: 1 | 4 — distinct values produce distinct cache keys.
+ */
+describe('cacheKeyOf sampleCount axis', () => {
+  const SHADER_ID = 'forgeax::default-unlit';
+
+  it('sampleCount=1 produces stable key', () => {
+    const key1 = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined, 1));
+    const key2 = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined, 1));
+    expect(key1).toBe(key2);
+  });
+
+  it('sampleCount=4 produces a key distinct from count=1 (MSAA-variant slot)', () => {
+    const keyCount1 = cacheKeyOf(
+      specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined, 1),
+    );
+    const keyCount4 = cacheKeyOf(
+      specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined, 4),
+    );
+    expect(keyCount1).not.toBe(keyCount4);
+  });
+
+  it('sampleCount interacts correctly with existing axes (hdr + variantSet + passKind)', () => {
+    const key1 = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined, 1));
+    const key2 = cacheKeyOf(specOf(SHADER_ID, true, 'forward', 'triangle-list', undefined, 1));
+    const key3 = cacheKeyOf(
+      specOf(
+        SHADER_ID,
+        false,
+        'forward',
+        'triangle-list',
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+        1,
+      ),
+    );
+    const key4 = cacheKeyOf(
+      specOf(SHADER_ID, false, 'shadow-caster', 'triangle-list', undefined, 1),
+    );
+    const unique = new Set([key1, key2, key3, key4]);
+    expect(unique.size).toBe(4);
+  });
+});
+
+/*
+ * bug-20260708 M2 (b) AC-02: `cacheKeyOf` sentinel `~` distinguishes
+ * `variantSet=undefined` from canonical all-true key `''`.
+ *
+ * Before the sentinel `?? ''` collapsed both into the same segment,
+ * causing character (no SpriteInstances, variantSet=undefined) and
+ * terrain-fold (SpriteInstances batch,
+ * `SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET === ''`) requests to hit
+ * the same pipeline cache slot — the first-cached PSO wins, and both end
+ * up with the same shader module (research R-11 / R-12 flow rebuild).
+ *
+ * These assertions are the reverse falsifier for the sentinel:
+ *   1. undefined vs canonical '' (all-true) MUST produce distinct keys.
+ *   2. undefined vs an explicit `'PER_INSTANCE_REGION=true'`-style key
+ *      MUST produce distinct keys (sentinel keeps `undefined` separate
+ *      from any concrete variantSet string).
+ *   3. `''` vs an explicit `'PER_INSTANCE_REGION=true'`-style key MUST
+ *      produce distinct keys (unchanged axis discipline, sanity check
+ *      the sentinel doesn't collapse other values by accident).
+ */
+describe('cacheKeyOf variantSet sentinel (bug-20260708 AC-02)', () => {
+  const SHADER_ID = 'forgeax::sprite';
+
+  it('cacheKeyOf(variantSet=undefined) !== cacheKeyOf(variantSet="") — sentinel decouples undefined from canonical all-true', () => {
+    const undefKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined));
+    const emptyKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', ''));
+    expect(undefKey).not.toBe(emptyKey);
+  });
+
+  it('cacheKeyOf(variantSet=undefined) !== cacheKeyOf(variantSet="PER_INSTANCE_REGION=true")', () => {
+    const undefKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined));
+    const namedKey = cacheKeyOf(
+      specOf(SHADER_ID, false, 'forward', 'triangle-list', 'PER_INSTANCE_REGION=true'),
+    );
+    expect(undefKey).not.toBe(namedKey);
+  });
+
+  it('cacheKeyOf(variantSet="") !== cacheKeyOf(variantSet="PER_INSTANCE_REGION=true")', () => {
+    const emptyKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', ''));
+    const namedKey = cacheKeyOf(
+      specOf(SHADER_ID, false, 'forward', 'triangle-list', 'PER_INSTANCE_REGION=true'),
+    );
+    expect(emptyKey).not.toBe(namedKey);
+  });
+
+  it("sentinel `~` reserved: no legitimate variantSet literal in the codebase contains `~` (reverse falsifier for R-2')", () => {
+    // The sentinel `~` (ASCII 0x7E) is reserved for the `variantSet=undefined`
+    // branch of `cacheKeyOf`. This assertion pins the reserved status by
+    // enumerating known variantSet literals used by the runtime: none may
+    // contain the sentinel char. Future axis additions must not introduce
+    // `~` into any variantSet string (a new axis using `~` collides with
+    // the sentinel and re-opens the R-11 undefined-vs-empty collapse).
+    const knownVariantSets: readonly (string | undefined)[] = [
+      undefined,
+      '',
+      'PER_INSTANCE_REGION=true',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      'STORAGE_BUFFER_AVAILABLE=true',
+      SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET,
+    ];
+    for (const vs of knownVariantSets) {
+      if (vs !== undefined) {
+        expect(vs).not.toContain('~');
+      }
+    }
+  });
+});
+
+/*
+ * bug-20260708 M2 (c) AC-05: `SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET`
+ * is aligned with the canonical variant key so `findVariantByKey` on the
+ * sprite manifest returns the PIR=true+SBA=true (all-true) variant WGSL.
+ * Verifies the constant's cacheKey participates in the cache-slot space
+ * distinct from `variantSet=undefined` (per AC-02 sentinel).
+ */
+describe('SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET (bug-20260708 AC-05)', () => {
+  const SHADER_ID = 'forgeax::sprite';
+
+  it('constant equals canonical all-true key `""` (findVariantByKey resolves to PIR=true+SBA=true variant)', () => {
+    // Canonical all-true key semantics per @forgeax/engine-shader:
+    // "Empty key `""` denotes the default variant (all axes `true`)".
+    // Sprite variants are keyed as `""` for PIR=true+SBA=true.
+    expect(SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET).toBe('');
+  });
+
+  it('cacheKeyOf(spec with SPRITE_PASS_...VARIANT_SET) !== cacheKeyOf(spec with variantSet=undefined) — sentinel gate', () => {
+    const spritePassKey = cacheKeyOf(
+      specOf(
+        SHADER_ID,
+        false,
+        'forward',
+        'triangle-list',
+        SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET,
+      ),
+    );
+    const undefKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward', 'triangle-list', undefined));
+    expect(spritePassKey).not.toBe(undefKey);
+  });
+});

package/src/__tests__/pipeline-layout-selection.test.ts

@@ -0,0 +1,298 @@
+// pipeline-layout-selection.test.ts
+// feat-20260609-hdrp-cluster-fragment-ggx M4.5 / w35 (test, TDD red phase).
+//
+// Verifies that the per-variant PipelineLayout selector correctly picks
+// `hdrpPbrPipelineLayout` for HDRP variants (CLUSTER_FORWARD_AVAILABLE=true
+// or canonical '' all-true) and `pbrPipelineLayout` for URP variants
+// (CLUSTER_FORWARD_AVAILABLE=false / undefined).
+//
+// Anchors:
+//   - plan-strategy D-10: per-variant PipelineLayout (option A) -- boot-time
+//     build a second `hdrpPbrPipelineLayout` with HDRP 7-slot BGL; selector
+//     dispatches by `variantSet`.
+//   - plan-strategy D-11: variantSet `''` is canonical all-true (when the
+//     shader declares CLUSTER_FORWARD_AVAILABLE axis) -- HDRP path.
+//   - implement-decisions section 3: hotfix-1 left URP-side standard pipeline
+//     using the 1-slot pbr-mesh-array BGL, mismatching HDRP 7-slot BGL.
+//
+// Mocks:
+//   PipelineLayout is an opaque RHI handle; we use sentinel objects to test
+//   reference identity (the selector returns one of two layouts).
+//
+// TDD red phase (w35): `selectPipelineLayoutForVariant` does NOT exist and
+// pipelineState carries no `hdrpPbrPipelineLayout` field yet. Test imports
+// will fail until w36 lands the boot-time build + w37 lands the selector.
+
+import {
+  resolveMaterialShaderVariantSet,
+  selectPipelineLayoutForVariant,
+} from '@forgeax/engine-render/internal';
+import type { PipelineLayout } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+
+// Sentinel handles -- structurally `unknown` opaque tokens.
+const URP_LAYOUT = { __brand: 'urp' } as unknown as PipelineLayout;
+const HDRP_LAYOUT = { __brand: 'hdrp' } as unknown as PipelineLayout;
+// bug-20260611-skin-pipeline-layout: selector state shape now includes
+// `pbrSkinPipelineLayout`. Pre-existing HDRP/URP routing tests pass null
+// for the skin slot to keep their behaviour byte-identical to pre-bug;
+// dedicated skin-routing cases live below in their own describe block.
+const SKIN_LAYOUT = { __brand: 'skin' } as unknown as PipelineLayout;
+
+const FULL_STATE = {
+  pbrPipelineLayout: URP_LAYOUT,
+  hdrpPbrPipelineLayout: HDRP_LAYOUT,
+  pbrSkinPipelineLayout: null,
+};
+
+describe('selectPipelineLayoutForVariant -- HDRP vs URP routing (M4.5 / w35)', () => {
+  it('(a) HDRP variantSet `CLUSTER_FORWARD_AVAILABLE=true+...` -> hdrpPbrPipelineLayout', () => {
+    const layout = selectPipelineLayoutForVariant(
+      FULL_STATE,
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(layout).toBe(HDRP_LAYOUT);
+  });
+
+  it("(a) HDRP variantSet '' (canonical all-true) -> hdrpPbrPipelineLayout", () => {
+    // Per D-11: '' is the canonical all-true variant key -- equivalent to
+    // explicit `CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true`
+    // when the shader declares both axes. boot-time registers the HDRP-active
+    // entry under '' (createRenderer.ts:2483-2485), so the selector must
+    // route '' to the HDRP layout.
+    const layout = selectPipelineLayoutForVariant(FULL_STATE, '');
+    expect(layout).toBe(HDRP_LAYOUT);
+  });
+
+  it("(b) URP variantSet `CLUSTER_FORWARD_AVAILABLE=false+...' -> pbrPipelineLayout", () => {
+    const layout = selectPipelineLayoutForVariant(
+      FULL_STATE,
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(layout).toBe(URP_LAYOUT);
+  });
+
+  it('(b) URP variantSet without CLUSTER_FORWARD_AVAILABLE axis -> pbrPipelineLayout', () => {
+    // STORAGE_BUFFER_AVAILABLE-only variant (shader without the cluster axis
+    // declared). Selector must fall back to pbrPipelineLayout because the
+    // entry was not registered as HDRP-active.
+    const layout = selectPipelineLayoutForVariant(FULL_STATE, 'STORAGE_BUFFER_AVAILABLE=true');
+    expect(layout).toBe(URP_LAYOUT);
+  });
+
+  it('(c) variantSet undefined -> pbrPipelineLayout (backward-compat default)', () => {
+    const layout = selectPipelineLayoutForVariant(FULL_STATE, undefined);
+    expect(layout).toBe(URP_LAYOUT);
+  });
+
+  it('null pipelineState -> null (Camera-only / empty-manifest path)', () => {
+    expect(selectPipelineLayoutForVariant(null, '')).toBeNull();
+    expect(selectPipelineLayoutForVariant(null, undefined)).toBeNull();
+    expect(
+      selectPipelineLayoutForVariant(
+        null,
+        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      ),
+    ).toBeNull();
+  });
+
+  it('hdrpPbrPipelineLayout null but pbrPipelineLayout non-null -> graceful URP fallback for HDRP variant', () => {
+    // When manifest has the cluster axis but boot-time HDRP layout build
+    // failed (e.g., storage buffer not capable), HDRP variant falls back to
+    // URP layout instead of returning null. This avoids hard-disabling the
+    // PSO build path; the WGSL itself will be the URP variant via
+    // findVariantByKey resolution upstream.
+    const partial = {
+      pbrPipelineLayout: URP_LAYOUT,
+      hdrpPbrPipelineLayout: null,
+      pbrSkinPipelineLayout: null,
+    };
+    expect(selectPipelineLayoutForVariant(partial, '')).toBe(URP_LAYOUT);
+    expect(
+      selectPipelineLayoutForVariant(
+        partial,
+        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+      ),
+    ).toBe(URP_LAYOUT);
+  });
+
+  it('pbrPipelineLayout null -> null (URP variant has no fallback)', () => {
+    const partial = {
+      pbrPipelineLayout: null,
+      hdrpPbrPipelineLayout: HDRP_LAYOUT,
+      pbrSkinPipelineLayout: null,
+    };
+    expect(selectPipelineLayoutForVariant(partial, undefined)).toBeNull();
+    expect(
+      selectPipelineLayoutForVariant(
+        partial,
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      ),
+    ).toBeNull();
+  });
+});
+
+// bug-20260611-skin-pipeline-layout-mesh-array-bgl-2bindings:
+// dedicated tests for the LayoutKind='pbr-skin' branch + grep gate.
+describe('selectPipelineLayoutForVariant -- skin LayoutKind routing (bug-20260611)', () => {
+  it('(a) layoutKind=pbr-skin -> pbrSkinPipelineLayout', () => {
+    const state = {
+      pbrPipelineLayout: URP_LAYOUT,
+      hdrpPbrPipelineLayout: HDRP_LAYOUT,
+      pbrSkinPipelineLayout: SKIN_LAYOUT,
+    };
+    expect(selectPipelineLayoutForVariant(state, undefined, 'pbr-skin')).toBe(SKIN_LAYOUT);
+  });
+
+  it('(b) layoutKind=pbr-skin + variantSet="" -> pbrSkinPipelineLayout (skin overrides HDRP)', () => {
+    // HDRP × skin is OOS-1; skin routing wins. Tests the precedence ordering.
+    const state = {
+      pbrPipelineLayout: URP_LAYOUT,
+      hdrpPbrPipelineLayout: HDRP_LAYOUT,
+      pbrSkinPipelineLayout: SKIN_LAYOUT,
+    };
+    expect(selectPipelineLayoutForVariant(state, '', 'pbr-skin')).toBe(SKIN_LAYOUT);
+  });
+
+  it('(c) layoutKind=pbr-skin + pbrSkinPipelineLayout=null -> null (charter P3 explicit fail, AC-10)', () => {
+    // Explicit failure -- no silent fallback to URP layout. Mirrors memory
+    // anchor `hdrp-active-must-not-fallback-to-urp-pipeline`.
+    const state = {
+      pbrPipelineLayout: URP_LAYOUT,
+      hdrpPbrPipelineLayout: HDRP_LAYOUT,
+      pbrSkinPipelineLayout: null,
+    };
+    expect(selectPipelineLayoutForVariant(state, undefined, 'pbr-skin')).toBeNull();
+  });
+
+  it('(d) layoutKind=undefined + skin layout present -> still URP/HDRP path (back-compat)', () => {
+    // Existing PBR/HDRP callers (no layoutKind argument) MUST NOT pick the
+    // skin layout. AC-08 no-collateral.
+    const state = {
+      pbrPipelineLayout: URP_LAYOUT,
+      hdrpPbrPipelineLayout: HDRP_LAYOUT,
+      pbrSkinPipelineLayout: SKIN_LAYOUT,
+    };
+    expect(selectPipelineLayoutForVariant(state, undefined)).toBe(URP_LAYOUT);
+    expect(selectPipelineLayoutForVariant(state, '')).toBe(HDRP_LAYOUT);
+  });
+});
+
+describe('resolveMaterialShaderVariantSet -- backend capability routing', () => {
+  const pbrVariants = [
+    { defines: { CLUSTER_FORWARD_AVAILABLE: false, STORAGE_BUFFER_AVAILABLE: false } },
+    { defines: { CLUSTER_FORWARD_AVAILABLE: false, STORAGE_BUFFER_AVAILABLE: true } },
+    { defines: { CLUSTER_FORWARD_AVAILABLE: true, STORAGE_BUFFER_AVAILABLE: true } },
+  ];
+
+  it('rewrites the storage axis for the WebGL2 fallback', () => {
+    expect(
+      resolveMaterialShaderVariantSet(
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+        pbrVariants,
+        'wgpu-webgl2',
+        false,
+      ),
+    ).toBe('CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false');
+  });
+
+  it('preserves the requested native variant when the backend supports storage buffers', () => {
+    expect(
+      resolveMaterialShaderVariantSet(
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+        pbrVariants,
+        'webgpu',
+        true,
+      ),
+    ).toBe('CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true');
+  });
+
+  it('does not rewrite shaders without capability axes', () => {
+    expect(
+      resolveMaterialShaderVariantSet(
+        'MY_FEATURE=true',
+        [{ defines: { MY_FEATURE: true } }],
+        'wgpu-webgl2',
+        false,
+      ),
+    ).toBe('MY_FEATURE=true');
+  });
+});
+
+// bug-20260708 M2 (c) AC-04: dedicated tests for the LayoutKind='sprite-urp'
+// branch. Sprite / sprite-lit shaders reuse the URP 1-slot mesh-array
+// pipeline layout but their canonical all-true variant key ''
+// (SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET === '') MUST NOT be
+// mis-routed through the variantSet==='' -> HDRP branch. Prevents
+// R-1' device-lost when a SpriteInstances batch requests the canonical
+// PIR=true variant.
+describe('selectPipelineLayoutForVariant -- sprite-urp LayoutKind routing (bug-20260708)', () => {
+  const SPRITE_FULL_STATE = {
+    pbrPipelineLayout: URP_LAYOUT,
+    hdrpPbrPipelineLayout: HDRP_LAYOUT,
+    pbrSkinPipelineLayout: SKIN_LAYOUT,
+  };
+
+  it('(a) layoutKind=sprite-urp + variantSet=undefined -> pbrPipelineLayout (character / sprite-atlas per-entity path)', () => {
+    expect(selectPipelineLayoutForVariant(SPRITE_FULL_STATE, undefined, 'sprite-urp')).toBe(
+      URP_LAYOUT,
+    );
+  });
+
+  it('(b) layoutKind=sprite-urp + variantSet="" -> pbrPipelineLayout (SpriteInstances canonical PIR=true batch, NOT HDRP)', () => {
+    // Critical assertion. Without the sprite-urp branch the canonical ''
+    // variantSet falls into the isHdrpVariant branch of
+    // selectPipelineLayoutForVariant (variantSet === '' short-circuit) and
+    // returns HDRP_LAYOUT — a 7-slot mesh-array BGL incompatible with the
+    // sprite shader's group(2) binding shape. R-1' device-lost path.
+    expect(selectPipelineLayoutForVariant(SPRITE_FULL_STATE, '', 'sprite-urp')).toBe(URP_LAYOUT);
+  });
+
+  it('(c) layoutKind=sprite-urp overrides variantSet with CLUSTER_FORWARD_AVAILABLE=true -> URP (sprite has no HDRP variant)', () => {
+    // Sprite shaders never emit CLUSTER_FORWARD_AVAILABLE axis; this
+    // scenario is a defensive check that sprite-urp routing is stable
+    // even if some caller mis-passes an HDRP-like variantSet.
+    expect(
+      selectPipelineLayoutForVariant(
+        SPRITE_FULL_STATE,
+        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+        'sprite-urp',
+      ),
+    ).toBe(URP_LAYOUT);
+  });
+
+  it('(d) layoutKind=sprite-urp + pbrPipelineLayout=null -> null (URP layout unavailable, charter P3 explicit fail)', () => {
+    const partial = {
+      pbrPipelineLayout: null,
+      hdrpPbrPipelineLayout: HDRP_LAYOUT,
+      pbrSkinPipelineLayout: SKIN_LAYOUT,
+    };
+    expect(selectPipelineLayoutForVariant(partial, undefined, 'sprite-urp')).toBeNull();
+    expect(selectPipelineLayoutForVariant(partial, '', 'sprite-urp')).toBeNull();
+  });
+
+  it('(e) pbr-skin still wins over sprite-urp when both would apply (skin precedence anchored earlier in selector)', () => {
+    // Defensive: if a call ever lands with layoutKind='pbr-skin' + a
+    // sprite-like variantSet, the skin branch must take precedence (order
+    // of switch arms in the selector). This pins the ordering so a future
+    // reshuffle of the switch arms doesn't silently accept sprite routing
+    // for a skin caller.
+    expect(selectPipelineLayoutForVariant(SPRITE_FULL_STATE, '', 'pbr-skin')).toBe(SKIN_LAYOUT);
+  });
+});
+
+describe('selectPipelineLayoutForVariant -- unlit-urp LayoutKind routing', () => {
+  it("keeps default-unlit's canonical all-true variant on the URP layout", () => {
+    expect(selectPipelineLayoutForVariant(FULL_STATE, '', 'unlit-urp')).toBe(URP_LAYOUT);
+  });
+
+  it('keeps default-unlit false-color variants on the URP layout', () => {
+    expect(
+      selectPipelineLayoutForVariant(
+        FULL_STATE,
+        'STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+        'unlit-urp',
+      ),
+    ).toBe(URP_LAYOUT);
+  });
+});