@forgeax/engine-render 0.1.28 → 0.1.30

package/src/reflection/record-owner.ts

@@ -9,6 +9,8 @@ import type {
   TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { toShared } from '@forgeax/engine-types';
 import { buildCubeCameraFaceViews } from '../capture/cube-views';
 import {
   createFaceUniformsBuffer,
@@ -30,7 +32,6 @@ import {
   createIblPipelines,
   getOrCreateIblCache,
   PREFILTER_MIP_LEVELS,
-  PREFILTER_SIZE,
 } from '../ibl/IblPipelineCache';
 import type {
   ReflectionFallbackReadbackReceipt,
@@ -42,7 +43,8 @@ import type { ReflectionProbeRecordState, RenderSystemInternals } from '../recor
 import type { ReflectionProbeGraphWork } from '../record/typed-frame-graph';
 import { REFLECTION_PROBE_VIEW_SLOT_BASE, VIEW_UNIFORM_SLOT_STRIDE } from '../record/view-ubo';
 import type { CameraSnapshot } from '../render-contract';
-import type { SkylightSnapshot } from '../render-system-extract';
+import type { SkyboxSnapshot, SkylightSnapshot } from '../render-system-extract';
+import { createProbeBackgroundResources, type ProbeBackgroundResources } from './background';
 import {
   advanceProbeFilter,
   commitProbeFilterStep,
@@ -76,6 +78,12 @@ type ProbeCubeSet = {
 
 type ProbeGpuResource = {
   fact: ReflectionProbeFact;
+  captureFact: ReflectionProbeFact;
+  diffusePayload: readonly number[];
+  captureSceneRevision: string;
+  captureStartedFrame: number;
+  lastCompletedFrame: number;
+  activeFact?: ReflectionProbeFact;
   index: number;
   filter: ProbeFilterState;
   rawFaceCursor: number;
@@ -93,6 +101,7 @@ type ProbeGpuResource = {
 };
 
 type ProbeSharedResources = {
+  readonly background: ProbeBackgroundResources | undefined;
   readonly faceUniforms: Buffer;
   readonly prefilterUniforms: Buffer;
   readonly vertexBuffer: Buffer;
@@ -126,16 +135,16 @@ export class ReflectionProbeRecordOwner {
   private lastAcceptedCount = 0;
   private lastScheduledRawFaces = 0;
   private lastScheduledFilteredSteps = 0;
+  private workCursor = 0;
+  private currentFrame = 0;
   private lastSelection: ReflectionProbeSelectionInspection = { kind: 'skylight' };
   private outputFormat: TextureFormat;
   private fallbackFormatAvailable: boolean;
   private nextFallbackTicket = 0;
-  // Readback completion is asynchronous and can overlap the next frame's
-  // prepare. Key tickets by immutable id and retain only the latest ticket
-  // per renderable; an older completion is stale by definition once a newer
-  // candidate has been staged, but cannot erase the newer ticket.
-  private pendingFallback = new Map<number, PendingFallback>();
-  private latestFallbackTickets = new Map<string, number>();
+  // Submitted frames own their immutable candidates until completion. Keep
+  // only the current projection here: preparing a source-identical frame
+  // must not starve an earlier asynchronous readback of publication.
+  private latestFallbackTickets = new Map<string, PendingFallback>();
   private fallbackRetiredFrames = new Map<string, number>();
   private fallbackCommittedFrames = new Map<string, number>();
   private fallbackGenerations = new Map<
@@ -173,6 +182,22 @@ export class ReflectionProbeRecordOwner {
       if (resource.active !== undefined) activeCount += 1;
     }
     return {
+      updates: [...this.resources.values()].map((resource) => ({
+        worldId: resource.fact.worldId,
+        entityKey: resource.fact.entityKey,
+        intent: resource.fact.updateIntent ?? 'once',
+        activeGeneration: resource.filter.activeGeneration,
+        requestedRevision: resource.fact.revision,
+        capturedRevision: resource.captureFact.revision,
+        pending: resource.filter.cursor < resource.filter.faceCount * resource.filter.mipCount,
+        captureStartedFrame: resource.captureStartedFrame,
+        lastCompletedFrame: resource.lastCompletedFrame,
+        latencyFrames:
+          resource.lastCompletedFrame < resource.captureStartedFrame
+            ? undefined
+            : resource.lastCompletedFrame - resource.captureStartedFrame,
+      })),
+      workBudgetPerFrame: 1,
       selection: this.lastSelection,
       factCount: this.lastFactCount,
       acceptedCount: this.lastAcceptedCount,
@@ -283,14 +308,13 @@ export class ReflectionProbeRecordOwner {
   }
 
   private retireFallbackState(frameId: number): void {
-    for (const pending of this.pendingFallback.values()) {
+    for (const pending of this.latestFallbackTickets.values()) {
       const key = pending.projection.renderableKey;
       if (key !== undefined) this.fallbackRetiredFrames.set(key, frameId);
     }
     for (const key of this.fallbackReceipts.keys()) {
       this.fallbackRetiredFrames.set(key, frameId);
     }
-    this.pendingFallback.clear();
     this.latestFallbackTickets.clear();
     this.fallbackReceipts.clear();
     this.fallbackSignatures.clear();
@@ -307,7 +331,8 @@ export class ReflectionProbeRecordOwner {
     if (factory === undefined) return;
     const attempt = this.pipelineWarmupAttempts + 1;
     this.pipelineWarmupAttempts = attempt;
-    this.pipelineWarmup = createIblPipelines(
+    const device = this.internals.device;
+    const warmup = createIblPipelines(
       this.internals.deviceScope,
       this.internals.device,
       (device, descriptor) => {
@@ -320,20 +345,42 @@ export class ReflectionProbeRecordOwner {
           : this.internals.createShaderModule(device, labeled);
       },
       this.outputFormat,
-    ).then((result) => {
-      if (!result.ok) {
-        this.pipelineWarmupFailure = `${result.error.code}: ${result.error.hint}`;
-        console.warn('[forgeax] ReflectionProbe IBL warmup retry', this.pipelineWarmupFailure);
-        this.pipelineWarmup = undefined;
-        return;
-      }
-      this.shared = this.createSharedResources(result.value.prefilterPipeline);
-      if (this.shared === undefined) {
-        this.pipelineWarmupFailure = 'renderer-owned IBL resources could not be allocated';
-        console.warn('[forgeax] ReflectionProbe IBL resource allocation retry');
+    )
+      .then(async (result) => {
+        if (this.pipelineWarmup !== warmup) return;
+        if (!result.ok) {
+          this.pipelineWarmupFailure = `${result.error.code}: ${result.error.hint}`;
+          console.warn('[forgeax] ReflectionProbe IBL warmup retry', this.pipelineWarmupFailure);
+          this.pipelineWarmup = undefined;
+          return;
+        }
+        const background = await createProbeBackgroundResources(this.internals, this.outputFormat);
+        if (this.pipelineWarmup !== warmup) {
+          if (background !== undefined) device.destroyBuffer(background.uniform);
+          return;
+        }
+        this.shared = this.createSharedResources(result.value.prefilterPipeline, background);
+        if (this.shared === undefined) {
+          this.pipelineWarmupFailure = 'renderer-owned IBL resources could not be allocated';
+          console.warn('[forgeax] ReflectionProbe IBL resource allocation retry');
+          this.pipelineWarmup = undefined;
+        }
+      })
+      .catch((cause: unknown) => {
+        if (this.pipelineWarmup !== warmup) return;
+        this.pipelineWarmupFailure = cause instanceof Error ? cause.message : String(cause);
         this.pipelineWarmup = undefined;
-      }
-    });
+        this.internals.errorRegistry.fire(
+          cause instanceof RhiError
+            ? cause
+            : new RhiError({
+                code: 'shader-compile-failed',
+                expected: 'complete reflection probe background and IBL pipelines',
+                hint: `inspect the shader manifest and device error: ${this.pipelineWarmupFailure}`,
+              }),
+        );
+      });
+    this.pipelineWarmup = warmup;
   }
 
   prepare(
@@ -342,7 +389,10 @@ export class ReflectionProbeRecordOwner {
     displayCamera: CameraSnapshot | undefined,
     frameId = this.nextFallbackTicket + 1,
     skylight: SkylightSnapshot | undefined = undefined,
+    sceneRevision = '',
+    skybox?: SkyboxSnapshot,
   ): ReflectionProbeRecordState {
+    this.currentFrame = frameId;
     this.refreshFallbackCapabilities(frameId);
     this.lastFactCount = facts.length;
     this.lastScheduledRawFaces = 0;
@@ -374,7 +424,7 @@ export class ReflectionProbeRecordOwner {
       );
       if (!admission.ok) continue;
       const key = `${fact.worldId}:${fact.entityKey}`;
-      const resource = this.resourceFor(key, fact, acceptedCount);
+      const resource = this.resourceFor(key, fact, acceptedCount, sceneRevision, skylight);
       if (resource === undefined) continue;
       acceptedCount += 1;
       acceptedBytes = admission.acceptedBytes;
@@ -392,7 +442,9 @@ export class ReflectionProbeRecordOwner {
     }
     const rows = [...accepted.values()]
       .map((resource) => {
-        const active = resource.active;
+        const active = resource.activeFact?.center.every((v, i) => v === resource.fact.center[i])
+          ? resource.active
+          : undefined;
         if (active === undefined) return undefined;
         return {
           primitiveKey: `${resource.fact.worldId}:${resource.fact.entityKey}`,
@@ -411,7 +463,23 @@ export class ReflectionProbeRecordOwner {
       .filter((row): row is NonNullable<typeof row> => row !== undefined);
     const table = buildReflectionProbeTable(rows);
     const work: ReflectionProbeGraphWork[] = [];
-    for (const resource of accepted.values()) {
+    const environmentReady = [skylight?.equirectHandle, skybox?.equirectHandle].every(
+      (handle) =>
+        handle === undefined ||
+        handle === 0 ||
+        this.internals.gpuStore.getCubemapGpuView(toShared<'EquirectAsset'>(handle)) !== undefined,
+    );
+    const candidates = [...accepted.values()];
+    const captureTickets: Array<{
+      resource: ProbeGpuResource;
+      pending: NonNullable<ProbeGpuResource['pending']>;
+    }> = [];
+    const deviceGeneration = this.internals.deviceScope.generation;
+    for (let offset = 0; offset < candidates.length; offset++) {
+      const candidateIndex = (this.workCursor + offset) % candidates.length;
+      const resource = candidates[candidateIndex];
+      if (resource === undefined) continue;
+      if (resource.pending !== undefined) continue;
       const rawCaptureFace =
         resource.rawFaceCursor < resource.raw.faceViews.length ? resource.rawFaceCursor : undefined;
       const step =
@@ -419,7 +487,7 @@ export class ReflectionProbeRecordOwner {
           ? advanceProbeFilter(resource.filter)
           : undefined;
       if (this.shared === undefined) continue;
-      if (rawCaptureFace === undefined && step === undefined) continue;
+      if (!environmentReady || (rawCaptureFace === undefined && step === undefined)) continue;
       const filterGroup0 =
         step === undefined
           ? undefined
@@ -452,15 +520,15 @@ export class ReflectionProbeRecordOwner {
               ],
             });
       if (filterGroup0 !== undefined && !filterGroup0.ok) continue;
-      if (resource.pending !== undefined) continue;
       resource.pending = { rawCaptureFace, step };
+      captureTickets.push({ resource, pending: resource.pending });
       if (rawCaptureFace !== undefined) this.lastScheduledRawFaces += 1;
       if (step !== undefined) this.lastScheduledFilteredSteps += 1;
       const face =
         rawCaptureFace === undefined
           ? undefined
           : buildCubeCameraFaceViews({
-              position: resource.fact.center,
+              position: resource.captureFact.center,
               near: 0.1,
               far: 100,
             })[rawCaptureFace];
@@ -470,9 +538,9 @@ export class ReflectionProbeRecordOwner {
           : {
               ...displayCamera,
               position: vec3.create(
-                resource.fact.center[0] ?? 0,
-                resource.fact.center[1] ?? 0,
-                resource.fact.center[2] ?? 0,
+                resource.captureFact.center[0] ?? 0,
+                resource.captureFact.center[1] ?? 0,
+                resource.captureFact.center[2] ?? 0,
               ),
               world: mat4.invert(mat4.create(), face.view),
               fov: Math.PI / 2,
@@ -493,6 +561,7 @@ export class ReflectionProbeRecordOwner {
         outputFormat: this.outputFormat,
         sampler: resource.sampler,
         filterPipeline: this.shared.filterPipeline,
+        ...(this.shared.background === undefined ? {} : { background: this.shared.background }),
         filterGroup0: filterGroup0?.value,
         filterGroup1: resource.filterGroup1,
         cubeVertexBuffer: this.shared.vertexBuffer,
@@ -509,6 +578,8 @@ export class ReflectionProbeRecordOwner {
         filteredSize: resource.candidate.size,
         step,
       });
+      this.workCursor = (candidateIndex + 1) % candidates.length;
+      break;
     }
     return {
       table,
@@ -533,6 +604,9 @@ export class ReflectionProbeRecordOwner {
           completed,
           fallbackOutput,
           fallbackRequested,
+          captureTickets,
+          deviceGeneration,
+          frameId,
         ),
     };
   }
@@ -555,15 +629,13 @@ export class ReflectionProbeRecordOwner {
       }>;
     },
     fallbackRequested = true,
+    captureTickets: readonly {
+      resource: ProbeGpuResource;
+      pending: NonNullable<ProbeGpuResource['pending']>;
+    }[] = [],
+    deviceGeneration = this.internals.deviceScope.generation,
+    submittedFrame = this.currentFrame,
   ): Promise<void> {
-    if (!fallbackRequested) {
-      // The scene has no Standard PBR renderable that can consume the
-      // producer's second output, so the graph intentionally omits the MRT.
-      // Retire only this frame's candidate tickets; keep any previously
-      // committed LKG receipt without manufacturing a readback failure.
-      this.discardFallbackTickets(fallbackTickets);
-      return;
-    }
     let completionFailure: ReflectionFallbackFailureInput | undefined;
     if (completed !== undefined) {
       try {
@@ -577,14 +649,20 @@ export class ReflectionProbeRecordOwner {
         };
       }
     }
-    await this.completeFallbackSubmission(
-      submitted,
-      fallbackTickets,
-      fallbackOutput,
-      completionFailure,
-    );
-    for (const resource of this.resources.values()) {
-      const pending = resource.pending;
+    if (fallbackRequested)
+      await this.completeFallbackSubmission(
+        submitted,
+        fallbackTickets,
+        fallbackOutput,
+        completionFailure,
+      );
+    if (deviceGeneration !== this.internals.deviceScope.generation) return;
+    for (const { resource, pending } of captureTickets) {
+      if (
+        resource.pending !== pending ||
+        this.resources.get(`${resource.fact.worldId}:${resource.fact.entityKey}`) !== resource
+      )
+        continue;
       delete resource.pending;
       if (!submitted || pending === undefined) continue;
       if (pending.rawCaptureFace !== undefined) {
@@ -599,6 +677,8 @@ export class ReflectionProbeRecordOwner {
       if (resource.filter.cursor >= resource.filter.faceCount * resource.filter.mipCount) {
         const previous = resource.active;
         resource.active = resource.candidate;
+        resource.activeFact = resource.captureFact;
+        resource.lastCompletedFrame = submittedFrame;
         resource.candidate = resource.spare ?? previous ?? resource.candidate;
         resource.spare = undefined;
       }
@@ -622,18 +702,29 @@ export class ReflectionProbeRecordOwner {
       facts.length === 0 && skylight === undefined
         ? new Map([['__frame__', { kind: 'skylight' as const }]])
         : selections;
+    const skylightSignature =
+      skylight === undefined
+        ? ''
+        : `:${JSON.stringify([skylight.equirectHandle, skylight.intensity, ...skylight.color, ...skylight.rotation])}`;
     for (const [renderableKey, selection] of stagedSelections) {
       const probeKey =
         selection.kind === 'probe' ? `${selection.worldId}:${selection.entityKey}` : undefined;
       const resource = probeKey === undefined ? undefined : accepted.get(probeKey);
       const source = resolveReflectionFallbackSource(
         selection,
-        resource?.active !== undefined,
+        resource?.active !== undefined &&
+          resource.activeFact?.center.every((v, i) => v === resource.fact.center[i]) === true,
         skylight !== undefined,
       );
       const projection = deriveReflectionFallbackProjection({
         renderableKey,
-        sourceKey: reflectionFallbackSourceKey(source, selection, skylight),
+        sourceKey:
+          reflectionFallbackSourceKey(source, selection, skylight) +
+          (source === 'probe' && resource !== undefined
+            ? `@${resource.filter.activeGeneration}:${resource.fact.boxProjection === true}:${resource.fact.intensity}`
+            : '') +
+          skylightSignature +
+          (source === 'neutral' ? '' : `:catalog:${this.internals.assets.catalogEpoch}`),
         source,
         coverage: reflectionFallbackCoverage(source, resource?.fact, selection),
         ...(resource === undefined ? {} : { extent: resource.fact.halfExtents }),
@@ -650,6 +741,13 @@ export class ReflectionProbeRecordOwner {
         continue;
       }
       const signature = reflectionFallbackProjectionSignature(projection.value);
+      const previousCandidate = this.latestFallbackTickets.get(renderableKey);
+      if (
+        previousCandidate !== undefined &&
+        reflectionFallbackProjectionSignature(previousCandidate.projection) !== signature
+      ) {
+        this.fallbackRetiredFrames.set(renderableKey, frameId);
+      }
       const previousSignature = this.fallbackSignatures.get(renderableKey);
       if (previousSignature !== undefined && previousSignature !== signature) {
         // A changed source, coverage, extent, or BRDF is not a compatible LKG.
@@ -668,11 +766,8 @@ export class ReflectionProbeRecordOwner {
         deviceGeneration: this.internals.deviceScope.generation,
         projection: projection.value,
       };
-      const previousTicket = this.latestFallbackTickets.get(renderableKey);
-      if (previousTicket !== undefined) this.pendingFallback.delete(previousTicket);
       tickets.set(renderableKey, pending);
-      this.pendingFallback.set(pending.ticket, pending);
-      this.latestFallbackTickets.set(renderableKey, pending.ticket);
+      this.latestFallbackTickets.set(renderableKey, pending);
     }
     // Retire rows that disappeared from this frame's main-pass selection.
     // Keeping them would make a detached inspection row outlive its source.
@@ -688,23 +783,12 @@ export class ReflectionProbeRecordOwner {
     for (const renderableKey of this.fallbackGenerations.keys()) {
       if (!tickets.has(renderableKey)) this.fallbackGenerations.delete(renderableKey);
     }
-    // An in-flight ticket for a row that disappeared is no longer admissible.
-    // Remove it eagerly so the map remains bounded; completion still sees the
-    // missing ticket and safely rejects it as stale.
-    for (const [ticket, pending] of this.pendingFallback) {
-      const key = pending.projection.renderableKey;
-      const current = key === undefined ? undefined : tickets.get(key);
-      if (
-        key !== undefined &&
-        pending.frameId < frameId &&
-        (current === undefined ||
-          current.projection.source === 'neutral' ||
-          reflectionFallbackProjectionSignature(current.projection) !==
-            reflectionFallbackProjectionSignature(pending.projection))
-      ) {
-        this.pendingFallback.delete(ticket);
-        if (current === undefined) this.fallbackRetiredFrames.set(key, frameId);
-      }
+    // Retire even uncommitted rows, so disappear/reappear cannot revive an
+    // old completion. Storage stays bounded by current renderables.
+    for (const key of this.latestFallbackTickets.keys()) {
+      if (tickets.has(key)) continue;
+      this.latestFallbackTickets.delete(key);
+      this.fallbackRetiredFrames.set(key, frameId);
     }
     if (tickets.size === 0 && facts.length === 0) {
       const neutralKey = '__frame__';
@@ -723,11 +807,8 @@ export class ReflectionProbeRecordOwner {
           deviceGeneration: this.internals.deviceScope.generation,
           projection: projection.value,
         };
-        const previousTicket = this.latestFallbackTickets.get(neutralKey);
-        if (previousTicket !== undefined) this.pendingFallback.delete(previousTicket);
         tickets.set(neutralKey, pending);
-        this.pendingFallback.set(pending.ticket, pending);
-        this.latestFallbackTickets.set(neutralKey, pending.ticket);
+        this.latestFallbackTickets.set(neutralKey, pending);
       }
     }
     this.selectFallbackReceiptKey(tickets, skylight !== undefined);
@@ -762,7 +843,8 @@ export class ReflectionProbeRecordOwner {
     let sourceMatch: string | undefined;
     for (const [key, pending] of tickets) {
       const matches =
-        pending.projection.sourceKey === selectedSourceKey ||
+        (selectedSourceKey !== undefined &&
+          pending.projection.sourceKey?.startsWith(`${selectedSourceKey}@`) === true) ||
         (selectedSourceKey === undefined && pending.projection.source === 'skylight');
       if (matches && (sourceMatch === undefined || key < sourceMatch)) sourceMatch = key;
     }
@@ -778,19 +860,13 @@ export class ReflectionProbeRecordOwner {
     this.fallbackReceiptKey = firstKey;
   }
 
-  private discardFallbackTickets(fallbackTickets: ReadonlyMap<string, PendingFallback>): void {
-    for (const pending of fallbackTickets.values()) {
-      this.pendingFallback.delete(pending.ticket);
-    }
-  }
-
   /** Commit exact-zero neutral rows even when a non-neutral MRT readback fails. */
   private commitNeutralFallbacks(fallbackTickets: ReadonlyMap<string, PendingFallback>): number {
     let committed = 0;
     for (const [renderableKey, pending] of fallbackTickets) {
       if (
         pending.projection.source === 'neutral' &&
-        this.latestFallbackTickets.get(renderableKey) === pending.ticket &&
+        this.latestFallbackTickets.get(renderableKey) === pending &&
         pending.deviceGeneration === this.internals.deviceScope.generation
       ) {
         this.commitFallbackProjection(renderableKey, pending, 'neutral');
@@ -813,8 +889,9 @@ export class ReflectionProbeRecordOwner {
       source: previous?.sourceGeneration ?? 0,
       projection: previous?.projectionGeneration ?? 0,
     };
+    const { linearHdr: _referencePixel, ...projection } = pending.projection;
     const receipt = Object.freeze({
-      ...pending.projection,
+      ...projection,
       rendererId: this.internals.deviceScope.owner,
       producerId: REFLECTION_PROBE_PRODUCER_ID,
       ...(this.internals.ssrIdentity === undefined ? {} : { identity: this.internals.ssrIdentity }),
@@ -839,7 +916,7 @@ export class ReflectionProbeRecordOwner {
   /** Retain only a source-identical committed row after candidate failure. */
   private preserveFallbackLkg(fallbackTickets: ReadonlyMap<string, PendingFallback>): void {
     for (const [renderableKey, pending] of fallbackTickets) {
-      if (this.latestFallbackTickets.get(renderableKey) !== pending.ticket) continue;
+      if (this.latestFallbackTickets.get(renderableKey) !== pending) continue;
       const previous = this.fallbackReceipts.get(renderableKey);
       const signature = reflectionFallbackProjectionSignature(pending.projection);
       const compatible =
@@ -887,14 +964,10 @@ export class ReflectionProbeRecordOwner {
     // fallback attachment probe. The prepare phase already published the
     // structured capability failure and retired all current rows.
     if (!this.fallbackFormatAvailable) {
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
-    // A graph attachment descriptor is not a producer receipt.  Until the
-    // completed frame has supplied mapped bytes and their digest, discard the
-    // pending ticket and keep the last committed row (if any) as LKG.  This
-    // prevents the projection's zero quartet from becoming false active
-    // evidence when the copy/readback owner has not run.
+    // Source/coverage publication follows real graph execution and GPU completion.
+    // Pixel validation is a separate, explicitly requested diagnostic capability.
     if (!submitted || fallbackTickets.size === 0) {
       if (!submitted) {
         this.recordFallbackFailure(
@@ -906,13 +979,14 @@ export class ReflectionProbeRecordOwner {
         );
         this.preserveFallbackLkg(fallbackTickets);
       }
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
-    if (fallbackOutput?.readback === undefined) {
-      // Neutral is an exact producer-owned zero and does not need an MRT
-      // sample.  A successfully submitted frame may commit those rows even
-      // when the non-neutral rows have no mapped readback and must stay LKG.
+    if (
+      fallbackOutput === undefined ||
+      (this.internals.captureReflectionFallbackReadback === true &&
+        fallbackOutput.readback === undefined)
+    ) {
+      // Neutral rows require no attachment; non-neutral rows need an executed output.
       const committedNeutral = this.commitNeutralFallbacks(fallbackTickets);
       const nonNeutral = new Map(
         [...fallbackTickets].filter(([, pending]) => pending.projection.source !== 'neutral'),
@@ -924,21 +998,25 @@ export class ReflectionProbeRecordOwner {
       if (nonNeutral.size > 0) {
         this.recordFallbackFailure({
           stage: 'completion',
-          code: 'reflection-fallback-readback-missing',
-          expected: 'a mapped fallback MRT readback for every non-neutral source',
+          code:
+            fallbackOutput === undefined
+              ? 'reflection-fallback-output-missing'
+              : 'reflection-fallback-readback-missing',
+          expected: 'a completed fallback MRT output and, when requested, mapped diagnostic bytes',
           detail: { frameId: fallbackTickets.values().next().value?.frameId },
         });
       }
       this.preserveFallbackLkg(nonNeutral);
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
-    let readback: {
-      readonly linearHdr: readonly [number, number, number, number];
-      readonly hash: string;
-      readonly graphGeneration: number;
-      readonly textureIdentity: number;
-    };
+    let readback:
+      | {
+          readonly linearHdr: readonly [number, number, number, number];
+          readonly hash: string;
+          readonly graphGeneration: number;
+          readonly textureIdentity: number;
+        }
+      | undefined;
     try {
       readback = await fallbackOutput.readback;
     } catch (cause) {
@@ -954,12 +1032,12 @@ export class ReflectionProbeRecordOwner {
           [...fallbackTickets].filter(([, pending]) => pending.projection.source !== 'neutral'),
         ),
       );
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     if (
-      readback.graphGeneration !== fallbackOutput.graphGeneration ||
-      readback.textureIdentity !== fallbackOutput.textureIdentity
+      readback !== undefined &&
+      (readback.graphGeneration !== fallbackOutput.graphGeneration ||
+        readback.textureIdentity !== fallbackOutput.textureIdentity)
     ) {
       this.recordFallbackFailure({
         stage: 'completion',
@@ -979,25 +1057,23 @@ export class ReflectionProbeRecordOwner {
           [...fallbackTickets].filter(([, pending]) => pending.projection.source !== 'neutral'),
         ),
       );
-      this.discardFallbackTickets(fallbackTickets);
       return;
     }
     const eligible: Array<[string, PendingFallback]> = [];
     let staleCount = 0;
     for (const [renderableKey, pending] of fallbackTickets) {
-      const staged = this.pendingFallback.get(pending.ticket);
       const latest = this.latestFallbackTickets.get(renderableKey);
       const retiredAt = this.fallbackRetiredFrames.get(renderableKey);
       const committedFrame = this.fallbackCommittedFrames.get(renderableKey);
       if (
-        staged !== pending ||
-        latest !== pending.ticket ||
+        latest === undefined ||
+        reflectionFallbackProjectionSignature(latest.projection) !==
+          reflectionFallbackProjectionSignature(pending.projection) ||
         pending.frameId !== fallbackOutput.frameId ||
         pending.deviceGeneration !== this.internals.deviceScope.generation ||
         (retiredAt !== undefined && pending.frameId < retiredAt) ||
         (committedFrame !== undefined && pending.frameId <= committedFrame)
       ) {
-        this.pendingFallback.delete(pending.ticket);
         staleCount += 1;
         continue;
       }
@@ -1009,7 +1085,7 @@ export class ReflectionProbeRecordOwner {
           stage: 'completion',
           code: 'reflection-fallback-stale-ticket',
           expected:
-            'the fallback completion ticket to match the latest frame and device generation',
+            'the completed fallback to match the current projection and device without rolling back a committed frame',
           detail: { staleCount },
         });
       }
@@ -1020,6 +1096,7 @@ export class ReflectionProbeRecordOwner {
     const previousReadback = this.fallbackReadback;
     if (
       hasNonNeutral &&
+      readback !== undefined &&
       (previousReadback === undefined || fallbackOutput.frameId >= previousReadback.frameId)
     ) {
       this.fallbackReadback = Object.freeze({
@@ -1041,8 +1118,8 @@ export class ReflectionProbeRecordOwner {
         readbackStatus: 'complete',
       });
     }
+    if (readback === undefined) this.fallbackReadback = undefined;
     for (const [renderableKey, pending] of eligible) {
-      this.pendingFallback.delete(pending.ticket);
       this.commitFallbackProjection(
         renderableKey,
         pending,
@@ -1058,7 +1135,6 @@ export class ReflectionProbeRecordOwner {
       this.destroyProbeResource(resource);
     }
     this.resources.clear();
-    this.pendingFallback.clear();
     this.latestFallbackTickets.clear();
     this.fallbackRetiredFrames.clear();
     this.fallbackCommittedFrames.clear();
@@ -1071,6 +1147,8 @@ export class ReflectionProbeRecordOwner {
     this.fallbackFormatAvailable = this.internals.device.caps.rgba16floatRenderable === true;
     this.fallbackReceipt = this.createFallbackReceipt('unavailable');
     if (this.shared !== undefined) {
+      if (this.shared.background !== undefined)
+        this.internals.device.destroyBuffer(this.shared.background.uniform);
       this.internals.device.destroyBuffer(this.shared.faceUniforms);
       this.internals.device.destroyBuffer(this.shared.prefilterUniforms);
       this.internals.device.destroyBuffer(this.shared.vertexBuffer);
@@ -1096,35 +1174,92 @@ export class ReflectionProbeRecordOwner {
     key: string,
     fact: ReflectionProbeFact,
     index: number,
+    sceneRevision = '',
+    skylight?: SkylightSnapshot,
   ): ProbeGpuResource | undefined {
-    const existing = this.resources.get(key);
+    const diffuse =
+      skylight === undefined
+        ? [0, 0, 0, 0, 0, 0, 0, 1]
+        : [...skylight.color.map((value) => value * skylight.intensity), 0, ...skylight.rotation];
+    let existing = this.resources.get(key);
+    if (
+      existing !== undefined &&
+      existing.raw.size !== fact.resolution &&
+      existing.pending === undefined
+    ) {
+      this.destroyProbeResource(existing);
+      this.resources.delete(key);
+      existing = undefined;
+    }
     if (existing !== undefined) {
-      if (existing.fact.revision !== fact.revision) {
-        existing.fact = fact;
+      const previous = existing.fact;
+      const settled =
+        existing.filter.cursor >= existing.filter.faceCount * existing.filter.mipCount;
+      const moved = existing.captureFact.center.some((value, axis) => value !== fact.center[axis]);
+      const requested =
+        existing.captureFact.revision !== fact.revision ||
+        moved ||
+        fact.updateIntent === 'continuous' ||
+        (fact.updateIntent === 'on-change' && existing.captureSceneRevision !== sceneRevision);
+      // Finish the current bounded cycle. Coalesce newer changes into the next
+      // cycle instead of continuously restarting face zero under motion.
+      if (settled && existing.pending === undefined && requested) {
+        existing.captureFact = fact;
+        existing.captureSceneRevision = sceneRevision;
+        existing.captureStartedFrame = this.currentFrame;
         existing.filter = createProbeFilterState({
           probeIndex: index,
           mipCount: PREFILTER_MIP_LEVELS,
           activeGeneration: existing.filter.activeGeneration,
         });
         existing.rawFaceCursor = 0;
-      } else {
-        existing.fact = fact;
-        existing.index = index;
+      }
+      existing.fact = fact;
+      existing.index = index;
+      if (
+        previous.intensity !== fact.intensity ||
+        previous.boxProjection !== fact.boxProjection ||
+        previous.center.some((v, i) => v !== fact.center[i]) ||
+        previous.halfExtents.some((v, i) => v !== fact.halfExtents[i]) ||
+        existing.diffusePayload.some((v, i) => v !== diffuse[i])
+      ) {
+        const written = this.internals.device.queue.writeBuffer(
+          existing.uniformBuffer,
+          0,
+          new Float32Array([
+            -(Math.max(0, fact.intensity) + PROBE_INTENSITY_SENTINEL_OFFSET),
+            ...fact.center,
+            ...fact.halfExtents,
+            fact.boxProjection === true ? 1 : 0,
+            ...diffuse,
+          ]),
+        );
+        if (!written.ok) this.internals.errorRegistry.fire(written.error);
+        else existing.diffusePayload = diffuse;
       }
       return existing;
     }
     if (this.shared === undefined) return undefined;
-    const raw = this.createCubeSet(`reflection-probe-${index}-raw`, fact.resolution);
+    const raw = this.createCubeSet(`reflection-probe-${index}-raw`, fact.resolution, 1);
     const candidate = this.createCubeSet(`reflection-probe-${index}-candidate`, fact.resolution);
     const spare = this.createCubeSet(`reflection-probe-${index}-spare`, fact.resolution);
-    if (raw === undefined || candidate === undefined || spare === undefined) return undefined;
+    const releaseSets = () => {
+      for (const set of [raw, candidate, spare]) if (set !== undefined) this.destroyCubeSet(set);
+    };
+    if (raw === undefined || candidate === undefined || spare === undefined) {
+      releaseSets();
+      return undefined;
+    }
     const uniformBuffer = this.internals.device.createBuffer({
       label: `reflection-probe-${index}-uniforms`,
-      size: 32,
+      size: 64,
       usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
       mappedAtCreation: false,
     });
-    if (!uniformBuffer.ok) return undefined;
+    if (!uniformBuffer.ok) {
+      releaseSets();
+      return undefined;
+    }
     const payload = new Float32Array([
       -(Math.max(0, fact.intensity) + PROBE_INTENSITY_SENTINEL_OFFSET),
       fact.center[0],
@@ -1133,10 +1268,15 @@ export class ReflectionProbeRecordOwner {
       fact.halfExtents[0],
       fact.halfExtents[1],
       fact.halfExtents[2],
-      0,
+      fact.boxProjection === true ? 1 : 0,
+      ...diffuse,
     ]);
     const written = this.internals.device.queue.writeBuffer(uniformBuffer.value, 0, payload);
-    if (!written.ok) return undefined;
+    if (!written.ok) {
+      releaseSets();
+      this.internals.device.destroyBuffer(uniformBuffer.value);
+      return undefined;
+    }
     const filterGroup1 = this.internals.device.createBindGroup({
       label: `reflection-probe-${index}-filter-input`,
       layout: this.shared.cubeGroup1Bgl,
@@ -1145,11 +1285,20 @@ export class ReflectionProbeRecordOwner {
         { binding: 1, resource: { kind: 'sampler', value: this.shared.sampler } },
       ],
     });
-    if (!filterGroup1.ok) return undefined;
+    if (!filterGroup1.ok) {
+      releaseSets();
+      this.internals.device.destroyBuffer(uniformBuffer.value);
+      return undefined;
+    }
     const resource: ProbeGpuResource = {
       fact,
+      captureFact: fact,
+      diffusePayload: diffuse,
+      captureSceneRevision: sceneRevision,
+      captureStartedFrame: this.currentFrame,
+      lastCompletedFrame: 0,
       index,
-      filter: createProbeFilterState({ probeIndex: index, mipCount: PREFILTER_MIP_LEVELS }),
+      filter: createProbeFilterState({ probeIndex: index, mipCount: candidate.mipViews.length }),
       rawFaceCursor: 0,
       raw,
       active: undefined,
@@ -1163,12 +1312,15 @@ export class ReflectionProbeRecordOwner {
     return resource;
   }
 
-  private createSharedResources(filterPipeline: RenderPipeline): ProbeSharedResources | undefined {
+  private createSharedResources(
+    filterPipeline: RenderPipeline,
+    background?: ProbeBackgroundResources,
+  ): ProbeSharedResources | undefined {
     const faceUniforms = createFaceUniformsBuffer(this.internals.device);
     const prefilterUniforms = createPrefilterUniformsBuffer(this.internals.device);
     if (!faceUniforms.ok || !prefilterUniforms.ok) return undefined;
     if (!writeAllFaceUniforms(this.internals.device, faceUniforms.value).ok) return undefined;
-    if (!writeAllPrefilterUniforms(this.internals.device, prefilterUniforms.value).ok)
+    if (!writeAllPrefilterUniforms(this.internals.device, prefilterUniforms.value, 1, 'camera').ok)
       return undefined;
     const vertexBuffer = this.internals.device.createBuffer({
       label: 'reflection-probe-capture-cube-vertices',
@@ -1201,6 +1353,7 @@ export class ReflectionProbeRecordOwner {
       return undefined;
     }
     return {
+      background,
       faceUniforms: faceUniforms.value,
       prefilterUniforms: prefilterUniforms.value,
       vertexBuffer: vertexBuffer.value,
@@ -1211,9 +1364,11 @@ export class ReflectionProbeRecordOwner {
     };
   }
 
-  private createCubeSet(label: string, requestedSize: number): ProbeCubeSet | undefined {
-    const size = Math.min(Math.max(1, Math.floor(requestedSize)), PREFILTER_SIZE);
-    const mipCount = Math.min(PREFILTER_MIP_LEVELS, Math.floor(Math.log2(size)) + 1);
+  private createCubeSet(
+    label: string,
+    size: number,
+    mipCount = PREFILTER_MIP_LEVELS,
+  ): ProbeCubeSet | undefined {
     const texture = this.internals.device.createTexture({
       label,
       size: { width: size, height: size, depthOrArrayLayers: 6 },
@@ -1233,7 +1388,10 @@ export class ReflectionProbeRecordOwner {
       mipLevelCount: mipCount,
       arrayLayerCount: 6,
     });
-    if (!cubeView.ok) return undefined;
+    if (!cubeView.ok) {
+      this.internals.device.destroyTexture(texture.value);
+      return undefined;
+    }
     const faceViews: TextureView[] = [];
     const mipViews: TextureView[][] = [];
     for (let mip = 0; mip < mipCount; mip += 1) {
@@ -1247,7 +1405,10 @@ export class ReflectionProbeRecordOwner {
           baseArrayLayer: face,
           arrayLayerCount: 1,
         });
-        if (!view.ok) return undefined;
+        if (!view.ok) {
+          this.internals.device.destroyTexture(texture.value);
+          return undefined;
+        }
         if (mip === 0) faceViews.push(view.value);
         faces.push(view.value);
       }
@@ -1264,12 +1425,19 @@ export class ReflectionProbeRecordOwner {
       viewFormats: [],
       textureBindingViewDimension: undefined,
     });
-    if (!depthTexture.ok) return undefined;
+    if (!depthTexture.ok) {
+      this.internals.device.destroyTexture(texture.value);
+      return undefined;
+    }
     const depthView = this.internals.device.createTextureView(depthTexture.value, {
       label: `${label}-depth-view`,
       dimension: '2d',
     });
-    if (!depthView.ok) return undefined;
+    if (!depthView.ok) {
+      this.internals.device.destroyTexture(texture.value);
+      this.internals.device.destroyTexture(depthTexture.value);
+      return undefined;
+    }
     return {
       texture: texture.value,
       cubeView: cubeView.value,