@forgeax/engine-render 0.1.33 → 0.1.34

package/src/record/main-pass-geometry.ts

@@ -43,11 +43,9 @@ import type { PointsLinesRecordPlan } from '../points-lines/record';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { RenderRecordPhase } from '../render-contract';
 import type { DispatchEntry, MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
-import {
-  PROBE_BLEND_RECORD_BYTE_SIZE,
-  PROBE_BLEND_RECORD_STRIDE,
-  probeBlendRecordOffset,
-} from '../scene/probe-blend-record';
+import { PROBE_BLEND_RECORD_BYTE_SIZE, probeBlendRecordOffset } from '../scene/probe-blend-record';
+import type { SurfacePassName } from '../surface/submission-observation';
+import { resolveFoldInstanceBuffer } from './fold-instance-buffer';
 import {
   getOpaqueResourceIdentity,
   instanceCollectionCacheKey,
@@ -69,6 +67,7 @@ import {
   MESH_UBO_FULL_ARRAY_BYTES,
   packInstanceStorageBuffer,
 } from './mesh-ssbo';
+import { ensureProbeBlendRecordBuffer } from './probe-blend-buffer';
 import type { _InternalRenderPipelineContext, MaterialShaderPipelineEntry } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 import { POINTS_LINES_VIEW_SLOT_STRIDE, writePointsLinesViewUbo } from './view-ubo';
@@ -93,11 +92,19 @@ export function sameOpaqueTemporalDraw(a: DispatchEntry, b: DispatchEntry): bool
 type GeometryInstanceDraw = {
   readonly instanceBuffer: Buffer;
   readonly instanceBindGroup: BindGroup;
+  /** Producer-owned Probe buffer paired with probeOffset, when present. */
+  readonly probeBuffer?: Buffer;
   /** -1 means the no-probe layout and therefore no dynamic offset. */
   readonly probeOffset: number;
+  readonly dynamicOffsets?: readonly number[];
   readonly instanceCount: number;
+  readonly firstInstanceOrdinal?: number;
+  readonly surfaceFrameBase?: number;
+  readonly surfaceMemberIds?: readonly string[];
 };
 
+type DirectSurfaceLayoutKind = 'surface-direct-pbr' | 'surface-direct-cluster-pbr';
+
 type InstanceUploadResult =
   | {
       readonly ok: true;
@@ -113,6 +120,7 @@ type InstanceUploadResult =
 type GeometryBindingState = {
   pipeline: RenderPipeline | null;
   instancesBuffer: Buffer | null;
+  instanceBindGroup: BindGroup | null;
   probeOffset: number;
 };
 
@@ -143,6 +151,7 @@ type MaterialPipelineLookup = {
   readonly colorFormatOverride: GPUTextureFormat | undefined;
   readonly additionalColorFormats: readonly GPUTextureFormat[] | undefined;
   readonly textureMask: number | undefined;
+  readonly layoutKind: DirectSurfaceLayoutKind | undefined;
   readonly handle: MaterialShaderPipelineEntry | null;
 };
 
@@ -219,10 +228,11 @@ function isGpuDrivenMainClaimedSubmesh(
   if (drawItemIndex === undefined || draw === undefined) return false;
   const material = source.materials[draw.materialSlot] ?? source.material;
   const sourceDrawItemIndex = gpuDrivenSourceDrawItemIndex(draw, drawItemIndex);
+  const stableWorld = c.gpuDrivenWorldKeys?.[source.worldId] ?? source.worldId;
   return (
     c.gpuDrivenDrawKeys?.has(
       gpuDrivenDrawKey(
-        worldEntityKey(source.worldId, source.entityKey),
+        worldEntityKey(stableWorld, source.entityKey),
         material.materialHandle ?? -1,
         sourceDrawItemIndex,
       ),
@@ -365,6 +375,22 @@ export function geometryRenderStateForPass(
   };
 }
 
+/**
+ * Transparent depth is an authored medium policy. A transparent pass with no
+ * explicit depth-write bit remains read-only, which keeps alpha smoke and
+ * ordinary blending from becoming an opaque occluder; water or a cutout-like
+ * medium can opt in by setting the bit on its own pass state.
+ */
+export function authoredTransparentDepthWrite(
+  transparent: boolean | undefined,
+  renderState: MaterialSnapshot['renderState'],
+): boolean {
+  return (
+    (transparent === true || renderState?.blend !== undefined) &&
+    renderState?.depthWriteEnabled === true
+  );
+}
+
 function geometryRecordPhase(
   passKind: PassKind,
   segment: GeometryRecordProfileSegment,
@@ -394,7 +420,7 @@ function submitSubmeshDraws(
   indexCount: number,
   vertexCount: number,
   indexOffset: number,
-  onDraw?: () => void,
+  onDraw?: (draw: GeometryInstanceDraw, command: 'draw' | 'draw-indexed') => void,
 ): void {
   if (state.pipeline !== pipeline) {
     pass.setPipeline(pipeline);
@@ -403,14 +429,18 @@ function submitSubmeshDraws(
   for (const instanceDraw of instanceDraws) {
     if (
       instanceDraw.instanceBuffer !== state.instancesBuffer ||
+      instanceDraw.instanceBindGroup !== state.instanceBindGroup ||
       instanceDraw.probeOffset !== state.probeOffset
     ) {
-      if (instanceDraw.probeOffset < 0) {
+      if (instanceDraw.dynamicOffsets !== undefined) {
+        pass.setBindGroup(3, instanceDraw.instanceBindGroup, instanceDraw.dynamicOffsets);
+      } else if (instanceDraw.probeOffset < 0) {
         pass.setBindGroup(3, instanceDraw.instanceBindGroup);
       } else {
         pass.setBindGroup(3, instanceDraw.instanceBindGroup, [instanceDraw.probeOffset]);
       }
       state.instancesBuffer = instanceDraw.instanceBuffer;
+      state.instanceBindGroup = instanceDraw.instanceBindGroup;
       state.probeOffset = instanceDraw.probeOffset;
     }
     if (indexed) {
@@ -418,7 +448,7 @@ function submitSubmeshDraws(
     } else {
       pass.draw(vertexCount, instanceDraw.instanceCount, 0, 0);
     }
-    onDraw?.();
+    onDraw?.(instanceDraw, indexed ? 'draw-indexed' : 'draw');
   }
 }
 
@@ -472,6 +502,9 @@ export function recordGeometryDraws(
   selectedDispatch?: readonly DispatchEntry[],
   colorFormats: readonly GPUTextureFormat[] = [],
   coverageOnly = false,
+  fragmentEntryPoint?: string,
+  surfacePass?: SurfacePassName,
+  transparentDepthWrite = false,
 ): void {
   const {
     runtime,
@@ -520,6 +553,7 @@ export function recordGeometryDraws(
   const bindingState: GeometryBindingState = {
     pipeline: null,
     instancesBuffer: null,
+    instanceBindGroup: null,
     probeOffset: -1,
   };
   const identityInstanceBuffer = pipelineState.identityInstanceBuffer;
@@ -563,6 +597,7 @@ export function recordGeometryDraws(
     vertexEntry?: string,
     fragmentEntry?: string,
     textureMask?: number,
+    layoutKind?: DirectSurfaceLayoutKind,
   ): MaterialShaderPipelineEntry | null => {
     const pipelineVariantSet = withCoverageVariant(variantSet);
     // The fallback MRT is an extension of the built-in Standard PBR output
@@ -594,6 +629,7 @@ export function recordGeometryDraws(
           cached.vertexEntry === vertexEntry &&
           cached.fragmentEntry === fragmentEntry &&
           cached.textureMask === textureMask &&
+          cached.layoutKind === layoutKind &&
           cached.passKind === passKind &&
           cached.layoutProjection.digest === layoutProjection.digest &&
           cached.sampleCount === sampleCount &&
@@ -604,8 +640,13 @@ export function recordGeometryDraws(
         }
       }
     }
+    // Published Surface artifacts carry both direct and scene-index modules.
+    // The boot artifact may be the scene-index specialization selected by the
+    // retained producer, so a direct slot-3 layout must still resolve the
+    // explicit capability key. This keeps the module source, entry point and
+    // pipeline layout on the same GPU_DRIVEN_SCENE_INDEX_AVAILABLE=false ABI.
     const resolvedVariantSetResult =
-      runtime.getMaterialArtifact?.(materialShaderId) !== undefined
+      runtime.getMaterialArtifact?.(materialShaderId) !== undefined && layoutKind === undefined
         ? ({ ok: true, value: undefined } as const)
         : pipelineVariantSet === undefined &&
             (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
@@ -639,7 +680,7 @@ export function recordGeometryDraws(
         undefined,
         layoutProjection,
         undefined,
-        undefined,
+        layoutKind,
         undefined,
         reflectionFallbackFormats,
         vertexEntry,
@@ -674,6 +715,7 @@ export function recordGeometryDraws(
         colorFormatOverride: colorFormat,
         additionalColorFormats: reflectionFallbackFormats,
         textureMask,
+        layoutKind,
         handle,
       };
       if (shaderLookupCache === undefined) {
@@ -693,6 +735,9 @@ export function recordGeometryDraws(
   for (let i = 0; i < validatedOrdered.length; i++) {
     const entry = validatedOrdered[i];
     if (entry === undefined) continue;
+    // The typed transparent pass uses this common draw owner. Consume the
+    // same fold plan as the legacy sprite pass, including coverage/depth draws.
+    if (c.foldDispatchPlan?.skipIndices.has(i) === true) continue;
     // Points/Lines share the Standard geometry pass. Their retained source
     // is prepared once by the renderer owner, while this loop remains the
     // sole pass/draw submission owner and preserves the authored topology.
@@ -822,8 +867,22 @@ export function recordGeometryDraws(
     // length instead.
     if (pipelineTag === 'unlit') dispatchCounts.unlit += 1;
 
-    const instanceDraws = resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, false);
-    if (instanceDraws === null) continue;
+    const fold = c.foldDispatchPlan?.headBuckets.get(i);
+    const foldBuffer = fold === undefined ? null : resolveFoldInstanceBuffer(c, fold, i);
+    const baseInstanceDraws =
+      fold === undefined
+        ? resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, false)
+        : foldBuffer === null
+          ? null
+          : [
+              {
+                instanceBuffer: foldBuffer,
+                instanceBindGroup: resolveGeometryInstancesBindGroup(c, foldBuffer, undefined),
+                probeOffset: -1,
+                instanceCount: fold.bucketSize,
+              },
+            ];
+    if (baseInstanceDraws === null) continue;
 
     // feat-20260611 R2 / M8 / w28 (IS-14): skin entries need a 3-binding
     // group(2) BG matching `pbr-skin-pl` (binding 0 mesh-array UBO +
@@ -1114,16 +1173,22 @@ export function recordGeometryDraws(
       ) {
         continue;
       }
+      const selectedMaterialPasses = materialPasses
+        .get(entry.renderableIndex)
+        ?.get(submeshMaterial.materialHandle ?? 0);
       const draws: readonly (DispatchEntry | undefined)[] =
-        selectedDispatch === undefined
+        selectedDispatch === undefined ||
+        (selectedMaterialPasses === undefined &&
+          submeshMaterial.surfaceModel === 'single-layer-medium' &&
+          matchedMaterials?.get(entry.renderableIndex)?.has(submeshMaterial.materialHandle ?? 0))
           ? [undefined]
-          : (materialPasses.get(entry.renderableIndex)?.get(submeshMaterial.materialHandle ?? 0) ??
-            []);
+          : (selectedMaterialPasses ?? []);
       for (const selectedPass of draws) {
         // Temporal projects the selected material's alpha/motion contract,
         // not its authored Forward entry points or color outputs.
         const vertexEntry = passKind === 'temporal' ? undefined : selectedPass?.vertexEntry;
-        const fragmentEntry = passKind === 'temporal' ? undefined : selectedPass?.fragmentEntry;
+        const fragmentEntry =
+          passKind === 'temporal' ? undefined : (fragmentEntryPoint ?? selectedPass?.fragmentEntry);
         const selectedShaderId =
           selectedPass === undefined
             ? submeshMaterial.materialShaderId
@@ -1228,7 +1293,9 @@ export function recordGeometryDraws(
                 : SKIN_MATERIAL_SHADER_ID
               : submeshMaterial.materialShaderId;
         const probeBlendAvailable =
-          probeBlendRecordAvailable && isStandardPbrMaterialShader(smMaterialShaderId);
+          probeBlendRecordAvailable &&
+          (isStandardPbrMaterialShader(smMaterialShaderId) ||
+            submeshMaterial.surfaceModel === 'single-layer-medium');
         const isSpriteShader =
           smMaterialShaderId === 'forgeax::sprite' || smMaterialShaderId === 'forgeax::sprite-lit';
         // Preserve the dedicated sprite-pass state when the linear-LDR graph
@@ -1243,11 +1310,25 @@ export function recordGeometryDraws(
               blend: selectedRenderState?.blend ?? SPRITE_PREMULTIPLIED_ALPHA_BLEND,
             }
           : geometryRenderStateForTopology(smTopology, selectedRenderState);
-        const pipelineRenderState = geometryRenderStateForPass(
+        let pipelineRenderState = geometryRenderStateForPass(
           basePipelineRenderState,
           passKind,
           coverageOnly,
         );
+        if (
+          transparentDepthWrite &&
+          passKind === 'forward' &&
+          (submeshMaterial.transparent === true || selectedRenderState?.blend !== undefined)
+        ) {
+          pipelineRenderState = {
+            ...pipelineRenderState,
+            depthWriteEnabled: authoredTransparentDepthWrite(
+              submeshMaterial.transparent,
+              selectedRenderState,
+            ),
+            depthCompare: 'less-equal',
+          };
+        }
         let smPipelineHandle: typeof pipelineState.unlitPipeline;
         let materialGroup2Contract: 'mesh' | 'skin' | 'cluster' | 'skin-cluster' | undefined;
         let materialPipelineEntry: MaterialShaderPipelineEntry | null = null;
@@ -1319,15 +1400,17 @@ export function recordGeometryDraws(
             transmissionAvailable && !capabilityVariantSet.includes('TRANSMISSION_AVAILABLE=')
               ? `${capabilityVariantSet}+TRANSMISSION_AVAILABLE=true`
               : capabilityVariantSet;
-          // Sprite's base request must retain the boot-selected artifact. Only
-          // SpriteInstances uses the explicit empty key for the
-          // PER_INSTANCE_REGION=true variant; synthesizing the generic PBR
-          // capability axes for a base sprite would invent a lazy module label
-          // that has no boot seed and skip the first HDR draw.
+          // Regular sprite keeps the boot-selected artifact; SpriteInstances
+          // uses the explicit empty key for PER_INSTANCE_REGION=true. Sprite-lit
+          // is different: the typed Standard transparent lane records it here,
+          // so its shader must follow the frame-owned cluster topology or local
+          // lights disappear while the ordinary sprite path remains direct.
           const variantSet = isSpriteShader
-            ? smMaterialShaderId === 'forgeax::sprite' && entry.source.spriteInstances !== undefined
-              ? ''
-              : undefined
+            ? smMaterialShaderId === 'forgeax::sprite-lit'
+              ? materialCapabilityVariantSet
+              : entry.source.spriteInstances !== undefined
+                ? ''
+                : undefined
             : entry.variantSet === undefined
               ? materialCapabilityVariantSet
               : `${materialCapabilityVariantSet}+${entry.variantSet}`;
@@ -1342,6 +1425,11 @@ export function recordGeometryDraws(
             vertexEntry,
             fragmentEntry,
             submeshMaterial.standardTextureMask,
+            submeshMaterial.surfaceModel === 'single-layer-medium' && passKind === 'forward'
+              ? capabilityVariantSet.includes('CLUSTER_FORWARD_AVAILABLE=true')
+                ? 'surface-direct-cluster-pbr'
+                : 'surface-direct-pbr'
+              : undefined,
           );
           // feat-20260615-pipeline-spec-ssot M6-T1: cache miss resolves to
           // null uniformly across URP / HDRP / skin shaders. Charter P3
@@ -1380,12 +1468,28 @@ export function recordGeometryDraws(
         // renderable, but unlit/custom shaders still use the one-binding
         // instances BGL and must never receive the probe bind group. Resolve
         // this per submesh so mixed-material meshes cannot cross the layouts.
-        const instanceDraws = resolveGeometryInstanceBuffer(
-          c,
-          entry,
-          identityInstanceDraws,
-          probeBlendAvailable,
-        );
+        const resolvedInstanceDraws = probeBlendAvailable
+          ? resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, true)
+          : baseInstanceDraws;
+        if (resolvedInstanceDraws === null) continue;
+        const compactDrawIndex = gpuDrivenDrawIndices.get(smIdx);
+        const compactDraw =
+          compactDrawIndex === undefined
+            ? undefined
+            : entry.source.gpuDrivenDraws?.[compactDrawIndex];
+        const sourceDrawItemIndex =
+          compactDrawIndex === undefined || compactDraw === undefined
+            ? smIdx
+            : gpuDrivenSourceDrawItemIndex(compactDraw, compactDrawIndex);
+        const instanceDraws =
+          submeshMaterial.surfaceModel === 'single-layer-medium' && passKind === 'forward'
+            ? resolveSurfaceDirectInstanceDraws(
+                c,
+                entry,
+                sourceDrawItemIndex,
+                resolvedInstanceDraws,
+              )
+            : resolvedInstanceDraws;
         if (instanceDraws === null) continue;
         // Standard clustered PBR variants declare the unified cluster/SSAO
         // group(2) layout. Unlit and other URP-layout materials must bind the
@@ -1441,7 +1545,26 @@ export function recordGeometryDraws(
               sm.indexCount,
               sm.vertexCount,
               sm.indexOffset,
-              () => c.onRenderableDraw?.(entry),
+              (draw, command) => {
+                c.onRenderableDraw?.(entry, smIdx);
+                if (surfacePass === undefined || draw.surfaceFrameBase === undefined) return;
+                c.frameState.surfaceSubmissionObservation?.record(surfacePass, {
+                  kind: command,
+                  count: entry.mesh.indexed ? sm.indexCount : sm.vertexCount,
+                  first: entry.mesh.indexed ? sm.indexOffset : 0,
+                  instanceCount: draw.instanceCount,
+                  firstInstance: 0,
+                  surfaceFrameBase: draw.surfaceFrameBase,
+                  memberIds: draw.surfaceMemberIds ?? [],
+                  pipelineIdentity: getOpaqueResourceIdentity(smPipelineHandle as object),
+                  ...(materialPipelineEntry?.receipt === undefined
+                    ? {}
+                    : {
+                        receiptIdentity: materialPipelineEntry.receipt.identity,
+                        receiptGeneration: materialPipelineEntry.receipt.generation,
+                      }),
+                });
+              },
             ),
           );
         } else {
@@ -1456,7 +1579,26 @@ export function recordGeometryDraws(
                 sm.indexCount,
                 sm.vertexCount,
                 sm.indexOffset,
-                () => c.onRenderableDraw?.(entry),
+                (draw, command) => {
+                  c.onRenderableDraw?.(entry, smIdx);
+                  if (surfacePass === undefined || draw.surfaceFrameBase === undefined) return;
+                  c.frameState.surfaceSubmissionObservation?.record(surfacePass, {
+                    kind: command,
+                    count: entry.mesh.indexed ? sm.indexCount : sm.vertexCount,
+                    first: entry.mesh.indexed ? sm.indexOffset : 0,
+                    instanceCount: draw.instanceCount,
+                    firstInstance: 0,
+                    surfaceFrameBase: draw.surfaceFrameBase,
+                    memberIds: draw.surfaceMemberIds ?? [],
+                    pipelineIdentity: getOpaqueResourceIdentity(smPipelineHandle as object),
+                    ...(materialPipelineEntry?.receipt === undefined
+                      ? {}
+                      : {
+                          receiptIdentity: materialPipelineEntry.receipt.identity,
+                          receiptGeneration: materialPipelineEntry.receipt.generation,
+                        }),
+                  });
+                },
               ),
             ),
           );
@@ -1475,7 +1617,7 @@ export function recordGeometryDraws(
  * @internal
  */
 function uploadInstanceRanges(
-  c: _InternalRenderPipelineContext,
+  c: InstanceBufferContext,
   inst: NonNullable<RenderableSnapshot['instances']>,
   buffer: Buffer,
   ranges: readonly { readonly start: number; readonly end: number }[],
@@ -1532,7 +1674,7 @@ function uploadInstanceRanges(
 }
 
 export function reportInstanceResidency(
-  c: _InternalRenderPipelineContext,
+  c: InstanceBufferContext,
   inst: NonNullable<RenderableSnapshot['instances']>,
   input: {
     readonly lane: 'direct-storage' | 'chunked-storage' | 'direct-uniform' | 'chunked-uniform';
@@ -1557,7 +1699,7 @@ export function reportInstanceResidency(
 }
 
 function reportInstanceFailure(
-  c: _InternalRenderPipelineContext,
+  c: InstanceBufferContext,
   inst: NonNullable<RenderableSnapshot['instances']>,
   error: {
     readonly code: InstanceCollectionFailureCode;
@@ -1584,7 +1726,7 @@ function reportInstanceFailure(
   });
 }
 
-function clearInstanceChunksForOwner(c: _InternalRenderPipelineContext, ownerKey: number): void {
+function clearInstanceChunksForOwner(c: InstanceBufferContext, ownerKey: number): void {
   const chunks = c.frameState.instanceBufferChunks;
   if (chunks === undefined) return;
   const prefix = `${ownerKey}:`;
@@ -1599,7 +1741,7 @@ function clearInstanceChunksForOwner(c: _InternalRenderPipelineContext, ownerKey
 }
 
 export function resolveStorageInstanceChunks(
-  c: _InternalRenderPipelineContext,
+  c: InstanceBufferContext,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
   inst: NonNullable<RenderableSnapshot['instances']>,
   cap: number,
@@ -1734,8 +1876,10 @@ export function resolveStorageInstanceChunks(
         activeBuffer.buffer.handle,
         probeBuffer,
       ),
+      ...(probeBuffer === undefined ? {} : { probeBuffer }),
       probeOffset,
       instanceCount: count,
+      firstInstanceOrdinal: start,
     });
   }
   if (chunks !== undefined) {
@@ -1759,8 +1903,13 @@ export function resolveStorageInstanceChunks(
   return draws;
 }
 
-function resolveGeometryInstanceBuffer(
-  c: _InternalRenderPipelineContext,
+type InstanceBufferContext = Pick<
+  _InternalRenderPipelineContext,
+  'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+>;
+
+export function resolveGeometryInstanceBuffer(
+  c: InstanceBufferContext,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
   identityInstanceDraws: readonly GeometryInstanceDraw[],
   useProbeBlend: boolean,
@@ -1788,6 +1937,7 @@ function resolveGeometryInstanceBuffer(
           pipelineState.identityInstanceBuffer,
           probeBinding?.buffer,
         ),
+        ...(probeBinding?.buffer === undefined ? {} : { probeBuffer: probeBinding.buffer }),
         probeOffset: probeBinding?.offset ?? -1,
       },
     ];
@@ -1918,8 +2068,10 @@ function resolveGeometryInstanceBuffer(
             active.buffer.handle,
             probeBinding?.buffer,
           ),
+          ...(probeBinding?.buffer === undefined ? {} : { probeBuffer: probeBinding.buffer }),
           probeOffset: probeBinding?.offset ?? -1,
           instanceCount: count,
+          firstInstanceOrdinal: start,
         });
       }
       if (chunks !== undefined) {
@@ -1988,6 +2140,7 @@ function resolveGeometryInstanceBuffer(
           if (!bufRes.ok) {
             runtime.errorRegistry.fire(bufRes.error);
             reportInstanceFailure(c, inst, bufRes.error, requestedBytes, cap);
+            return null;
           } else {
             // feat-20260619 M4 / F12: destroy the old cached buffer
             // before replacing it with the new one (D-6).
@@ -2078,62 +2231,78 @@ function resolveGeometryInstanceBuffer(
     {
       instanceBuffer,
       instanceBindGroup: resolveGeometryInstancesBindGroup(c, instanceBuffer, probeBinding?.buffer),
+      ...(probeBinding?.buffer === undefined ? {} : { probeBuffer: probeBinding.buffer }),
       probeOffset: probeBinding?.offset ?? -1,
       instanceCount,
     },
   ];
 }
 
-export function resolveProbeBlendBuffer(
+function resolveSurfaceDirectInstanceDraws(
   c: _InternalRenderPipelineContext,
+  entry: _InternalRenderPipelineContext['validatedOrdered'][number],
+  drawItemIndex: number,
+  draws: readonly GeometryInstanceDraw[],
+): readonly GeometryInstanceDraw[] | null {
+  const resolve = c.gpuDrivenStandardPbrFrameResources?.surfaceDirectInstances;
+  if (resolve === undefined) {
+    c.runtime.errorRegistry.fire(
+      new RhiError({
+        code: 'rhi-not-available',
+        expected: 'the prepared Surface producer publishes the direct slot-3 resource closure',
+        hint: 'prepare the retained Surface frame before recording direct medium draws',
+      }),
+    );
+    return null;
+  }
+  const resolved: GeometryInstanceDraw[] = [];
+  for (const draw of draws) {
+    const direct = resolve({
+      worldId: entry.source.worldId,
+      entityKey: entry.source.entityKey,
+      drawItemIndex,
+      instanceCount: draw.instanceCount,
+      firstInstanceOrdinal: draw.firstInstanceOrdinal ?? 0,
+      instanceBuffer: draw.instanceBuffer,
+      ...(draw.probeBuffer === undefined ? {} : { probeBuffer: draw.probeBuffer }),
+      ...(draw.probeOffset < 0
+        ? {}
+        : {
+            probeOffset: draw.probeOffset,
+          }),
+    });
+    if (!direct.ok) {
+      c.runtime.errorRegistry.fire(direct.error);
+      return null;
+    }
+    resolved.push({
+      ...draw,
+      instanceBindGroup: direct.value.bindGroup,
+      dynamicOffsets: direct.value.dynamicOffsets,
+      surfaceFrameBase: direct.value.frameBase,
+      surfaceMemberIds: direct.value.memberIds,
+    });
+  }
+  return resolved;
+}
+
+export function resolveProbeBlendBuffer(
+  c: InstanceBufferContext,
   record: import('../scene/probe-blend-record').ProbeBlendRecord | undefined,
   entityKey?: number,
 ): { readonly buffer: Buffer; readonly offset: number } {
   const { runtime, frameState } = c;
-  const usage = runtime.device.caps.storageBuffer
-    ? GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST
-    : GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST;
   if (record === undefined) throw new Error('probe blend record is required for probe allocation');
   if (entityKey === undefined) throw new Error('probe blend record requires an entity key');
-  const offset = probeBlendRecordOffset(record.objectKey);
-  const requiredCapacity = record.objectKey + 2;
-  let buffer = frameState.probeBlendRecordBuffer;
-  if (buffer === undefined || frameState.probeBlendRecordBufferCapacity < requiredCapacity) {
-    const created = runtime.device.createBuffer({
-      label: 'probe-blend-records',
-      size: requiredCapacity * PROBE_BLEND_RECORD_STRIDE,
-      usage,
-      mappedAtCreation: false,
-    });
-    if (!created.ok) throw created.error;
-    buffer = new GpuBuffer(runtime.device, created.value);
-    frameState.probeBlendRecordBuffer = buffer;
-    frameState.probeBlendRecordBufferCapacity = requiredCapacity;
-    // The cache is tied to the previous backing allocation. A new buffer has
-    // no valid record contents, so every later object must upload its full
-    // 160B payload even when generation/bytes match the old allocation.
-    frameState.probeBlendBuffers.clear();
-  }
-  const cached = frameState.probeBlendBuffers.get(entityKey);
-  const unchanged =
-    cached !== undefined &&
-    cached.generation === record.generation &&
-    cached.bytes.length === record.bytes.length &&
-    cached.bytes.every((value, index) => value === record.bytes[index]);
-  if (!unchanged) {
-    const uploaded = runtime.device.queue.writeBuffer(buffer.handle, offset, record.bytes);
-    if (!uploaded.ok) throw uploaded.error;
-    // Publish the generation only after the complete 160B queue write succeeds.
-    frameState.probeBlendBuffers.set(entityKey, {
-      generation: record.generation,
-      bytes: new Uint8Array(record.bytes),
-    });
-  }
-  return { buffer: buffer.handle, offset };
+  const buffer = ensureProbeBlendRecordBuffer(runtime.device, frameState, [
+    { cacheKey: entityKey, record },
+  ]);
+  if (buffer === undefined) throw new Error('probe blend record buffer allocation failed');
+  return { buffer, offset: probeBlendRecordOffset(record.objectKey) };
 }
 
 export function resolveGeometryInstancesBindGroup(
-  c: _InternalRenderPipelineContext,
+  c: InstanceBufferContext,
   instanceBuffer: Buffer,
   probeBuffer?: Buffer,
 ): BindGroup {