@forgeax/engine-render 0.1.21 → 0.1.23

package/src/record/frame-lighting.ts

@@ -25,7 +25,7 @@ import {
   getOrCreateHdrpBuffers,
   packClusterUniform,
 } from '../hdrp-buffers';
-import { packLightSlot } from '../light-buffer-layout';
+import { DIRECT_LIGHT_SLOT_FLOAT_COUNT, packDirectLightSlot } from '../light-buffer-layout';
 import {
   type PreparedStandardLighting,
   prepareStandardLighting,
@@ -36,6 +36,12 @@ import {
   selectStandardClusterTransport,
 } from '../pipeline/standard-lighting/transport';
 import { DEFAULT_CLUSTER_GRID, DEFAULT_STANDARD_PROFILE } from '../pipeline/standard-profile';
+import {
+  COOKIE_MATRIX_BYTES,
+  COOKIE_SLICE_SIZE,
+  IES_SLICE_HEIGHT,
+  IES_SLICE_WIDTH,
+} from '../prepare/extended-lighting/resources';
 import type { ReflectionProbeTable } from '../reflection/gpu-table';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { CameraSnapshot, RenderHdrpClusterPhase } from '../render-contract';
@@ -53,6 +59,8 @@ import {
 } from '../shadow-atlas';
 import { getOrCreateSsaoBuffers } from '../ssao-buffers';
 import { getSsaoParameters } from '../ssao-config';
+// extendedLighting keeps Spot modifier factors on the existing light record
+// path; no additional render pass or submit owner is introduced.
 import type { BindGroupCounts, RenderFrameState } from './frame-snapshot';
 import {
   computeProjectionMatrix,
@@ -155,10 +163,10 @@ export function buildPerFrameBindGroups(
   hdrpClusterBindGroup: BindGroup | null;
   hdrpClusterMembershipBindGroup: BindGroup | null;
 } {
-  // View main (#1) chain = b0(viewUniformBuffer), b1(pointLightsBuffer),
-  // b2(spotLightsBuffer), b3(graph shadowDepth view or
+  // View main (#1) chain = b0(viewUniformBuffer), b3(graph shadowDepth view or
   // shadowFallbackTextureView), b4(shadowSampler), b5(atlas view), b6
-  // (shadowParams); variant 'view-main'.
+  // (shadowParams); variant 'view-main'. Local lights are never mirrored in
+  // the view group: Standard consumes the one Cluster group(2) payload.
   // Mesh (#2) chain = inner b0 buffer (meshStorageBuffer.buffer); variant 'mesh'.
   let viewBindGroup: BindGroup | null = null;
   let meshBindGroup: BindGroup | null = null;
@@ -229,6 +237,47 @@ export function buildPerFrameBindGroups(
         graphSpotShadowView !== undefined
           ? graphSpotShadowView
           : pipelineState.shadowFallbackTextureView;
+      const extendedLighting = pipelineState.extendedLightingAvailable ?? true;
+      const iesProfileTextureView = pipelineState.iesProfileTextureView;
+      const cookieTextureView = pipelineState.cookieTextureView;
+      const cookieMatrixBuffer = pipelineState.cookieMatrixBuffer;
+      const ltcLambertTextureView = pipelineState.ltcLambertTextureView;
+      const ltcGgxTextureView = pipelineState.ltcGgxTextureView;
+      const extendedLightingResources =
+        extendedLighting &&
+        iesProfileTextureView !== undefined &&
+        cookieTextureView !== undefined &&
+        cookieMatrixBuffer !== undefined &&
+        ltcLambertTextureView !== undefined &&
+        ltcGgxTextureView !== undefined
+          ? {
+              sampler: pipelineState.defaultSampler,
+              iesProfileTextureView,
+              cookieTextureView,
+              ltcLambertTextureView,
+              ltcGgxTextureView,
+              cookieMatrixBuffer,
+            }
+          : undefined;
+      if (extendedLighting && extendedLightingResources === undefined) {
+        return {
+          viewBindGroup: null,
+          meshBindGroup: null,
+          hdrpClusterBindGroup: null,
+          hdrpClusterMembershipBindGroup,
+        };
+      }
+      const extendedLightingViews =
+        extendedLightingResources !== undefined
+          ? [
+              extendedLightingResources.sampler,
+              extendedLightingResources.iesProfileTextureView,
+              extendedLightingResources.cookieTextureView,
+              extendedLightingResources.ltcLambertTextureView,
+              extendedLightingResources.ltcGgxTextureView,
+              extendedLightingResources.cookieMatrixBuffer,
+            ]
+          : [];
       const projectorAvailable = pipelineState.projectorAvailable !== false;
       const b11View = graphTargets?.projector ?? pipelineState.defaultWhiteTextureView;
       const b12Sampler = graphTargets?.projectorSampler ?? pipelineState.defaultSampler;
@@ -236,14 +285,15 @@ export function buildPerFrameBindGroups(
         frameState.viewBindGroupCache,
         [
           pipelineState.viewUniformBuffer,
-          pipelineState.pointLightsBuffer,
-          pipelineState.spotLightsBuffer,
           b3View,
           shadowSampler,
           b5View,
           pipelineState.shadowParamsBuffer,
           b8View,
-          ...(projectorAvailable ? [b11View, b12Sampler] : []),
+          ...extendedLightingViews,
+          ...(extendedLightingResources === undefined && projectorAvailable
+            ? [b11View, b12Sampler]
+            : []),
           pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
         ],
         'view-main',
@@ -256,20 +306,6 @@ export function buildPerFrameBindGroups(
                 value: { buffer: pipelineState.viewUniformBuffer, size: VIEW_UNIFORM_BYTES },
               },
             },
-            {
-              binding: 1,
-              resource: {
-                kind: 'buffer',
-                value: { buffer: pipelineState.pointLightsBuffer },
-              },
-            },
-            {
-              binding: 2,
-              resource: {
-                kind: 'buffer',
-                value: { buffer: pipelineState.spotLightsBuffer },
-              },
-            },
             {
               binding: 3,
               resource: {
@@ -339,12 +375,61 @@ export function buildPerFrameBindGroups(
                 },
               },
             },
-            ...(projectorAvailable
+            ...(extendedLightingResources === undefined && projectorAvailable
               ? [
                   { binding: 11, resource: { kind: 'textureView' as const, value: b11View } },
                   { binding: 12, resource: { kind: 'sampler' as const, value: b12Sampler } },
                 ]
               : []),
+            ...(extendedLightingResources !== undefined
+              ? [
+                  {
+                    binding: 9,
+                    resource: {
+                      kind: 'sampler' as const,
+                      value: extendedLightingResources.sampler,
+                    },
+                  },
+                  {
+                    binding: 11,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: extendedLightingResources.iesProfileTextureView,
+                    },
+                  },
+                  {
+                    binding: 12,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: extendedLightingResources.cookieTextureView,
+                    },
+                  },
+                  {
+                    binding: 13,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: extendedLightingResources.ltcLambertTextureView,
+                    },
+                  },
+                  {
+                    binding: 14,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: extendedLightingResources.ltcGgxTextureView,
+                    },
+                  },
+                  {
+                    binding: 15,
+                    resource: {
+                      kind: 'buffer' as const,
+                      value: {
+                        buffer: extendedLightingResources.cookieMatrixBuffer,
+                        size: COOKIE_MATRIX_BYTES,
+                      },
+                    },
+                  },
+                ]
+              : []),
             // feat-20260625-spot-light-shadow-mapping w25: the per-spot
             // fragment-read lightViewProj matrices fold into the View UBO
             // (binding 0, `view.spotLightViewProj`) — no standalone binding 9
@@ -451,12 +536,11 @@ export function buildPerFrameBindGroups(
 
 /**
  * feat-20260704 M3/w18: per-frame lighting preparation, extracted verbatim from
- * `recordFrame`. (1) pin the
- * point + spot shadow snapshot lists onto frameState for the URP shadow caster
+ * `recordFrame`. (1) pin the point + spot shadow snapshot lists onto frameState
+ * for the shadow caster
  * pass closures + lazy-allocate the point-shadow cube_array atlas on first
- * non-empty frame (AC-09 zero-shadow zero-alloc). (3) destructure ExtractedLights
- * into the directional-fallback `light` (zero-intensity Case C default), point /
- * spot arrays, and totalLightCount.
+ * non-empty frame (AC-09 zero-shadow zero-alloc). (3) derive the directional
+ * fallback and the unified local-light corpus used by Standard Cluster.
  *
  * @internal
  */
@@ -474,6 +558,7 @@ export function prepareFrameLighting(
     light: DirectionalLightSnapshot;
     pointLights: ExtractedLights['point'];
     spotLights: ExtractedLights['spot'];
+    rectLights: ExtractedLights['rect'];
     totalLightCount: number;
     standard: StandardTopologyInputValue;
   },
@@ -528,14 +613,16 @@ export function prepareFrameLighting(
   //
   //   - lights.directional : feeds the View UBO at slot [16..23]
   //                          (lightDir + lightColor; existing path).
-  //   - lights.point[]     : packed into pointLightsBuffer (std430).
-  //   - lights.spot[]      : packed into spotLightsBuffer (std430).
+  //   - lights.point/spot/rect[] : packed into the one unified Standard
+  //                                Cluster payload below. No per-kind light
+  //                                transport exists at the renderer boundary.
   //
   // Each variant carries the discriminant `kind` so the record-time packing
   // call sites can run exhaustive switch (charter P2 + AC-03).
   const directionalLight: DirectionalLightSnapshot | undefined = lights.directional;
   const pointLights = lights.point;
   const spotLights = lights.spot;
+  const rectLights = lights.rect;
 
   // Case C: 0 DirectionalLight = legitimate scene; the View UBO falls
   // back to a zero-intensity directional payload so the shader's
@@ -549,7 +636,10 @@ export function prepareFrameLighting(
   };
 
   const totalLightCount =
-    (directionalLight !== undefined ? 1 : 0) + pointLights.length + spotLights.length;
+    (directionalLight !== undefined ? 1 : 0) +
+    pointLights.length +
+    spotLights.length +
+    rectLights.length;
 
   const clusterGrid = frameState.installedPipelineConfig?.clusterGrid ?? DEFAULT_CLUSTER_GRID;
   const local = [
@@ -574,6 +664,16 @@ export function prepareFrameLighting(
           : 1000,
       source,
     })),
+    ...rectLights.map((source) => ({
+      kind: 'rect-area' as const,
+      shadowed: false,
+      position: source.position,
+      range:
+        (Number.isFinite(source.invRangeSquared) && source.invRangeSquared > 0
+          ? Math.sqrt(1 / source.invRangeSquared)
+          : 1000) + Math.hypot(source.halfWidth, source.halfHeight),
+      source,
+    })),
   ];
   const prepared = prepareStandardLighting({
     directional: directionalLight,
@@ -590,14 +690,16 @@ export function prepareFrameLighting(
   // Storage-capable Standard frames keep the same Cluster ABI even when the
   // local-light corpus is empty.  Directional-only scenes still need the
   // unified mesh group(2) contract so their PBR draws do not select a second
-  // direct layout; the existing transport emits a zero-light payload and the
-  // graph remains structurally identical.  The non-storage backend is the
-  // sole direct exception because no proven Cluster representation exists.
+  // local-light layout; the existing transport emits a zero-light payload and
+  // the graph remains structurally identical. The no-storage backend has no
+  // storage-backed local-light representation, so a directional-only frame
+  // remains the sole no-local transport case.
   if (prepared.value.local.length === 0 && !internals.device.caps.storageBuffer) {
     return ok({
       light,
       pointLights,
       spotLights,
+      rectLights,
       totalLightCount,
       standard: { kind: 'no-local-lights', prepared: prepared.value },
     });
@@ -619,11 +721,109 @@ export function prepareFrameLighting(
     light,
     pointLights,
     spotLights,
+    rectLights,
     totalLightCount,
     standard: { kind: 'clustered', prepared: prepared.value, transport: transport.value },
   });
 }
 
+function modifierDigest(data: Uint8Array): number {
+  let hash = 2166136261;
+  for (let index = 0; index < data.length; index += 1) {
+    hash ^= data[index] ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+/** Upload authored Spot modifier payloads into the renderer-owned array lane. */
+export function writeSpotModifierTextures(
+  internals: RenderSystemInternals,
+  pipelineState: PipelineState,
+  spots: readonly ExtractedLights['spot'][number][],
+): void {
+  const iesTexture = pipelineState.iesProfileTexture;
+  const cookieTexture = pipelineState.cookieTexture;
+  const cookieMatrixBuffer = pipelineState.cookieMatrixBuffer;
+  if (iesTexture === undefined && cookieTexture === undefined && cookieMatrixBuffer === undefined)
+    return;
+  let state = pipelineState.spotModifierUploadState;
+  if (state === undefined) {
+    state = { ies: new Map(), cookie: new Map(), cookieMatrix: new Map() };
+    pipelineState.spotModifierUploadState = state;
+  } else if (state.cookieMatrix === undefined) {
+    state = { ...state, cookieMatrix: new Map() };
+    pipelineState.spotModifierUploadState = state;
+  }
+  for (const spot of spots) {
+    if (spot.iesProfileSlice !== undefined && spot.iesProfileData !== undefined && iesTexture) {
+      if (spot.iesProfileData.byteLength === IES_SLICE_WIDTH * IES_SLICE_HEIGHT * 2) {
+        const digest = modifierDigest(spot.iesProfileData);
+        if (state.ies.get(spot.iesProfileSlice) !== digest) {
+          const result = internals.device.queue.writeTexture(
+            { texture: iesTexture, mipLevel: 0, origin: { x: 0, y: 0, z: spot.iesProfileSlice } },
+            spot.iesProfileData,
+            { offset: 0, bytesPerRow: IES_SLICE_WIDTH * 2, rowsPerImage: IES_SLICE_HEIGHT },
+            { width: IES_SLICE_WIDTH, height: IES_SLICE_HEIGHT, depthOrArrayLayers: 1 },
+          );
+          if (!result.ok) throw result.error;
+          state.ies.set(spot.iesProfileSlice, digest);
+        }
+      }
+    }
+    // Authored Cookie and the SpotLight projector share the same
+    // fixed 256x256 array transport on the extended topology. Their shader
+    // projection remains distinct: Cookie uses cookieMatrices, projector
+    // uses View.spotLightViewProj. Upload both identities when a frame carries
+    // both fields, while the direct-light metadata selects the one in use.
+    for (const modifier of [
+      {
+        slice: spot.cookieSlice,
+        data: spot.cookieData,
+        matrix: spot.cookieMatrix,
+      },
+      {
+        slice: spot.projectorSlice,
+        data: spot.projectorData,
+        matrix: spot.projectorMatrix,
+      },
+    ]) {
+      if (modifier.slice !== undefined && modifier.data !== undefined && cookieTexture) {
+        if (modifier.data.byteLength === COOKIE_SLICE_SIZE * COOKIE_SLICE_SIZE * 4) {
+          const digest = modifierDigest(modifier.data);
+          if (state.cookie.get(modifier.slice) !== digest) {
+            const result = internals.device.queue.writeTexture(
+              { texture: cookieTexture, mipLevel: 0, origin: { x: 0, y: 0, z: modifier.slice } },
+              modifier.data,
+              { offset: 0, bytesPerRow: COOKIE_SLICE_SIZE * 4, rowsPerImage: COOKIE_SLICE_SIZE },
+              { width: COOKIE_SLICE_SIZE, height: COOKIE_SLICE_SIZE, depthOrArrayLayers: 1 },
+            );
+            if (!result.ok) throw result.error;
+            state.cookie.set(modifier.slice, digest);
+          }
+        }
+      }
+      if (modifier.slice !== undefined && modifier.matrix !== undefined && cookieMatrixBuffer) {
+        const matrixBytes = new Uint8Array(
+          modifier.matrix.buffer,
+          modifier.matrix.byteOffset,
+          modifier.matrix.byteLength,
+        );
+        const digest = modifierDigest(matrixBytes);
+        if (state.cookieMatrix.get(modifier.slice) !== digest) {
+          const result = internals.device.queue.writeBuffer(
+            cookieMatrixBuffer,
+            modifier.slice * 16 * Float32Array.BYTES_PER_ELEMENT,
+            modifier.matrix,
+          );
+          if (!result.ok) throw result.error;
+          state.cookieMatrix.set(modifier.slice, digest);
+        }
+      }
+    }
+  }
+}
+
 /**
  * feat-20260704 M3/w18: write the point-shadow params UBO (bound at viewBg
  * binding 6), extracted verbatim from `recordFrame`.
@@ -723,6 +923,7 @@ export function writeHdrpClusterAndSsaoBuffers(
   gpuMembershipPipelineReady = false,
   membershipBindGroupLayout: BindGroupLayout | null = null,
   projectorLightSlotIndex?: number,
+  pipelineState?: PipelineState,
 ): Result<void, RenderError> {
   const configuredClusterGrid = prepared.layout.grid;
   const gpuMembership = transport.producer === 'gpu';
@@ -778,6 +979,14 @@ export function writeHdrpClusterAndSsaoBuffers(
     };
   }
 
+  if (pipelineState !== undefined) {
+    const preparedSpots: ExtractedLights['spot'][number][] = [];
+    for (const local of prepared.local) {
+      if (local.source?.kind === 'spot') preparedSpots.push(local.source);
+    }
+    writeSpotModifierTextures(internals, pipelineState, preparedSpots);
+  }
+
   const gridX = prepared.layout.grid.x;
   const gridY = prepared.layout.grid.y;
   const gridZ = prepared.layout.grid.z;
@@ -795,30 +1004,17 @@ export function writeHdrpClusterAndSsaoBuffers(
     profilePhase,
     'record/scene-state/hdrp-cluster/payload-packing',
     () => {
-      const lightDataPayload = new Float32Array(prepared.layout.lightDataSlotCount * 16);
+      const lightDataPayload = new Float32Array(
+        prepared.layout.lightDataSlotCount * DIRECT_LIGHT_SLOT_FLOAT_COUNT,
+      );
       let slotIdx = 0;
       for (const local of prepared.local) {
         const source = local.source;
         if (source === undefined) return null;
         const projectorSelected =
-          projectorLightSlotIndex !== undefined && projectorLightSlotIndex === slotIdx;
-        const packed =
-          source.kind === 'point' &&
-          source.shadowAtlasLayer !== undefined &&
-          source.shadowAtlasLayer >= 0 &&
-          source.shadowNear !== undefined &&
-          source.shadowFar !== undefined
-            ? packLightSlot(
-                source,
-                {
-                  shadowAtlasLayer: source.shadowAtlasLayer,
-                  near: source.shadowNear,
-                  far: source.shadowFar,
-                },
-                projectorSelected,
-              )
-            : packLightSlot(source, undefined, projectorSelected);
-        lightDataPayload.set(packed, slotIdx * 16);
+          projectorLightSlotIndex === undefined ? undefined : projectorLightSlotIndex === slotIdx;
+        const packed = packDirectLightSlot(source, projectorSelected);
+        lightDataPayload.set(packed, slotIdx * DIRECT_LIGHT_SLOT_FLOAT_COUNT);
         slotIdx += 1;
       }
 
@@ -843,7 +1039,10 @@ export function writeHdrpClusterAndSsaoBuffers(
 
       return {
         hdrpBuffers,
-        lightDataUploadPayload: lightDataPayload.subarray(0, slotIdx * 16),
+        lightDataUploadPayload: lightDataPayload.subarray(
+          0,
+          slotIdx * DIRECT_LIGHT_SLOT_FLOAT_COUNT,
+        ),
         clusterUniformPayload: new Uint8Array(clusterUniformPayload),
       };
     },

package/src/record/frame-snapshot.ts

@@ -2,6 +2,7 @@
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
 import type { World } from '@forgeax/engine-ecs';
+import type { RenderReadVersion } from '@forgeax/engine-ecs/projection';
 import { vec3 } from '@forgeax/engine-math';
 import type { ResolvedColorTargetDescriptor } from '@forgeax/engine-render-graph';
 import type {
@@ -81,6 +82,7 @@ import type {
   RenderableSnapshot,
   SpotLightSnapshot,
 } from '../render-system-extract';
+import type { ProbeBlendRecord } from '../scene/probe-blend-record';
 import type { ShadowAtlas } from '../shadow-atlas';
 import type {
   TemporalFrame,
@@ -90,6 +92,18 @@ import type {
 import type { VolumetricFogInspection } from '../volume/inspection';
 import type { VolumeTemporalSignature } from '../volume/temporal';
 
+/** Retained probe record bytes carried with one extracted render frame. */
+export interface ProbeBlendFrameSnapshot {
+  readonly records: readonly ProbeBlendRecord[];
+  readonly recordByteLength: 160;
+}
+
+/** Renderer-owned GPU cache entry for one object's 160B probe record. */
+export interface ProbeBlendBufferCacheEntry {
+  readonly generation: number;
+  readonly bytes: Uint8Array;
+}
+
 /**
  * feat-20260608-create-app-param-surface-trim / M1 / D-8 (q8 user lock):
  * fallback clear color when the world carries no Camera entity. Opaque
@@ -154,14 +168,17 @@ export function validateGraphTargetCaptureReadback(input: {
   readonly bytes: Uint8Array;
   readonly expectedByteLength: number;
   readonly sentinel?: Uint8Array;
+  readonly allowZero?: boolean;
 }): GraphTargetCaptureReadbackValidation {
-  const { bytes, expectedByteLength, sentinel } = input;
+  const { bytes, expectedByteLength, sentinel, allowZero = false } = input;
   if (bytes.byteLength !== expectedByteLength)
     return { ok: false, code: 'capture-readback-length' };
   if (sentinel?.every((value, index) => bytes[index] === value)) {
     return { ok: false, code: 'capture-readback-untouched-sentinel' };
   }
-  if (bytes.every((value) => value === 0)) return { ok: false, code: 'capture-readback-empty' };
+  if (!allowZero && bytes.every((value) => value === 0)) {
+    return { ok: false, code: 'capture-readback-empty' };
+  }
   for (let index = 0; index + 1 < bytes.length; index += 2) {
     const exponent = ((bytes[index + 1] ?? 0) >>> 2) & 0x1f;
     if (exponent === 0x1f) return { ok: false, code: 'capture-readback-non-finite' };
@@ -191,6 +208,25 @@ export interface GraphTargetCaptureRequest {
   };
 }
 
+/** Renderer-private readback request for the Standard fallback MRT. */
+export interface ReflectionFallbackReadbackRequest {
+  readonly name: string;
+  readonly buffer: Buffer;
+  readonly bytesPerRow: number;
+  readonly width: number;
+  readonly height: number;
+  readonly expected: {
+    readonly format: ResolvedColorTargetDescriptor['format'];
+    readonly width: number;
+    readonly height: number;
+    readonly usage: number;
+    readonly graphGeneration: number;
+    readonly frameId: number;
+    readonly textureIdentity: number;
+  };
+  encoded: boolean;
+}
+
 /**
  * Build a synthetic CameraSnapshot the record stage uses when the world
  * carries no Camera entity. Identity-shaped projection / view inputs
@@ -253,12 +289,14 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
  */
 export interface RenderFrameState {
   frameNumber: number;
+  /** Demand for the frame-local Standard fallback MRT. */
+  reflectionFallbackDemand?: boolean;
   /** Monotonic compiled-graph identity used by diagnostic readbacks. */
   graphGeneration: number;
   /** Number of successfully submitted TAA frames; failed attempts do not advance it. */
   successfulTemporalFrameIndex?: number;
   /** The renderer-owned accepted-submit temporal fact consumed by consumers. */
-  temporalFrame?: TemporalFrame;
+  temporalFrame?: TemporalFrame | undefined;
   /** The sole transaction that advances temporal history after queue.submit. */
   readonly temporalFrameTransaction: TemporalFrameTransaction;
   /** Staged input is consumed only by the graph submit owner. */
@@ -271,6 +309,8 @@ export interface RenderFrameState {
     readonly graphGeneration: number;
   } | null;
   graphTargetCapture?: GraphTargetCaptureRequest | undefined;
+  /** One-frame producer-owned copy target for fallback MRT readback. */
+  reflectionFallbackReadback?: ReflectionFallbackReadbackRequest | undefined;
   /** Last successfully rendered static directional shadow atlas token. */
   directionalShadowCache: DirectionalShadowCache | null;
   /** Last successfully submitted camera post-process mode. */
@@ -314,6 +354,10 @@ export interface RenderFrameState {
   readonly retiredCompiledFrameGraphs: Set<CompiledRenderGraph<RenderPipelineFrame>>;
   /** Physical outputs projected by typed graph passes for downstream observers. */
   currentFrameObservationSource: FrameObservationSource | undefined;
+  /** Completed-frame source for the producer-owned fallback MRT. */
+  reflectionFallbackObservationSource?: FrameObservationSource | undefined;
+  /** Completion fence for the producer-owned fallback row/readback promotion. */
+  reflectionFallbackCompletion?: Promise<void> | undefined;
   /** Camera antialias mode for the last successfully submitted graph. */
   lastSuccessfulCameraAntialias: CameraSnapshot['antialias'] | undefined;
   /** Staged TAA GPU state is promoted only after queue.submit succeeds. */
@@ -331,6 +375,11 @@ export interface RenderFrameState {
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
+  /** Per-object ProbeBlendRecord buffers; upload is one atomic 160B write. */
+  readonly probeBlendBuffers: Map<number, ProbeBlendBufferCacheEntry>;
+  /** One renderer-owned record array; each object selects its 256B-aligned lane. */
+  probeBlendRecordBuffer?: GpuBuffer;
+  probeBlendRecordBufferCapacity: number;
   /** Per-entity vertex buffers for the Standard CPU morph lane. */
   readonly morphBuffers?: Map<number, MorphBufferCacheEntry>;
   readonly hdrpClusterBinScratch: ClusterBinScratch;
@@ -358,15 +407,11 @@ export interface RenderFrameState {
   transientInstanceBuffers: InstanceBufferCacheEntry[];
   warnedZeroLightStandard: boolean;
   /**
-   * feax-20260608-multi-light-warn-once M3: once-warn latch for multi-light
-   * overrun per bucket (directional N>1 / point N>4 / spot N>4). Fires at
-   * most once per RenderSystem lifetime per bucket so AI users see a single
-   * actionable console.warn without per-frame flooding (charter P3 explicit
-   * failure: warn-once preserves signal/noise floor).
+   * feat-20260608-multi-light-warn-once M3: once-warn latch for the
+   * single-directional authoring constraint. Standard local lights use the
+   * unified Cluster budget; there is no per-kind local-light cap.
    */
   warnedMultiLightDirectional: boolean;
-  warnedMultiLightPoint: boolean;
-  warnedMultiLightSpot: boolean;
   /**
    * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
    * once-warn latches for >1 Skylight / >1 SkyboxBackground entity. Fire at most
@@ -662,11 +707,11 @@ export interface DirectionalShadowCache {
  * ECS state that can change the contents of a directional shadow map.
  *
  * The ECS-owned RenderReadLease is the only render-facing mutation boundary.
- * Its cursor is intentionally conservative: any published World change
+ * Its version is intentionally conservative: any published World change
  * invalidates the cached atlas, while render never reaches through World for
  * component-clock storage.
  */
 export interface DirectionalShadowWorldState {
   readonly worldIdentity: string;
-  readonly changeCursor: number;
+  readonly version: RenderReadVersion;
 }