@forgeax/engine-render 0.1.33 → 0.1.34

package/src/recovery/render-system-candidate.ts

@@ -9,9 +9,11 @@ import {
   type Result,
   RhiError,
 } from '@forgeax/engine-rhi';
+import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
 import type { Handle, MeshAsset, SamplerAsset, TextureAsset } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
 import { standardBloomAdmitted } from '../bloom-admission';
+import { cloudShadowResolutionForQuality } from '../cloud/parameters';
 import { createClusterBinScratch } from '../cluster-binner';
 import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import {
@@ -29,8 +31,12 @@ import {
   type PostProcessShaderEntry,
   postProcessShaderEntrySignature,
 } from '../fullscreen-post-process-pass';
-import { collectGpuDrivenMaterialArtifacts } from '../gpu-driven/material-artifacts';
+import {
+  collectGpuDrivenMaterialArtifacts,
+  requiresProbeBlendRecord,
+} from '../gpu-driven/material-artifacts';
 import { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import { disposeInstanceBufferChunks, disposeInstanceBuffers } from '../instance-buffer-cache';
 import { inspectStandardLighting } from '../pipeline/standard-lighting/inspection';
 import { retireAutoExposureGpuResources } from '../pipeline/standard-output/auto-exposure/gpu';
 import {
@@ -38,12 +44,15 @@ import {
   resetStandardOutputForDeviceLoss,
 } from '../pipeline/standard-output/resources';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
+import { standardTopologyVariantSet } from '../pipeline-spec';
 import { inspectPointShadow } from '../point-shadow-inspection';
 import type { PreparedGraphicsResolver } from '../prepare/prepared-graphics-resolver';
 import { gpuDrivenMeshesForFrame, validateRenderables } from '../record/frame';
 import { prepareFrameLighting } from '../record/frame-lighting';
 import type { RenderFrameState, ValidatedRenderable } from '../record/frame-snapshot';
+import { resolveGeometryInstanceBuffer } from '../record/main-pass-geometry';
 import { computeSplitLdrSprite } from '../record/main-pass-sprite-draws';
+import { ensureProbeBlendRecordBuffer } from '../record/probe-blend-buffer';
 import {
   prepareRecoveryPipelineReadiness,
   type RecoveryPipelineReadiness,
@@ -53,6 +62,8 @@ import {
   ensureCompiledFrameGraph,
   getRenderFeatureGraphState,
   type RenderFeatureGraphCandidate,
+  retire as retireCompiledGraph,
+  shareRenderGraphGenerationAllocationOwner,
 } from '../record/typed-frame-graph';
 import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
 import type {
@@ -62,6 +73,7 @@ import type {
 } from '../render-system-extract';
 import type { PersistentGpuDrivenCandidate, PersistentRenderScene } from '../scene/render-scene';
 import { SHADOW_ATLAS_DEFAULT_LAYERS } from '../shadow-atlas';
+import { ReadonlyDynamicInputPage, type SurfaceDynamicInputFrame } from '../surface/dynamic-input';
 import { createTemporalFrameTransaction } from '../temporal/frame';
 import {
   getTemporalBindGroupResources,
@@ -93,6 +105,14 @@ export interface RecoveryFrameSeed {
   readonly resourceOwner: number;
   readonly width: number;
   readonly height: number;
+  /** Last submitted Surface page is reused while the replacement device warms. */
+  readonly surfaceDynamicInput?: SurfaceDynamicInputFrame;
+  /** Last submitted World/App time snapshot for the Surface frame ABI. */
+  readonly frameTime?: number;
+  /** Exact forward artifacts accepted by the submitted frame. */
+  readonly materialArtifacts?: ReadonlyMap<string, MaterialShaderArtifact>;
+  /** Exact ShadowCaster artifacts accepted by the submitted frame. */
+  readonly shadowMaterialArtifacts?: ReadonlyMap<string, MaterialShaderArtifact>;
 }
 
 export interface RenderSystemRecoveryDependencies {
@@ -213,9 +233,14 @@ export function createRenderSystemRecovery(
   let lastSuccessfulFrameSeed: RecoveryFrameSeed | undefined;
 
   const createRecoveryCandidateFrameState = (): RenderFrameState => {
-    const { probeBlendRecordBuffer: discardedProbeBlendRecordBuffer, ...baseFrameState } =
-      frameState;
+    const {
+      probeBlendRecordBuffer: discardedProbeBlendRecordBuffer,
+      instanceCollections: discardedInstanceInspection,
+      ...baseFrameState
+    } = frameState;
     void discardedProbeBlendRecordBuffer;
+    // Candidate uploads must not publish residency into the active inspection.
+    void discardedInstanceInspection;
     return {
       ...baseFrameState,
       successfulTemporalFrameIndex: 0,
@@ -256,15 +281,18 @@ export function createRenderSystemRecovery(
       retiredCompiledFrameGraphs: new Set(),
       currentFrameObservationSource: undefined,
       lastSuccessfulCameraAntialias: undefined,
+      lastSuccessfulBarrelDistortion: undefined,
       temporalGpuState: undefined,
       activeTemporalGpuState: undefined,
       retiringTemporalGpuStates: new Set(),
+      cloudHistoryActive: false,
       lastSuccessfulTemporalView: undefined,
       pendingTemporalCommit: { kind: 'none' },
       environmentGeneration: undefined,
       currentDirectionalShadowView: null,
       currentSpotShadowView: null,
       instanceBuffers: new Map(),
+      instanceBufferChunks: new Map(),
       morphBuffers: new Map(),
       hdrpClusterBinScratch: createClusterBinScratch(),
       hdrpClusterGridScratch: null,
@@ -299,6 +327,18 @@ export function createRenderSystemRecovery(
       candidate.recoveryReadiness.assertPreparedCache();
     }
     const previousFeatureHost = internals.featureHost;
+    // The candidate graph proves topology and pipeline readiness before the
+    // publication boundary, but its imported display view was acquired before
+    // the shared canvas context was reconfigured for the replacement device.
+    // Retire that frame-bound graph and preserve the prepared owners/caches;
+    // the first recovered frame recompiles the same topology against the
+    // newly configured context instead of submitting a view from the lost
+    // device generation.
+    const candidateDisplayGraph = candidate.frameState.compiledFrameGraph;
+    candidate.frameState.compiledFrameGraph = null;
+    candidate.frameState.compiledFrameGraphTopologyKey = null;
+    candidate.frameState.perFrameGraph = null;
+    candidateDisplayGraph?.retire().catch(() => undefined);
     // The caller enters this method only after the active generation swap and
     // after resetForRecover() has shed every lost-device owner. Replace the
     // whole device-bound frame projection so no stale cache/map/temporal view
@@ -370,6 +410,9 @@ export function createRenderSystemRecovery(
     if (camera === undefined) return { kind: 'no-seed' };
 
     const candidateFrameState = createRecoveryCandidateFrameState();
+    // Candidate graph generations are one renderer-owned allocation stream;
+    // publication changes their role, not their accounting owner.
+    shareRenderGraphGenerationAllocationOwner(frameState, candidateFrameState);
     resetStandardOutputForDeviceLoss(candidateFrameState, runtime.internals.deviceScope.generation);
     Object.assign(candidateFrameState, {
       temporalFrame: undefined,
@@ -382,6 +425,7 @@ export function createRenderSystemRecovery(
     let candidateFeatureHost: RenderFeatureHost | undefined;
     let candidateFeatureGpuWork: RenderFeatureGpuWorkOwner | undefined;
     let candidatePointsLines: RecoveryPointsLinesCandidate | undefined;
+    let candidateSurfacePage: ReadonlyDynamicInputPage | undefined;
     let candidateFeatureGraph: RenderFeatureGraphCandidate = {
       plans: Object.freeze([]),
       fullscreenEffects: new Map(),
@@ -406,7 +450,7 @@ export function createRenderSystemRecovery(
       candidateFrameState.compiledFrameGraph = null;
       candidateFrameState.perFrameGraph = null;
       try {
-        graph?.retire().catch(() => undefined);
+        if (graph !== null) retireCompiledGraph(candidateFrameState, graph);
       } catch {
         // Candidate cleanup continues through every independent owner.
       }
@@ -430,10 +474,21 @@ export function createRenderSystemRecovery(
       candidateGpuDrivenScene = undefined;
       candidatePointsLines?.release();
       candidatePointsLines = undefined;
+      candidateSurfacePage?.release();
+      candidateSurfacePage = undefined;
+      disposeInstanceBuffers(candidateFrameState.instanceBuffers, runtime.internals.errorRegistry);
+      if (candidateFrameState.instanceBufferChunks !== undefined) {
+        disposeInstanceBufferChunks(
+          candidateFrameState.instanceBufferChunks,
+          runtime.internals.errorRegistry,
+        );
+      }
       candidateGpuStore.destroyAll();
     };
     const markPublished = (): void => {
       candidatePointsLines?.publish();
+      candidateSurfacePage?.release();
+      candidateSurfacePage = undefined;
       candidatePublished = true;
     };
     const failed = (
@@ -457,11 +512,101 @@ export function createRenderSystemRecovery(
       );
       if (!gpuScene.ok) return failed('candidate GPU scene preparation failed', gpuScene.error);
       candidateGpuDrivenScene = gpuScene.value;
+      candidateValidated = validateRenderables(
+        runtime.internals,
+        seed.worlds[seed.cameraOwner] as World,
+        seed.worlds,
+        runtime.pipelineState,
+        candidateFrameState,
+        seed.frame.renderables,
+        seed.frame.dispatch,
+      );
+      if (candidateValidated.length !== seed.frame.renderables.length) {
+        return failed('candidate validation did not retain every LKG-visible renderable');
+      }
+      const lighting = prepareFrameLighting(
+        runtime.internals,
+        candidateFrameState,
+        seed.frame.lights,
+        camera,
+        runtime.pipelineState,
+      );
+      if (!lighting.ok) return failed('candidate lighting preparation failed');
+      let recoverySurfaceDynamicInput = seed.surfaceDynamicInput;
+      if (
+        recoverySurfaceDynamicInput !== undefined &&
+        recoverySurfaceDynamicInput.page.deviceGeneration !==
+          runtime.internals.deviceScope.generation
+      ) {
+        const source = recoverySurfaceDynamicInput;
+        const created = ReadonlyDynamicInputPage.create({
+          sourceId: source.page.sourceId,
+          pageId: source.page.pageId,
+          schema: source.page.schema,
+        });
+        if (!created.ok) {
+          return failed('candidate Surface recovery page creation failed', created.error);
+        }
+        candidateSurfacePage = created.value;
+        // Preserve CPU-authored parameters before preparing the replacement GPU page.
+        candidateSurfacePage.bytes.set(source.page.bytes);
+        const reconfigured = candidateSurfacePage.reconfigureDevice(
+          runtime.internals.deviceScope.generation,
+        );
+        if (!reconfigured.ok) {
+          return failed('candidate Surface recovery page generation failed', reconfigured.error);
+        }
+        const ranges = (source.ranges ?? []).map((range) => {
+          const reserved = candidateSurfacePage?.reserveRange({
+            domain: range.domain,
+            recordStart: range.recordStart,
+            recordCount: range.recordCount,
+            instanceIndex: range.instanceIndex,
+            member: range.member,
+          });
+          if (reserved === undefined || !reserved.ok) {
+            throw reserved?.error ?? new Error('candidate Surface recovery range unavailable');
+          }
+          return reserved.value;
+        });
+        recoverySurfaceDynamicInput = {
+          page: candidateSurfacePage,
+          ranges,
+          projectionRevision: source.projectionRevision + 1,
+          frameTime: source.frameTime,
+        };
+      }
       if (candidateGpuDrivenScene.state !== undefined) {
         candidateGpuDrivenProduction = GpuDrivenProduction.forDevice(
           runtime.internals.device,
           gpuDrivenShaderFactory,
         );
+        const clustered = lighting.value.standard?.kind === 'clustered';
+        const standardVariantSet = standardTopologyVariantSet(
+          lighting.value.standard,
+          runtime.internals.device.caps.storageBuffer,
+          false,
+        );
+        const standardPbrArtifact = runtime.internals.getMaterialShaderArtifact?.(
+          'forgeax::default-standard-pbr',
+          {
+            vertexColorAvailable: false,
+            deformation: 'rigid',
+            pass: 'forward',
+            address: 'scene-index',
+            variantSet: standardVariantSet,
+          },
+        );
+        const standardPbrSkinArtifact = runtime.internals.getMaterialShaderArtifact?.(
+          'forgeax::pbr-skin',
+          {
+            vertexColorAvailable: false,
+            deformation: 'skin',
+            pass: 'forward',
+            address: 'scene-index',
+            variantSet: standardVariantSet,
+          },
+        );
         const shadowProjection = persistentRenderScene.shadowCasterProjection();
         // The retained scene owns prepared draw receipts. The extraction seed
         // precedes GPU admission and must not stand in for that projection.
@@ -482,20 +627,45 @@ export function createRenderSystemRecovery(
             },
             renderableIndex,
           }));
-        const { materialArtifacts, shadowMaterialArtifacts, firstArtifact, firstSkinArtifact } =
-          collectGpuDrivenMaterialArtifacts({
-            rows: artifactRows(seed.frame.renderables),
-            shadowRows: artifactRows(shadowProjection?.renderables ?? []),
-            dispatch: seed.frame.dispatch,
-            shadowDispatch: shadowProjection?.dispatch ?? seed.frame.dispatch,
-            resolve: runtime.internals.getMaterialShaderArtifact,
-            clustered:
-              seed.frame.lights.point.length +
-                seed.frame.lights.spot.length +
-                seed.frame.lights.rect.length >
-                0 || candidateFrameState.installedPipelineConfig?.ssao?.enabled === true,
-            reflectionFallback: candidateFrameState.reflectionFallbackDemand === true,
-          });
+        const collectedArtifacts = collectGpuDrivenMaterialArtifacts({
+          rows: artifactRows(seed.frame.renderables),
+          shadowRows: artifactRows(shadowProjection?.renderables ?? []),
+          dispatch: seed.frame.dispatch,
+          shadowDispatch: shadowProjection?.dispatch ?? seed.frame.dispatch,
+          resolve: runtime.internals.getMaterialShaderArtifact,
+          clustered:
+            seed.frame.lights.point.length +
+              seed.frame.lights.spot.length +
+              seed.frame.lights.rect.length >
+              0 || candidateFrameState.installedPipelineConfig?.ssao?.enabled === true,
+          reflectionFallback: candidateFrameState.reflectionFallbackDemand === true,
+        });
+        const materialArtifacts =
+          collectedArtifacts.materialArtifacts.size > 0
+            ? collectedArtifacts.materialArtifacts
+            : (seed.materialArtifacts ?? new Map());
+        const shadowMaterialArtifacts =
+          collectedArtifacts.shadowMaterialArtifacts.size > 0
+            ? collectedArtifacts.shadowMaterialArtifacts
+            : (seed.shadowMaterialArtifacts ?? new Map());
+        const firstMaterialArtifact = materialArtifacts.values().next().value as
+          | MaterialShaderArtifact
+          | undefined;
+        const firstSkinArtifact = [...materialArtifacts.values()].find(
+          (artifact) => artifact.receipt?.skinPaletteAddress !== undefined,
+        );
+        const firstArtifact = firstMaterialArtifact ?? standardPbrArtifact;
+        const materialSkinArtifact = firstSkinArtifact ?? standardPbrSkinArtifact;
+        const probeBlendRequested = [...materialArtifacts.values()].some((artifact) =>
+          requiresProbeBlendRecord(artifact),
+        );
+        const probeBlendRecordBuffer = probeBlendRequested
+          ? ensureProbeBlendRecordBuffer(
+              runtime.internals.device,
+              candidateFrameState,
+              candidateGpuDrivenScene.state.probeBlend,
+            )
+          : undefined;
         const prepared = candidateGpuDrivenProduction.prepare({
           scene: candidateGpuDrivenScene.state,
           camera,
@@ -507,11 +677,21 @@ export function createRenderSystemRecovery(
           ),
           viewBindGroupLayout: runtime.pipelineState.viewBindGroupLayout,
           meshResidencyEpoch: runtime.internals.gpuStore.meshResidencyEpoch,
-
+          hdrp:
+            clustered &&
+            ((lighting.value.standard?.prepared.local.length ?? 0) > 0 ||
+              candidateFrameState.installedPipelineConfig?.ssao?.enabled === true),
+          clustered,
           ...(firstArtifact === undefined ? {} : { materialArtifact: firstArtifact }),
-          ...(firstSkinArtifact === undefined ? {} : { materialSkinArtifact: firstSkinArtifact }),
+          ...(materialSkinArtifact === undefined ? {} : { materialSkinArtifact }),
           ...(materialArtifacts.size === 0 ? {} : { materialArtifacts }),
           ...(shadowMaterialArtifacts.size === 0 ? {} : { shadowMaterialArtifacts }),
+          ...(probeBlendRecordBuffer === undefined ? {} : { probeBlendRecordBuffer }),
+          ...(seed.frameTime === undefined ? {} : { frameTime: seed.frameTime }),
+          ...(recoverySurfaceDynamicInput === undefined
+            ? {}
+            : { surfaceDynamicInput: recoverySurfaceDynamicInput }),
+          deviceGeneration: runtime.internals.deviceScope.generation,
           materialPipelineState: runtime.pipelineState,
           ...(runtime.internals.getMaterialShaderPipelineEntry === undefined
             ? {}
@@ -520,6 +700,25 @@ export function createRenderSystemRecovery(
         if (!prepared.ok) return failed('candidate GPU-driven preparation failed', prepared.error);
         preparedGpuDriven = prepared.value;
       }
+      // A fully GPU-owned frame recovers through GPU Scene above. Only mixed
+      // or direct frames need the legacy instance-buffer closure as well.
+      if (!preparedGpuDriven?.ownsAllDrawItems || !preparedGpuDriven.ownsAllShadowCasters) {
+        for (const entry of candidateValidated) {
+          if (entry.source.instances === undefined) continue;
+          const prepared = resolveGeometryInstanceBuffer(
+            {
+              runtime: runtime.internals,
+              pipelineState: runtime.pipelineState,
+              frameState: candidateFrameState,
+              bindGroupCounts: { createBindGroup: 0, keys: [] },
+            },
+            entry,
+            [],
+            false,
+          );
+          if (prepared === null) return failed('candidate instance preparation failed');
+        }
+      }
       candidateFeatureHost = runtime.internals.featureHost;
       if (candidateFeatureHost !== undefined && candidateFeatureHost.size > 0) {
         candidateFeatureGpuWork = createFeatureGpuWorkOwner(runtime.internals);
@@ -529,11 +728,13 @@ export function createRenderSystemRecovery(
           colorAttachmentFormat: runtime.pipelineState.colorAttachmentFormat,
           storageBuffer: runtime.internals.device.caps.storageBuffer,
           multisample: runtime.internals.device.caps.backendKind !== 'wgpu-webgl2',
+          cloudHistory: seed.frame.cloudLayer !== undefined,
         });
         const featureFrame = runRenderFeatureFrame(candidateFeatureHost, {
           worlds: seed.worlds,
           owner: seed.resourceOwner,
           frameNumber: candidateFrameState.frameNumber,
+          selectedCamera: camera,
           frameSize: {
             width: runtime.internals.canvas.width,
             height: runtime.internals.canvas.height,
@@ -557,7 +758,7 @@ export function createRenderSystemRecovery(
           gpuWork: candidateFeatureGpuWork,
         });
         if (featureFrame.errors.length > 0) {
-          return failed('candidate render-feature preparation failed');
+          return failed('candidate render-feature preparation failed', featureFrame.errors[0]);
         }
         const featurePreparationIncomplete = featureFrame.plans.some((planned) => {
           const execution = getRenderFeaturePlanExecutionProjection(planned);
@@ -586,6 +787,7 @@ export function createRenderSystemRecovery(
         candidateFeatureGraph = {
           plans: featureFrame.plans,
           fullscreenEffects: featureFrame.fullscreenEffects,
+          postProcessIdentities: featureFrame.postProcessIdentities,
           ...(batches.length === 0
             ? {}
             : { preparedResourceKey: `recovery-${runtime.internals.deviceScope.generation}` }),
@@ -678,26 +880,6 @@ export function createRenderSystemRecovery(
           }
         }
       }
-      candidateValidated = validateRenderables(
-        runtime.internals,
-        resourceWorld,
-        seed.worlds,
-        runtime.pipelineState,
-        candidateFrameState,
-        seed.frame.renderables,
-        seed.frame.dispatch,
-      );
-      if (candidateValidated.length !== seed.frame.renderables.length) {
-        return failed('candidate validation did not retain every LKG-visible renderable');
-      }
-      const lighting = prepareFrameLighting(
-        runtime.internals,
-        candidateFrameState,
-        seed.frame.lights,
-        camera,
-        runtime.pipelineState,
-      );
-      if (!lighting.ok) return failed('candidate lighting preparation failed');
       candidatePointsLines = pointsLinesOwner.prepareRecoveryCandidate(
         candidateValidated,
         lighting.value.standard?.kind === 'clustered',
@@ -723,7 +905,11 @@ export function createRenderSystemRecovery(
       });
       const candidatePostProcessIds = new Set<string>([
         ...(candidateFrameState.installedPipelineConfig?.postEffects ?? []),
-        ...candidateFeatureGraph.fullscreenEffects.keys(),
+        // Required identities include effects disabled for this frame. Warm only
+        // published entries, using their public identity rather than graph aliases.
+        ...(candidateFeatureGraph.postProcessIdentities ?? []).filter((id) =>
+          candidateFeatureGraph.fullscreenEffects.has(id),
+        ),
       ]);
       const configuredPostEffects = candidateFrameState.installedPipelineConfig?.postEffects ?? [];
       const postProcessPipeline = runtime.internals.getPostProcessPipeline;
@@ -855,6 +1041,13 @@ export function createRenderSystemRecovery(
         (error) => {
           recoveryGraphFailure ??= error;
         },
+        undefined,
+        undefined,
+        false,
+        false,
+        seed.frame.cloudLayer === undefined
+          ? undefined
+          : cloudShadowResolutionForQuality(seed.frame.cloudLayer.params.quality),
       );
       if (graph === null) return failed('candidate frame graph compilation failed');
       if (recoveryReadiness === undefined)

package/src/reflection/record-owner.ts

@@ -397,9 +397,13 @@ export class ReflectionProbeRecordOwner {
     this.lastFactCount = facts.length;
     this.lastScheduledRawFaces = 0;
     this.lastScheduledFilteredSteps = 0;
-    const firstSelection = selections.values().next().value as
-      | ReflectionProbeSelectionResult
-      | undefined;
+    // The fallback MRT has one representative readback, so choose a stable
+    // non-neutral probe consumer when the scene contains one. Renderable map
+    // order is not a source-selection contract: the first entry is commonly
+    // an outside panel while the local probe consumer appears later.
+    const firstSelection =
+      [...selections.values()].find((selection) => selection.kind === 'probe') ??
+      (selections.values().next().value as ReflectionProbeSelectionResult | undefined);
     this.lastSelection =
       firstSelection?.kind === 'probe'
         ? {

package/src/render-contract.ts

@@ -3,7 +3,12 @@ import type { World } from '@forgeax/engine-ecs';
 import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
 import type { Vec3 } from '@forgeax/engine-math';
 import type { ProfileFrameToken, Profiler } from '@forgeax/engine-profiler';
-import type { ColorValueDomain, RenderGraphError } from '@forgeax/engine-render-graph';
+import type {
+  ColorValueDomain,
+  RenderGraphError,
+  RenderGraphGenerationAllocationInspection,
+  RenderGraphResourceAllocationInspection,
+} from '@forgeax/engine-render-graph';
 import type {
   BindGroupLayout,
   Buffer,
@@ -24,6 +29,8 @@ import type {
 import type { SkinError } from '@forgeax/engine-skinning';
 import type { ImageError } from '@forgeax/engine-types';
 import type { RhiBackendInstrumentation } from './assembly/backend-contract.js';
+import type { CloudLayerInspection } from './cloud/inspection.js';
+import type { BarrelDistortionData } from './components/barrel-distortion.js';
 import type { Antialias, BloomEnabled, CameraExposure, Tonemap } from './components/camera.js';
 import type { DynamicResolutionData } from './components/dynamic-resolution.js';
 import type { ScreenSpaceReflectionData } from './components/screen-space-reflection.js';
@@ -53,7 +60,7 @@ import type {
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types.js';
-import type { InstanceCollectionInspection, InstanceCollectionStore } from './instances.js';
+import type { InstanceCollectionInspection } from './instances.js';
 import type { RenderExtent } from './pipeline/render-extent.js';
 import type { RenderSceneBounds } from './scene/render-scene-types.js';
 import type { SsrAdmissionIdentity } from './ssr/identity.js';
@@ -94,6 +101,7 @@ import type {
   GpuPassTimingOptions,
 } from './record/gpu-pass-timing/index.js';
 import type { VolumeTimingObservation } from './record/gpu-timing.js';
+import type { SurfaceDynamicInputFrame } from './surface/dynamic-input.js';
 import type { TemporalView } from './temporal/view.js';
 import type { VolumetricFogInspection } from './volume/inspection.js';
 
@@ -189,6 +197,8 @@ export interface CameraSnapshot {
     /** Target presentation rate; zero follows the accepted frame interval. */
     readonly targetFps?: number;
   };
+  /** Optional active-camera barrel projection, copied from the ECS schema. */
+  readonly barrelDistortion?: BarrelDistortionData;
 }
 
 /** Stable identity owned by the Standard feature host for output transform. */
@@ -370,6 +380,11 @@ export interface AtmosphereShaderSources {
  * and never reach into AssetRegistry or World.
  */
 export interface VolumetricFogFrameContext {
+  readonly additional?: readonly {
+    readonly densityTexture: Texture;
+    readonly densityView: TextureView;
+    readonly densityGeneration: number;
+  }[];
   readonly densityTexture: Texture;
   readonly densityView: TextureView;
   readonly paramsBuffer: Buffer;
@@ -407,8 +422,8 @@ export interface SpotLightProjectorFrameContext {
  * leases, receipts, inspection PODs, and recovery Result values.
  */
 export interface Renderer {
-  /** Renderer-owned authoring and update path for large instance collections. */
-  readonly instances: InstanceCollectionStore;
+  /** Publish one renderer-owned read-only Surface dynamic page for the next frame. */
+  setSurfaceDynamicInput(frame: SurfaceDynamicInputFrame | undefined): void;
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   /** Prepare a standard MeshAsset for the active device generation. */
   prepareDynamicGeometry(
@@ -499,6 +514,8 @@ export type RendererEvent =
       readonly kind: 'frame-submitted';
       readonly frameId: number;
       readonly deviceGeneration: number;
+      /** Compiled graph identity paired with the submitted picture. */
+      readonly graphGeneration?: number;
       /** The exact draw receipt, for observation when App owns the draw loop. */
       readonly receipt: FrameReceipt;
     };
@@ -553,13 +570,25 @@ export interface FrameObservationRequest {
 export interface FrameReceipt {
   readonly frameId: number;
   readonly deviceGeneration: number;
+  /** Whether this frame can present the active scene without a readiness fallback. */
+  readonly presentation: FramePresentation;
   /** Backend identity captured at submit and checked before observation. */
   readonly backendId?: RhiCaps['backendKind'];
   /** Monotonic compiled graph identity used by renderer-issued observations. */
   readonly graphGeneration?: number;
+  /**
+   * Effective output mapping for the submitted camera, including identity
+   * when this receipt has an accepted camera context. `undefined` means that
+   * no submitted display context is available; consumers must fail closed and
+   * must not infer identity or read the live World camera.
+   */
+  readonly barrelDistortion?: import('./barrel-distortion.js').BarrelDistortionMapping;
   readonly completed: Promise<RenderResult<void, RenderError>>;
 }
 
+/** Producer-derived presentation readiness for one submitted frame. */
+export type FramePresentation = 'pending' | 'ready';
+
 /**
  * The sole public draw input; World objects never cross this boundary. Render
  * owns extraction and graph interpretation, while the host owns encoding,
@@ -586,6 +615,12 @@ export interface RenderFrameInput {
   readonly fixedStep?: number;
   /** Optional profiler correlation token owned by App and consumed by Render. */
   readonly profileFrame?: ProfileFrameToken;
+  /**
+   * Select the geometry submission command lane while retaining the same
+   * extracted scene and material inputs. This is an acceptance/debug seam;
+   * both lanes remain subject to the ordinary resource and generation gates.
+   */
+  readonly geometryLane?: 'automatic' | 'direct';
 }
 
 /** Detached, bounded observation metadata tied to one FrameReceipt and request. */
@@ -719,8 +754,12 @@ export interface RenderInspection {
     readonly frameId: number;
     readonly deviceGeneration: number;
   };
+  /** Effective output mapping and accepted/LKG identity for the last picture. */
+  readonly barrelDistortion: import('./inspection-types').BarrelDistortionInspection;
   /** Renderer-owned authored volume projection and submit/LKG state. */
   readonly volumetricFog?: VolumetricFogInspection;
+  /** Renderer-owned procedural cloud projection from the latest resource-owner extract. */
+  readonly cloudLayer?: CloudLayerInspection;
   readonly features: readonly string[];
   /** Truthful lifecycle facts for every registered declarative feature. */
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
@@ -737,6 +776,10 @@ export interface RenderInspection {
   /** Standard MeshAsset dynamic-candidate lifecycle facts. */
   readonly dynamicGeometry?: DynamicGeometryInspection;
   readonly renderScene: RenderSceneInspection;
+  /** Detached logical allocation facts for graph-created render targets. */
+  readonly renderGraphResourceAllocation?: RenderGraphResourceAllocationInspection;
+  /** Detached logical allocation facts across graph generations. */
+  readonly renderGraphGenerationAllocation?: RenderGraphGenerationAllocationInspection;
   readonly reflectionProbes: ReflectionProbeInspection;
   /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */
   readonly ssrDependencies: SsrDependenciesInspection;
@@ -832,6 +875,7 @@ export type DrawOwnerOptions = {
   /** Explicit pause/resume or replay lifecycle boundary for temporal owners. */
   readonly temporalReset?: boolean;
   readonly profileFrame?: ProfileFrameToken;
+  readonly geometryLane?: 'automatic' | 'direct';
 };
 
 /** Information attached to a device-loss notification. */

package/src/render-graph-primitives.ts

@@ -586,7 +586,13 @@ function dispatchFullscreenPass(
         detail: { readsKey: reads[0] ?? 'ldrColor', passName: name },
       });
     }
-    recordFxaaPass(requireRenderGraphRecordContext(ctx), resolveCtx, graphPass, paramsOverride);
+    recordFxaaPass(
+      requireRenderGraphRecordContext(ctx),
+      resolveCtx,
+      graphPass,
+      paramsOverride,
+      graphOutputFormat,
+    );
     return;
   }
   const lookup = ctx.runtime.lookupPostProcess;