@forgeax/engine-render 0.1.33 → 0.1.35

package/src/assembly/webgpu-ready.ts

@@ -30,6 +30,7 @@ import type { ManifestEntry } from '@forgeax/engine-types';
 import { handleSlot } from '@forgeax/engine-types';
 import { prewarmDepthOfField } from '../features/depth-of-field/depth-of-field-assembly';
 import { prewarmAtmosphereShaders } from './atmosphere-shader-prewarm';
+import { selectCloudShadowCompatibleEntry } from './cloud-shadow-entry';
 import { prewarmSsrShaders } from './ssr-shader-prewarm';
 
 export type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
@@ -85,11 +86,10 @@ import { deriveExtendedLightingCapability } from '../prepare/extended-lighting/r
 import type { BloomPersistentBundle } from '../record/render-context';
 import { SHADOW_CASTER_BUFFER_SIZE } from '../record/shadow-pass';
 import { POINTS_LINES_VIEW_BUFFER_SIZE } from '../record/view-ubo';
-import {
-  type AtmosphereShaderSources,
-  type SsrShaderSources,
-  STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
-  type VolumetricFogShaderSources,
+import type {
+  AtmosphereShaderSources,
+  SsrShaderSources,
+  VolumetricFogShaderSources,
 } from '../render-contract';
 import {
   MATERIAL_PER_ENTITY_STRIDE,
@@ -129,6 +129,7 @@ import {
   VIEW_UBO_BYTES,
 } from './webgpu-ready-contract';
 import { prewarmMipmapPipeline } from './webgpu-ready-mipmap';
+import { createReadyPerPassResources } from './webgpu-ready-per-pass';
 
 /**
  * Build the `Renderer.initialization` Promise (D-S3 three-step strict-serial chain).
@@ -235,8 +236,7 @@ export async function buildReadyWebGPU(
 ): Promise<PipelineState> {
   const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
   // Shader and layout construction consume the same storage capability.
-  const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
-    .maxStorageBuffersPerShaderStage;
+  const capValue = rhiDevice.limits.maxStorageBuffersPerShaderStage;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
   let storageBufferCapable = !webgl2Downlevel && rhiDevice.caps.storageBuffer;
   if (typeof capValue === 'number') {
@@ -590,11 +590,25 @@ export async function buildReadyWebGPU(
       return wgsl !== undefined ? { ...entry, wgsl } : entry;
     };
     pbrEntry = patchRuntimeVariant(pbrEntry, 'forgeax::default-standard-pbr');
+    const pbrMaterialEntry = Array.from(registry.materialShaderManifestEntries()).find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+    pbrEntry = selectCloudShadowCompatibleEntry(pbrEntry, pbrMaterialEntry, projectorAvailable);
     if (pbrSkinEntry !== undefined) {
       pbrSkinEntry = patchRuntimeVariant(
         patchRuntimeVariant(pbrSkinEntry, SKIN_MATERIAL_SHADER_ID),
         'forgeax::default-standard-pbr-skin',
       );
+      const pbrSkinMaterialEntry = Array.from(registry.materialShaderManifestEntries()).find(
+        (entry) =>
+          entry.identifier === SKIN_MATERIAL_SHADER_ID ||
+          entry.identifier === 'forgeax::default-standard-pbr-skin',
+      );
+      pbrSkinEntry = selectCloudShadowCompatibleEntry(
+        pbrSkinEntry,
+        pbrSkinMaterialEntry,
+        projectorAvailable,
+      );
     }
     unlitEntry = patchRuntimeVariant(unlitEntry, 'forgeax::default-unlit');
     if (shadowCasterEntry !== undefined) {
@@ -693,7 +707,7 @@ export async function buildReadyWebGPU(
       seedShaderModule,
     });
     for (const postProcess of requiredFullscreenPostProcesses) {
-      const label = postProcessShaderModuleLabel(postProcess.identity, postProcess.source);
+      const label = postProcessShaderModuleLabel(postProcess.source);
       const shaderResult = await runShimStep(
         () =>
           asyncCreateShaderModule
@@ -1111,7 +1125,7 @@ export async function buildReadyWebGPU(
     // frames (e.g. the hello-tonemap dawn smoke) would stall on a black frame
     // forever. Mirror the shadow_caster prewarm: await-compile the tonemap module
     // here and `seedShaderModule` it under the exact label
-    // `buildPostProcessPipeline` requests (`post-process-${id}-module`), so the
+    // `buildPostProcessPipeline` requests (keyed by shader source), so the
     // first `getPostProcessPipeline(STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, …)` hits the module cache
     // synchronously and builds the pipeline on frame 1.
     const tonemapPrewarm = await runShimStep(
@@ -1119,27 +1133,18 @@ export async function buildReadyWebGPU(
         asyncCreateShaderModule
           ? asyncCreateShaderModule(rhiDevice, {
               code: tonemapEntry.wgsl,
-              label: postProcessShaderModuleLabel(
-                STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
-                tonemapEntry.wgsl,
-              ),
+              label: postProcessShaderModuleLabel(tonemapEntry.wgsl),
             })
           : invokeDeviceCreateShaderModule(rhiDevice, {
               code: tonemapEntry.wgsl,
-              label: postProcessShaderModuleLabel(
-                STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
-                tonemapEntry.wgsl,
-              ),
+              label: postProcessShaderModuleLabel(tonemapEntry.wgsl),
             }),
       'shader-compile-failed',
       'tonemap shader module compiled (unified post-process prewarm)',
       'inspect manifest tonemap entry composed wgsl; check device.features',
     );
     if (!tonemapPrewarm.ok) throw tonemapPrewarm.error;
-    seedShaderModule(
-      postProcessShaderModuleLabel(STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, tonemapEntry.wgsl),
-      tonemapPrewarm.value,
-    );
+    seedShaderModule(postProcessShaderModuleLabel(tonemapEntry.wgsl), tonemapPrewarm.value);
     registerBuiltinTonemap(tonemapEntry.wgsl);
 
     // Prewarm temporal fullscreen modules before readiness so first-frame
@@ -1309,6 +1314,12 @@ export async function buildReadyWebGPU(
       if (!fxaaShaderResult.ok) throw fxaaShaderResult.error;
       fxaaModule = fxaaShaderResult.value;
       registerBuiltinFxaa(fxaaEntry.wgsl);
+      // The typed graph may need a second FXAA pipeline for a graph-owned
+      // linear-LDR target (for example BarrelDistortion + FXAA). Seed the
+      // shared post-process adapter with the already compiled module so that
+      // this alternate color format is available on the first submitted
+      // frame instead of waiting for an async recompile.
+      seedShaderModule(postProcessShaderModuleLabel(fxaaEntry.wgsl), fxaaModule);
     }
 
     // feat-20260531-skybox-env-background M3 / w15: skybox shader module.
@@ -1428,7 +1439,7 @@ export async function buildReadyWebGPU(
   // instances) and the 4-slot pipeline layout in one call, throwing on each
   // device.createBindGroupLayout / device.createPipelineLayout failure.
   // material BGL now carries 24 entries (canonical material 0..14 + Skylight
-  // 15..21 + transmission 22..23); authored physical maps append after the
+  // 15..20 + transmission 21..22); authored physical maps append after the
   // engine-owned injections. The pipeline layout itself stays at 4 slots, no
   // @group(4) allocated (D-5 round-4 fix for the round-2 maxBindGroups=4
   // BLOCKER). The standalone unlit BGL is the 15-entry user region exposed by
@@ -1479,6 +1490,7 @@ export async function buildReadyWebGPU(
   let hdrpPbrPipelineLayoutHandle: PipelineLayout | null = null;
   let hdrpMeshBindGroupLayoutHandle: BindGroupLayout | null = null;
   let hdrpProbePbrPipelineLayoutHandle: PipelineLayout | null = null;
+  let hdrpUnifiedBglHandle: BindGroupLayout | null = null;
   // The cluster layout is storage-buffer backed. On the WebGL2/fallback
   // capability tier its uniform-buffer projection exceeds the backend's
   // fragment-stage limit, and HDRP is not a valid route there anyway.
@@ -1486,6 +1498,7 @@ export async function buildReadyWebGPU(
     const hdrpUnifiedBglDesc = createHdrpBindGroupLayoutDescriptor();
     const hdrpUnifiedBglRes = rhiDevice.createBindGroupLayout(hdrpUnifiedBglDesc);
     if (hdrpUnifiedBglRes.ok) {
+      hdrpUnifiedBglHandle = hdrpUnifiedBglRes.value;
       hdrpMeshBindGroupLayoutHandle = hdrpUnifiedBglRes.value;
       const hdrpPlRes = rhiDevice.createPipelineLayout({
         label: 'hdrp-pbr-pl',
@@ -1571,6 +1584,7 @@ export async function buildReadyWebGPU(
     gpuDrivenInstancesBindGroupLayout: gpuDrivenInstancesBindGroupLayoutHandle,
     gpuDrivenPbrPipelineLayout: gpuDrivenPbrPipelineLayoutHandle,
     gpuDrivenPbrSkinPipelineLayout: gpuDrivenPbrSkinPipelineLayoutHandle,
+    surfaceDirectInstancesBindGroupLayout: surfaceDirectInstancesBindGroupLayoutHandle,
   } = buildGpuDrivenPbrReadyLayouts(rhiDevice, storageBufferCapable, pbrLayouts.value);
   let hdrpSkinPipelineLayoutHandle: PipelineLayout | null = null;
   let hdrpSkinMeshBindGroupLayoutHandle: BindGroupLayout | null = null;
@@ -1595,6 +1609,46 @@ export async function buildReadyWebGPU(
     }
   }
 
+  // GPU-driven Standard batches use the compact scene-index slot(3) while
+  // retaining the same clustered group(2) bind group that the ordinary main
+  // pass publishes. Build a matching pipeline layout from those exact
+  // producer-owned layouts; a separate URP mesh-array layout would validate
+  // the indirect draw but reject its clustered bind group at encode time.
+  let gpuDrivenClusterPbrPipelineLayoutHandle: PipelineLayout | null = null;
+  let gpuDrivenClusterPbrSkinPipelineLayoutHandle: PipelineLayout | null = null;
+  if (
+    storageBufferCapable &&
+    hdrpUnifiedBglHandle !== null &&
+    gpuDrivenInstancesBindGroupLayoutHandle !== null
+  ) {
+    const rigidResult = rhiDevice.createPipelineLayout({
+      label: 'pbr-gpu-driven-cluster-pl',
+      bindGroupLayouts: [
+        viewBglResult.value,
+        materialBglResult.value,
+        hdrpUnifiedBglHandle,
+        gpuDrivenInstancesBindGroupLayoutHandle,
+      ],
+    });
+    if (rigidResult.ok) gpuDrivenClusterPbrPipelineLayoutHandle = rigidResult.value;
+  }
+  if (
+    storageBufferCapable &&
+    hdrpSkinMeshBindGroupLayoutHandle !== null &&
+    gpuDrivenInstancesBindGroupLayoutHandle !== null
+  ) {
+    const skinResult = rhiDevice.createPipelineLayout({
+      label: 'pbr-skin-gpu-driven-cluster-pl',
+      bindGroupLayouts: [
+        viewBglResult.value,
+        materialBglResult.value,
+        hdrpSkinMeshBindGroupLayoutHandle,
+        gpuDrivenInstancesBindGroupLayoutHandle,
+      ],
+    });
+    if (skinResult.ok) gpuDrivenClusterPbrSkinPipelineLayoutHandle = skinResult.value;
+  }
+
   // feat-20260612-skin-palette-per-frame-upload M1 / m1-2: skin palette
   // allocator. Replaces the prior 16320 B identity-seeded UBO stub (PR #353,
   // feat-20260611 R2 / M8 / w28 IS-14, retired identity-buffer field) with
@@ -1622,9 +1676,7 @@ export async function buildReadyWebGPU(
   const skinPaletteLimitKey = storageBufferCapable
     ? 'maxStorageBufferBindingSize'
     : 'maxUniformBufferBindingSize';
-  const skinPaletteDeviceLimit = (rhiDevice.limits as Readonly<Record<string, number>>)[
-    skinPaletteLimitKey
-  ];
+  const skinPaletteDeviceLimit = rhiDevice.limits[skinPaletteLimitKey];
   const SKIN_PALETTE_MAX_BINDING_BYTES =
     typeof skinPaletteDeviceLimit === 'number' && skinPaletteDeviceLimit > 0
       ? skinPaletteDeviceLimit
@@ -2016,6 +2068,24 @@ export async function buildReadyWebGPU(
   );
   if (!defaultSamplerResult.ok) throw defaultSamplerResult.error;
 
+  // r32float Surface raw-depth views are unfilterable. Keep their sampler
+  // distinct from the filtering material sampler so WebGPU's sample-type
+  // validation remains explicit at the material BGL boundary.
+  const surfaceMediumDepthSamplerResult = runShimSyncStep(
+    () =>
+      rhiDevice.createSampler({
+        label: 'surface-medium-depth-sampler',
+        magFilter: 'nearest',
+        minFilter: 'nearest',
+        addressModeU: 'clamp-to-edge',
+        addressModeV: 'clamp-to-edge',
+      }),
+    'webgpu-runtime-error',
+    'createSampler (single-layer medium raw depth) succeeded',
+    'check device.limits.maxSamplersPerShaderStage',
+  );
+  if (!surfaceMediumDepthSamplerResult.ok) throw surfaceMediumDepthSamplerResult.error;
+
   // feat-20260520-directional-light-shadow-mapping M1c / w8 + M2 / w14:
   // shadow comparison sampler — clamp-to-edge, linear filter, compare:'less'.
   // Used for shadow map sampling in M2/M3 and shadow depth pass. comparison
@@ -3879,6 +3949,18 @@ export async function buildReadyWebGPU(
     gpuDrivenPbrPrograms,
     gpuDrivenPbrSkinPipelineLayout:
       unlitModule !== null && pbrModule !== null ? gpuDrivenPbrSkinPipelineLayoutHandle : null,
+    surfaceDirectInstancesBindGroupLayout:
+      unlitModule !== null && pbrModule !== null
+        ? surfaceDirectInstancesBindGroupLayoutHandle
+        : null,
+    gpuDrivenClusterPbrPipelineLayout:
+      unlitModule !== null && pbrModule !== null ? gpuDrivenClusterPbrPipelineLayoutHandle : null,
+    gpuDrivenClusterPbrSkinPipelineLayout:
+      unlitModule !== null && pbrModule !== null
+        ? gpuDrivenClusterPbrSkinPipelineLayoutHandle
+        : null,
+    gpuDrivenClusterMeshBindGroupLayout:
+      unlitModule !== null && pbrModule !== null ? hdrpUnifiedBglHandle : null,
     // HDRP variant uses the unified group(2) layout built above.
     hdrpPbrPipelineLayout:
       unlitModule !== null && pbrModule !== null ? hdrpPbrPipelineLayoutHandle : null,
@@ -3924,6 +4006,7 @@ export async function buildReadyWebGPU(
     probeInstancesBindGroupLayout: probeInstancesBglResult.value,
     identityInstanceBuffer: identityInstanceResult.value,
     defaultSampler: defaultSamplerResult.value,
+    surfaceMediumDepthSampler: surfaceMediumDepthSamplerResult.value,
     fallbackTextureView: fallbackTextureViewResult.value,
     defaultWhiteTextureView: fallbackTextureViewResult.value,
     // Exactly neutral half-float RG=(0.5,0.5) decodes to tangent (0,0,1).
@@ -3952,44 +4035,15 @@ export async function buildReadyWebGPU(
     // matrices fold into the View UBO tail (`view.spotLightViewProj`); no
     // dedicated buffer / view-BG binding 9 (WebGL2 uniform-buffer budget).
     skylightFallback,
-    // feat-20260529-rendergraph-pass-abstraction M3 / w11 (D-2 + Finding 3):
-    // per-pass mutable resource slots moved to PerPassResources.
-    perPassResources: {
-      depthTexture: null,
-      depthTextureView: null,
-      depthTextureWidth: 0,
-      depthTextureHeight: 0,
-      configured: false,
-      hdrColorTexture: null,
-      hdrColorView: null,
-      hdrDepthTexture: null,
-      hdrDepthView: null,
-      hdrTextureWidth: 0,
-      hdrTextureHeight: 0,
-      hdrDepthSampleCount: 1,
+    perPassResources: createReadyPerPassResources({
       fxaaPipeline: fxaaPipelineHandle,
       fxaaBindGroupLayout: fxaaBglHandle,
       fxaaSampler: fxaaSamplerHandle,
-      // feat-20260604-learn-render-4.10-anti-aliasing-msaa M2 / w7: MSAA
-      // attachment slots. All null/0 until the first antialias='msaa' frame.
-      msaaColorTexture: null,
-      msaaColorView: null,
-      msaaSpriteColorTexture: null,
-      msaaSpriteColorView: null,
-      msaaDepthTexture: null,
-      msaaDepthView: null,
-      msaaTextureWidth: 0,
-      msaaTextureHeight: 0,
-      hdrColorMsaaTexture: null,
-      hdrColorMsaaView: null,
       skyboxPipeline: skyboxPipelineHandle,
       skyboxPipelineMsaa: skyboxPipelineMsaaHandle,
       skyboxBindGroupLayout: skyboxBglHandle,
       skyboxSampler: skyboxSamplerHandle,
       skyboxRotationBuffer: skyboxRotationBufferHandle,
-      shadowTexture: null,
-      shadowMapSize: 0,
-      shadowCascadeCount: 0,
       shadowSampler: shadowSamplerResult.value,
       shadowLightSpaceMatrix: null,
       shadowCsmLightViewProj: null,
@@ -4020,13 +4074,13 @@ export async function buildReadyWebGPU(
       ssaoCalcPipeline: ssaoCalcPipelineHandle,
       ssaoBlurPipeline: ssaoBlurPipelineHandle,
       ssaoBgl: ssaoBglHandle,
-      // M8 / w38: lazy-allocated on first SSAO record frame. Sampler kinds
-      // and the 1x1 ssaoRaw fallback view are constant across frames and
-      // cached after first construction.
-      ssaoFilteringSampler: null,
-      ssaoDepthSampler: null,
-      ssaoFallbackRawView: null,
-    },
+    }),
   };
+  // Boot-time fallback resources submit real GPU work before the renderer is
+  // published. Keep initialization as the readiness barrier for the first
+  // frame: a Worker can otherwise receive `ready`, start its frame deadline,
+  // and report `frame-submitted` while that earlier queue work still holds the
+  // receipt's completion fence.
+  await queue.onSubmittedWorkDone();
   return pipelineState;
 }

package/src/assembly/webgpu-renderer-bootstrap.ts

@@ -53,18 +53,6 @@ export async function tryCreateWebGPURenderer(
     onDeviceLost: (detail) => lossObserver.current?.(detail),
   });
 
-  if (pack._internal_getRawDevice && pack.translateErrorEventToRhiError) {
-    const backendDevice = pack._internal_getRawDevice(device);
-    if (backendDevice && typeof backendDevice === 'object') {
-      const target = backendDevice as {
-        onuncapturederror?: ((event: unknown) => void) | null;
-      };
-      target.onuncapturederror = (event: unknown): void => {
-        const translated = pack.translateErrorEventToRhiError?.(event);
-        if (translated && !translated.ok) errorRegistry.fire(translated.error);
-      };
-    }
-  }
   return {
     kind: 'ok',
     renderer: await createRenderer({

package/src/assembly/webgpu-renderer-observation-owner.ts

@@ -0,0 +1,222 @@
+import type { Buffer } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-rhi';
+import { type RenderError, RendererContractFailureError } from '../errors/render';
+import type { FrameReceipt, RenderResult } from '../render-contract';
+import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
+import { disposeObservationCaptureSet } from './webgpu-renderer-observation';
+
+export type ObservationCaptureRead = () => Promise<
+  RenderResult<
+    readonly {
+      readonly capture: TypedFrameObservationCapture;
+      readonly bytes: Uint8Array;
+    }[],
+    RenderError
+  >
+>;
+
+export interface RendererObservationCaptureOwner {
+  readonly observationCaptureOwner: {
+    register(capture: TypedFrameObservationCapture): void;
+    consume(frameNumber: number): readonly TypedFrameObservationCapture[];
+    drain(): readonly TypedFrameObservationCapture[];
+  };
+  readonly stats: {
+    allocationCount: number;
+    liveCount: number;
+    peakLiveCount: number;
+    mapCount: number;
+    readbackCount: number;
+    liveByteLength: number;
+  };
+  expectedGraphGeneration: number | undefined;
+  readonly receiptObservationCaptures: Map<FrameReceipt, ObservationCaptureRead>;
+  readonly receiptObservationBuffers: Map<FrameReceipt, readonly TypedFrameObservationCapture[]>;
+  readonly destroyedObservationBuffers: WeakSet<Buffer>;
+  readonly observationBufferCleanupFailures: WeakMap<Buffer, RendererContractFailureError>;
+  readonly failedObservationCaptures: Map<Buffer, TypedFrameObservationCapture>;
+  readonly disposeObservationCaptures: (
+    captures: readonly TypedFrameObservationCapture[],
+  ) => RendererContractFailureError | undefined;
+  readonly disposeOwnedObservationCaptures: (
+    captures: readonly TypedFrameObservationCapture[],
+  ) => RendererContractFailureError | undefined;
+  readonly readObservationCapture: (
+    capture: TypedFrameObservationCapture,
+  ) => Promise<RenderResult<Uint8Array, RenderError>>;
+  readonly disposeReceiptObservationCaptures: () => RendererContractFailureError | undefined;
+}
+
+export function createRendererObservationCaptureOwner(
+  fireError: (error: RendererContractFailureError) => void,
+): RendererObservationCaptureOwner {
+  const stats = {
+    allocationCount: 0,
+    liveCount: 0,
+    peakLiveCount: 0,
+    mapCount: 0,
+    readbackCount: 0,
+    liveByteLength: 0,
+  };
+  const capturesByFrame = new Map<number, TypedFrameObservationCapture[]>();
+  const observationCaptureOwner = {
+    register(capture: TypedFrameObservationCapture): void {
+      const captures = capturesByFrame.get(capture.frameNumber) ?? [];
+      captures.push(capture);
+      capturesByFrame.set(capture.frameNumber, captures);
+      stats.allocationCount += 1;
+      stats.liveCount += 1;
+      stats.peakLiveCount = Math.max(stats.peakLiveCount, stats.liveCount);
+      stats.liveByteLength += 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 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,
+      fireError,
+    );
+    for (const capture of captures) {
+      if (!wasDestroyed.has(capture.buffer) && destroyedObservationBuffers.has(capture.buffer)) {
+        stats.liveCount = Math.max(0, stats.liveCount - 1);
+        stats.liveByteLength = Math.max(
+          0,
+          stats.liveByteLength - 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`,
+            ),
+        );
+      }
+      stats.mapCount += 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();
+      stats.readbackCount += 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 receiptObservationCaptures = new Map<FrameReceipt, ObservationCaptureRead>();
+  const receiptObservationBuffers = new Map<
+    FrameReceipt,
+    readonly TypedFrameObservationCapture[]
+  >();
+  const owner: RendererObservationCaptureOwner = {
+    observationCaptureOwner,
+    stats,
+    expectedGraphGeneration: undefined,
+    receiptObservationCaptures,
+    receiptObservationBuffers,
+    destroyedObservationBuffers,
+    observationBufferCleanupFailures,
+    failedObservationCaptures,
+    disposeObservationCaptures,
+    disposeOwnedObservationCaptures,
+    readObservationCapture,
+    disposeReceiptObservationCaptures: () => {
+      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;
+    },
+  };
+  return owner;
+}