@forgeax/engine-render 0.1.21 → 0.1.23

package/src/pbr-pipeline.ts

@@ -25,11 +25,11 @@ 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';
@@ -72,6 +72,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,6 +88,14 @@ 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) ────────────────────────────────────────────
 
 /**
@@ -325,14 +337,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 +391,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 +404,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 +430,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 +482,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 +545,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
@@ -545,9 +582,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 +616,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 +638,8 @@ export function buildPbrPipelineLayouts(
     materialBgl: materialBglRes.value,
     meshArrayBgl: meshArrayBglRes.value,
     instancesBgl: instancesBglRes.value,
+    probeInstancesBgl: probeInstancesBglRes.value,
+    probePipelineLayout,
     bindGroupLayouts: layouts,
   };
 }
@@ -685,6 +757,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 +779,8 @@ export function buildPbrSkinLayouts(
     materialBgl: pbr.materialBgl,
     meshArrayBgl: skinMeshArrayBglRes.value,
     instancesBgl: pbr.instancesBgl,
+    probeInstancesBgl: pbr.probeInstancesBgl,
+    probePipelineLayout,
     bindGroupLayouts: layouts,
   };
 }
@@ -860,8 +949,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 +999,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 +1051,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 +1178,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': {

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;

package/src/pipeline/standard-lighting/light-frame.ts

@@ -2,12 +2,13 @@ import type { Mat4, Vec3 } from '@forgeax/engine-math';
 import type {
   DirectionalLightSnapshot,
   PointLightSnapshot,
+  RectAreaDirectLightSnapshot,
   SpotLightSnapshot,
 } from '../../render-system-extract';
 import type { StandardLightCount } from '../standard-profile';
 
 export interface StandardLocalLightInput {
-  readonly kind: 'point' | 'spot';
+  readonly kind: 'point' | 'spot' | 'rect-area';
   readonly position: Vec3;
   readonly range: number;
   /** Whether the shadow producer admitted this local light to its atlas. */
@@ -17,7 +18,7 @@ export interface StandardLocalLightInput {
    * it on the POD frame prevents Forward/Deferred from rebuilding a second
    * light list while leaving hand-authored unit fixtures source-free.
    */
-  readonly source?: PointLightSnapshot | SpotLightSnapshot;
+  readonly source?: PointLightSnapshot | SpotLightSnapshot | RectAreaDirectLightSnapshot;
 }
 
 export interface StandardLightFrame {

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

@@ -2,7 +2,7 @@ import { err, ok, type Result } from '@forgeax/engine-types';
 import type { PreparedStandardLighting } from './prepare';
 import type { StandardClusterTransport } from './transport';
 
-/** A prepared frame with no local lights on a non-storage direct backend. */
+/** A prepared frame with no local lights on a non-storage backend. */
 export interface StandardNoLocalTopologyInput {
   readonly kind: 'no-local-lights';
   readonly prepared: PreparedStandardLighting;

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

@@ -1,5 +1,6 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { type RenderError, StandardClusterTransportUnavailableError } from '../../errors/render';
+import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../../light-buffer-layout';
 import type { PreparedStandardLighting } from './prepare';
 
 export interface StandardClusterCapabilities {
@@ -71,7 +72,7 @@ export function selectStandardClusterTransport(
     occupiedClusterCount: occupiedClusterCount(prepared),
     clusterGridBytes: prepared.layout.clusterGridU32Length * Uint32Array.BYTES_PER_ELEMENT,
     lightIndexListBytes: prepared.membershipEntryCount * Uint32Array.BYTES_PER_ELEMENT,
-    lightDataBytes: requested * 64,
+    lightDataBytes: requested * BYTES_PER_DIRECT_LIGHT_SLOT,
     lightBoundsBytes: prepared.lightBounds.byteLength,
   });
 }

package/src/pipeline/standard-pipeline.ts

@@ -312,6 +312,7 @@ function buildStandardDeferredLane(
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
     passKind: 'forward',
     ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
+    ...(context.occlusion === undefined ? {} : { occlusion: context.occlusion }),
     extraAccesses: forwardExtraAccesses,
   });
   if (!forward.ok) return forward;
@@ -403,6 +404,7 @@ function buildStandardDeferredLane(
       depthSample.value,
       shadows.value.directional?.view,
       shadows.value.spot.view,
+      buffers.value,
     );
     if (!volume.ok) return volume;
   }

package/src/pipeline-builder.ts

@@ -122,6 +122,8 @@ export interface PipelineBuilderContext {
    * tonemap field (M9 keeps the LDR shape; HDR variants are OOS-M9).
    */
   readonly colorFormat: GPUTextureFormat;
+  /** Additional color targets for an MRT pass; the first target is colorFormat. */
+  readonly colorFormats?: readonly GPUTextureFormat[] | undefined;
   /** Depth attachment format, or `undefined` for a color-only pass. */
   readonly depthFormat: GPUTextureFormat | undefined;
   /**
@@ -324,7 +326,8 @@ export function buildPipelineForMaterialShader(
   // layout. The skinned variant additionally reads JOINTS_0 / WEIGHTS_0;
   // both layouts come from the same geometry projection used by the main
   // pass, so shadow rendering cannot silently reinterpret an 18F stream.
-  if (colorFormatsForPassKind(passKind, ctx.colorFormat).length === 0) {
+  const attachmentFormats = ctx.colorFormats ?? colorFormatsForPassKind(passKind, ctx.colorFormat);
+  if (attachmentFormats.length === 0) {
     // bug-20260619-csm RC-3 (AC-10): a material may supply a custom
     // ShadowCaster pass shader that carries a fragment stage (e.g. an
     // alpha-test cutout that calls `discard` and returns
@@ -399,7 +402,7 @@ export function buildPipelineForMaterialShader(
   const forwardSpec: PipelineSpec = {
     shader: { id, passKind, variantSet: undefined },
     attachments: {
-      colorFormats: colorFormatsForPassKind(passKind, ctx.colorFormat),
+      colorFormats: attachmentFormats,
       depthFormat: ctx.depthFormat,
       sampleCount: (sampleCount === 4 ? 4 : 1) as 1 | 4,
     },

package/src/pipeline-spec.ts

@@ -319,12 +319,23 @@ export function standardTopologyVariantSet(
   topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
   storageBuffer: boolean,
   vertexColorAvailable: boolean,
+  probeBlendAvailable = false,
 ): string {
-  return standardCapabilityVariantSet(
+  const capabilityVariantSet = standardCapabilityVariantSet(
     topology?.kind === 'clustered',
     storageBuffer,
     vertexColorAvailable,
   );
+  if (!probeBlendAvailable || !storageBuffer) return capabilityVariantSet;
+  // The canonical empty key cannot carry the clustered=true fact through
+  // resolveMaterialShaderVariantSet (an omitted cluster axis means false).
+  // Expand that base before adding the object-level Probe ABI axis so shader,
+  // group(3) bind group, and pipeline layout remain one exact variant.
+  const explicitCapabilityVariantSet =
+    capabilityVariantSet === ''
+      ? 'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true'
+      : capabilityVariantSet;
+  return `${explicitCapabilityVariantSet}+PROBE_BLEND_AVAILABLE=true`;
 }
 
 /**

package/src/plugin.ts

@@ -5,6 +5,7 @@ import { Camera } from './components/camera';
 import { DirectionalLight } from './components/directional-light';
 import { Instances } from './components/instances';
 import { Layer } from './components/layer';
+import { LightProbe } from './components/light-probe';
 import { Lines } from './components/lines';
 import { MeshFilter } from './components/mesh-filter';
 import { MeshRenderer } from './components/mesh-renderer';
@@ -12,6 +13,7 @@ import { PointLight } from './components/point-light';
 import { PointLightShadow } from './components/point-light-shadow';
 import { Points } from './components/points';
 import { PostProcessParams } from './components/post-process-params';
+import { RectAreaLight } from './components/rect-area-light';
 import { SceneInstance } from './components/scene-instance';
 import { SkyboxBackground } from './components/skybox-background';
 import { Skylight } from './components/skylight';
@@ -30,6 +32,7 @@ const RENDER_COMPONENTS: readonly Component[] = [
   DirectionalLight,
   Instances,
   Layer,
+  LightProbe,
   MeshFilter,
   MeshRenderer,
   PointLight,
@@ -37,6 +40,7 @@ const RENDER_COMPONENTS: readonly Component[] = [
   Points,
   Lines,
   PostProcessParams,
+  RectAreaLight,
   SceneInstance,
   SkyboxBackground,
   Skylight,

package/src/prepare/__tests__/extended-lighting-capability.unit.test.ts

@@ -0,0 +1,56 @@
+import type { RhiCaps, RhiDevice } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { deriveExtendedLightingCapability } from '../extended-lighting/resources';
+
+const device = {
+  caps: {
+    backendKind: 'null',
+    compute: true,
+    storageBuffer: true,
+    storageTexture: true,
+    rgba16floatRenderable: true,
+    samplerAliasing: true,
+  } as RhiCaps,
+  limits: {
+    maxSampledTexturesPerShaderStage: 20,
+    maxTextureDimension2D: 4096,
+    maxTextureArrayLayers: 32,
+    maxUniformBuffersPerShaderStage: 12,
+  },
+} as unknown as RhiDevice;
+
+describe('extended lighting capability admission', () => {
+  it('derives admission from real format, filter, array, and uniform facts', () => {
+    expect(deriveExtendedLightingCapability(device)).toEqual({
+      admitted: true,
+      topology: 'extendedLighting',
+      reason: undefined,
+    });
+  });
+
+  it('rejects a device whose array or uniform limit cannot hold the contract', () => {
+    const limited = {
+      ...device,
+      limits: { ...device.limits, maxTextureArrayLayers: 16, maxUniformBuffersPerShaderStage: 0 },
+    } as RhiDevice;
+
+    expect(deriveExtendedLightingCapability(limited)).toMatchObject({
+      admitted: false,
+      topology: 'extendedLighting',
+      reason: expect.stringContaining('maxTextureArrayLayers'),
+    });
+  });
+
+  it('rejects the topology when the sampled-texture limit is below the shader contract', () => {
+    const limited = {
+      ...device,
+      limits: { ...device.limits, maxSampledTexturesPerShaderStage: 16 },
+    } as RhiDevice;
+
+    expect(deriveExtendedLightingCapability(limited)).toEqual({
+      admitted: false,
+      topology: 'extendedLighting',
+      reason: 'maxSampledTexturesPerShaderStage 16 < 20',
+    });
+  });
+});