@forgeax/engine-render 0.1.21 → 0.1.24

package/src/record/main-pass-material.ts

@@ -20,8 +20,8 @@ import {
 import {
   DEFAULT_MSDF_TEXT_PARAM_SCHEMA,
   DEFAULT_SPRITE_PARAM_SCHEMA,
-  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
 } from '@forgeax/engine-shader';
 import type {
   Handle,
@@ -38,10 +38,16 @@ import { VideoUploadUnsupportedError } from '../errors/render';
 import {
   assembleMaterialWithSkylightEntries,
   type SkylightBindGroupResources,
+  type TextureInjectionResource,
   type TransmissionBindGroupResources,
 } from '../ibl/skylight-bind-group';
+import type { IblBindingEntryInspection } from '../mesh-material-bindings';
 import type { PipelineGroup2Contract } from '../pbr-pipeline';
-import { isStandardPbrMaterialShader } from '../pbr-pipeline';
+import {
+  isCanonicalStandardPbrMaterialShader,
+  isStandardPbrMaterialShader,
+  physicalTextureFields,
+} from '../pbr-pipeline';
 import { deriveTextureExtent } from '../render-data';
 import type { MaterialSnapshot } from '../render-system-extract';
 import type { RenderTargetTextureSource } from '../targets/contracts';
@@ -50,7 +56,12 @@ import {
   resolveRenderTargetMaterialSource,
 } from '../targets/material-source';
 import type { StandardReflectionProbeBinding } from './frame-lighting';
-import type { BindGroupCounts, MaterialBgAssemblyCacheEntry } from './frame-snapshot';
+import type {
+  BindGroupCounts,
+  MaterialBgAssemblyCacheEntry,
+  RenderFrameState,
+} from './frame-snapshot';
+import { getOpaqueResourceIdentity } from './frame-snapshot';
 import { extractEntryResourceHandle, getOrCreatePerEntity } from './mesh-ssbo';
 import {
   type PipelineState,
@@ -232,6 +243,18 @@ function isImageError(error: unknown): error is ImageError {
   return typeof code === 'string' && code.startsWith('image-');
 }
 
+function materialDiagnosticsEnabled(): boolean {
+  if (typeof globalThis !== 'object' || globalThis === null || !('process' in globalThis)) {
+    return false;
+  }
+  const processValue = (
+    globalThis as {
+      readonly process?: { readonly env?: Record<string, string | undefined> };
+    }
+  ).process;
+  return processValue?.env?.FORGEAX_MATERIAL_DIAGNOSTICS === '1';
+}
+
 export function residentTextureView(
   world: World,
   store: GpuResidencyCache,
@@ -240,7 +263,15 @@ export function residentTextureView(
   worldId: World | number = world,
 ): TextureView | undefined {
   const podRes = resolveAssetHandle<TextureAsset>(world, handle);
-  if (!podRes.ok) return undefined;
+  const diagnosticsEnabled = materialDiagnosticsEnabled();
+  if (!podRes.ok) {
+    if (diagnosticsEnabled) {
+      console.error(
+        `[render-material] texture resolve failed: ${JSON.stringify({ handle: handleSlot(handle), error: podRes.error })}`,
+      );
+    }
+    return undefined;
+  }
   const residentRes = store.ensureResident(handle, podRes.value, worldId);
   if (!residentRes.ok) {
     // Preserve the concrete asset-capability boundary on the renderer error
@@ -249,9 +280,41 @@ export function residentTextureView(
     if (residentRes.error instanceof RhiError || isImageError(residentRes.error)) {
       runtime.errorRegistry.fire(residentRes.error);
     }
+    if (diagnosticsEnabled) {
+      console.error(
+        `[render-material] texture residency failed: ${JSON.stringify({
+          handle: handleSlot(handle),
+          pod: {
+            kind: podRes.value.kind,
+            shape: podRes.value.shape,
+            format: podRes.value.format,
+            dataByteLength: podRes.value.data.byteLength,
+            mips: podRes.value.mips,
+          },
+          error: residentRes.error,
+        })}`,
+      );
+    }
     return undefined;
   }
-  return store.getTextureGpuView(handle, worldId);
+  const view = store.getTextureGpuView(handle, worldId);
+  if (diagnosticsEnabled) {
+    console.error(
+      `[render-material] texture residency ready: ${JSON.stringify({
+        handle: handleSlot(handle),
+        pod: {
+          kind: podRes.value.kind,
+          shape: podRes.value.shape,
+          format: podRes.value.format,
+          dataByteLength: podRes.value.data.byteLength,
+          mips: podRes.value.mips,
+        },
+        receipt: 'receipt' in residentRes.value ? residentRes.value.receipt : undefined,
+        viewReady: view !== undefined,
+      })}`,
+    );
+  }
+  return view;
 }
 
 function residentSampler(
@@ -398,7 +461,6 @@ export const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
   'baseColorTexture',
   'metallicRoughnessTexture',
   'normalTexture',
-  'specularTintTexture',
   'emissiveTexture',
   'occlusionTexture',
   'transmissionTexture',
@@ -406,21 +468,6 @@ export const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
 ];
 
 const LEGACY_MATERIAL_TEXTURE_SCALE_OFFSET = 80;
-// The Standard schema owns five transmission numeric fields between
-// normalScale and the engine-owned coordinate records. Keep this fallback
-// aligned with derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA): the first record is
-// at byte 128, not the pre-transmission byte 96.
-const STANDARD_PBR_TEXTURE_SCALE_OFFSET = 128;
-const MATERIAL_TEXTURE_SCALE_FIELDS = [
-  'baseColorTexture',
-  'metallicRoughnessTexture',
-  'normalTexture',
-  'specularTintTexture',
-  'emissiveTexture',
-  'occlusionTexture',
-  'transmissionTexture',
-  'thicknessTexture',
-] as const;
 const LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS = [
   'baseColorTexture',
   'metallicRoughnessTexture',
@@ -428,19 +475,20 @@ const LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS = [
   'emissiveTexture',
   'occlusionTexture',
 ] as const;
-const STANDARD_PBR_TEXTURE_COORDINATE_OFFSET = 128;
-const STANDARD_PBR_TEXTURE_COORDINATE_STRIDE = 8;
 const DEFAULT_LEGACY_TEXTURE_SCALES = new Float32Array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]);
-const DEFAULT_STANDARD_TEXTURE_COORDINATES = new Float32Array([
-  0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0,
-  0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1,
-]);
 
 export interface StandardReflectionProbeMaterialProjection {
   readonly probeIndex: number | undefined;
   readonly fallbackToSkylight: boolean;
 }
 
+/** Keeps the fallback output as a same-pass, linear-HDR material projection. */
+export function standardPbrFallbackDemand(
+  projection: StandardReflectionProbeMaterialProjection,
+): boolean {
+  return projection.probeIndex !== undefined || projection.fallbackToSkylight;
+}
+
 /** Projects the selected scene row into the Standard material lane. */
 export function projectReflectionProbeMaterialBinding(
   binding: StandardReflectionProbeBinding,
@@ -529,13 +577,10 @@ export function applyMaterialTextureUvScales(
     }
     return;
   }
-  // Standard PBR has a schema-derived 128-byte authored region before the
-  // engine-owned UV records. Sprite, sprite-lit, unlit, and text keep their
-  // own legacy tail positions because their WGSL layouts differ.
-  const textureScaleOffset = isStandardPbrMaterialShader(material.materialShaderId)
-    ? STANDARD_PBR_TEXTURE_SCALE_OFFSET
-    : LEGACY_MATERIAL_TEXTURE_SCALE_OFFSET;
-  const isStandardPbr = textureScaleOffset === STANDARD_PBR_TEXTURE_SCALE_OFFSET;
+  // Unknown legacy material paths retain their historical packed scale tail.
+  // Every registered Standard/material-schema path returns above and is
+  // therefore fully schema-driven (including physical texture coordinates).
+  const textureScaleOffset = LEGACY_MATERIAL_TEXTURE_SCALE_OFFSET;
   const hasTextureMetadata =
     material.textureCoordinates !== undefined ||
     material.textureHandles !== undefined ||
@@ -546,15 +591,10 @@ export function applyMaterialTextureUvScales(
     material.emissiveTexture !== undefined ||
     material.occlusionTexture !== undefined;
   if (!hasTextureMetadata) {
-    f32.set(
-      isStandardPbr ? DEFAULT_STANDARD_TEXTURE_COORDINATES : DEFAULT_LEGACY_TEXTURE_SCALES,
-      textureScaleOffset / 4,
-    );
+    f32.set(DEFAULT_LEGACY_TEXTURE_SCALES, textureScaleOffset / 4);
     return;
   }
-  const fields = isStandardPbr
-    ? MATERIAL_TEXTURE_SCALE_FIELDS
-    : LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS;
+  const fields = LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS;
   for (let index = 0; index < fields.length; index++) {
     const field = fields[index];
     if (field === undefined) continue;
@@ -563,39 +603,19 @@ export function applyMaterialTextureUvScales(
       handle === undefined ? undefined : resolveAssetHandle<TextureAsset>(world, handle);
     const texture = resolved?.ok === true ? resolved.value : undefined;
     const [u, v] = materialTextureUvScale(texture);
-    if (isStandardPbr) {
-      const coordinates = material.textureCoordinates?.get(field);
-      const transform = coordinates?.transform;
-      const offset =
-        STANDARD_PBR_TEXTURE_COORDINATE_OFFSET / 4 + index * STANDARD_PBR_TEXTURE_COORDINATE_STRIDE;
-      f32[offset] = transform?.offset?.[0] ?? 0;
-      f32[offset + 1] = transform?.offset?.[1] ?? 0;
-      f32[offset + 2] = transform?.scale?.[0] ?? 1;
-      f32[offset + 3] = transform?.scale?.[1] ?? 1;
-      f32[offset + 4] = coordinates?.set ?? 0;
-      f32[offset + 5] = transform?.rotation ?? 0;
-      f32[offset + 6] = u;
-      f32[offset + 7] = v;
-    } else {
-      const offset = textureScaleOffset / 4 + index * 2;
-      f32[offset] = u;
-      f32[offset + 1] = v;
-    }
+    const offset = textureScaleOffset / 4 + index * 2;
+    f32[offset] = u;
+    f32[offset + 1] = v;
   }
 }
 
 function materialCoordinateSchema(
   material: MaterialSnapshot,
 ): readonly ParamSchemaEntry[] | undefined {
-  if (
-    isStandardPbrMaterialShader(material.materialShaderId) &&
-    material.paramSnapshot !== undefined
-  ) {
-    return DEFAULT_STANDARD_PBR_PARAM_SCHEMA;
-  }
   if (material.materialParamSchema !== undefined && material.materialParamSchema.length > 0) {
     return material.materialParamSchema;
   }
+  if (isStandardPbrMaterialShader(material.materialShaderId)) return STANDARD_PIPELINE_PARAM_SCHEMA;
   switch (material.materialShaderId) {
     case 'forgeax::default-unlit':
       return DEFAULT_UNLIT_PARAM_SCHEMA;
@@ -645,6 +665,13 @@ export function defaultViewForUserRegionField(
   }
   if (field === 'normalTexture') return pipelineState.defaultNormalTextureView;
   if (field === 'baseColorTexture') return pipelineState.fallbackTextureView;
+  if (field === 'anisotropyTexture') {
+    // The flat-normal fallback encodes a zero tangent direction and unit B
+    // strength; the shader's zero-vector guard selects its neutral (1, 0)
+    // axis. This keeps an absent anisotropy map neutral even on hosts that do
+    // not allocate the optional dedicated identity texture.
+    return pipelineState.defaultAnisotropyTextureView ?? pipelineState.defaultNormalTextureView;
+  }
   return pipelineState.defaultWhiteTextureView;
 }
 
@@ -662,7 +689,7 @@ export function defaultViewForUserRegionField(
  * `renderableIndex` per RenderSystem lifetime via the `seenIndices` Set
  * (the same warn-once anchor pattern used for missing-texture sprites).
  *
- * @param transformWorld The entity's resolved Transform.world mat4 (16 floats column-major).
+ * @param transformWorld The entity's resolved GlobalTransform.world mat4 (16 floats column-major).
  * @param slices         The four anchor distances `[left, top, right, bottom]`
  *                       (sentinel `bottom < 0` for tile mode is consumed via abs()).
  * @param renderableIndex The entity index into the validated renderables list.
@@ -691,17 +718,7 @@ export function detectNineSliceScaleTooSmall(
   }
 }
 
-/**
- * Build the 384-byte Material UBO payload for a PBR / unlit material entry
- * (feat-20260527-sprite-nineslice M2 / w11; D-7 regression-net helper).
- *
- * Byte-for-byte equivalent to the legacy hard-coded PBR write path; each
- * deviation is caught by `render-system-record-pbr-ubo-stable.test.ts`.
- * The schema-driven paramSnapshot overlay (feat-20260523 M9-T05; AC-14)
- * positions vec4 / f32 slots onto std140 [slot0 vec4, slot1 f32 metallic,
- * slot1 f32 roughness] mirroring the engine-shipped default-standard-pbr
- * Material struct.
- */
+/** Build one max-sized, schema-driven Standard material UBO payload. */
 export function buildPbrMaterialUboPayload(material: MaterialSnapshot): Uint8Array {
   const buf = new Uint8Array(STANDARD_PBR_UBO_SIZE);
   writePbrMaterialUboPayload(buf, material);
@@ -711,11 +728,10 @@ export function buildPbrMaterialUboPayload(material: MaterialSnapshot): Uint8Arr
 /**
  * Write the standard material payload into caller-owned storage.
  *
- * The allocating wrapper above remains the byte-stable test/helper surface,
- * while the frame recorder reuses one scratch slot for all materials. A
- * scene with thousands of submeshes otherwise allocates one 384-byte
- * Uint8Array per material per frame, creating avoidable GC pressure without
- * changing GPU-visible bytes.
+ * The allocating wrapper above remains the helper/test surface, while the
+ * frame recorder reuses one scratch slot for all materials.  Field offsets are
+ * read from the material's admitted schema; no Standard field offset table is
+ * maintained in the record stage.
  */
 export function writePbrMaterialUboPayload(
   buf: Uint8Array | Float32Array,
@@ -728,114 +744,52 @@ export function writePbrMaterialUboPayload(
   }
   buf.fill(0);
   const f32 = materialUboFloatView(buf);
-  // Layout (issue-1: channelMap split per D-8) -- byte-equivalent to the
-  // post-split sidecar paramSchema for default-standard-pbr (12 numeric
-  // entries packed std140 into one merged UBO at binding(0)).
-  //   f32[0..3]   baseColor          (offset 0,  vec4)
-  //   f32[4]      metallic           (offset 16)
-  //   f32[5]      roughness          (offset 20)
-  //   f32[6]      metallicChannel    (offset 24)  -- glTF 2.0 default = B = 2
-  //   f32[7]      roughnessChannel   (offset 28)  -- glTF 2.0 default = G = 1
-  //   f32[8]      aoChannel          (offset 32)  -- glTF 2.0 default = R = 0
-  //   f32[9]      extraChannel       (offset 36)  -- reserved = 0
-  //                                  (offset 40..47 implicit pad: vec3 align=16)
-  //   f32[12..14] emissive           (offset 48,  vec3)
-  //   f32[15]     emissiveIntensity  (offset 60)
-  //   f32[16]     occlusionStrength  (offset 64)
-  //   f32[17]     alphaCutoff        (offset 68)
-  //   f32[18]     clearcoat          (offset 72)
-  //   f32[19]     clearcoatRoughness (offset 76)
-  //   f32[20..22] specularTint       (offset 80, vec3)
-  //   f32[23]     normalScale        (offset 92)
-  //   f32[24]     transmission       (offset 96)
-  //   f32[25]     ior                (offset 100)
-  //   f32[26]     thickness          (offset 104)
-  //   f32[28..30] attenuationColor   (offset 112, vec3)
-  //   f32[31]     attenuationDistance(offset 124)
-  //   f32[32..95] engine-owned texture coordinate records (offset 128)
-  f32[0] = material.baseColor[0] ?? 0;
-  f32[1] = material.baseColor[1] ?? 0;
-  f32[2] = material.baseColor[2] ?? 0;
-  f32[3] = 1;
-  f32[4] = material.metallic;
-  f32[5] = material.roughness;
-  // channelMap default = (B, G, R, _) per AGENTS.md + glTF 2.0
-  // KHR_materials_pbrSpecularGlossiness ARM packing -- now 4 independent
-  // f32 selectors; fragment casts each to u32 at the pick site.
-  f32[6] = 2; // metallicChannel  <- B
-  f32[7] = 1; // roughnessChannel <- G
-  f32[8] = 0; // aoChannel        <- R
-  f32[9] = 0; // extraChannel     <- reserved
-  // emissive vec3 + emissiveIntensity (offset 48..63)
-  const em = material.emissive;
-  f32[12] = em?.[0] ?? 0;
-  f32[13] = em?.[1] ?? 0;
-  f32[14] = em?.[2] ?? 0;
-  f32[15] = material.emissiveIntensity ?? 0;
-  // occlusionStrength (offset 64)
-  f32[16] = material.occlusionStrength ?? 1;
-  // alphaCutoff (offset 68).
-  const alphaCutoff = material.paramSnapshot?.alphaCutoff;
-  f32[17] = typeof alphaCutoff === 'number' ? alphaCutoff : 0;
-  f32[18] = material.clearcoat ?? 0;
-  f32[19] = material.clearcoatRoughness ?? 0.5;
-  const specularTint = material.specularTint;
-  f32[20] = specularTint?.[0] ?? 1;
-  f32[21] = specularTint?.[1] ?? 1;
-  f32[22] = specularTint?.[2] ?? 1;
-  const snapshotNumber = (name: string, fallback: number): number => {
-    const value = material.paramSnapshot?.[name];
-    return typeof value === 'number' ? value : fallback;
-  };
-  const snapshotVec3 = (
-    name: string,
-    fallback: readonly [number, number, number],
-  ): readonly [number, number, number] => {
-    const value = material.paramSnapshot?.[name];
-    return Array.isArray(value)
-      ? [value[0] ?? fallback[0], value[1] ?? fallback[1], value[2] ?? fallback[2]]
-      : fallback;
+  const schema =
+    material.materialParamSchema === undefined || material.materialParamSchema.length === 0
+      ? STANDARD_PIPELINE_PARAM_SCHEMA
+      : material.materialParamSchema;
+  const snapshot = material.paramSnapshot;
+  const fallback = (name: string, entry: (typeof schema)[number]): unknown => {
+    switch (name) {
+      case 'baseColor':
+        return [
+          material.baseColor[0] ?? 1,
+          material.baseColor[1] ?? 1,
+          material.baseColor[2] ?? 1,
+          1,
+        ];
+      case 'metallic':
+        return material.metallic;
+      case 'roughness':
+        return material.roughness;
+      case 'specularColor':
+        return material.specularColor ?? [1, 1, 1];
+      case 'normalScale':
+        return material.normalScale ?? 1;
+      case 'emissive':
+        return material.emissive ?? [0, 0, 0];
+      case 'emissiveIntensity':
+        return material.emissiveIntensity ?? 0;
+      case 'occlusionStrength':
+        return material.occlusionStrength ?? 1;
+      default:
+        return entry.default;
+    }
   };
-  f32[23] = material.normalScale ?? snapshotNumber('normalScale', 1);
-  f32[24] = snapshotNumber('transmission', 0);
-  f32[25] = snapshotNumber('ior', 1.5);
-  f32[26] = snapshotNumber('thickness', 0);
-  const attenuationColor = snapshotVec3('attenuationColor', [1, 1, 1]);
-  f32[28] = attenuationColor[0];
-  f32[29] = attenuationColor[1];
-  f32[30] = attenuationColor[2];
-  f32[31] = snapshotNumber('attenuationDistance', 0);
-  // Schema-driven paramSnapshot overlay (feat-20260523 M9-T05, AC-14):
-  // for user-shaders with a paramSnapshot, project the first vec4/color
-  // entry onto slot 0 and the first two f32 entries onto slot 1's first
-  // two floats. The default-standard-pbr path lands on the same offsets
-  // via the explicit fields above, so the overlay is a no-op for the
-  // engine's stock PBR shader (charter P4 + R-H regression fence).
-  const paramSnap = material.paramSnapshot;
-  if (paramSnap !== undefined) {
-    const f32Snap = (name: string): number | undefined => {
-      const v = paramSnap[name];
-      return typeof v === 'number' ? v : undefined;
-    };
-    const colorSnap = (name: string): readonly number[] | undefined => {
-      const v = paramSnap[name];
-      return Array.isArray(v) && v.every((x) => typeof x === 'number')
-        ? (v as readonly number[])
-        : undefined;
-    };
-    // Walk schema in declared order, fill positional UBO slots.
-    const materialShaderId = material.materialShaderId;
-    // Note: schema lookup is the caller's job (it owns the runtime ref);
-    // when the helper has no access to runtime, paramSnap is consumed
-    // positionally without a schema walk. The inline caller (recordFrame)
-    // still performs the schema-driven walk and writes the overlay before
-    // queueing this payload, so this helper is only the byte-stable
-    // baseline. To preserve byte-for-byte equivalence in the helper-only
-    // unit-test path, the overlay pass is skipped when the helper is
-    // called without an external schema reference.
-    void materialShaderId;
-    void f32Snap;
-    void colorSnap;
+  for (const entry of derivedParamSchema(schema).uboLayout.entries) {
+    const value =
+      snapshot?.[entry.name] ??
+      fallback(entry.name, schema.find((item) => item.name === entry.name) ?? entry);
+    const offset = entry.offset / 4;
+    const width = entry.size / 4;
+    if (typeof value === 'number') {
+      f32[offset] = value;
+    } else if (Array.isArray(value)) {
+      for (let index = 0; index < Math.min(width, value.length); index += 1) {
+        const component = value[index];
+        if (typeof component === 'number') f32[offset + index] = component;
+      }
+    }
   }
 }
 
@@ -884,13 +838,7 @@ export function applyParamSnapshotToUbo(
   if (paramSchema === undefined) return;
   if (paramSnapshot === undefined) return;
   const f32 = materialUboFloatView(payload);
-  const effectiveSchema =
-    Object.hasOwn(paramSnapshot, 'transmission') &&
-    Object.hasOwn(paramSnapshot, 'ior') &&
-    Object.hasOwn(paramSnapshot, 'thickness')
-      ? DEFAULT_STANDARD_PBR_PARAM_SCHEMA
-      : paramSchema;
-  const { uboLayout } = derivedParamSchema(effectiveSchema);
+  const { uboLayout } = derivedParamSchema(paramSchema);
   for (const entry of uboLayout.entries) {
     const value = paramSnapshot[entry.name];
     if (value === undefined) continue;
@@ -955,6 +903,46 @@ export interface PerSubmeshMaterialBgDeps {
   /** Active transmission backdrop; undefined/null means layout placeholder. */
   readonly transmissionBackdropView?: TextureView | null;
   readonly bindGroupCounts: BindGroupCounts;
+  readonly frameState: RenderFrameState;
+}
+
+function recordIblMaterialBinding(
+  frameState: RenderFrameState,
+  materialBgl: BindGroupLayout,
+  bindGroup: BindGroup,
+  entries: readonly BindGroupEntry[],
+  iblStart: number,
+  cache: 'hit' | 'miss',
+): void {
+  const receipt = frameState.iblBindingInspection;
+  if (receipt === undefined) return;
+  const skylightBindingStart = entries.findIndex((entry) => entry.binding === iblStart);
+  if (skylightBindingStart < 0) return;
+  const iblEntries = entries.slice(skylightBindingStart, skylightBindingStart + 7);
+  const projected: IblBindingEntryInspection[] = [];
+  for (const entry of iblEntries) {
+    if (entry.resource.kind === 'externalTexture') continue;
+    const value =
+      entry.resource.kind === 'buffer' ? entry.resource.value.buffer : entry.resource.value;
+    if (typeof value !== 'object' || value === null) continue;
+    projected.push({
+      binding: entry.binding,
+      kind: entry.resource.kind,
+      resourceIdentity: getOpaqueResourceIdentity(value as object),
+    });
+  }
+  frameState.iblBindingInspection = {
+    ...receipt,
+    material: {
+      bindGroupIdentity: getOpaqueResourceIdentity(bindGroup as object),
+      materialBglIdentity: getOpaqueResourceIdentity(materialBgl as object),
+      cache,
+      skylightBindingStart: iblEntries[0]?.binding ?? 0,
+      entries: projected,
+      reflectionBindings: projected.map((entry) => entry.binding),
+    },
+    errors: [],
+  };
 }
 
 /** @internal Exported only so buffer-generation invalidation stays regression-tested. */
@@ -1002,6 +990,7 @@ export function buildPerSubmeshMaterialBg(
     materialBgAssemblyCache,
     transmissionBackdropView,
     bindGroupCounts,
+    frameState,
   } = deps;
   const effectiveSkylightResources =
     resolveReflectionProbeResources?.(materialWorld, entityKey) ?? skylightResources;
@@ -1010,10 +999,31 @@ export function buildPerSubmeshMaterialBg(
     smMaterialHandle === undefined ? undefined : `${materialWorld.identity}:${smMaterialHandle}`;
   const smHasVideoFields = (submeshMaterial.videoTextureFields?.size ?? 0) > 0;
   const smShaderId = submeshMaterial.materialShaderId;
+  // The cooked shader schema owns the resource ABI. A material snapshot may
+  // carry only the authored values (for example a clearcoat-only root omits
+  // the standard emissive/occlusion maps), while the Standard template still
+  // declares those slots and expects neutral fallbacks to be bound.
+  const smSchema =
+    (smShaderId !== undefined ? runtime.getParamSchema?.(smShaderId) : undefined) ??
+    submeshMaterial.materialParamSchema;
   const smPerShaderBgl =
-    smShaderId !== undefined ? runtime.getMaterialBindGroupLayout?.(smShaderId) : undefined;
+    smShaderId !== undefined
+      ? runtime.getMaterialBindGroupLayout?.(smShaderId, smSchema)
+      : undefined;
   const smMaterialBgl = smPerShaderBgl ?? pipelineState.materialBindGroupLayout;
+  const standardMaterial = isStandardPbrMaterialShader(smShaderId);
+  const physicalFields =
+    standardMaterial && smSchema !== undefined ? physicalTextureFields(smSchema) : [];
+  // Standard's built-in shader owns the canonical seven-pair user region even
+  // when the authored root only declares a subset.  Physical maps are appended
+  // after the reserved IBL/transmission tail, so compacting this list would
+  // shift the shader's IBL bindings and invalidate the render pipeline.
+  const smUserRegionFields =
+    smPerShaderBgl === undefined || isCanonicalStandardPbrMaterialShader(smShaderId)
+      ? BUILTIN_USER_REGION_TEXTURE_FIELDS
+      : userRegionTextureFieldOrder(smSchema).filter((field) => !physicalFields.includes(field));
   const hasActiveTransmissionBackdrop = transmissionBackdropView != null;
+  const diagnosticsEnabled = materialDiagnosticsEnabled();
   if (smMaterialHandle !== undefined && !smHasVideoFields && !hasActiveTransmissionBackdrop) {
     const cached =
       materialCacheKey === undefined ? undefined : materialBgAssemblyCache.get(materialCacheKey);
@@ -1028,21 +1038,48 @@ export function buildPerSubmeshMaterialBg(
         transmissionBackdropView,
       )
     ) {
+      if (diagnosticsEnabled) {
+        recordIblMaterialBinding(
+          frameState,
+          smMaterialBgl,
+          cached.bindGroup,
+          [
+            {
+              binding: 1 + smUserRegionFields.length * 2,
+              resource: { kind: 'textureView', value: skylightResources.irradianceView },
+            },
+            {
+              binding: 2 + smUserRegionFields.length * 2,
+              resource: { kind: 'sampler', value: skylightResources.irradianceSampler },
+            },
+            {
+              binding: 3 + smUserRegionFields.length * 2,
+              resource: { kind: 'textureView', value: skylightResources.prefilterView },
+            },
+            {
+              binding: 4 + smUserRegionFields.length * 2,
+              resource: { kind: 'sampler', value: skylightResources.prefilterSampler },
+            },
+            {
+              binding: 5 + smUserRegionFields.length * 2,
+              resource: { kind: 'textureView', value: skylightResources.brdfLutView },
+            },
+            {
+              binding: 6 + smUserRegionFields.length * 2,
+              resource: { kind: 'sampler', value: skylightResources.brdfLutSampler },
+            },
+            {
+              binding: 7 + smUserRegionFields.length * 2,
+              resource: { kind: 'buffer', value: { buffer: skylightResources.intensityBuffer } },
+            },
+          ],
+          1 + smUserRegionFields.length * 2,
+          'hit',
+        );
+      }
       return cached.bindGroup;
     }
   }
-  const smSchema =
-    submeshMaterial.materialParamSchema ??
-    (smShaderId !== undefined ? runtime.getParamSchema?.(smShaderId) : undefined);
-  // The shipped PBR shaders always own the eight texture pairs declared by the
-  // standard shader artifact. The runtime PBR BGL exposes those pairs directly;
-  // emissive and occlusion are not duplicated in an engine injection region.
-  // Keep the record projection on the shader-owned layout so IBL starts at
-  // binding 17 rather than colliding with transmissionSampler.
-  const smUserRegionFields =
-    smPerShaderBgl === undefined || isStandardPbrMaterialShader(smShaderId)
-      ? BUILTIN_USER_REGION_TEXTURE_FIELDS
-      : userRegionTextureFieldOrder(smSchema);
   let materialResourcesResident = true;
   const smSamplerForField = (field: string | undefined): Sampler => {
     const handle = field === undefined ? undefined : submeshMaterial.samplerHandles?.get(field);
@@ -1125,6 +1162,38 @@ export function buildPerSubmeshMaterialBg(
       },
     );
   }
+  // Physical Standard maps are deliberately appended after the stable IBL /
+  // transmission tail.  Keep their resource projection separate from the
+  // user-region loop so the slot order is the same as
+  // `appendTextureInjection(afterTransmission, physicalFields)` in the
+  // layout owner.
+  const physicalTextureInjections: TextureInjectionResource[] = [];
+  for (let slot = 0; slot < physicalFields.length; slot += 1) {
+    const field = physicalFields[slot];
+    if (field === undefined) continue;
+    let view = defaultViewForUserRegionField(field, pipelineState, smSchema);
+    const targetSource = materialRenderTargetSourceForField(
+      submeshMaterial,
+      field,
+      resolveRenderTargetTextureSource,
+    );
+    if (targetSource !== undefined) {
+      if (targetSource.textureView !== undefined) view = targetSource.textureView;
+      else materialResourcesResident = false;
+    } else {
+      const handle = submeshMaterial.textureHandles?.get(field);
+      if (handle !== undefined) {
+        const resident = residentTextureView(materialWorld, store, runtime, handle);
+        if (resident !== undefined) view = resident;
+        else materialResourcesResident = false;
+      }
+    }
+    physicalTextureInjections.push({
+      slot,
+      sampler: smSamplerForField(field),
+      view,
+    });
+  }
   // The backdrop is a full mip-chain view owned by the pipeline. Reuse the
   // pipeline's existing filtering/clamp sampler for screen-space sampling;
   // the material default sampler intentionally keeps repeat addressing for
@@ -1140,6 +1209,7 @@ export function buildPerSubmeshMaterialBg(
       sampler: transmissionSampler,
       ...(transmissionBackdropView === undefined ? {} : { backdropView: transmissionBackdropView }),
     } satisfies TransmissionBindGroupResources,
+    physicalTextureInjections,
   );
   const createBindGroup = (): BindGroup => {
     const result = runtime.device.createBindGroup({
@@ -1150,16 +1220,60 @@ export function buildPerSubmeshMaterialBg(
     if (!result.ok) throw result.error;
     return result.value;
   };
+  const materialCacheHandles = smMergedEntries.map((entry) => extractEntryResourceHandle(entry));
+  if (
+    diagnosticsEnabled &&
+    submeshMaterial.textureHandles === undefined &&
+    smMaterialHandle !== undefined
+  ) {
+    console.error(
+      `[render-material] scalar material cache handles: ${JSON.stringify({
+        entityKey,
+        materialHandle: smMaterialHandle,
+        shader: smShaderId,
+        paramSnapshot: submeshMaterial.paramSnapshot,
+        handleTypes: materialCacheHandles.map((handle) => typeof handle),
+      })}`,
+    );
+  }
+  if (
+    diagnosticsEnabled &&
+    materialCacheHandles.some((handle) => typeof handle !== 'object' || handle === null)
+  ) {
+    console.error(
+      `[render-material] invalid material cache handle: ${JSON.stringify({
+        entityKey,
+        materialHandle: smMaterialHandle,
+        shader: smShaderId,
+        entries: smMergedEntries.map((entry, index) => ({
+          index,
+          binding: entry.binding,
+          kind: entry.resource.kind,
+          handleType: typeof materialCacheHandles[index],
+        })),
+      })}`,
+    );
+  }
   const smBindGroup = hasActiveTransmissionBackdrop
     ? createBindGroup()
     : getOrCreatePerEntity(
         materialBgShared,
         smShaderId ?? '',
-        smMergedEntries.map((e) => extractEntryResourceHandle(e)),
+        materialCacheHandles,
         'material-shared',
         createBindGroup,
         bindGroupCounts,
       );
+  if (diagnosticsEnabled) {
+    recordIblMaterialBinding(
+      frameState,
+      smMaterialBgl,
+      smBindGroup,
+      smMergedEntries,
+      smBaseEntries.length,
+      'miss',
+    );
+  }
   if (
     smMaterialHandle !== undefined &&
     !smHasVideoFields &&