@forgeax/engine-render 0.1.31 → 0.1.32

package/src/render-system-extract-tail.ts

@@ -120,6 +120,7 @@ import type {
   ExtractPipelineSurface,
   InstancesSnapshot,
   LightProbeSnapshot,
+  MaterialProgramSelection,
   MaterialSnapshot,
   MaterialSnapshotCache,
   MaterialSnapshotCachesByWorld,
@@ -161,7 +162,7 @@ import {
   materialColorParameterSchema,
   materialNormalScale,
   materialParamSchemaForMaterial,
-  materialProgramKeysForMaterial,
+  materialProgramSelectionsForMaterial,
   materialSceneIndexProgramKeysForMaterial,
   materialStandardTextureMask,
   materialTextureFields,
@@ -191,6 +192,25 @@ function skinPaletteIdentity(world: World, entity: number): string {
   return `skin:${world.identity}:${entity}`;
 }
 
+function materialProgramSelectionRequiresSkin(selection: {
+  readonly abi?: {
+    readonly skinPaletteAddress?: unknown;
+    readonly vertexInputs?: readonly { readonly semantic?: unknown }[];
+  };
+}): boolean {
+  if (selection.abi?.skinPaletteAddress !== undefined) return true;
+  const semantics = new Set((selection.abi?.vertexInputs ?? []).map((input) => input.semantic));
+  return semantics.has('skinIndex') && semantics.has('skinWeight');
+}
+
+function isMissingMaterialProgram(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    (error as { readonly code?: unknown }).code === 'material-specialization-not-cooked'
+  );
+}
+
 export function extractFrames(
   worlds: readonly World[],
   owner: number | ExtractFramesOwner,
@@ -482,8 +502,8 @@ export function extractFrames(
   // bug-20260710-editor-cross-world-shadow: RECOMPUTE directional CSM matrices
   // against the surfaced camera. In a single-world app the per-world extract
   // already produced correct matrices (light+camera share the world), and this
-  // recompute reproduces them byte-identically (same config, same camera). In
-  // the editor super-composite the directional light's world has NO camera, so
+  // recompute uses the same config and camera. In the editor super-composite
+  // the directional light's world has NO camera, so
   // its per-world `lightViewProj` is undefined/degenerate; the surfaced camera
   // lives in the cameraOwner world. Pairing them here is the ONLY place both
   // are visible. Point/spot shadows are camera-independent (light-space only)
@@ -1226,9 +1246,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // bug-20260710-editor-cross-world-shadow: CSM matrices are computed by the
   // shared pure {@link computeDirectionalCsm}, called here per-world with THIS
   // world's own `cameras[0]`. In a single-world app the light and camera share
-  // the world, so this per-world result is final (byte-identical to the prior
-  // inline block). In the editor super-composite the light's world may have no
-  // camera → this yields no matrices; {@link extractFrames} then RECOMPUTES at
+  // the world, so this per-world result is final. In the editor
+  // super-composite the light's world may have no camera → this yields no
+  // matrices; {@link extractFrames} then RECOMPUTES at
   // the merge layer using the surfaced (cameraOwner) camera + the raw config
   // carried on ExtractedLights. The raw config + direction are surfaced
   // unconditionally so the merge layer can re-run the builder.
@@ -2030,6 +2050,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           : undefined;
 
       let materialSnap: MaterialSnapshot;
+      let materialProgramSelections: readonly MaterialProgramSelection[] | undefined;
 
       if (cachedMaterial !== undefined) {
         materialSnap = cachedMaterial.snapshot;
@@ -2143,11 +2164,59 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                     ...context.materialContext,
                     geometry: hasSkin ? ('skinned' as const) : context.materialContext.geometry,
                   };
-            const materialProgramKeys = materialProgramKeysForMaterial(
-              asset,
-              assets,
-              materialContext,
-            );
+            try {
+              materialProgramSelections = materialProgramSelectionsForMaterial(
+                asset,
+                assets,
+                materialContext,
+              );
+            } catch (error) {
+              // A standalone mesh can only satisfy a cooked skinned program
+              // through a Skin-bearing mesh. Probe that same exact owner
+              // selection only when the resolved mesh really lacks the
+              // advertised attributes; otherwise retain the producer's exact
+              // publication error instead of guessing from module names/order.
+              if (isMissingMaterialProgram(error) && materialContext?.geometry === 'mesh') {
+                try {
+                  const skinnedSelections = materialProgramSelectionsForMaterial(asset, assets, {
+                    ...materialContext,
+                    geometry: 'skinned',
+                  });
+                  if (
+                    skinnedSelections?.some(materialProgramSelectionRequiresSkin) === true &&
+                    gpuDrivenMesh !== undefined
+                  ) {
+                    const hasSkinIndex = gpuDrivenMesh.attributes.skinIndex !== undefined;
+                    const hasSkinWeight = gpuDrivenMesh.attributes.skinWeight !== undefined;
+                    if (!hasSkinIndex || !hasSkinWeight) {
+                      const missing =
+                        !hasSkinIndex && !hasSkinWeight
+                          ? 'both'
+                          : !hasSkinIndex
+                            ? 'skinIndex'
+                            : 'skinWeight';
+                      worldInternal._routeError(new MaterialSkinAttrMissingError(entity, missing), {
+                        severity: Severity.Error,
+                        systemName: 'RenderSystem.extract (material-skin-attr-missing)',
+                      });
+                      continue;
+                    }
+                  }
+                } catch {
+                  // Preserve the original exact-context publication error.
+                }
+              }
+              throw error;
+            }
+            const materialProgramKeys =
+              materialProgramSelections === undefined
+                ? undefined
+                : Object.fromEntries(
+                    materialProgramSelections.map(({ pass, specializationKey }) => [
+                      pass,
+                      specializationKey,
+                    ]),
+                  );
             const materialSceneIndexProgramKeys = materialSceneIndexProgramKeysForMaterial(
               asset,
               assets,
@@ -2208,7 +2277,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 skinSkeletonView !== undefined &&
                 skinSkeletonView !== undefined &&
                 skinSkeletonView !== 0;
-              const isPbrSkinMaterial = isStandardPbrSkinMaterialShader(firstPassShader);
+              const isPbrSkinMaterial =
+                materialProgramSelections?.some(materialProgramSelectionRequiresSkin) === true ||
+                isStandardPbrSkinMaterialShader(firstPassShader);
               if (hasSkinSkel && !isPbrSkinMaterial) {
                 worldInternal._routeError(new SkinMaterialMismatchError(entity, firstPassShader), {
                   severity: Severity.Error,
@@ -2759,7 +2830,10 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // reinterpret a skinned vertex stream through an ordinary mesh group.
         if (skinSlice === undefined && hasSkin) {
           releaseSkinIdentity();
-          if (materialSnap.materialShaderId === 'forgeax::pbr-skin') {
+          if (
+            materialSnap.materialShaderId === 'forgeax::pbr-skin' ||
+            materialProgramSelections?.some(materialProgramSelectionRequiresSkin) === true
+          ) {
             pendingDispatch.length = 0;
             continue;
           }

package/src/render-system-extract.ts

@@ -116,6 +116,7 @@ import type {
   MaterialColorParameterSchema,
   MaterialParameter,
   MaterialPass,
+  MaterialProgramAbi,
   MaterialRenderState,
   MaterialTextureCoordinates,
   MaterialTextureValue,
@@ -149,6 +150,7 @@ import {
   tonemapToU32,
   validateDynamicResolutionCamera,
 } from './components';
+import { DepthOfField } from './components/depth-of-field';
 import type { DirectionalShadowQuality } from './components/directional-shadow-filter';
 import type { LightValidationError } from './components/light-helpers';
 import { selectEnvironment } from './environment/frame';
@@ -165,6 +167,10 @@ import type {
 } from './extract/environment';
 import type { GpuDrivenDrawSnapshot } from './extract/gpu-driven';
 import { resolveVisibility, type VisibilitySnapshot } from './extract/visibility';
+import {
+  depthOfFieldRequestFailure,
+  resolveDepthOfFieldParams,
+} from './features/depth-of-field/depth-of-field-params';
 import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
@@ -1543,6 +1549,53 @@ export function materialProgramKeysForMaterial(
   return materialProgramKeysForAddress(material, assets, context, 'direct');
 }
 
+/**
+ * Return the exact direct/scene-index programs selected for one renderer
+ * context.  The selection result is kept next to the key projection so
+ * consumers that validate a mesh contract can inspect the producer ABI
+ * without rebuilding pass/context matching from payload order.
+ */
+export interface MaterialProgramSelection {
+  readonly pass: string;
+  readonly context: MaterialCookProgramContext;
+  readonly specializationKey: string;
+  readonly abi?: MaterialProgramAbi;
+}
+
+export function materialProgramSelectionsForMaterial(
+  material: MaterialAsset,
+  assets: AssetRegistry,
+  context: MaterialCookProgramContext | undefined,
+  address: 'direct' | 'scene-index' = 'direct',
+): readonly MaterialProgramSelection[] | undefined {
+  const projection = assets.getMaterialProjectionForPayload(material);
+  if (projection === undefined) return undefined;
+  if (context === undefined)
+    throw new Error('Published material selection requires renderer-owned compiler context');
+  return projection.passes.map((pass) => {
+    const mode = String(
+      (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+    );
+    const passKind = /shadow/i.test(mode)
+      ? ('shadow' as const)
+      : /depth/i.test(mode)
+        ? ('depth' as const)
+        : ('forward' as const);
+    const selectedContext: MaterialCookProgramContext = {
+      ...context,
+      pass: passKind,
+      pipeline: /deferred|gbuffer/i.test(mode) ? 'deferred' : context.pipeline,
+    };
+    const selected = selectMaterialPassProgram(projection, pass.name, selectedContext, address);
+    return {
+      pass: pass.name,
+      context: selectedContext,
+      specializationKey: selected.specializationKey,
+      ...(selected.abi === undefined ? {} : { abi: selected.abi }),
+    };
+  });
+}
+
 /** Resolve the producer's scene-index program key for each cooked Pass. */
 export function materialSceneIndexProgramKeysForMaterial(
   material: MaterialAsset,
@@ -1597,26 +1650,12 @@ function materialProgramKeysForAddress(
   context: MaterialCookProgramContext | undefined,
   address: 'direct' | 'scene-index',
 ): Readonly<Record<string, string>> | undefined {
-  const projection = assets.getMaterialProjectionForPayload(material);
-  if (projection === undefined) return undefined;
-  if (context === undefined)
-    throw new Error('Published material selection requires renderer-owned compiler context');
-  const entries: [string, string][] = [];
-  for (const pass of projection.passes) {
-    const mode = String(
-      (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
-    );
-    const selectedContext: MaterialCookProgramContext = {
-      ...context,
-      pass: /shadow/i.test(mode) ? 'shadow' : /depth/i.test(mode) ? 'depth' : 'forward',
-      pipeline: /deferred|gbuffer/i.test(mode) ? 'deferred' : context.pipeline,
-    };
-    entries.push([
-      pass.name,
-      selectMaterialPassProgram(projection, pass.name, selectedContext, address).specializationKey,
-    ]);
-  }
-  return entries.length === 0 ? undefined : Object.fromEntries(entries);
+  const selections = materialProgramSelectionsForMaterial(material, assets, context, address);
+  return selections === undefined
+    ? undefined
+    : Object.fromEntries(
+        selections.map(({ pass, specializationKey }) => [pass, specializationKey]),
+      );
 }
 
 export function runtimeMaterialShaderIdForMaterial(
@@ -2712,9 +2751,10 @@ export interface DirectionalCsmResult {
  * the caller leaves lightViewProj undefined rather than emitting zero matrices
  * that the WGSL reader would sample as NaN → "fully lit").
  *
- * Byte-identical to the prior inline computation for the single-world case
- * (same PSSM lambda, same toward-light Z reach RC-2 fix, same clip-space
- * matrix / tile-placement-in-shader split).
+ * Keeps the prior PSSM lambda, toward-light Z reach RC-2 fix, and clip-space
+ * matrix / tile-placement-in-shader split. The XY fit is additionally snapped
+ * to the cascade's shadow-texel grid so camera motion cannot continuously
+ * shimmer a receiver across raster texel boundaries.
  */
 export function computeDirectionalCsm(
   direction: Vec3,
@@ -2820,6 +2860,29 @@ export function computeDirectionalCsm(
       if ((ls[2] ?? 0) < minZ) minZ = ls[2] ?? 0;
       if ((ls[2] ?? 0) > maxZ) maxZ = ls[2] ?? 0;
     }
+    // Stabilize the orthographic receiver grid against sub-texel camera
+    // motion. The raster pass writes each cascade into a square `mapSize`
+    // viewport, so the light-space texel pitch is the fitted extent divided
+    // by that viewport size. Snap the fitted center to that grid and retain a
+    // half-texel guard on each side; caster and receiver projections then move
+    // together in whole shadow texels without clipping a frustum corner when
+    // the rounded center shifts by half a texel.
+    const texelX = (maxX - minX) / config.mapSize;
+    const texelY = (maxY - minY) / config.mapSize;
+    if (Number.isFinite(texelX) && texelX > 0) {
+      const centerX = (minX + maxX) * 0.5;
+      const snappedCenterX = Math.round(centerX / texelX) * texelX;
+      const halfWidth = (maxX - minX) * 0.5 + texelX * 0.5;
+      minX = snappedCenterX - halfWidth;
+      maxX = snappedCenterX + halfWidth;
+    }
+    if (Number.isFinite(texelY) && texelY > 0) {
+      const centerY = (minY + maxY) * 0.5;
+      const snappedCenterY = Math.round(centerY / texelY) * texelY;
+      const halfHeight = (maxY - minY) * 0.5 + texelY * 0.5;
+      minY = snappedCenterY - halfHeight;
+      maxY = snappedCenterY + halfHeight;
+    }
     // Orthographic projection from light-space AABB. RC-2: whole-frustum
     // toward-light extreme for the near bound; per-cascade far (minZ) + X/Y.
     const nearZ = Math.max(maxZ, lightSpaceMaxZFull);
@@ -2924,15 +2987,26 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection],
+      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
       with: [Transform, GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const depthOfField = row.get(DepthOfField);
     const dynamicResolution = row.get(DynamicResolution);
     const screenSpaceReflection = row.get(ScreenSpaceReflection);
+    const projection = cameraProjectionFromF32(cam.projection);
+    const depthOfFieldResult = resolveDepthOfFieldParams(depthOfField, {
+      projection,
+      fov: cam.fov,
+      near: cam.near,
+      far: cam.far,
+    });
+    const depthOfFieldError = depthOfFieldResult.ok
+      ? undefined
+      : depthOfFieldRequestFailure(depthOfFieldResult.error);
     const entity = row.entity;
     const view = worldInternal._getArrayView(entity, GlobalTransform, 'world');
     if (view === undefined) continue;
@@ -2967,7 +3041,7 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
       aspect: cam.aspect,
       near: cam.near,
       far: cam.far,
-      projection: cameraProjectionFromF32(cam.projection),
+      projection,
       orthoLeft: cam.left,
       orthoRight: cam.right,
       orthoBottom: cam.bottom,
@@ -2990,6 +3064,10 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
         cam.clearColor[2] ?? 0,
         cam.clearColor[3] ?? 1,
       ],
+      ...(depthOfFieldResult.ok && depthOfFieldResult.value !== undefined
+        ? { depthOfField: depthOfFieldResult.value }
+        : {}),
+      ...(depthOfFieldError === undefined ? {} : { depthOfFieldError }),
       ...(motionBlur === undefined
         ? {}
         : {

package/src/render-system.ts

@@ -46,6 +46,8 @@ import {
   type RenderError,
   TransmissionCapabilityMissingError,
 } from './errors/render';
+import { projectDepthOfFieldInspection } from './features/depth-of-field/depth-of-field-inspection';
+import { resolveDepthOfFieldFrameParams } from './features/depth-of-field/depth-of-field-params';
 import {
   type RenderFeaturePreparedGraphicsResolverInput,
   runRenderFeatureFrame,
@@ -68,6 +70,7 @@ import {
 } from './fullscreen-post-process-pass';
 import type {
   BloomInspection,
+  DepthOfFieldInspection,
   DirectionalShadowInspection,
   GpuDrivenProductionInspection,
   LodOcclusionInspection,
@@ -215,6 +218,7 @@ import {
   type RenderFeatureGraphCandidate,
   recordRenderFeatureCandidate,
   resetRenderFeatureGraphState,
+  settleDepthOfFieldGraphCandidate,
   settleVolumetricFogGraphCandidate,
 } from './record/typed-frame-graph';
 import {
@@ -576,6 +580,7 @@ export interface RenderSystem {
   readonly temporal: TemporalInspection;
   readonly bloom: BloomInspection;
   readonly motionBlurInspection: MotionBlurInspection | undefined;
+  readonly depthOfFieldInspection: DepthOfFieldInspection | undefined;
   readonly temporalTargetInspection: TemporalTargetInspection | undefined;
   readonly lodOcclusionInspection: LodOcclusionInspection | undefined;
   /** Bounded GPU-driven counters without materializing the persistent scene table. */
@@ -1159,6 +1164,14 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     compiledFrameGraph: null,
     compiledFrameGraphTopologyKey: null,
     compiledFrameGraphGeneration: 0,
+    depthOfFieldPreviousGraph: null,
+    depthOfFieldPreviousGraphKey: null,
+    depthOfFieldPreviousPerFrameGraph: undefined,
+    depthOfFieldPreviousGraphGeneration: 0,
+    depthOfFieldPreviousStandardLightingGraphSignature: '',
+    depthOfFieldCandidateGraph: null,
+    depthOfFieldAccepted: undefined,
+    depthOfFieldLastSubmitFailed: false,
     volumetricFogPreviousGraph: null,
     volumetricFogPreviousGraphKey: null,
     volumetricFogCandidateGraph: null,
@@ -2280,6 +2293,26 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
         ...(unavailable ? { lastFailure: 'scene-data-unavailable' as const } : {}),
       };
     },
+    get depthOfFieldInspection(): DepthOfFieldInspection | undefined {
+      const camera = latestCamera;
+      if (camera === undefined) return undefined;
+      const graph = frameState.compiledFrameGraph?.inspect();
+      return projectDepthOfFieldInspection({
+        ...(camera.depthOfField === undefined ? {} : { params: camera.depthOfField }),
+        ...(camera.depthOfFieldError === undefined ? {} : { error: camera.depthOfFieldError }),
+        ...(graph === undefined ? {} : { graph }),
+        // The explicit property keeps the inspector on the submit-bound
+        // transaction path even before the first accepted frame. A missing
+        // property remains supported for direct structural callers/tests.
+        accepted: frameState.depthOfFieldAccepted,
+        ...(frameState.depthOfFieldLastSubmitFailed === true ? { lastSubmitFailed: true } : {}),
+        // Inspection can be queried while the renderer is being assembled,
+        // before a device scope has been published. Keep that observation
+        // bounded instead of turning a not-yet-ready renderer into a getter
+        // exception.
+        deviceGeneration: internals.deviceScope?.generation ?? 0,
+      });
+    },
     get temporalTargetInspection(): TemporalTargetInspection | undefined {
       const graph = frameState.compiledFrameGraph?.inspect();
       if (graph === undefined) return undefined;
@@ -2888,6 +2921,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             const materialWorld = preparedWorlds[renderable.worldId];
             return projectMeshMaterialBindingObservation({
               worldId: renderable.worldId,
+              ...(materialWorld === undefined ? {} : { worldIdentity: materialWorld.identity }),
               entityKey: renderable.entityKey,
               bindings: renderable.materials.map((material, slotIndex) => ({
                 handle: material.materialHandle ?? 0,
@@ -3283,6 +3317,29 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             internals.errorRegistry.fire(temporalCommit.error);
           }
           frameState.lastSuccessfulCameraAntialias = cameras[0]?.antialias;
+          const submittedCamera = cameras[0];
+          const submittedDepthOfField =
+            submittedCamera === undefined
+              ? undefined
+              : resolveDepthOfFieldFrameParams(
+                  submittedCamera.depthOfField,
+                  submittedCamera.depthOfFieldError,
+                  frameState.depthOfFieldAccepted?.params,
+                );
+          const submittedDepthOfFieldGraph = frameState.compiledFrameGraph?.inspect();
+          if (submittedDepthOfField !== undefined && submittedDepthOfFieldGraph !== undefined) {
+            frameState.depthOfFieldAccepted = {
+              params: submittedDepthOfField,
+              graph: submittedDepthOfFieldGraph,
+              deviceGeneration: internals.deviceScope.generation,
+            };
+            frameState.depthOfFieldLastSubmitFailed = false;
+          } else if (submittedDepthOfField === undefined) {
+            frameState.depthOfFieldAccepted = undefined;
+            frameState.depthOfFieldLastSubmitFailed = false;
+          } else {
+            frameState.depthOfFieldLastSubmitFailed = true;
+          }
           internals.getPipelineState()?.perPassResources.commitBloomResources?.();
           const nextBloom = cameras[0]?.bloom ?? 'off';
           if (frameState.lastSuccessfulBloom === 'on' && nextBloom !== 'on') {
@@ -3294,6 +3351,9 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           }
           frameState.lastSuccessfulBloom = nextBloom;
         } else {
+          if (cameras[0]?.depthOfField !== undefined) {
+            frameState.depthOfFieldLastSubmitFailed = true;
+          }
           internals.getPipelineState()?.perPassResources.discardBloomResources?.();
         }
         if (!submitted && frameState.environmentGeneration !== undefined) {
@@ -3638,6 +3698,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       frameState.volumetricFogHistorySlot = null;
       frameState.volumetricFogHistorySignature = null;
       frameState.hdrpClusterMembership = null;
+      settleDepthOfFieldGraphCandidate(frameState, false);
       const compiled = frameState.compiledFrameGraph;
       frameState.compiledFrameGraph = null;
       frameState.compiledFrameGraphTopologyKey = null;
@@ -3645,6 +3706,14 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       frameState.standardLightingGraphSignature = '';
       frameState.standardLightingInspection = undefined;
       frameState.pointShadowInspection = undefined;
+      frameState.depthOfFieldPreviousGraph = null;
+      frameState.depthOfFieldPreviousGraphKey = null;
+      frameState.depthOfFieldPreviousPerFrameGraph = undefined;
+      frameState.depthOfFieldPreviousGraphGeneration = 0;
+      frameState.depthOfFieldPreviousStandardLightingGraphSignature = '';
+      frameState.depthOfFieldCandidateGraph = null;
+      frameState.depthOfFieldAccepted = undefined;
+      frameState.depthOfFieldLastSubmitFailed = false;
       if (compiled !== null) compiled.retire().catch(() => undefined);
       for (const retired of frameState.retiredCompiledFrameGraphs) {
         retired.retire().catch(() => undefined);
@@ -3746,12 +3815,19 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       // handles cannot be used on the fresh device and the next draw must
       // lazily build a new graph from the preserved ECS / asset POD caches.
       settleVolumetricFogGraphCandidate(frameState, false);
+      settleDepthOfFieldGraphCandidate(frameState, false);
       frameState.compiledFrameGraph?.retire().catch(() => undefined);
       frameState.compiledFrameGraph = null;
       frameState.compiledFrameGraphTopologyKey = null;
       frameState.volumetricFogPreviousGraph = null;
       frameState.volumetricFogPreviousGraphKey = null;
       frameState.volumetricFogCandidateGraph = null;
+      frameState.depthOfFieldPreviousGraph = null;
+      frameState.depthOfFieldPreviousGraphKey = null;
+      frameState.depthOfFieldPreviousPerFrameGraph = undefined;
+      frameState.depthOfFieldPreviousGraphGeneration = 0;
+      frameState.depthOfFieldPreviousStandardLightingGraphSignature = '';
+      frameState.depthOfFieldCandidateGraph = null;
       frameState.volumetricFogAccepted = undefined;
       frameState.volumetricFogAcceptedContext = undefined;
       frameState.volumetricFogHistoryGraph = null;
@@ -3772,6 +3848,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       frameState.standardLightingGraphSignature = '';
       frameState.standardLightingInspection = undefined;
       frameState.pointShadowInspection = undefined;
+      frameState.depthOfFieldAccepted = undefined;
+      frameState.depthOfFieldLastSubmitFailed = false;
       frameState.directionalShadowCache = null;
       frameState.directionalShadowCacheRecorded = false;
       frameState.currentFrameObservationSource = undefined;

package/src/typed-render-graph-primitives.ts

@@ -84,6 +84,8 @@ function resolvedDepthView(
   if (!texture.ok) throw texture.error;
   const view = frame.runtime.device.createTextureView(texture.value, {
     label: 'typed-ssao-depth-only-view',
+    // Multisampled WebGPU textures still use a `2d` view dimension; the
+    // sample count is carried by the source texture and WGSL type.
     dimension: '2d',
     aspect: 'depth-only',
     baseMipLevel: 0,
@@ -892,6 +894,7 @@ export function addTypedFullscreenPass(
         ...(options.fragmentEntryPoint === undefined
           ? {}
           : { fragmentEntryPoint: options.fragmentEntryPoint }),
+        ...(options.depth === undefined ? {} : { msaaActive: options.depth.sampleCount === 4 }),
       });
     },
   });