@forgeax/engine-render 0.1.21 → 0.1.24

package/src/pbr-pipeline.ts

@@ -25,14 +25,18 @@ import type {
   BindGroup,
   BindGroupEntry,
   BindGroupLayout,
-  BindGroupLayoutDescriptor,
   Buffer,
   PipelineLayout,
   RhiDevice,
   Sampler,
+  TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
-import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA, type ShaderCatalog } from '@forgeax/engine-shader';
+import {
+  type ShaderCatalog,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+  standardPhysicalTextureFields,
+} from '@forgeax/engine-shader';
 import { derive, type ParamSchemaEntry } from '@forgeax/engine-types';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from './gpu-stage';
 import type { PipelineSpec } from './pipeline-spec-types';
@@ -72,6 +76,10 @@ export interface PbrPipelineLayoutBundle {
   readonly meshArrayBgl: BindGroupLayout;
   /** Per-instance storage BindGroupLayout (slot 3). */
   readonly instancesBgl: BindGroupLayout;
+  /** Probe-enabled slot-3 BGL; aliases `instancesBgl` when probes are unavailable. */
+  readonly probeInstancesBgl: BindGroupLayout;
+  /** Same pipeline layout with the probe-enabled slot-3 BGL, when supported. */
+  readonly probePipelineLayout: PipelineLayout | null;
   /**
    * Same 4 layouts in slot order. Useful for assertion sites that check the
    * pipeline-layout `bindGroupLayouts` array shape (t57 (a) + (d)).
@@ -84,16 +92,26 @@ export interface PbrPipelineLayoutBundle {
   ];
 }
 
+/** Derives the Standard PBR attachment list without allocating a closed path. */
+export function standardPbrColorFormats(
+  baseFormat: TextureFormat,
+  fallbackDemand: boolean,
+): readonly TextureFormat[] {
+  return fallbackDemand ? [baseFormat, 'rgba16float'] : [baseFormat];
+}
+
 // ─── Base entries (round-4 SSOT) ────────────────────────────────────────────
 
 /**
  * The built-in standard-PBR material paramSchema's texture/user-region shape,
  * used as the fallback when the material BGL is built without a registry
- * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the 8 Standard
- * user-region textures + a numeric UBO run; `derive()` collapses the numerics
- * into binding 0 and emits sampler/texture pairs at 1..6 — byte-equivalent to
- * the legacy fixed base-7. The shared PBR parameter contract comes from the
- * shader package; this module only derives the GPU layout.
+ * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the canonical
+ * Standard user-region textures + a numeric UBO run; `derive()` collapses the
+ * numerics into binding 0 and emits one sampler/texture pair per declared
+ * texture. Physical map pairs stay outside this boot region and are appended
+ * only for an authored root that declares them. The shared PBR parameter
+ * contract comes from the shader package; this module only derives the GPU
+ * layout.
  */
 /**
  * Build the PBR material BGL **user-region** from a paramSchema via the
@@ -104,9 +122,10 @@ export interface PbrPipelineLayoutBundle {
  * custom schema (e.g. parallax + heightTexture) shifts the injection region by
  * one sampler/texture pair automatically.
  *
- * The built-in `default-standard-pbr` paramSchema declares exactly 8 textures,
- * so this derives to binding 0 UBO + 8 pairs = 17 entries. Injection is appended
- * after that derived region.
+ * The canonical `STANDARD_PIPELINE_PARAM_SCHEMA` currently declares seven
+ * non-physical textures, so this derives to binding 0 UBO + seven pairs = 15
+ * entries. IBL and transmission injection are appended after that region;
+ * authored physical maps are appended after the engine-owned injections.
  *
  * One material-UBO convention is layered on top of the pure `derive()` output:
  * binding 0 is patched to `{ type: 'uniform', hasDynamicOffset: true }` with
@@ -120,9 +139,18 @@ export interface PbrPipelineLayoutBundle {
  *   built-in standard-PBR shape when omitted, for the caps-driven seam).
  */
 export function buildPbrMaterialUserRegionEntries(
-  paramSchema: readonly ParamSchemaEntry[] = DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  paramSchema: readonly ParamSchemaEntry[] = STANDARD_PIPELINE_PARAM_SCHEMA,
+  excludedTextureFields: readonly string[] = [],
 ): GPUBindGroupLayoutEntry[] {
-  const derived = derive(paramSchema);
+  const excluded = new Set(excludedTextureFields);
+  for (const field of standardPhysicalTextureFields(paramSchema)) excluded.add(field);
+  const derived = derive(
+    excluded.size === 0
+      ? paramSchema
+      : paramSchema.filter(
+          (entry) => !excluded.has(entry.name) || !entry.type.startsWith('texture'),
+        ),
+  );
   // Project the engine-owned entry shape into the DOM WebGPU descriptor. Omit
   // absent optional members so exactOptionalPropertyTypes remains true at the
   // boundary instead of leaking an `undefined` property into the descriptor.
@@ -318,6 +346,68 @@ export const INJECTION_KIND_LENGTHS = {
   transmission: TRANSMISSION_INJECTION_LENGTH,
 };
 
+export function physicalTextureFields(paramSchema: readonly ParamSchemaEntry[]): readonly string[] {
+  return standardPhysicalTextureFields(paramSchema);
+}
+
+export function appendTextureInjection(
+  bgl: readonly GPUBindGroupLayoutEntry[],
+  fields: readonly string[],
+): GPUBindGroupLayoutEntry[] {
+  const start = bgl.length;
+  const fieldSet = new Set(fields);
+  return standardPhysicalTextureFields(
+    fields.map((name) => ({ name, type: 'texture2d' as const })),
+  ).flatMap((field, index) => {
+    if (!fieldSet.has(field)) return [];
+    const binding = start + index * 2;
+    return [
+      {
+        binding,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' as const },
+      },
+      {
+        binding: binding + 1,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float' as const, viewDimension: '2d' as const },
+      },
+    ];
+  });
+}
+
+/**
+ * Return the stable identity of the merged material bind-group layout.
+ *
+ * This is deliberately derived from the same descriptor builder consumed by
+ * the device path. Callers use it to keep pipeline, bind-group, and
+ * frame-local lookup caches on one layout identity even when equivalent
+ * paramSchema arrays were allocated independently.
+ */
+export function materialBindGroupLayoutIdentity(
+  shaderId: string,
+  paramSchema: readonly ParamSchemaEntry[],
+): string {
+  const descriptor = buildBindGroupLayoutDescriptor(
+    {
+      shader: { id: shaderId, passKind: 'forward', variantSet: undefined },
+      attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+      geometry: { topology: 'triangle-list', vertexLayout: {} },
+      renderState: undefined,
+    },
+    { kind: 'pbr-material-merged', materialParamSchema: paramSchema },
+  );
+  // Descriptor shape alone cannot distinguish two Standard roots that expose
+  // the same number of physical texture pairs under different semantic names.
+  // The resource order is part of the admitted root contract, so include the
+  // canonical physical projection in the cache identity while keeping the
+  // actual WebGPU descriptor owned by the builder above.
+  return JSON.stringify({
+    entries: descriptor.entries,
+    physicalTextureFields: physicalTextureFields(paramSchema),
+  });
+}
+
 /**
  * Caps shape consumed by the BGL factory functions for storage-buffer vs
  * uniform-buffer branching. Mirrors the two fields the engine reads from
@@ -325,14 +415,21 @@ export const INJECTION_KIND_LENGTHS = {
  */
 export interface PbrCaps {
   readonly storageBuffer: boolean;
+  /**
+   * Whether the selected material variant declares the optional extended
+   * lighting view resources.  The default keeps the historical helper shape
+   * for callers that build the canonical full PBR layout; the renderer passes
+   * the device/variant decision explicitly.
+   */
+  readonly extendedLighting?: boolean;
+  /** Selects the optional binding(1) ProbeBlendRecord lane. */
+  readonly probeBlend?: boolean;
   /** Whether the device can carry the optional SpotLight projector texture. */
   readonly projectorAvailable?: boolean;
 }
 
 /**
  * The view BGL entry list. binding 0 = view UBO (vertex + fragment);
- * binding 1 = pointLights (storage or uniform, per caps);
- * binding 2 = spotLights (storage or uniform, per caps);
  * binding 3 = directional shadowMap atlas (texture_depth_2d, vertex+fragment).
  *   feat-20260613-csm-cascaded-shadow-maps: this is the CSM atlas — N
  *   cascades tiled into one 2D depth texture, sampled via per-cascade UV
@@ -372,12 +469,11 @@ export interface PbrCaps {
  *   layout and consumed only by the dedicated points-lines shader).
  * Isolated here so M4 round-4 tests can recreate the layout.
  *
- * feat-20260526-pbr-uniform-fallback-no-storage-buffer M3 / w9:
- * caps.storageBuffer===false switches bindings 1+2 from
- * 'read-only-storage' to 'uniform'.
+ * Local lights are not part of the view group. Standard material variants
+ * consume the one Cluster payload in group(2), while this group retains only
+ * camera and shadow resources.
  */
 export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[] {
-  const lightBufType: GPUBufferBindingType = caps.storageBuffer ? 'read-only-storage' : 'uniform';
   const entries: GPUBindGroupLayoutEntry[] = [
     {
       binding: 0,
@@ -386,16 +482,6 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
       // Keeping this dynamic is also valid for the display slot at offset 0.
       buffer: { type: 'uniform', hasDynamicOffset: true },
     },
-    {
-      binding: 1,
-      visibility: GPU_SHADER_STAGE_FRAGMENT,
-      buffer: { type: lightBufType },
-    },
-    {
-      binding: 2,
-      visibility: GPU_SHADER_STAGE_FRAGMENT,
-      buffer: { type: lightBufType },
-    },
     {
       binding: 3,
       visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
@@ -422,9 +508,9 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
     // shadow-casting point light slot (shadowAtlasLayer in [0, 4)). Each
     // lane stores `(near, far, 1/(far-near), 0)` so the fragment-shader
     // depth-ref reconstruction (lighting-punctual.wgsl evalPointShadowed)
-    // can avoid sampling LightSlot for the URP path. HDRP rides the same
-    // constants on `LightSlot.kind_and_pad.zw` so binding 6 is unused on
-    // HDRP shaders even though the BGL declares it (charter P4 single SSOT
+    // can avoid sampling DirectLightSlot for the URP path. The shared
+    // DirectLightSlot metadata remains the identity owner, so binding 6 is
+    // unused on HDRP shaders even though the BGL declares it (charter P4 single SSOT
     // BGL across pipelines; the HDRP variant simply doesn't reference the
     // binding in WGSL, which is allowed).
     {
@@ -474,12 +560,41 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
       texture: { sampleType: 'depth', viewDimension: '2d' },
     },
   ];
-  // The projector is optional, but when present it is a sampled texture in
-  // the fragment stage. Keep it out of the low-limit view layout so the
-  // remaining HDRP PBR ABI stays within WebGPU's minimum 16 sampled textures.
-  // The corresponding PROJECTOR_AVAILABLE shader variant is selected from
-  // the same device capability bit and returns a white modulation.
-  if (caps.projectorAvailable !== false) {
+  const extendedLighting = caps.extendedLighting ?? true;
+  if (extendedLighting) {
+    entries.push(
+      {
+        binding: 9,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' },
+      },
+      {
+        binding: 11,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d-array' },
+      },
+      {
+        binding: 12,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d-array' },
+      },
+      {
+        binding: 13,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d' },
+      },
+      {
+        binding: 14,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d' },
+      },
+      {
+        binding: 15,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: 'uniform' },
+      },
+    );
+  } else if (caps.projectorAvailable !== false) {
     entries.push(
       {
         binding: 11,
@@ -508,8 +623,8 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
  * material, mesh-array, instances]`; the material BGL is derived from the
  * standard material schema and engine injection chain.
  *
- * `caps.storageBuffer===false` switches every storage-buffer BGL entry
- * (view bindings 1+2, mesh-array, instances) to `uniform`.
+ * `caps.storageBuffer===false` switches the mesh-array and instances entries
+ * to `uniform`; local-light resources are never part of this view group.
  *
  * Throws on each `createBindGroupLayout` / `createPipelineLayout` Result
  * failure -- the engine bootstrap path (createRenderer) wraps the call in
@@ -531,7 +646,7 @@ export function buildPbrPipelineLayouts(
 
   // Material BGL: derived user region + Skylight + transmission injection.
   // The transmission start binding is computed from the post-Skylight BGL
-  // length (= 24 for the built-in Standard schema) by appendInjection.
+  // length (= 22 for the canonical Standard schema) by appendInjection.
   const materialBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-material-merged' }),
   );
@@ -545,9 +660,27 @@ export function buildPbrPipelineLayouts(
 
   // instances BGL.
   const instancesBglRes = device.createBindGroupLayout(
-    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-instances', caps }),
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: 'pbr-instances',
+      caps: { ...caps, probeBlend: false },
+    }),
   );
   if (!instancesBglRes.ok) throw instancesBglRes.error;
+  // ProbeBlendRecord is a storage-buffer-only ABI extension. A uniform
+  // fallback cannot afford the extra fragment-stage uniform binding on
+  // WebGL2/GLES, so do not even construct the probe BGL on that capability
+  // route. The record stage gates the matching variant and bind group with
+  // the same storage capability; aliasing the ordinary BGL keeps the bundle
+  // total and makes an accidental probe request fail closed at layout select.
+  const probeInstancesBglRes = caps.storageBuffer
+    ? device.createBindGroupLayout(
+        buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+          kind: 'pbr-instances',
+          caps: { ...caps, probeBlend: true },
+        }),
+      )
+    : { ok: true as const, value: instancesBglRes.value };
+  if (!probeInstancesBglRes.ok) throw probeInstancesBglRes.error;
 
   // Pipeline layout (4 slots).
   const layouts: readonly [BindGroupLayout, BindGroupLayout, BindGroupLayout, BindGroupLayout] = [
@@ -561,6 +694,21 @@ export function buildPbrPipelineLayouts(
     bindGroupLayouts: layouts,
   });
   if (!pipelineLayoutRes.ok) throw pipelineLayoutRes.error;
+  const probeLayouts: readonly [
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+  ] = [viewBglRes.value, materialBglRes.value, meshArrayBglRes.value, probeInstancesBglRes.value];
+  let probePipelineLayout: PipelineLayout | null = null;
+  if (caps.storageBuffer) {
+    const probePipelineLayoutRes = device.createPipelineLayout({
+      label: 'pbr-probe-pl',
+      bindGroupLayouts: probeLayouts,
+    });
+    if (!probePipelineLayoutRes.ok) throw probePipelineLayoutRes.error;
+    probePipelineLayout = probePipelineLayoutRes.value;
+  }
 
   return {
     pipelineLayout: pipelineLayoutRes.value,
@@ -568,6 +716,8 @@ export function buildPbrPipelineLayouts(
     materialBgl: materialBglRes.value,
     meshArrayBgl: meshArrayBglRes.value,
     instancesBgl: instancesBglRes.value,
+    probeInstancesBgl: probeInstancesBglRes.value,
+    probePipelineLayout,
     bindGroupLayouts: layouts,
   };
 }
@@ -586,6 +736,21 @@ export function buildPbrPipelineLayouts(
 export const SKIN_MATERIAL_SHADER_ID = 'forgeax::pbr-skin' as const;
 export const SHADOW_CASTER_SHADER_ID = 'forgeax::default-shadow-caster' as const;
 
+// Authored Standard templates are published under a unique module id for each
+// root contract.  Keep the family marker in the id so every downstream render
+// owner (extract, layout, and record) can make the same Standard-vs-custom and
+// rigid-vs-skinned decision without a second registry or a runtime shader
+// inspection pass.
+const AUTHORED_STANDARD_ID_RE = /::(?:standard|pbr-skin)(?:-|$)/;
+
+export function isStandardPbrSkinMaterialShader(shaderId: string | undefined): boolean {
+  return (
+    shaderId === SKIN_MATERIAL_SHADER_ID ||
+    shaderId === 'forgeax::default-standard-pbr-skin' ||
+    (shaderId !== undefined && /::pbr-skin(?:-|$)/.test(shaderId))
+  );
+}
+
 export function shadowCasterVariantSet(storageBuffer: boolean, skinned: boolean): string {
   const skinningDisabled = !skinned;
   if (storageBuffer && skinningDisabled) return '';
@@ -620,6 +785,22 @@ export function resolvePipelineGroup2Contract(source: string): PipelineGroup2Con
 
 /** Returns true for the engine-shipped standard-PBR material shader family. */
 export function isStandardPbrMaterialShader(shaderId: string | undefined): boolean {
+  return (
+    shaderId === 'forgeax::default-standard-pbr' ||
+    shaderId === SKIN_MATERIAL_SHADER_ID ||
+    shaderId === 'forgeax::default-standard-pbr-skin' ||
+    (shaderId !== undefined && AUTHORED_STANDARD_ID_RE.test(shaderId))
+  );
+}
+
+/**
+ * Return true only for the two engine-owned Standard roots. Authored Standard
+ * aliases intentionally remain outside this set: their cooked root schema may
+ * omit transmission or other optional resources, so their compact user-region
+ * layout must be derived from that artifact instead of borrowing the boot
+ * layout's reserved slots.
+ */
+export function isCanonicalStandardPbrMaterialShader(shaderId: string | undefined): boolean {
   return (
     shaderId === 'forgeax::default-standard-pbr' ||
     shaderId === SKIN_MATERIAL_SHADER_ID ||
@@ -685,6 +866,21 @@ export function buildPbrSkinLayouts(
     bindGroupLayouts: layouts,
   });
   if (!pipelineLayoutRes.ok) throw pipelineLayoutRes.error;
+  const probeLayouts: readonly [
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+  ] = [pbr.viewBgl, pbr.materialBgl, skinMeshArrayBglRes.value, pbr.probeInstancesBgl];
+  let probePipelineLayout: PipelineLayout | null = null;
+  if (caps.storageBuffer) {
+    const probePipelineLayoutRes = device.createPipelineLayout({
+      label: 'pbr-skin-probe-pl',
+      bindGroupLayouts: probeLayouts,
+    });
+    if (!probePipelineLayoutRes.ok) throw probePipelineLayoutRes.error;
+    probePipelineLayout = probePipelineLayoutRes.value;
+  }
 
   return {
     pipelineLayout: pipelineLayoutRes.value,
@@ -692,6 +888,8 @@ export function buildPbrSkinLayouts(
     materialBgl: pbr.materialBgl,
     meshArrayBgl: skinMeshArrayBglRes.value,
     instancesBgl: pbr.instancesBgl,
+    probeInstancesBgl: pbr.probeInstancesBgl,
+    probePipelineLayout,
     bindGroupLayouts: layouts,
   };
 }
@@ -860,8 +1058,9 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *    - `'unlit-material'` — 7 entries: base PBR material only (no inject)
  *    - `'hdrp-7-slot'` — 7 entries (binding 0 + 3..8): HDRP cluster + SSAO group(2) BGL
  * 2. Caps-driven literal shapes (no shader):
- *    - `'pbr-view'` — 12 entries: view UBO + lights + shadow bindings,
- *      projector texture/sampler (11/12), and the Points/Lines UBO (10)
+ *    - `'pbr-view'` — camera/shadow bindings, optional projector
+ *      texture/sampler (11/12), and the Points/Lines UBO (10). Local lights
+ *      are carried exclusively by the Standard Cluster group(2).
  *      (directional 3/4, point 5/6, cascade 7, spot atlas 8; the former
  *      spot lightViewProj matrices moved into the View UBO)
  *    - `'pbr-mesh-array'` — 1 entry: per-entity mesh SSBO (dynamic-offset)
@@ -909,7 +1108,7 @@ export interface BindGroupLayoutDescriptorOutput {
 }
 
 /** Build the canonical HDRP group(2) bind-group layout. */
-export function createHdrpBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor {
+export function createHdrpBindGroupLayoutDescriptor(): BindGroupLayoutDescriptorOutput {
   const meshBufType: GPUBufferBindingType = 'read-only-storage';
   const clusterBufType: GPUBufferBindingType = 'read-only-storage';
   return {
@@ -961,7 +1160,7 @@ export function createHdrpBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor
 }
 
 /** Build the HDRP group(2) layout for the clustered skin variant. */
-export function createHdrpSkinBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor {
+export function createHdrpSkinBindGroupLayoutDescriptor(): BindGroupLayoutDescriptorOutput {
   const base = createHdrpBindGroupLayoutDescriptor();
   const baseEntries = base.entries;
   if (baseEntries === undefined || baseEntries[0] === undefined) {
@@ -1088,19 +1287,35 @@ export function buildBindGroupLayoutDescriptor(
       const meshBufType: GPUBufferBindingType = caps.storageBuffer
         ? 'read-only-storage'
         : 'uniform';
+      const entries: GPUBindGroupLayoutEntry[] = [
+        {
+          binding: 0,
+          visibility: GPU_SHADER_STAGE_VERTEX,
+          buffer: { type: meshBufType, hasDynamicOffset: false },
+        },
+        ...(caps.probeBlend === true
+          ? [
+              {
+                // Per-object fragment lane; the record is always exactly 160B.
+                binding: 1,
+                visibility: GPU_SHADER_STAGE_FRAGMENT,
+                buffer: { type: meshBufType, hasDynamicOffset: true },
+              },
+            ]
+          : []),
+      ];
       return {
-        label: 'pbr-instances-bgl',
-        entries: [
-          {
-            binding: 0,
-            // Standard transmission reads the same per-instance transform in
-            // fs_main to convert glTF unit-space thickness into world metres.
-            // Keep one shared instances BGL and widen its visibility instead
-            // of introducing a second transform upload or six new varyings.
-            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
-            buffer: { type: meshBufType, hasDynamicOffset: false },
-          },
-        ],
+        label: caps.probeBlend === true ? 'pbr-probe-instances-bgl' : 'pbr-instances-bgl',
+        entries: entries.map((entry) =>
+          entry.binding === 0
+            ? {
+                ...entry,
+                // Standard transmission reads the same per-instance transform in
+                // fs_main to convert glTF unit-space thickness into world metres.
+                visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+              }
+            : entry,
+        ),
       };
     }
     case 'pbr-skin-mesh-array': {
@@ -1134,14 +1349,29 @@ export function buildBindGroupLayoutDescriptor(
       // + IBL injection (7) + transmission injection (2). The user-region
       // size is the only variable; injection start = userRegion.length so a
       // custom schema shifts IBL/transmission by its sampler/texture pairs.
-      // The built-in 8-texture standard-PBR schema is 17 + 7 + 2 = 26 entries.
+      // The built-in standard-PBR schema is 17 + 7 + 2 = 26 entries;
+      // clearcoat texture pairs are derived from the effective root schema.
       //
       // Schema source priority (D-1): explicit materialParamSchema option >
       // registry lookup of spec.shader.id > built-in standard-PBR fallback.
       const resolvedSchema = resolveMaterialParamSchema(spec, options);
-      const userRegion = buildPbrMaterialUserRegionEntries(resolvedSchema);
+      const effectiveSchema = resolvedSchema ?? STANDARD_PIPELINE_PARAM_SCHEMA;
+      const physicalFields = physicalTextureFields(effectiveSchema);
+      // Standard's built-in shader keeps the transmission user-region slots
+      // reserved even when a particular root omits those values.  Physical
+      // maps extend that canonical region; they must not compact the IBL
+      // bindings to the smaller authored subset.  A compact user region is
+      // still correct for authored (non-engine) material shaders.
+      const userRegionSchema = isCanonicalStandardPbrMaterialShader(spec.shader.id)
+        ? STANDARD_PIPELINE_PARAM_SCHEMA
+        : effectiveSchema;
+      const userRegion = buildPbrMaterialUserRegionEntries(userRegionSchema);
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
-      const merged = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
+      const afterTransmission = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
+      const merged = [
+        ...afterTransmission,
+        ...appendTextureInjection(afterTransmission, physicalFields),
+      ];
       return {
         label: 'pbr-material-skylight-bgl',
         entries: merged,

package/src/pipeline/standard-forward-lane.ts

@@ -5,6 +5,11 @@ import type {
 } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { SceneDataUnavailableError } from '../errors/render';
+import {
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
 import type {
   RenderPipeline,
   RenderPipelineBuildContext,
@@ -29,6 +34,7 @@ import {
   transmissionDemandForTopology,
 } from '../transmission/backdrop';
 import {
+  addReflectionFallbackObservationPass,
   addTypedFrameObservationPass,
   addTypedScenePass,
   addTypedSkyboxPass,
@@ -135,6 +141,35 @@ function buildUrp(
     : sceneResolved;
   if (!scene.ok) return scene;
 
+  const reflectionFallback = topology.reflectionFallback?.enabled
+    ? target(graph, 'reflection-fallback-linear-hdr', {
+        format: 'rgba16float',
+        size: 'surface',
+        sampleCount: scene.value.sampleCount,
+        domain: 'linear-hdr',
+        usage:
+          GPU_TEXTURE_USAGE_COPY_SRC |
+          GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+          GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+      })
+    : ok(undefined);
+  if (!reflectionFallback.ok) return reflectionFallback;
+  if (reflectionFallback.value !== undefined) {
+    const initialized = graph.addRasterPass('reflection-fallback-clear', {
+      accesses: [{ resource: reflectionFallback.value.view, usage: 'color-attachment' }],
+      colorAttachments: [
+        {
+          view: reflectionFallback.value.view,
+          loadOp: 'clear',
+          storeOp: 'store',
+          clearValue: { r: 0, g: 0, b: 0, a: 0 },
+        },
+      ],
+      encode: () => {},
+    });
+    if (!initialized.ok) return initialized;
+  }
+
   const shadows = addTypedShadowPasses(graph, topology);
   if (!shadows.ok) return shadows;
 
@@ -163,6 +198,9 @@ function buildUrp(
   const main = addTypedScenePass(graph, {
     name: 'main',
     color: scene.value,
+    ...(reflectionFallback.value === undefined
+      ? {}
+      : { colorTargets: [scene.value, reflectionFallback.value] }),
     depth: depth.value,
     ...(msaa ? { resolve: sceneResolved.value } : {}),
     sampled: [
@@ -179,6 +217,7 @@ function buildUrp(
     extraAccesses: clusterReads,
     ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
+    ...(context.occlusion === undefined ? {} : { occlusion: context.occlusion }),
   });
   if (!main.ok) return main;
 
@@ -286,6 +325,7 @@ function buildUrp(
       depthSample.value,
       shadows.value.directional?.view,
       shadows.value.spot.view,
+      clusterBuffers.value,
     );
     if (!volume.ok) return volume;
   }
@@ -318,6 +358,13 @@ function buildUrp(
     );
     if (!observation.ok) return observation;
   }
+  if (reflectionFallback.value?.sampleCount === 1) {
+    const fallbackObservation = addReflectionFallbackObservationPass(
+      graph,
+      reflectionFallback.value,
+    );
+    if (!fallbackObservation.ok) return fallbackObservation;
+  }
 
   const post = addStandardPost(
     context,

package/src/pipeline/standard-lighting/graph.ts

@@ -11,6 +11,7 @@ import {
   GPU_BUFFER_USAGE_UNIFORM,
 } from '../../gpu-usage';
 import { getOrCreateHdrpBuffers, type HdrpBuffers } from '../../hdrp-buffers';
+import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../../light-buffer-layout';
 import type { _InternalRenderPipelineContext } from '../../record/render-context';
 import type { RenderPipelineFrame } from '../../render-pipeline';
 import type { StandardTopologyInputValue } from './topology';
@@ -65,7 +66,7 @@ export function importStandardClusterBuffers(
   const usage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
   const lightData = graph.importBuffer(
     'hdrp-light-data',
-    { size: layout.lightDataSlotCount * 64, usage },
+    { size: layout.lightDataSlotCount * BYTES_PER_DIRECT_LIGHT_SLOT, usage },
     (frame) => resolveBuffers(frame, descriptor).lightDataBuffer,
   );
   if (!lightData.ok) return lightData;