@forgeax/engine-render 0.1.32 → 0.1.34

package/src/assembly/webgpu-renderer.ts

@@ -14,7 +14,6 @@ import {
 } from '@forgeax/engine-geometry';
 import type {
   BindGroupLayout,
-  Buffer,
   PipelineLayout,
   RenderPipeline,
   Result,
@@ -28,6 +27,9 @@ import {
   type MaterialShaderEntry,
   type MaterialShaderManifestEntry,
   ShaderCatalog,
+  SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_WGSL,
+  SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_WGSL,
+  SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL,
   standardPhysicalTextureFields,
 } from '@forgeax/engine-shader';
 import type {
@@ -53,11 +55,16 @@ import {
   RenderFeatureCapabilityMissingError,
   RenderFeatureStageFailedError,
 } from '../errors/render';
+import {
+  BARREL_DISTORTION_FEATURE_IDENTITY,
+  createBarrelDistortionRenderFeature,
+} from '../features/barrel-distortion';
 import {
   dofInspection,
   registerDepthOfFieldBuiltins,
 } from '../features/depth-of-field/depth-of-field-assembly';
 import { createRenderFeatureHost } from '../features/host';
+import { motionBlurDrawOptions } from '../features/motion-blur/motion-blur-runtime';
 import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
 import type { RenderFeature, RenderFeatureShaderModuleMode } from '../features/types';
 import {
@@ -66,16 +73,20 @@ import {
 } from '../fullscreen-post-process-pass';
 import { glyphTextLayoutSystem } from '../glyph-text-layout-system';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
-import type { BloomInspection } from '../inspection-types';
+import { type BloomInspection, emptyBloomInspection } from '../inspection-types';
 import { DeviceScope } from '../lifecycle';
 import {
   createHdrpBindGroupLayoutDescriptor,
   isCanonicalStandardPbrMaterialShader,
   isStandardPbrMaterialShader,
   type PipelineGroup2Contract,
-  resolvePipelineGroup2Contract,
   SKIN_MATERIAL_SHADER_ID,
 } from '../pbr-pipeline';
+import {
+  SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID,
+  SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID,
+  SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID,
+} from '../pipeline/single-layer-medium-passes';
 import { standardPipeline } from '../pipeline/standard-pipeline';
 import { DEFAULT_STANDARD_PROFILE } from '../pipeline/standard-profile';
 import { buildPipelineForMaterialShader } from '../pipeline-builder';
@@ -146,13 +157,19 @@ import { postSpawnResolveJoints } from '../scene-instances/post-spawn-resolve-jo
 import type { RenderTarget } from '../targets/contracts';
 import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
 import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
+import { registerAnalyticFogPostProcess } from './analytic-fog-registration';
 import type { RhiBackendPack } from './backend-contract';
+import { inspectBarrelDistortion } from './barrel-distortion-inspection';
 import type { BundlerOptions } from './bundler-contract';
+import { rejectZeroCanvasSize } from './canvas-draw-guard';
 import { createRendererDynamicGeometryController } from './dynamic-geometry-host';
+import { registerFxaaPostProcess } from './fxaa-registration';
 import type { RendererAssemblyImplementation } from './host-contract';
+import { observeLodOcclusionForReceipt } from './lod-observation';
 import {
   isEngineOwnedMaterialShader,
   resolveMaterialPipelineBindGroups,
+  resolveMaterialPipelineGroup2Contract,
   resolveMaterialPipelineShaderId,
   resolveMaterialPipelineVertexEntry,
   resolveRendererMaterialShaderArtifact,
@@ -165,6 +182,7 @@ import {
   type MaterialShaderBindingContract,
   makeShaderDeviceAdapter,
   normalizeMaterialShaderVariantSet,
+  prepareLowLimitMaterialShaderEntry,
   prepareMaterialShaders,
   resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
@@ -177,12 +195,14 @@ import {
   shouldDeferMissingPreparedMaterialShader,
 } from './material-shader-policy';
 import type { MeshSsboGrowResult, MeshSsboState } from './mesh-ssbo-grow';
+import { registerMotionBlurPostProcess } from './motion-blur-registration';
 import {
   type GenerationAggregate,
   type GenerationPublication,
   publishGeneration,
 } from './recovery/generation';
 import { createRendererRecovery, type RendererRecovery } from './recovery/renderer-recover';
+import { collectRequiredFullscreenPostProcesses } from './render-feature-post-processes';
 import { createRenderTargetHost } from './render-target-host';
 import {
   freezeRenderProfile,
@@ -193,6 +213,7 @@ import { projectRendererFeatureInspection } from './renderer-feature-inspection'
 import {
   type ContinuationTerminator,
   createContinuationTerminator,
+  guardFrameCompletion,
 } from './renderer-frame-transaction';
 import {
   ensureContextConfigured,
@@ -200,7 +221,7 @@ import {
   rendererInitializationPipelineError,
   wrapDisposeError,
 } from './renderer-helpers';
-import { projectRendererOutputInspection } from './renderer-inspection';
+import { projectRendererOutputInspectionFromSurface } from './renderer-inspection';
 import {
   createRecoveryContinuation,
   createRecoveryDeadline,
@@ -224,7 +245,10 @@ import {
   type WebGPURendererInternals,
 } from './webgpu-renderer-bootstrap';
 import type { WebGPUOutcome } from './webgpu-renderer-contract';
-import { disposeObservationCaptureSet } from './webgpu-renderer-observation';
+import {
+  createRendererObservationCaptureOwner,
+  type ObservationCaptureRead,
+} from './webgpu-renderer-observation-owner';
 import {
   isPreparedMaterialVertexLayout,
   PREPARED_INSTANCE_VERTEX_ATTRS,
@@ -252,6 +276,7 @@ export {
   selectNoColorPbrVariant,
   selectPipelineLayoutForVariant,
   shouldDeferMissingPreparedMaterialShader,
+  stripCloudShadowBindingsForLowLimit,
 } from './material-shader-policy';
 export {
   createMeshSsboGrowController,
@@ -328,7 +353,13 @@ async function makeWebGPURenderer(
   let renderTargetDevice = internals.device;
   let renderTargetGeneration = 0;
   let renderSystemForTargetPromotion: RenderSystem | undefined;
-  const featureHostResult = createRenderFeatureHost(internals.options?.features ?? []);
+  const requestedFeatures = internals.options?.features ?? [];
+  const featureHostFeatures = requestedFeatures.some(
+    (f) => f.identity === BARREL_DISTORTION_FEATURE_IDENTITY,
+  )
+    ? requestedFeatures
+    : [...requestedFeatures, createBarrelDistortionRenderFeature()];
+  const featureHostResult = createRenderFeatureHost(featureHostFeatures);
   if (!featureHostResult.ok) throw featureHostResult.error;
   internals.featureHost = featureHostResult.value;
   let rendererRecovery: RendererRecovery | undefined;
@@ -461,27 +492,8 @@ async function makeWebGPURenderer(
     featureHostResult.value.features.flatMap((feature) => feature.requiredMaterialShaders ?? []),
   );
   let requiredMaterialShaders = Object.freeze([...requiredMaterialShaderSet]);
-  const collectRequiredFullscreenPostProcesses = (
-    features: readonly RenderFeature<unknown>[],
-  ): readonly { readonly identity: string; readonly source: string }[] => {
-    const entries = new Map<string, { readonly identity: string; readonly source: string }>();
-    for (const feature of features) {
-      for (const entry of feature.requiredFullscreenPostProcesses ?? []) {
-        const existing = entries.get(entry.identity);
-        if (existing !== undefined && existing.source !== entry.source) {
-          throw new RhiError({
-            code: 'internal-error',
-            expected: `fullscreen identity '${entry.identity}' has one source across render features`,
-            hint: 'rename the conflicting fullscreen identity or make its WGSL source identical',
-          });
-        }
-        entries.set(entry.identity, entry);
-      }
-    }
-    return Object.freeze([...entries.values()]);
-  };
-  let requiredFullscreenPostProcesses = collectRequiredFullscreenPostProcesses(
-    featureHostResult.value.features,
+  let requiredFullscreenPostProcesses = Object.freeze(
+    collectRequiredFullscreenPostProcesses(featureHostResult.value.features),
   );
   // Lazy ShaderCatalog instance (plan-strategy section S-10 / D-R10 / OQ-5
   // close): constructed on first access; subsequent accesses return the
@@ -531,7 +543,7 @@ async function makeWebGPURenderer(
     feature: RenderFeature<unknown>,
   ): Promise<Result<void, RhiError>> => {
     for (const postProcess of feature.requiredFullscreenPostProcesses ?? []) {
-      const label = postProcessShaderModuleLabel(postProcess.identity, postProcess.source);
+      const label = postProcessShaderModuleLabel(postProcess.source);
       const shaderResult = internals.pack.createShaderModule
         ? await internals.pack.createShaderModule(internals.device, {
             code: postProcess.source,
@@ -1132,6 +1144,9 @@ async function makeWebGPURenderer(
     const lookup = getShader().findMaterialArtifact(materialShaderId);
     const source = lookup.ok ? lookup.value.source : '';
     const paramSchema = lookup.ok ? lookup.value.paramSchema : explicitParamSchema;
+    const singleLayerMedium =
+      materialShaderId === 'forgeax::single-layer-medium' ||
+      (lookup.ok && lookup.value.receipt?.surface?.model === 'single-layer-medium');
     if (paramSchema === undefined) return null;
     const cacheKey = `${materialShaderId}:${layoutKind}:${clustered}`;
     const cached = cacheState.perShaderMaterialLayoutCache.get(cacheKey);
@@ -1150,7 +1165,12 @@ async function makeWebGPURenderer(
       isStandardPbrMaterialShader(materialShaderId) ||
       standardPhysicalTextureFields(paramSchema).length > 0;
     const isStandardMapLayout = requiresStandardMapLayout;
-    if (!clustered && !isStandardMapLayout && isSharedMaterialUserRegionCompatible(paramSchema)) {
+    if (
+      !clustered &&
+      !singleLayerMedium &&
+      !isStandardMapLayout &&
+      isSharedMaterialUserRegionCompatible(paramSchema)
+    ) {
       cacheState.perShaderMaterialLayoutCache.set(cacheKey, {
         source,
         paramSchema,
@@ -1160,7 +1180,11 @@ async function makeWebGPURenderer(
       return null;
     }
     const spec: PipelineSpec = {
-      shader: { id: materialShaderId, passKind: 'forward', variantSet: undefined },
+      shader: {
+        id: singleLayerMedium ? 'forgeax::single-layer-medium' : materialShaderId,
+        passKind: 'forward',
+        variantSet: undefined,
+      },
       attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
       geometry: { topology: 'triangle-list', vertexLayout: {} },
       renderState: undefined,
@@ -1339,22 +1363,14 @@ async function makeWebGPURenderer(
         tonemapRegistered = true;
       },
       (source: string) => {
-        if (fxaaRegistered) return;
-        renderSystem.registerBuiltinPostProcess(FXAA_POST_PROCESS_ID, {
-          source,
-          params: { byteSize: 16, defaultValue: new Uint8Array(16) },
-          reads: ['ldrColor'],
-        });
-        fxaaRegistered = true;
+        fxaaRegistered = registerFxaaPostProcess(renderSystem, source, fxaaRegistered);
       },
+      (source: string) =>
+        registerAnalyticFogPostProcess(renderSystem, source, candidateBuildState !== undefined),
       (entries: { readonly motionBlur?: string; readonly taaResolve?: string }) => {
         if (candidateBuildState !== undefined || temporalPostProcessesRegistered) return;
         if (entries.motionBlur !== undefined) {
-          renderSystem.registerBuiltinPostProcess('forgeax.motion-blur', {
-            source: entries.motionBlur,
-            params: { byteSize: 16, defaultValue: new Uint8Array(16) },
-            reads: ['scene-color', 'scene-temporal'],
-          });
+          registerMotionBlurPostProcess(renderSystem, entries.motionBlur);
         }
         if (entries.taaResolve !== undefined) {
           renderSystem.registerBuiltinPostProcess('forgeax.taa-resolve', {
@@ -1555,7 +1571,11 @@ async function makeWebGPURenderer(
           : getShaderModuleAdapter(),
       pipelineLayout,
       vertexBuffers,
-      ...(layoutKind === 'pbr-skin' || layoutKind === 'gpu-driven-skin' ? { layoutKind } : {}),
+      ...(layoutKind === 'pbr-skin' ||
+      layoutKind === 'gpu-driven-skin' ||
+      layoutKind === 'gpu-driven-cluster-skin'
+        ? { layoutKind }
+        : {}),
     };
   };
   /**
@@ -1622,7 +1642,10 @@ async function makeWebGPURenderer(
     particleInputLanes?: number,
     coverageOnly = false,
   ): RenderPipeline | null => {
-    const declaredGroup2Contract = resolvePipelineGroup2Contract(entry.source);
+    const declaredGroup2Contract = resolveMaterialPipelineGroup2Contract(
+      entry.source,
+      layoutKindOverride,
+    );
     const group2Contract =
       declaredGroup2Contract === 'mesh' &&
       (materialShaderId === 'forgeax::vfx-render.particles.mesh' ||
@@ -2051,6 +2074,10 @@ async function makeWebGPURenderer(
         }
       }
     }
+    shaderEntry = prepareLowLimitMaterialShaderEntry(
+      shaderEntry,
+      currentBuildDevice().limits.maxSampledTexturesPerShaderStage,
+    );
     // feat-20260609 M4 / R3-fixup: append `-${passKind}` to the PSO label so
     // GPU debug captures (and the shadow-caster branch in the builder)
     // make the cache variant visible. The fallback path above keeps the
@@ -2118,10 +2145,50 @@ async function makeWebGPURenderer(
   ) => {
     const pipeline = getMaterialShaderPipeline(...args);
     if (pipeline === null) return null;
+    const materialShaderId = args[0];
+    const variantSet = args[5];
+    const passKind = args[6] ?? 'forward';
+    const vertexLayoutProjection = args[13];
+    const layoutKind = args[15];
+    const sceneIndexAddress =
+      layoutKind === 'gpu-driven-pbr' ||
+      layoutKind === 'gpu-driven-skin' ||
+      layoutKind === 'gpu-driven-cluster-pbr' ||
+      layoutKind === 'gpu-driven-cluster-skin';
+    const artifact = resolveRendererMaterialShaderArtifact(
+      materialShaderId,
+      getShader(),
+      pipelineState?.gpuDrivenPbrPrograms,
+      {
+        ...(vertexLayoutProjection === undefined
+          ? {}
+          : {
+              vertexColorAvailable: vertexLayoutProjection.attributes.some(
+                (attribute) => attribute.key === 'color',
+              ),
+            }),
+        ...(layoutKind === 'pbr-skin' ||
+        layoutKind === 'gpu-driven-skin' ||
+        layoutKind === 'gpu-driven-cluster-skin'
+          ? { deformation: 'skin' as const }
+          : {}),
+        ...(variantSet === undefined ? {} : { variantSet }),
+        address: sceneIndexAddress ? 'scene-index' : 'direct',
+        pass: passKind === 'shadow-caster' ? 'shadow' : 'forward',
+      },
+    );
     return {
       pipeline,
       group2Contract:
         materialShaderPipelineGroup2Contracts.get(pipeline as object) ?? ('mesh' as const),
+      ...(artifact?.receipt === undefined
+        ? {}
+        : {
+            receipt: {
+              identity: artifact.receipt.receiptIdentity,
+              generation: artifact.receipt.generation,
+            },
+          }),
     };
   };
   const getParamSchema = (materialShaderId: string) => {
@@ -2175,10 +2242,11 @@ async function makeWebGPURenderer(
     colorFormats: readonly GPUTextureFormat[],
     label: string,
   ): RenderPipeline | null => {
+    const isFxaaPipeline = label.startsWith(`post-process-${FXAA_POST_PROCESS_ID}-pso-`);
     const moduleFactory = getShaderModuleAdapter();
     const moduleResult = moduleFactory.createShaderModule({
       code: entry.source,
-      label: `${label}-module`,
+      label: postProcessShaderModuleLabel(entry.source),
     });
     if (!moduleResult.ok) {
       // 'rhi-not-available' = async compile in flight: caller falls back one frame.
@@ -2189,7 +2257,7 @@ async function makeWebGPURenderer(
       }
       return null;
     }
-    if (currentEmptyPostProcessBgl() === null) {
+    if (!isFxaaPipeline && entry.usesView !== true && currentEmptyPostProcessBgl() === null) {
       const bglRes = currentBuildDevice().createBindGroupLayout({ entries: [] });
       if (!bglRes.ok) {
         internals.errorRegistry.fire(bglRes.error);
@@ -2202,9 +2270,18 @@ async function makeWebGPURenderer(
         emptyPostProcessBgl = bglRes.value;
       }
     }
+    const viewLayout =
+      entry.usesView === true ? currentPipelineState()?.viewBindGroupLayout : undefined;
+    const group0Layout = viewLayout ?? currentEmptyPostProcessBgl();
+    if (group0Layout === null || group0Layout === undefined) {
+      internals.errorRegistry.fire(
+        new Error('fullscreen post-process View layout is unavailable') as never,
+      );
+      return null;
+    }
     const layoutRes = currentBuildDevice().createPipelineLayout({
       label: `${label}-layout`,
-      bindGroupLayouts: [currentEmptyPostProcessBgl() as BindGroupLayout, bgl],
+      bindGroupLayouts: isFxaaPipeline ? [bgl] : [group0Layout as BindGroupLayout, bgl],
     });
     if (!layoutRes.ok) {
       internals.errorRegistry.fire(layoutRes.error);
@@ -2442,6 +2519,22 @@ async function makeWebGPURenderer(
   });
   attachGpuPassTimingSession(internals, gpuPassTimingSession);
   renderSystemForTargetPromotion = renderSystem;
+  renderSystem.registerBuiltinPostProcess(SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID, {
+    source: SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL,
+    reads: ['input', { key: 'scene-depth', sampleType: 'depth' }],
+  });
+  const pairedMsaaReads = [
+    { key: 'input', sampleType: 'multisampled-float' as const },
+    { key: 'scene-depth', sampleType: 'depth' as const },
+  ];
+  renderSystem.registerBuiltinPostProcess(SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID, {
+    source: SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_WGSL,
+    reads: pairedMsaaReads,
+  });
+  renderSystem.registerBuiltinPostProcess(SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID, {
+    source: SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_WGSL,
+    reads: pairedMsaaReads,
+  });
   if (
     internals.device.caps.backendKind === 'null' &&
     Array.from(getShader().entries()).length === 0
@@ -2478,183 +2571,33 @@ async function makeWebGPURenderer(
   const receiptTimings = new WeakMap<FrameReceipt, Promise<VolumeTimingObservation>>();
   let latestReceipt: FrameReceipt | undefined;
   let pendingObservationDomains: readonly FrameObservationDomain[] | undefined;
-  let observationAllocationCount = 0;
-  let observationLiveCount = 0;
-  let observationPeakLiveCount = 0;
-  let observationMapCount = 0;
-  let observationReadbackCount = 0;
-  let observationLiveByteLength = 0;
-  const observationCaptureOwner = (() => {
-    const capturesByFrame = new Map<number, TypedFrameObservationCapture[]>();
-    return {
-      register(capture: TypedFrameObservationCapture): void {
-        const captures = capturesByFrame.get(capture.frameNumber) ?? [];
-        captures.push(capture);
-        capturesByFrame.set(capture.frameNumber, captures);
-        observationAllocationCount += 1;
-        observationLiveCount += 1;
-        observationPeakLiveCount = Math.max(observationPeakLiveCount, observationLiveCount);
-        observationLiveByteLength += capture.bytesPerRow * capture.height;
-      },
-      consume(frameNumber: number): readonly TypedFrameObservationCapture[] {
-        const captures = capturesByFrame.get(frameNumber) ?? [];
-        capturesByFrame.delete(frameNumber);
-        return Object.freeze(captures);
-      },
-      drain(): readonly TypedFrameObservationCapture[] {
-        const captures = [...capturesByFrame.values()].flat();
-        capturesByFrame.clear();
-        return Object.freeze(captures);
-      },
-    };
-  })();
+  const observationOwner = createRendererObservationCaptureOwner((error) => {
+    internals.errorRegistry.fire(error);
+  });
+  const {
+    observationCaptureOwner,
+    stats: observationStats,
+    receiptObservationCaptures,
+    receiptObservationBuffers,
+    destroyedObservationBuffers,
+    disposeObservationCaptures,
+    disposeOwnedObservationCaptures,
+    readObservationCapture,
+    disposeReceiptObservationCaptures,
+  } = observationOwner;
   Object.assign(internals, { observationCaptureOwner });
-  let expectedObservationGraphGeneration: number | undefined;
   Object.defineProperty(internals, 'observationGraphGeneration', {
     configurable: true,
-    get: () => expectedObservationGraphGeneration,
+    get: () => observationOwner.expectedGraphGeneration,
     set: (generation: number | undefined) => {
-      expectedObservationGraphGeneration = generation;
+      observationOwner.expectedGraphGeneration = generation;
     },
   });
-  type ObservationCaptureRead = () => Promise<
-    RenderResult<
-      readonly {
-        readonly capture: TypedFrameObservationCapture;
-        readonly bytes: Uint8Array;
-      }[],
-      RenderError
-    >
-  >;
-  const receiptObservationCaptures = new Map<FrameReceipt, ObservationCaptureRead>();
-  const receiptObservationBuffers = new Map<
-    FrameReceipt,
-    readonly TypedFrameObservationCapture[]
-  >();
-  const destroyedObservationBuffers = new WeakSet<Buffer>();
-  const observationBufferCleanupFailures = new WeakMap<Buffer, RendererContractFailureError>();
-  const failedObservationCaptures = new Map<Buffer, TypedFrameObservationCapture>();
-  const disposeObservationCaptures = (
-    captures: readonly TypedFrameObservationCapture[],
-  ): RendererContractFailureError | undefined => {
-    const wasDestroyed = new Set(
-      captures
-        .filter((capture) => destroyedObservationBuffers.has(capture.buffer))
-        .map((capture) => capture.buffer),
-    );
-    const result = disposeObservationCaptureSet(
-      captures,
-      destroyedObservationBuffers,
-      observationBufferCleanupFailures,
-      (failure) => internals.errorRegistry.fire(failure),
-    );
-    for (const capture of captures) {
-      if (!wasDestroyed.has(capture.buffer) && destroyedObservationBuffers.has(capture.buffer)) {
-        observationLiveCount = Math.max(0, observationLiveCount - 1);
-        observationLiveByteLength = Math.max(
-          0,
-          observationLiveByteLength - capture.bytesPerRow * capture.height,
-        );
-      }
-    }
-    return result;
-  };
-  const disposeOwnedObservationCaptures = (
-    captures: readonly TypedFrameObservationCapture[],
-  ): RendererContractFailureError | undefined => {
-    const failure = disposeObservationCaptures(captures);
-    if (failure !== undefined) {
-      for (const capture of captures) {
-        if (!destroyedObservationBuffers.has(capture.buffer)) {
-          failedObservationCaptures.set(capture.buffer, capture);
-        }
-      }
-    }
-    return failure;
-  };
-  const readObservationCapture = async (
-    capture: TypedFrameObservationCapture,
-  ): Promise<RenderResult<Uint8Array, RenderError>> => {
-    try {
-      if (typeof capture.buffer.mapAsync !== 'function') {
-        const cleanupFailure = disposeObservationCaptures([capture]);
-        return err(
-          cleanupFailure ??
-            new RendererContractFailureError(
-              'observe',
-              `the ${capture.domain} receipt-bound readback backend has no mapAsync capability`,
-            ),
-        );
-      }
-      observationMapCount += 1;
-      const mapped = await capture.buffer.mapAsync(1);
-      if (!mapped.ok) {
-        const cleanupFailure = disposeObservationCaptures([capture]);
-        return err(
-          cleanupFailure ??
-            new RendererContractFailureError(
-              'observe',
-              `mapping ${capture.domain} receipt-bound readback failed: ${mapped.error.code}`,
-            ),
-        );
-      }
-      const range = mapped.value.getMappedRange();
-      if (!range.ok) {
-        mapped.value.unmap();
-        const cleanupFailure = disposeObservationCaptures([capture]);
-        return err(
-          cleanupFailure ??
-            new RendererContractFailureError(
-              'observe',
-              `reading ${capture.domain} receipt-bound readback failed: ${range.error.code}`,
-            ),
-        );
-      }
-      const bytes = new Uint8Array(range.value.slice(0));
-      mapped.value.unmap();
-      observationReadbackCount += 1;
-      const cleanupFailure = disposeObservationCaptures([capture]);
-      if (cleanupFailure !== undefined) return err(cleanupFailure);
-      return ok(bytes);
-    } catch (cause) {
-      const cleanupFailure = disposeObservationCaptures([capture]);
-      return err(
-        cleanupFailure ??
-          new RendererContractFailureError(
-            'observe',
-            `reading ${capture.domain} receipt-bound readback threw: ${
-              cause instanceof Error ? cause.message : String(cause)
-            }`,
-          ),
-      );
-    }
-  };
-
-  const disposeReceiptObservationCaptures = (): RendererContractFailureError | undefined => {
-    let firstFailure: RendererContractFailureError | undefined;
-    for (const [receipt, captures] of receiptObservationBuffers) {
-      const failure = disposeObservationCaptures(captures);
-      firstFailure ??= failure;
-      if (captures.every((capture) => destroyedObservationBuffers.has(capture.buffer))) {
-        receiptObservationBuffers.delete(receipt);
-      }
-    }
-    receiptObservationCaptures.clear();
-    const retryCaptures = [...failedObservationCaptures.values()];
-    const retryFailure = disposeObservationCaptures(retryCaptures);
-    firstFailure ??= retryFailure;
-    for (const capture of retryCaptures) {
-      if (destroyedObservationBuffers.has(capture.buffer)) {
-        failedObservationCaptures.delete(capture.buffer);
-      }
-    }
-    const ownedFailure = disposeOwnedObservationCaptures(observationCaptureOwner.drain());
-    firstFailure ??= ownedFailure;
-    return firstFailure;
-  };
   let surfaceReleased = false;
   const renderer: RendererAssemblyImplementation = {
-    instances: renderSystem.instances,
+    setSurfaceDynamicInput(frame) {
+      renderSystem.setSurfaceDynamicInput(frame);
+    },
     attach(world: World): RenderResult<RenderWorldLease, RenderError> {
       const attached = this.attachScene(world);
       if (!attached.ok) {
@@ -2717,40 +2660,29 @@ async function makeWebGPURenderer(
             ? 'faulted'
             : 'alive';
       const graph = deviceLost ? undefined : renderSystem.perFrameGraphInfo;
+      const graphResourceAllocation = graph?.resourceAllocation;
+      const graphGenerationAllocation = deviceLost
+        ? undefined
+        : renderSystem.renderGraphGenerationAllocation;
       const standardLighting = deviceLost ? undefined : renderSystem.standardLightingInspection;
-      const bloom: BloomInspection = deviceLost
-        ? {
-            graphStatus: 'empty',
-            enabled: false,
-            targetCount: 0,
-            targetBytes: 0,
-            resourceCount: 0,
-            passCount: 0,
-            encodeCount: 0,
-            bindGroupCount: 0,
-            uploadCount: 0,
-            residentChildBytes: 0,
-            generation: 0,
-            state: 'off',
-          }
-        : renderSystem.bloom;
-      const surfaceStorage = pipelineState?.format ?? 'rgba8unorm';
-      const surfaceDisplay = pipelineState?.colorAttachmentFormat ?? 'rgba8unorm';
+      const barrelDistortion = inspectBarrelDistortion(
+        disposed,
+        deviceLost,
+        surfaceReleased,
+        frameId,
+        activeDeviceScope.generation,
+        renderSystem.barrelDistortionInspection,
+      );
+      const bloom: BloomInspection = deviceLost ? emptyBloomInspection() : renderSystem.bloom;
       const observationId = `${STANDARD_OUTPUT_TRANSFORM_FEATURE_ID}:frame-${frameId}`;
-      const outputInspection = projectRendererOutputInspection({
+      const outputInspection = projectRendererOutputInspectionFromSurface({
         graph,
-        surfaceAvailable: !surfaceReleased && pipelineState !== null,
-        surfaceStorage,
-        surfaceDisplay,
-        ...(pipelineState?.surfaceProfile === undefined
-          ? {}
-          : { surfaceProfile: pipelineState.surfaceProfile }),
+        surfaceReleased,
+        pipelineState,
         rgba16floatRenderable: internals.device.caps.rgba16floatRenderable,
         autoExposure: renderSystem.autoExposure,
         standardLut: renderSystem.standardLut,
-        ...(internals.context?.presentationProof === undefined
-          ? {}
-          : { presentationProof: internals.context.presentationProof }),
+        presentationProof: internals.context?.presentationProof,
       });
       const volumetricFog = renderSystem.volumetricFog;
       const directionalShadow = renderSystem.directionalShadow;
@@ -2765,6 +2697,7 @@ async function makeWebGPURenderer(
           frameId,
           deviceGeneration: activeDeviceScope.generation,
         }),
+        barrelDistortion,
         ...projectRendererFeatureInspection(internals.featureHost),
         featureGraph: renderSystem.featureGraphInspection,
         materialTextureSources: renderSystem.materialTextureSources,
@@ -2774,9 +2707,6 @@ async function makeWebGPURenderer(
           renderSystem.instanceCollectionsInspection.map((collection) =>
             Object.freeze({
               ...collection,
-              dirtyRanges: Object.freeze(
-                collection.dirtyRanges.map((range) => Object.freeze({ ...range })),
-              ),
               uploadRanges: Object.freeze(
                 collection.uploadRanges.map((range) => Object.freeze({ ...range })),
               ),
@@ -2793,6 +2723,12 @@ async function makeWebGPURenderer(
         ),
         dynamicGeometry: dynamicGeometry.inspect(),
         renderScene: renderSystem.renderScene,
+        ...(graphResourceAllocation === undefined
+          ? {}
+          : { renderGraphResourceAllocation: graphResourceAllocation }),
+        ...(graphGenerationAllocation === undefined
+          ? {}
+          : { renderGraphGenerationAllocation: graphGenerationAllocation }),
         ...(renderSystem.iblBinding === undefined ? {} : { iblBinding: renderSystem.iblBinding }),
         reflectionProbes: renderSystem.reflectionProbes,
         ssrDependencies: renderSystem.ssrDependencies,
@@ -2873,12 +2809,12 @@ async function makeWebGPURenderer(
             ? {}
             : { standardOutputColor: Object.freeze({ ...outputInspection.standardOutputColor }) }),
           resourceStats: Object.freeze({
-            allocationCount: observationAllocationCount,
-            liveCount: observationLiveCount,
-            peakLiveCount: observationPeakLiveCount,
-            mapCount: observationMapCount,
-            readbackCount: observationReadbackCount,
-            liveByteLength: observationLiveByteLength,
+            allocationCount: observationStats.allocationCount,
+            liveCount: observationStats.liveCount,
+            peakLiveCount: observationStats.peakLiveCount,
+            mapCount: observationStats.mapCount,
+            readbackCount: observationStats.readbackCount,
+            liveByteLength: observationStats.liveByteLength,
           }),
         }),
       });
@@ -3226,9 +3162,13 @@ async function makeWebGPURenderer(
               ...(frameRequest.camera.entityKey === undefined
                 ? {}
                 : { cameraEntityKey: frameRequest.camera.entityKey }),
+              ...motionBlurDrawOptions(frameRequest),
               ...(frameRequest.profileFrame === undefined
                 ? {}
                 : { profileFrame: frameRequest.profileFrame }),
+              ...(frameRequest.geometryLane === undefined
+                ? {}
+                : { geometryLane: frameRequest.geometryLane }),
             }
           : (options ?? { cameraOwner: 0, resourceOwner: 0 });
       // feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M5 / w21
@@ -3256,6 +3196,8 @@ async function makeWebGPURenderer(
           }),
         );
       }
+      const canvasSizeError = rejectZeroCanvasSize(internals.canvas.width, internals.canvas.height);
+      if (canvasSizeError !== undefined) return err(canvasSizeError);
       // M2 / w9 (A-IN-5): device-lost guard — draw() silently returns err
       // without firing onError each frame. The device-lost channel fires once
       // through the dual-channel fan-out (:750-797); draw() does not repeat it
@@ -3377,6 +3319,8 @@ async function makeWebGPURenderer(
           const cleanupFailure = disposeOwnedObservationCaptures(observationCaptureOwner.drain());
           volumeTimingCapture?.discard();
           if (cleanupFailure !== undefined) return err(cleanupFailure);
+          const invalidMotionBlur = renderSystem.motionBlurInvalidParams;
+          if (invalidMotionBlur !== undefined) return err(invalidMotionBlur);
           return err(
             new RendererContractFailureError(
               'draw',
@@ -3415,34 +3359,30 @@ async function makeWebGPURenderer(
           );
         const continuation = createContinuationTerminator();
         frameContinuations.add(continuation);
-        const guardedCompletion = completion.then(
+        const guardedCompletion = guardFrameCompletion(
+          completion,
+          () => continuation.guard('queue-completion'),
           () =>
-            continuation.guard('queue-completion')
-              ? ok(undefined)
-              : err(
-                  new RendererOperationError('device-operation-failed', {
-                    operation: 'complete-frame',
-                    frameId: receiptFrameId,
-                    deviceGeneration: receiptGeneration,
-                    cause: structuredRendererCause(
-                      {
-                        code: 'stale-generation',
-                        expected: 'frame completion belongs to its device generation',
-                        hint: 'discard the stale receipt',
-                      },
-                      'complete-frame',
-                    ),
-                  }),
-                ),
+            new RendererOperationError('device-operation-failed', {
+              operation: 'complete-frame',
+              frameId: receiptFrameId,
+              deviceGeneration: receiptGeneration,
+              cause: structuredRendererCause(
+                {
+                  code: 'stale-generation',
+                  expected: 'frame completion belongs to its device generation',
+                  hint: 'discard the stale receipt',
+                },
+                'complete-frame',
+              ),
+            }),
           (cause: unknown) =>
-            err(
-              new RendererOperationError('device-operation-failed', {
-                operation: 'complete-frame',
-                frameId: receiptFrameId,
-                deviceGeneration: receiptGeneration,
-                cause: structuredRendererCause(cause, 'complete-frame'),
-              }),
-            ),
+            new RendererOperationError('device-operation-failed', {
+              operation: 'complete-frame',
+              frameId: receiptFrameId,
+              deviceGeneration: receiptGeneration,
+              cause: structuredRendererCause(cause, 'complete-frame'),
+            }),
         );
         const terminated = continuation.promise().then((reason) =>
           err(
@@ -3470,12 +3410,17 @@ async function makeWebGPURenderer(
         });
         const captures = observationCaptureOwner.consume(receiptFrameId);
         pendingObservationDomains = undefined;
-        const receiptGraphGeneration = timingHost.observationGraphGeneration ?? 0;
+        const receiptGraphGeneration =
+          timingHost.observationGraphGeneration ?? renderSystem.perFrameGraphInfo?.generation ?? 0;
         const receipt = Object.freeze({
           frameId: receiptFrameId,
           deviceGeneration: receiptGeneration,
+          presentation: renderSystem.presentation,
           backendId: internals.device.caps.backendKind,
           graphGeneration: receiptGraphGeneration,
+          ...(renderSystem.lastSuccessfulBarrelDistortion === undefined
+            ? {}
+            : { barrelDistortion: renderSystem.lastSuccessfulBarrelDistortion }),
           completed,
         });
         renderTargetHost.onFrameSubmitted(completed);
@@ -3715,7 +3660,7 @@ async function makeWebGPURenderer(
           receiptObservationBuffers.delete(receipt);
         }
       }
-      await renderSystem.observeLodOcclusion();
+      await observeLodOcclusionForReceipt(renderSystem, receipt);
       const targetReadbacks =
         request.targetReadbacks === undefined || request.targetReadbacks.length === 0
           ? undefined
@@ -4070,6 +4015,8 @@ async function makeWebGPURenderer(
     setCandidateEmptyPostProcessBgl(layout) {
       candidateEmptyPostProcessBgl = layout;
     },
+    getShaderModuleAdapter,
+    getImmediateShaderModuleAdapter,
     getShader,
     assets,
     adaptMipmapShaderModuleFactory,