@forgeax/engine-render 0.1.23 → 0.1.25

package/src/assembly/material-shader-policy.ts

@@ -0,0 +1,932 @@
+// Material shader policy and async adapter.
+// Variant selection, module caching, and manifest material preparation stay
+// independent from renderer lifetime and generation-scoped ready state.
+
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { PipelineLayout, Result, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  findVariantByKey,
+  type MaterialShaderManifestEntry,
+  type ShaderCatalog,
+  type ShaderCatalogDevice,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+  standardPhysicalTextureFields,
+} from '@forgeax/engine-shader';
+import type { AssetGuid as AssetGuidType, ParamSchemaEntry } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
+import type { RenderFeatureMaterialShaderBindingContract } from '../features/plan';
+import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
+import type { RhiErrorListenerRegistry } from '../lifecycle';
+import { assertStorageBufferCap } from '../light-buffer-layout';
+import { buildPbrMaterialUserRegionEntries } from '../pbr-pipeline';
+import {
+  deriveExtendedLightingCapability,
+  extendedLightingSampledTextureCapacityAvailable,
+} from '../prepare/extended-lighting/resources';
+import { STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES } from './shader-prewarm-policy';
+
+/**
+ * Sync-shaped `ShaderCatalogDevice` adapter wrapping the backend pack's
+ * async `createShaderModule(rhiDevice, desc)`.
+ *
+ * Shape: fire-and-forget pre-bake — the first call for hash X returns
+ * `Result.err(RhiError)` (a pending signal) while kicking off the async
+ * createShaderModule + cache write; subsequent calls for the same hash hit
+ * the cache and return `Result.ok(ShaderModule)` (charter proposition 9
+ * graceful degradation).
+ *
+ * @placeholder M3 scope limit: the full async pre-bake wiring is delivered
+ * by the ECS-driven render pipeline (later closure). The current shape is
+ * already enough to support MVP-2.2 instance-per-engine + AI consumer
+ * onboarding (charter proposition 1 progressive disclosure / proposition 4
+ * explicit failure with retry guidance in the error hint).
+ */
+/**
+ * Extended ShaderCatalogDevice contract for engine internals: adds a
+ * `seedModule(label, module)` to populate the lazy adapter cache from an
+ * already-compiled module, so eager-built modules (PBR / unlit / shadow
+ * caster) and the lazy MaterialShader pipeline cache share one cache and
+ * the lazy path is hit-on-first-call (no 1-frame warmup) for engine-shipped
+ * shaders. Externally still typed as ShaderCatalogDevice (see callers in
+ * ShaderCatalog).
+ */
+export interface ShaderDeviceAdapterInternal extends ShaderCatalogDevice {
+  /**
+   * feat-20260609 R3-fixup: seed the adapter's moduleCache with an
+   * already-compiled ShaderModule under `label`. Used by the eager
+   * shadow_caster pre-bake so the lazy PSO build hit on
+   * `module-forgeax::default-shadow-caster` returns OK on frame 1.
+   */
+  seedModule(label: string, module: ShaderModule): void;
+  invalidateModule(label: string): void;
+}
+
+type ShaderModuleAdapterMode = 'validated' | 'immediate';
+
+export function makeShaderDeviceAdapter(
+  rhiDevice: RhiDevice,
+  _errorRegistry: RhiErrorListenerRegistry,
+  asyncCreateShaderModule:
+    | ((
+        device: RhiDevice,
+        desc: { code: string; label?: string | undefined },
+      ) => Promise<Result<ShaderModule, RhiError>>)
+    | undefined,
+  immediateCreateShaderModule:
+    | ((
+        device: RhiDevice,
+        desc: { code: string; label?: string | undefined },
+      ) => Result<ShaderModule, RhiError>)
+    | undefined,
+  mode: ShaderModuleAdapterMode = 'validated',
+): ShaderDeviceAdapterInternal {
+  const moduleCache = new Map<string, ShaderModule>();
+  const errorCache = new Map<string, RhiError>();
+  const pending = new Map<string, number>();
+  const epochs = new Map<string, number>();
+
+  return {
+    createShaderModule(desc): Result<ShaderModule, RhiError> {
+      const key = desc.label ?? desc.code;
+      const cachedModule = moduleCache.get(key);
+      if (cachedModule !== undefined) return ok(cachedModule);
+      const cachedError = errorCache.get(key);
+      if (cachedError !== undefined) return err(cachedError);
+
+      // WebGPU's raw createShaderModule is synchronous. Only the explicitly
+      // selected immediate adapter uses that entry: generated feature programs
+      // can avoid a slow getCompilationInfo() round trip, while the default
+      // validated adapter keeps the compiler-readiness barrier for ordinary
+      // render pipelines. The public async factory still owns diagnostics;
+      // pipeline creation remains the validation point for the fast path.
+      if (mode === 'immediate' && immediateCreateShaderModule !== undefined) {
+        const immediateResult = immediateCreateShaderModule(rhiDevice, {
+          code: desc.code,
+          ...(desc.label === undefined ? {} : { label: desc.label }),
+        });
+        if (immediateResult.ok) {
+          moduleCache.set(key, immediateResult.value);
+          return immediateResult;
+        }
+        errorCache.set(key, immediateResult.error);
+        return immediateResult;
+      }
+
+      // Fire async creation; first sync call returns pending error (the AI consumer retry pattern).
+      // M3 D-P4: rhi-webgpu supplies the async factory; rhi-wgpu (no top-level
+      // async factory) falls back to the synchronous device.createShaderModule
+      // entry which already returns Result<ShaderModule, RhiError>.
+      if (!pending.has(key)) {
+        const epoch = epochs.get(key) ?? 0;
+        pending.set(key, epoch);
+        const desc2: { code: string; label?: string | undefined } = { code: desc.code };
+        if (desc.label !== undefined) desc2.label = desc.label;
+        const asyncResult: Promise<Result<ShaderModule, RhiError>> = asyncCreateShaderModule
+          ? asyncCreateShaderModule(rhiDevice, desc2)
+          : invokeDeviceCreateShaderModule(rhiDevice, desc2);
+        void asyncResult.then((result) => {
+          if (pending.get(key) !== epoch || (epochs.get(key) ?? 0) !== epoch) return;
+          if (result.ok) {
+            moduleCache.set(key, result.value);
+          } else {
+            errorCache.set(key, result.error);
+          }
+          pending.delete(key);
+        });
+      }
+
+      return err(makeRhiNotAvailableError(key));
+    },
+    seedModule(label: string, module: ShaderModule): void {
+      moduleCache.set(label, module);
+    },
+    invalidateModule(label: string): void {
+      epochs.set(label, (epochs.get(label) ?? 0) + 1);
+      moduleCache.delete(label);
+      errorCache.delete(label);
+      pending.delete(label);
+    },
+  };
+}
+
+/**
+ * Fallback path for the M3 D-P4 auto-select facade when the backend pack
+ * does not supply a top-level async `createShaderModule` (e.g. the rhi-wgpu
+ * path which routes through the synchronous `device.createShaderModule`
+ * entry, or an explicit escape-hatch instance that omits the async
+ * factory). The forgeax `RhiDevice` interface intentionally does not expose
+ * a sync `createShaderModule` (fix-f3; see packages/rhi/src/index.ts line
+ * 1164), so this helper performs a structural probe + returns a structured
+ * error when neither the async factory nor a structural sync entry exists
+ * (charter proposition 4 explicit failure baseline).
+ */
+export function invokeDeviceCreateShaderModule(
+  rhiDevice: RhiDevice,
+  desc: { code: string; label?: string | undefined },
+): Promise<Result<ShaderModule, RhiError>> {
+  const candidate = (
+    rhiDevice as RhiDevice & {
+      createShaderModule?: (d: {
+        code: string;
+        label?: string | undefined;
+      }) => Result<ShaderModule, RhiError>;
+    }
+  ).createShaderModule;
+  if (typeof candidate === 'function') {
+    try {
+      return Promise.resolve(candidate.call(rhiDevice, desc));
+    } catch (caught) {
+      const message = caught instanceof Error ? caught.message : String(caught);
+      return Promise.resolve(
+        err(
+          new RhiError({
+            code: 'shader-compile-failed',
+            expected: 'device.createShaderModule returns Result<ShaderModule, RhiError>',
+            hint: `synchronous fallback threw: ${message}`,
+          }),
+        ),
+      );
+    }
+  }
+  return Promise.resolve(
+    err(
+      new RhiError({
+        code: 'rhi-not-available',
+        expected:
+          'either RhiBackendPack.createShaderModule (async) or device.createShaderModule (sync) available',
+        hint: 'the explicit RhiInstance escape hatch must expose a top-level createShaderModule(device, desc) or RhiDevice.createShaderModule(desc) entry',
+      }),
+    ),
+  );
+}
+
+/**
+ * Synthesizes a `RhiError` with code 'rhi-not-available' for the
+ * sync-adapter pending path. AI-consumer onboarding: consume
+ * `.code === 'rhi-not-available'` → after `await loadManifest` retry
+ * `registry.get` (charter proposition 4 explicit failure + proposition 9).
+ *
+ * 'rhi-not-available' is the placeholder member of the 5-member closed
+ * union (plan-decisions OQ-P2).
+ */
+function makeRhiNotAvailableError(key: string): RhiError {
+  return new RhiError({
+    code: 'rhi-not-available',
+    expected: 'shader module pre-bake to complete asynchronously',
+    hint: `shader module '${key}' is still pending; await registry.loadManifest() finished and retry registry.get(hash) on next frame`,
+  });
+}
+
+/**
+ * bug-20260601-hello-tonemap-material-register M1: prepare engine-shipped
+ * material shaders (cap gate + manifest load + registration) before the
+ * renderer is returned so that `register<MaterialAsset>` referencing an
+ * engine shader (e.g. `forgeax::default-standard-pbr`) succeeds without
+ * waiting for `renderer.initialization` (plan-strategy D-1/D-2/D-5).
+ *
+ * Failures (cap-gate insufficient, manifest-malformed, shader-not-found)
+ * throw structured `RhiError` / `ShaderError` which propagate through
+ * `createRenderer`'s synchronous reject path (D-2 structured reject).
+ */
+export async function prepareMaterialShaders(
+  rhiDevice: RhiDevice,
+  getShader: () => ShaderCatalog,
+  assets: AssetRegistry,
+  // feat-20260629 M4: populated with uvSetCount from naga reflection JSON
+  // keyed by materialShaderId; consumed by getMaterialShaderPipeline for
+  // auto-fill of shaderUvSetCount clamp-to-last alias parameter.
+  materialShaderUvSetCounts: Map<string, number>,
+): Promise<void> {
+  const builtinGuid = (result: ReturnType<typeof AssetGuid.parse>): AssetGuidType => {
+    if (!result.ok) throw result.error;
+    return result.value;
+  };
+  // feat-20260528-material-shader-registration-unification M3 / w15:
+  // pre-computed UUIDv5 GUIDs for engine-shipped material shaders.
+  // Derived from FORGEAX_NAMESPACE (9a09805a-7623-482e-b322-9fc3591f2a38)
+  // with SHA-1 per RFC 4122 section 4.3.
+  const pbrGuidRes = AssetGuid.parse('94d85ce4-650c-54b1-a86a-eaf22696ecbc');
+  const unlitGuidRes = AssetGuid.parse('37f593ea-0c79-528c-b7f7-23d17045d776');
+  const spriteGuidRes = AssetGuid.parse('658234f6-a605-5fff-957d-7149b48fd0f4');
+  // feat-20260624-sprite-lit-shading-model-pure-2d-lighting M1' / t7: stable
+  // UUID for sprite-lit material shader (matches sprite-lit.material.json
+  // subAssets[0].guid; shader-id catalog SSOT).
+  const spriteLitGuidRes = AssetGuid.parse('f0ec6a4b-cad1-5a3d-9b4e-6d2b0fa14d8e');
+  const pbrSkinGuidRes = AssetGuid.parse('5ad0833e-2f17-56e5-a3d2-dab543afae65');
+  // feat-20260531-world-space-msdf-text-rendering M5 / w21: stable UUIDv5 for
+  // the world-space MSDF text material shader (deriveBuiltin('forgeax::msdf-text')
+  // under FORGEAX_NAMESPACE). Registered via the manifest materialShaders[]
+  // loop below alongside sprite / unlit (D-7 -- materialShaderId path).
+  const msdfTextGuidRes = AssetGuid.parse('b8f92146-3b24-519b-97a2-271419b53563');
+  const shadowCasterGuidRes = AssetGuid.parse('2e167c2a-1747-5bd7-b56d-aea9bc3f436e');
+  const pbrGuid = builtinGuid(pbrGuidRes);
+  const unlitGuid = builtinGuid(unlitGuidRes);
+  const spriteGuid = builtinGuid(spriteGuidRes);
+  const spriteLitGuid = builtinGuid(spriteLitGuidRes);
+  const pbrSkinGuid = builtinGuid(pbrSkinGuidRes);
+  const msdfTextGuid = builtinGuid(msdfTextGuidRes);
+  const shadowCasterGuid = builtinGuid(shadowCasterGuidRes);
+  const ENGINE_SHADER_GUIDS = new Map<string, AssetGuidType>([
+    ['forgeax::default-standard-pbr', pbrGuid],
+    ['forgeax::default-unlit', unlitGuid],
+    ['forgeax::sprite', spriteGuid],
+    ['forgeax::sprite-lit', spriteLitGuid],
+    ['forgeax::default-standard-pbr-skin', pbrSkinGuid],
+    ['forgeax::msdf-text', msdfTextGuid],
+    ['forgeax::default-shadow-caster', shadowCasterGuid],
+  ]);
+
+  // ── Step 0: storage-buffer cap gate ───────────────────────────────────────
+  const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
+    .maxStorageBuffersPerShaderStage;
+  const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
+  const storageBufferCapable = rhiDevice.caps.storageBuffer;
+  if (storageBufferCapable && typeof capValue === 'number') {
+    const capCheck = assertStorageBufferCap(capValue);
+    if (!capCheck.ok) throw capCheck.error;
+  }
+  const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
+  const projectorAvailable =
+    (rhiDevice.limits.maxSampledTexturesPerShaderStage ?? 0) >=
+    STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
+
+  // ── Step 1: manifest load ─────────────────────────────────────────────────
+  const registry = getShader();
+  const loaded = await registry.loadManifest();
+  if (!loaded.ok) {
+    throw loaded.error;
+  }
+
+  // ── Step 1b: material shader variant resolution + registration ───────────
+  // feat-20260609-hdrp-cluster-fragment-ggx M1 / w7: dual-axis variant
+  // resolution. At boot time isHdrpActive is always false (URP default),
+  // so CLUSTER_FORWARD_AVAILABLE=false variant is selected. HDRP variant
+  // (CLUSTER_FORWARD_AVAILABLE=true) is resolved later when
+  // clustered Standard profile activation selects the clustered variant.
+  const isHdrpActive = false; // M4: wire to actual renderSystem.frameState.isHdrpActive
+  for (const msEntry of registry.materialShaderManifestEntries()) {
+    // bug-20260610: skip synthetic non-material engine entries piggy-backing
+    // on the materialShaders channel for variant surfacing (shadow_caster).
+    // They use the `forgeax::engine-` prefix and are consumed by Step 2's
+    // engine-entry compile path, NOT by installMaterialArtifact.
+    if (msEntry.identifier.startsWith('forgeax::engine-')) continue;
+    // buildVariantKey logic: sorted key=value pairs joined with +; all-true = ''.
+    const variantDefines: Record<string, boolean> = {};
+    if (msEntry.variants.some((variant) => 'STORAGE_BUFFER_AVAILABLE' in variant.defines)) {
+      variantDefines.STORAGE_BUFFER_AVAILABLE = storageBufferCapable;
+    }
+    // User material manifests may declare WEBGL2_COMPAT alongside the shared
+    // mesh-storage axis. The fallback backend must select that authored
+    // branch at boot; otherwise it asks for the impossible bare
+    // `STORAGE_BUFFER_AVAILABLE=false` key and fails before the first frame.
+    if (msEntry.variants.some((v) => 'WEBGL2_COMPAT' in v.defines)) {
+      variantDefines.WEBGL2_COMPAT = webgl2Downlevel;
+    }
+    // Only include CLUSTER_FORWARD_AVAILABLE when the material shader declares
+    // the axis (has a variant with this key), preserving backward compat for
+    // entries without the pragma.
+    if (msEntry.variants.some((v) => 'CLUSTER_FORWARD_AVAILABLE' in v.defines)) {
+      variantDefines.CLUSTER_FORWARD_AVAILABLE = isHdrpActive;
+    }
+    if (msEntry.variants.some((v) => 'DIRECTIONAL_PCSS_AVAILABLE' in v.defines)) {
+      variantDefines.DIRECTIONAL_PCSS_AVAILABLE = directionalPcssCapable(
+        rhiDevice.caps.backendKind,
+      );
+    }
+    if (msEntry.variants.some((v) => 'VERTEX_COLOR_AVAILABLE' in v.defines)) {
+      variantDefines.VERTEX_COLOR_AVAILABLE = false;
+    }
+    if (msEntry.variants.some((v) => 'PROBE_BLEND_AVAILABLE' in v.defines)) {
+      variantDefines.PROBE_BLEND_AVAILABLE = false;
+    }
+    if (msEntry.variants.some((v) => 'EXTENDED_LIGHTING_AVAILABLE' in v.defines)) {
+      variantDefines.EXTENDED_LIGHTING_AVAILABLE = extendedLightingShaderAvailable;
+    }
+    if (
+      msEntry.identifier === 'forgeax::default-standard-pbr' &&
+      msEntry.variants.some((v) => 'PROJECTOR_AVAILABLE' in v.defines)
+    ) {
+      variantDefines.PROJECTOR_AVAILABLE = projectorAvailable;
+    }
+    if (msEntry.variants.some((v) => 'TRANSMISSION_AVAILABLE' in v.defines)) {
+      variantDefines.TRANSMISSION_AVAILABLE = false;
+    }
+    // Record-time fallback MRT is opt-in; boot the ordinary single-target
+    // Standard artifact even when the manifest declares this axis.
+    if (
+      msEntry.identifier === 'forgeax::default-standard-pbr' &&
+      msEntry.variants.some((v) => 'REFLECTION_FALLBACK_AVAILABLE' in v.defines)
+    ) {
+      variantDefines.REFLECTION_FALLBACK_AVAILABLE = false;
+    }
+    // bug-20260708 M2 (a): PER_INSTANCE_REGION axis default = false at boot.
+    // Per-entity spritePH path (`main-pass-sprite-draws.ts:511-513`) expects
+    // `variantSet=undefined` to resolve to the PIR=false shader source (64B
+    // InstanceData) via `lookup.value.source` fallback in
+    // `getMaterialShaderPipeline`. The PIR=true canonical variant (80B) is
+    // reserved for SpriteInstances batches which explicitly request it via
+    // `SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET === ''` (canonical all-
+    // true) — resolved through `findVariantByKey(msEntry, '')` in the same
+    // `getMaterialShaderPipeline` substitution branch. Mirrors the
+    // CLUSTER_FORWARD_AVAILABLE pattern above: axis default false unless
+    // explicitly requested by a caller variantSet.
+    if (msEntry.variants.some((v) => 'PER_INSTANCE_REGION' in v.defines)) {
+      variantDefines.PER_INSTANCE_REGION = false;
+    }
+    if (msEntry.variants.some((v) => 'SKINNING_DISABLED' in v.defines)) {
+      variantDefines.SKINNING_DISABLED = true;
+    }
+    const sortedEntries = Object.entries(variantDefines).sort(([a], [b]) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    );
+    const definesKey = sortedEntries.every(([, v]) => v === true)
+      ? ''
+      : sortedEntries.map(([k, v]) => `${k}=${v}`).join('+');
+    const chosen = findVariantByKey(msEntry, definesKey);
+    if (msEntry.variants.length > 0 && chosen === undefined) {
+      throw new RhiError({
+        code: 'shader-compile-failed',
+        expected: `material shader '${msEntry.identifier}' declares the exact boot variant '${definesKey}'`,
+        hint: 'regenerate the shader manifest with the complete variant Cartesian product',
+      });
+    }
+    const wgsl = chosen?.composedWgsl ?? msEntry.composedWgsl;
+    if (wgsl.length > 0) {
+      const existing = registry.findMaterialArtifact(msEntry.identifier);
+      if (existing.ok) continue;
+      const paramSchema = JSON.parse(
+        msEntry.paramSchema,
+      ) as readonly import('@forgeax/engine-types').ParamSchemaEntry[];
+      // feat-20260613-material-paramschema-driven-binding M3 / w12-w13:
+      // paramSchema is the SSOT; the BGL is derived on demand via
+      // `derive(paramSchema).bglEntries` and consumed by
+      // buildPbrPipelineLayouts at pipeline-build time. The historical
+      // separate bind-layout sidecar field has been deleted from
+      // MaterialShaderEntry / MaterialRuntimeInfo (D-1 / D-2).
+      registry.installMaterialArtifact(msEntry.identifier, {
+        source: wgsl,
+        paramSchema,
+      });
+      // feat-20260629 M4: store uvSetCount from naga reflection for
+      // auto-fill in getMaterialShaderPipeline clamp-to-last alias.
+      if (msEntry.uvSetCount !== undefined) {
+        materialShaderUvSetCounts.set(msEntry.identifier, msEntry.uvSetCount);
+      }
+      // Sanity check the schema parses through derive — a malformed sidecar
+      // schema (e.g. unknown type literal) should fail loud at register time
+      // (charter P3 explicit failure). The derived output is discarded; the
+      // SSOT consumer is buildPbrPipelineLayouts later.
+      derive(paramSchema);
+
+      const shaderGuid = ENGINE_SHADER_GUIDS.get(msEntry.identifier);
+      if (shaderGuid !== undefined) {
+        const shaderAsset = {
+          kind: 'shader' as const,
+          name: msEntry.identifier,
+          source: wgsl,
+          paramSchema,
+        };
+        // feat-20260614 M8 (D-17): catalogue the shader asset by GUID so it is
+        // GUID-addressable; no handle minted. A shader without an engine GUID
+        // lives only in the ShaderCatalog (the installMaterialArtifact SSOT
+        // above) -- there is no GUID to catalogue it under.
+        assets.catalog(shaderGuid, shaderAsset);
+      }
+    }
+  }
+
+  // ── Step 1c: register forgeax::default-shadow-caster from its manifest identity ──
+  // feat-20260609-pipeline-driven-pass-selector-shadowcaster-via-mat M3 / T-007:
+  // The reserved material-shader identifier is the SSOT. Content heuristics are
+  // invalid here: a game-authored vertex-only shader can legitimately expose
+  // position without normal (billboards and procedural VFX commonly do), and
+  // must never be mistaken for the engine shadow caster merely because it is
+  // encountered first in the flat manifest.
+  const shadowCasterIdentifier = 'forgeax::default-shadow-caster';
+  if (!registry.findMaterialArtifact(shadowCasterIdentifier).ok) {
+    const manifestEntry = Array.from(registry.materialShaderManifestEntries()).find(
+      (candidate) => candidate.identifier === shadowCasterIdentifier,
+    );
+    if (manifestEntry !== undefined) {
+      // shadow_caster evaluates the same default Surface as Standard. Keep
+      // its generated MaterialParameters contract aligned with the Standard
+      // pipeline even when a legacy manifest omitted the material entry.
+      registry.installMaterialArtifact(shadowCasterIdentifier, {
+        source: manifestEntry.composedWgsl,
+        paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA,
+      });
+      const shaderGuid = ENGINE_SHADER_GUIDS.get(shadowCasterIdentifier);
+      if (shaderGuid !== undefined) {
+        const shaderAsset = {
+          kind: 'shader' as const,
+          name: shadowCasterIdentifier,
+          source: manifestEntry.composedWgsl,
+          paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA,
+        };
+        // feat-20260614 M8 (D-17): catalogue by GUID; no handle minted.
+        assets.catalog(shaderGuid, shaderAsset);
+      }
+    }
+  }
+}
+
+/**
+ * Per-variant PipelineLayout selector (M4.5 / D-10 option A).
+ *
+ * The HDRP variant (`CLUSTER_FORWARD_AVAILABLE=true` or canonical `''`
+ * all-true when the shader declares the cluster axis) needs the 7-slot
+ * group(2) BGL chain (`hdrpPbrPipelineLayout`); URP variants
+ * (`CLUSTER_FORWARD_AVAILABLE=false` / undefined / no axis) keep the
+ * 1-slot mesh-array BGL chain (`pbrPipelineLayout`).
+ *
+ * Returns `null` only when the URP fallback layout itself is null
+ * (Camera-only / empty-manifest path). When the HDRP layout is null but
+ * URP exists, the HDRP variant gracefully falls back to URP — the WGSL
+ * resolved upstream by `findVariantByKey` is the URP variant in that
+ * case (manifest entry with all-true definesKey === '' was registered
+ * with isHdrpActive=false at boot when storage-buffer caps are absent).
+ *
+ * Pure function — exported for unit-test access (M4.5 / w35).
+ */
+/**
+ * Closed enum of pipeline-layout kinds the selector can dispatch to.
+ *
+ * `pbr` — standard PBR (1-entry mesh-array BGL).
+ * `pbr-skin` — bug-20260611-skin-pipeline-layout: 2-entry mesh-array BGL
+ *   (binding 0 meshes + binding 1 palette) for the `forgeax::pbr-skin`
+ *   material shader.
+ * `hdrp-pbr` — feat-20260609 HDRP cluster-forward variant (7-slot group(2)
+ *   BGL substituted at slot 2).
+ * `sprite-urp` — bug-20260708 M2 (c): sprite / sprite-lit shaders reuse
+ *   the URP 1-slot mesh-array BGL (they don't declare
+ *   CLUSTER_FORWARD_AVAILABLE) but their canonical all-true variant key
+ *   `''` (`SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET`) MUST NOT trigger
+ *   the `variantSet===''` → HDRP branch of the selector. Callers
+ *   (`buildPipelineContext`) resolve `sprite-urp` from the sprite
+ *   `materialShaderId` and pass it through; the selector short-circuits
+ *   to `pbrPipelineLayout` before the HDRP check.
+ *
+ * AC-09 grep gate: the selector body (`selectPipelineLayoutForVariant`)
+ * **MUST NOT** contain literal `'forgeax::pbr-skin'` (or another
+ * shader-id literal). The caller resolves `LayoutKind` upstream and passes
+ * the structured value through (charter P4 consistent abstraction). New
+ * material-shader layouts add a `LayoutKind` member + a PipelineState slot
+ * + a switch arm here in one cut (charter P3 extensibility).
+ */
+export type LayoutKind = 'pbr' | 'pbr-skin' | 'hdrp-pbr' | 'hdrp-skin' | 'sprite-urp' | 'unlit-urp';
+
+function directionalPcssCapable(backendKind: RhiDevice['caps']['backendKind']): boolean {
+  return backendKind === 'webgpu' || backendKind === 'wgpu-native';
+}
+
+export function isSharedMaterialUserRegionCompatible(
+  paramSchema: readonly ParamSchemaEntry[],
+): boolean {
+  const withoutPhysicalMaps = (
+    schema: readonly ParamSchemaEntry[],
+  ): readonly ParamSchemaEntry[] => {
+    const excluded = new Set<string>(standardPhysicalTextureFields(schema));
+    return schema.filter((entry) => !excluded.has(entry.name) || !entry.type.startsWith('texture'));
+  };
+  const sharedSchema = withoutPhysicalMaps(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
+  const candidateSchema = withoutPhysicalMaps(paramSchema);
+  const shared = buildPbrMaterialUserRegionEntries(sharedSchema);
+  const candidate = buildPbrMaterialUserRegionEntries(candidateSchema);
+  const sharedTextureNames = [...derive(sharedSchema).textureFieldNames];
+  const candidateTextureNames = [...derive(candidateSchema).textureFieldNames];
+  if (
+    candidateTextureNames.length !== sharedTextureNames.length ||
+    candidateTextureNames.some((name, index) => name !== sharedTextureNames[index])
+  ) {
+    return false;
+  }
+  if (candidate.length > shared.length) return false;
+  return candidate.every((entry, index) => {
+    const canonical = shared[index];
+    if (canonical === undefined) return false;
+    return (
+      JSON.stringify({
+        binding: entry.binding,
+        visibility: entry.visibility,
+        buffer: entry.buffer ?? null,
+        sampler: entry.sampler ?? null,
+        texture: entry.texture ?? null,
+        storageTexture: entry.storageTexture ?? null,
+      }) ===
+      JSON.stringify({
+        binding: canonical.binding,
+        visibility: canonical.visibility,
+        buffer: canonical.buffer ?? null,
+        sampler: canonical.sampler ?? null,
+        texture: canonical.texture ?? null,
+        storageTexture: canonical.storageTexture ?? null,
+      })
+    );
+  });
+}
+
+/**
+ * Select the PBR variant that matches a fallback mesh with no COLOR_0 input.
+ * Unknown/custom material IDs may still use the legacy PBR fallback, so that
+ * path must obey the same geometry-owned vertex-color axis as registered PBR.
+ */
+export function selectNoColorPbrVariant(
+  manifestEntry: MaterialShaderManifestEntry | undefined,
+  storageBufferCapable: boolean,
+  variantSet: string | undefined,
+  extendedLightingShaderAvailable = true,
+  directionalPcssAvailable = true,
+  projectorAvailable: boolean = true,
+): MaterialShaderManifestEntry['variants'][number] | undefined {
+  const hdrpRequested = variantSet === '' || requestsClusterVariant(variantSet);
+  const probeBlendRequested = requestsProbeBlendVariant(variantSet);
+  return manifestEntry?.variants.find(
+    (variant) =>
+      variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+      (!('EXTENDED_LIGHTING_AVAILABLE' in variant.defines) ||
+        variant.defines.EXTENDED_LIGHTING_AVAILABLE === extendedLightingShaderAvailable) &&
+      variant.defines.VERTEX_COLOR_AVAILABLE === false &&
+      (!('DIRECTIONAL_PCSS_AVAILABLE' in variant.defines) ||
+        variant.defines.DIRECTIONAL_PCSS_AVAILABLE === directionalPcssAvailable) &&
+      (!('PROJECTOR_AVAILABLE' in variant.defines) ||
+        variant.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
+      (!('PROBE_BLEND_AVAILABLE' in variant.defines) ||
+        variant.defines.PROBE_BLEND_AVAILABLE === probeBlendRequested) &&
+      (!('CLUSTER_FORWARD_AVAILABLE' in variant.defines) ||
+        variant.defines.CLUSTER_FORWARD_AVAILABLE === hdrpRequested),
+  );
+}
+
+function requestsClusterVariant(variantSet: string | undefined): boolean {
+  return variantSet?.includes('CLUSTER_FORWARD_AVAILABLE=true') === true;
+}
+
+function requestsProbeBlendVariant(variantSet: string | undefined): boolean {
+  return variantSet?.includes('PROBE_BLEND_AVAILABLE=true') === true;
+}
+
+export type MaterialShaderBindingContract = RenderFeatureMaterialShaderBindingContract;
+export type MaterialShaderVertexInputContract = 'none' | 'render-material';
+
+export function resolveMaterialShaderBindingContract(
+  source: string,
+): MaterialShaderBindingContract {
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//gu, '').replace(/\/\/.*$/gmu, '');
+  const groups = [...withoutComments.matchAll(/@group\s*\(\s*(\d+)\s*\)/gu)].map((match) =>
+    Number(match[1]),
+  );
+  if (groups.length === 0) return 'group-0';
+  const declaresView =
+    /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*0\s*\)\s*var\s*<\s*uniform\s*>\s*view(?:X_naga_oil_mod_[A-Z0-9]+)?\b/u.test(
+      withoutComments,
+    );
+  const declaresSceneDepth =
+    /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*1\s*\)\s*var\s+scene_depth\s*:\s*texture_depth_2d\b/u.test(
+      withoutComments,
+    );
+  if (declaresView && declaresSceneDepth && groups.every((group) => group === 0)) {
+    return 'view-and-scene-depth';
+  }
+  if (declaresView && groups.every((group) => group === 0)) return 'view-only';
+  return groups.every((group) => group === 0) ? 'group-0-resource' : 'render-material';
+}
+
+export function resolveMaterialShaderVertexInputContract(
+  source: string,
+): MaterialShaderVertexInputContract {
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//gu, '').replace(/\/\/.*$/gmu, '');
+  const inputStructs = [...withoutComments.matchAll(/struct\s+([A-Za-z_]\w*)\s*\{([^}]*)\}/gu)]
+    .filter((match) => /@location\s*\(/u.test(match[2] ?? ''))
+    .map((match) => match[1]);
+  // WGSL vertex inputs are commonly declared in a named struct before the
+  // `@vertex` function (the engine uses `VsIn`, while package shaders often
+  // use `VertexInput`). Match the type actually passed as the first vertex
+  // parameter so fragment/output structs do not accidentally enable a
+  // vertex buffer layout for fullscreen shaders.
+  for (const inputStruct of inputStructs) {
+    if (inputStruct === undefined) continue;
+    const firstParameter = new RegExp(
+      `@vertex\\s*fn\\s+\\w+\\s*\\(\\s*\\w+\\s*:\\s*${inputStruct}\\b`,
+      'u',
+    );
+    if (firstParameter.test(withoutComments)) return 'render-material';
+  }
+  // A shader may declare a location directly on a vertex parameter rather
+  // than through a struct. Keep that contract explicit as well.
+  return /@vertex\s*fn[^{]*\([^)]*@location\s*\(/u.test(withoutComments)
+    ? 'render-material'
+    : 'none';
+}
+
+/**
+ * Resolve the number of UV sets declared by one material artifact.
+ *
+ * Runtime-published Surface programs do not necessarily have a manifest
+ * reflection row, so the authored vertex input is the fallback source of
+ * truth. The renderer then feeds this count into the geometry alias
+ * projection, which clamps missing mesh UV sets to the last available set.
+ */
+export function resolveMaterialShaderUvSetCount(
+  source: string | undefined,
+  reflectedCount?: number,
+): number | undefined {
+  if (reflectedCount !== undefined) return reflectedCount;
+  if (source === undefined) return undefined;
+
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//gu, '').replace(/\/\/.*$/gmu, '');
+  const inputStructs = [
+    ...withoutComments.matchAll(/struct\s+([A-Za-z_]\w*)\s*\{([^}]*)\}/gu),
+  ].filter((match) => /@location\s*\(/u.test(match[2] ?? ''));
+  for (const inputStruct of inputStructs) {
+    const name = inputStruct[1];
+    const body = inputStruct[2];
+    if (name === undefined || body === undefined) continue;
+    const firstParameter = new RegExp(
+      `@vertex\\s*fn\\s+\\w+\\s*\\(\\s*\\w+\\s*:\\s*${name}\\b`,
+      'u',
+    );
+    if (!firstParameter.test(withoutComments)) continue;
+    let uvSetCount = 0;
+    for (const location of body.matchAll(/@location\s*\(\s*(\d+)\s*\)\s+([A-Za-z_]\w*)/gu)) {
+      const field = location[2];
+      if (field === 'uv') {
+        uvSetCount = Math.max(uvSetCount, 1);
+        continue;
+      }
+      const uvIndex = field?.match(/^uv(\d+)_?$/u)?.[1];
+      if (uvIndex !== undefined) uvSetCount = Math.max(uvSetCount, Number(uvIndex) + 1);
+    }
+    return uvSetCount > 0 ? uvSetCount : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Select a published material artifact that matches a downlevel backend.
+ *
+ * Cooked Surface publications carry immutable backend variants in their
+ * metadata. WebGL2 must select the uniform-fallback specialization before
+ * pipeline construction so its shader, bind-group layout, and cache key stay
+ * capability-consistent.
+ */
+export function resolveMaterialShaderBackendArtifactKey(
+  materialShaderId: string,
+  backendKind: 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null',
+  artifact:
+    | {
+        readonly metadata?: Readonly<Record<string, unknown>>;
+      }
+    | undefined,
+): string {
+  if (backendKind !== 'wgpu-webgl2') return materialShaderId;
+  const variants = artifact?.metadata?.variants;
+  if (!Array.isArray(variants)) return materialShaderId;
+  const fallback = variants.find((variant): variant is { specializationKey: string } => {
+    if (typeof variant !== 'object' || variant === null) return false;
+    const candidate = variant as Record<string, unknown>;
+    return (
+      candidate.backend === 'webgl2' &&
+      candidate.capability === 'uniform-fallback' &&
+      typeof candidate.specializationKey === 'string' &&
+      candidate.specializationKey.length > 0
+    );
+  });
+  return fallback?.specializationKey ?? materialShaderId;
+}
+
+export function allowsUnlitPreparedFallback(
+  depthFormatOverride: GPUTextureFormat | null | undefined,
+  vertexLayout: string | undefined,
+  materialShaderId?: string,
+): boolean {
+  return (
+    depthFormatOverride === null &&
+    (vertexLayout === undefined || !materialShaderId?.startsWith('forgeax::'))
+  );
+}
+
+/**
+ * Prepared VFX draws own their vertex inputs and bind groups. A missing
+ * authored material shader is therefore retryable, but it is never safe to
+ * substitute the built-in PBR module: PBR declares mesh/instance groups that
+ * the VFX draw does not bind. Returning true keeps the feature on its
+ * structured next-frame recovery path instead of creating an invalid PSO.
+ */
+export function shouldDeferMissingPreparedMaterialShader(
+  vertexLayout: string | undefined,
+): boolean {
+  return (
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance
+  );
+}
+
+export function selectPipelineLayoutForVariant(
+  state: {
+    readonly pbrPipelineLayout: PipelineLayout | null;
+    readonly pbrProbePipelineLayout?: PipelineLayout | null;
+    readonly hdrpPbrPipelineLayout: PipelineLayout | null;
+    readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
+    readonly pbrSkinPipelineLayout: PipelineLayout | null;
+    readonly pbrSkinProbePipelineLayout?: PipelineLayout | null;
+    readonly hdrpSkinPipelineLayout?: PipelineLayout | null;
+  } | null,
+  variantSet: string | undefined,
+  layoutKind?: LayoutKind,
+): PipelineLayout | null {
+  if (state === null) return null;
+  const probeBlendVariant = variantSet?.includes('PROBE_BLEND_AVAILABLE=true') === true;
+  // bug-20260611: skin layout selection takes precedence over HDRP variant
+  // resolution. HDRP × skin is OOS-1 (plan-strategy R-2 — left for a
+  // dedicated feat); when an HDRP-variant skin call ever lands, we fail
+  // fast with `null` rather than silently returning the URP layout
+  // (charter P3 explicit failure, mirrors memory anchor
+  // `hdrp-active-must-not-fallback-to-urp-pipeline`).
+  if (layoutKind === 'pbr-skin') {
+    return probeBlendVariant
+      ? (state.pbrSkinProbePipelineLayout ?? null)
+      : state.pbrSkinPipelineLayout;
+  }
+  if (layoutKind === 'hdrp-skin') {
+    return state.hdrpSkinPipelineLayout ?? null;
+  }
+  // bug-20260708 M2 (c): 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 trigger
+  // the `variantSet===''` → HDRP branch below. Caller-side
+  // (`buildPipelineContext`) resolves LayoutKind='sprite-urp' from the
+  // sprite `materialShaderId`; the selector short-circuits here before
+  // the HDRP variant check reads `variantSet`. Prevents R-1'
+  // device-lost when a SpriteInstances batch requests the PIR=true
+  // canonical variant.
+  if (layoutKind === 'sprite-urp') {
+    return state.pbrPipelineLayout;
+  }
+  if (layoutKind === 'unlit-urp') {
+    return state.pbrPipelineLayout;
+  }
+  // Static PBR callers can use the canonical all-true variant key (`''`)
+  // without becoming HDRP. Keep the shader variant identity independent from
+  // the pipeline-layout identity; shadow-caster static draws use this explicit
+  // kind so their ordinary mesh bind group remains compatible with the PSO.
+  if (layoutKind === 'pbr') {
+    return probeBlendVariant ? (state.pbrProbePipelineLayout ?? null) : state.pbrPipelineLayout;
+  }
+  // HDRP variant matches when:
+  //   - layoutKind === 'hdrp-pbr' (caller-driven, future-proof), OR
+  //   - variantSet is the canonical all-true key '' (boot-time HDRP
+  //     registration produces '' when both axes resolve to true), OR
+  //   - variantSet contains `CLUSTER_FORWARD_AVAILABLE=true` substring
+  //     (record-stage caller emits the expanded form).
+  // URP variants have CLUSTER_FORWARD_AVAILABLE=false explicitly, or omit
+  // the axis altogether, or pass undefined (no variant routing).
+  // G-14 (D-11): empty-string is the canonical all-true HDRP key, so we
+  // explicitly distinguish '' vs undefined rather than using an optional-chain
+  // (charter P3: explicit failure / no implicit empty-vs-missing collapse).
+  const isHdrpVariant = layoutKind === 'hdrp-pbr';
+  if (isHdrpVariant) {
+    return probeBlendVariant
+      ? (state.hdrpProbePbrPipelineLayout ?? null)
+      : state.hdrpPbrPipelineLayout;
+  }
+  return probeBlendVariant ? (state.pbrProbePipelineLayout ?? null) : state.pbrPipelineLayout;
+}
+
+/**
+ * Resolve a requested material variant against the actual backend capabilities.
+ * Record callers use the native-capability request; the backend-owned axes
+ * must be rewritten before the request reaches shader lookup and PSO layout
+ * selection.
+ */
+export function resolveMaterialShaderVariantSet(
+  requestedVariantSet: string | undefined,
+  variants: ReadonlyArray<{
+    readonly defines: Readonly<Record<string, boolean>>;
+  }>,
+  backendKind: RhiDevice['caps']['backendKind'],
+  storageBuffer: boolean,
+  maxSampledTexturesPerShaderStageOrProjectorAvailable?: number | boolean,
+): string | undefined {
+  const declaredAxes = new Set(variants.flatMap((variant) => Object.keys(variant.defines)));
+  const declaresCapabilityVariants =
+    declaredAxes.has('WEBGL2_COMPAT') ||
+    declaredAxes.has('STORAGE_BUFFER_AVAILABLE') ||
+    declaredAxes.has('EXTENDED_LIGHTING_AVAILABLE') ||
+    declaredAxes.has('DIRECTIONAL_PCSS_AVAILABLE') ||
+    declaredAxes.has('PROJECTOR_AVAILABLE');
+  if (!declaresCapabilityVariants) return requestedVariantSet;
+
+  const requested: Record<string, boolean> = {};
+  for (const part of requestedVariantSet?.split('+') ?? []) {
+    const separator = part.indexOf('=');
+    if (separator > 0) requested[part.slice(0, separator)] = part.slice(separator + 1) === 'true';
+  }
+  const sampledTextureLimit =
+    typeof maxSampledTexturesPerShaderStageOrProjectorAvailable === 'number'
+      ? maxSampledTexturesPerShaderStageOrProjectorAvailable
+      : undefined;
+  const extendedLightingAvailable =
+    sampledTextureLimit === undefined
+      ? true
+      : backendKind !== 'wgpu-webgl2' &&
+        storageBuffer &&
+        extendedLightingSampledTextureCapacityAvailable(sampledTextureLimit);
+  const projectorAvailable =
+    typeof maxSampledTexturesPerShaderStageOrProjectorAvailable === 'boolean'
+      ? maxSampledTexturesPerShaderStageOrProjectorAvailable
+      : sampledTextureLimit === undefined
+        ? true
+        : sampledTextureLimit >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
+  const filtered: Record<string, boolean> = {};
+  for (const axis of declaredAxes) {
+    filtered[axis] =
+      axis === 'WEBGL2_COMPAT'
+        ? backendKind === 'wgpu-webgl2'
+        : axis === 'STORAGE_BUFFER_AVAILABLE'
+          ? backendKind !== 'wgpu-webgl2' && storageBuffer
+          : axis === 'SKINNING_DISABLED'
+            ? (requested[axis] ?? true)
+            : axis === 'CLUSTER_FORWARD_AVAILABLE'
+              ? storageBuffer && backendKind !== 'wgpu-webgl2' && (requested[axis] ?? false)
+              : axis === 'PER_INSTANCE_REGION'
+                ? requestedVariantSet === '' || (requested[axis] ?? false)
+                : axis === 'VERTEX_COLOR_AVAILABLE'
+                  ? requestedVariantSet === '' || (requested[axis] ?? false)
+                  : axis === 'EXTENDED_LIGHTING_AVAILABLE'
+                    ? extendedLightingAvailable
+                    : axis === 'PROBE_BLEND_AVAILABLE'
+                      ? storageBuffer && (requested[axis] ?? false)
+                      : axis === 'TRANSMISSION_AVAILABLE'
+                        ? (requested[axis] ?? false)
+                        : axis === 'DIRECTIONAL_PCSS_AVAILABLE'
+                          ? directionalPcssCapable(backendKind)
+                          : axis === 'PROJECTOR_AVAILABLE'
+                            ? projectorAvailable
+                            : (requested[axis] ?? false);
+  }
+  const sorted = Object.entries(filtered).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return sorted.every(([, value]) => value)
+    ? requestedVariantSet === undefined
+      ? undefined
+      : ''
+    : sorted.map(([name, value]) => `${name}=${value}`).join('+');
+}
+
+/**
+ * Keep a single-source material on its canonical module identity. A manifest
+ * entry with no variants cannot consume a synthesized capability or geometry
+ * axis, so carrying one into the pipeline cache only creates an uncached lazy
+ * compile beside the prewarmed source module.
+ */
+export function normalizeMaterialShaderVariantSet(
+  requestedVariantSet: string | undefined,
+  manifestEntry: MaterialShaderManifestEntry | undefined,
+): string | undefined {
+  return manifestEntry !== undefined && manifestEntry.variants.length === 0
+    ? undefined
+    : requestedVariantSet;
+}