@forgeax/engine-render 0.1.33 → 0.1.35

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

@@ -1,14 +1,16 @@
 import { transmissionBackdropAvailable } from '../assembly/device-feature-admission';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { _InternalRenderPipelineContext } from './render-context';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass-material.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { EntityHandle } from '@forgeax/engine-ecs';
 import {
-  VIDEO_ELEMENT_PROVIDER_KEY,
-  type VideoElementProvider,
+  VIDEO_SOURCE_PROVIDER_KEY,
+  type VideoSourceProvider,
+  videoSourceExtent,
 } from '@forgeax/engine-graphics-extras';
 import {
   type BindGroup,
@@ -42,6 +44,7 @@ import { VideoUploadUnsupportedError } from '../errors/render';
 import {
   assembleMaterialWithSkylightEntries,
   type SkylightBindGroupResources,
+  type SurfaceMediumBindGroupResources,
   type TextureInjectionResource,
   type TransmissionBindGroupResources,
 } from '../ibl/skylight-bind-group';
@@ -260,11 +263,11 @@ function materialDiagnosticsEnabled(): boolean {
 }
 
 export function residentTextureView(
-  world: World,
+  world: RenderResourceScope,
   store: GpuResidencyCache,
   runtime: RenderSystemRuntime,
   handle: Handle<'TextureAsset', 'shared'>,
-  worldId: World | number = world,
+  worldId: RenderResourceScope | number = world,
 ): TextureView | undefined {
   const podRes = resolveAssetHandle<TextureAsset>(world, handle);
   const diagnosticsEnabled = materialDiagnosticsEnabled();
@@ -322,11 +325,11 @@ export function residentTextureView(
 }
 
 function residentSampler(
-  world: World,
+  world: RenderResourceScope,
   store: GpuResidencyCache,
   runtime: RenderSystemRuntime,
   handle: Handle<'SamplerAsset', 'shared'>,
-  worldId: World | number = world,
+  worldId: RenderResourceScope | number = world,
 ): Sampler | undefined {
   const podRes = resolveAssetHandle<SamplerAsset>(world, handle);
   if (!podRes.ok) return undefined;
@@ -343,7 +346,7 @@ function residentSampler(
 // transient DynamicTextureStore, NOT the static `residentTextureView` /
 // `ensureResident` cache (video never enters that switch; AC-08).
 //
-// Per frame: ask the host-registered VideoElementProvider (World Resource,
+// Per frame: ask the host-registered VideoSourceProvider (RenderResourceScope Resource,
 // D-1) for this entity's HTMLVideoElement, upload its current frame via
 // `store.uploadFrame` (copyExternalImageToTexture), and return the resulting
 // view. When the provider is absent / returns no element / the element has no
@@ -403,7 +406,7 @@ function clearVideoUploadFailureEpisode(
 }
 
 export function videoTextureView(
-  world: World,
+  world: RenderResourceScope,
   store: DynamicTextureStore | undefined,
   runtime: RenderSystemRuntime,
   entityKey: number,
@@ -411,10 +414,14 @@ export function videoTextureView(
   highPerfAvailable: boolean,
 ): TextureView | undefined {
   if (store === undefined) return undefined;
-  const provider = world.hasResource(VIDEO_ELEMENT_PROVIDER_KEY)
-    ? world.getResource<VideoElementProvider>(VIDEO_ELEMENT_PROVIDER_KEY)
-    : undefined;
-  const element = provider?.getElement(entityKey as EntityHandle, clip);
+  const provider =
+    !('resolveAsset' in world) && world.hasResource(VIDEO_SOURCE_PROVIDER_KEY)
+      ? world.getResource<VideoSourceProvider>(VIDEO_SOURCE_PROVIDER_KEY)
+      : undefined;
+  const element =
+    'resolveAsset' in world
+      ? world.videoFrame(entityKey, clip)
+      : provider?.getSource(entityKey as EntityHandle, clip);
   // AC-10 double-miss: a VideoPlayer entity can reach NEITHER upload path this
   // frame — no host HTMLVideoElement (general copyExternalImageToTexture path)
   // AND no high-perf GPUExternalTexture path. This is the genuine "this backend
@@ -440,13 +447,9 @@ export function videoTextureView(
     clearVideoUploadFailureEpisode(store, entityKey, clip);
     return store.getView(clip);
   }
-  const width = element.videoWidth;
-  const height = element.videoHeight;
-  // Metadata dimensions can be non-zero before the decoder has produced a
-  // current frame. WebGPU rejects copyExternalImageToTexture in that window
-  // because the video element has no back resource yet; keep the previous
-  // frame/default view until HAVE_CURRENT_DATA (2) is reached.
-  if (width <= 0 || height <= 0 || element.readyState < 2) return store.getView(clip);
+  const extent = videoSourceExtent(element);
+  if (extent === undefined) return store.getView(clip);
+  const { width, height } = extent;
   const uploaded = store.uploadFrame(clip, element, width, height);
   if (uploaded === undefined) return store.getView(clip);
   if (!uploaded.ok) {
@@ -591,7 +594,7 @@ function writeNumericParamValue(
 export function applyMaterialTextureUvScales(
   payload: MaterialUboPayload,
   material: MaterialSnapshot,
-  world: World,
+  world: RenderResourceScope,
 ): void {
   const f32 = materialUboFloatView(payload);
   const coordinateSchema = materialCoordinateSchema(material);
@@ -939,14 +942,14 @@ export function applyParamSchemaDefaultsToUbo(
 export interface PerSubmeshMaterialBgDeps {
   readonly runtime: RenderSystemRuntime;
   readonly pipelineState: PipelineState;
-  readonly world: World;
+  readonly world: RenderResourceScope;
   readonly store: GpuResidencyCache;
   readonly materialSlice: number;
   readonly videoHighPerfAvailable: boolean;
   readonly skylightResources: SkylightBindGroupResources;
   readonly resolveRenderTargetTextureSource?: RenderSystemRuntime['resolveRenderTargetTextureSource'];
   readonly resolveReflectionProbeResources?: (
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
     entityKey: number,
   ) => { readonly resources: SkylightBindGroupResources; readonly probeIndex: number } | undefined;
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
@@ -956,6 +959,12 @@ export interface PerSubmeshMaterialBgDeps {
   readonly sceneMaterialBuffer?: Buffer;
   /** Active transmission backdrop; undefined/null means layout placeholder. */
   readonly transmissionBackdropView?: TextureView | null;
+  /** Independent sampled raw depth for the active medium graph pass. */
+  readonly surfaceRawDepthView?: TextureView | null;
+  /** Nearest-layer color from the preceding medium graph pass. */
+  readonly surfaceNearestLayerView?: TextureView | null;
+  /** Nearest-layer depth from the preceding medium graph pass. */
+  readonly surfaceNearestDepthView?: TextureView | null;
   readonly bindGroupCounts: BindGroupCounts;
   readonly frameState: RenderFrameState;
 }
@@ -972,7 +981,7 @@ function recordIblMaterialBinding(
   if (receipt === undefined) return;
   const skylightBindingStart = entries.findIndex((entry) => entry.binding === iblStart);
   if (skylightBindingStart < 0) return;
-  const iblEntries = entries.slice(skylightBindingStart, skylightBindingStart + 7);
+  const iblEntries = entries.slice(skylightBindingStart, skylightBindingStart + 6);
   const projected: IblBindingEntryInspection[] = [];
   for (const entry of iblEntries) {
     if (entry.resource.kind === 'externalTexture') continue;
@@ -1009,8 +1018,17 @@ export function isMaterialBgAssemblyCacheHit(
   materialResourceEpoch: number,
   transmissionBackdropView?: TextureView | null,
   sceneMaterialBuffer?: Buffer,
+  surfaceRawDepthView?: TextureView | null,
 ): cached is MaterialBgAssemblyCacheEntry {
-  if (transmissionBackdropView != null) return false;
+  // Logical target sources keep their identity when a resize promotes a new
+  // physical view. Resolve those views each frame; the lower binding cache is
+  // keyed by the actual GPU resources and still reuses unchanged bindings.
+  if (
+    transmissionBackdropView != null ||
+    surfaceRawDepthView != null ||
+    (material.textureSources?.size ?? 0) > 0
+  )
+    return false;
   return (
     cached?.material === material &&
     cached.materialResourceEpoch === materialResourceEpoch &&
@@ -1023,7 +1041,6 @@ export function isMaterialBgAssemblyCacheHit(
     cached.skylightResources.skylightPrefilterView === skylightResources.skylightPrefilterView &&
     cached.skylightResources.prefilterSampler === skylightResources.prefilterSampler &&
     cached.skylightResources.brdfLutView === skylightResources.brdfLutView &&
-    cached.skylightResources.brdfLutSampler === skylightResources.brdfLutSampler &&
     cached.skylightResources.intensityBuffer === skylightResources.intensityBuffer
   );
 }
@@ -1032,7 +1049,7 @@ export function buildPerSubmeshMaterialBg(
   deps: PerSubmeshMaterialBgDeps,
   submeshMaterial: MaterialSnapshot,
   entityKey: number,
-  materialWorld: World = deps.world,
+  materialWorld: RenderResourceScope = deps.world,
   materialShaderId: string | undefined = submeshMaterial.materialShaderId,
 ): BindGroup {
   const {
@@ -1047,6 +1064,9 @@ export function buildPerSubmeshMaterialBg(
     materialBgShared,
     materialBgAssemblyCache,
     transmissionBackdropView,
+    surfaceRawDepthView,
+    surfaceNearestLayerView,
+    surfaceNearestDepthView,
     bindGroupCounts,
     frameState,
   } = deps;
@@ -1059,6 +1079,39 @@ export function buildPerSubmeshMaterialBg(
       : `${materialWorld.identity}:${smMaterialHandle}:${materialShaderId ?? ''}:${selectedProbe?.probeIndex ?? 'sky'}`;
   const smHasVideoFields = (submeshMaterial.videoTextureFields?.size ?? 0) > 0;
   const smShaderId = materialShaderId;
+  const selectedMaterialShaderArtifact =
+    smShaderId === undefined ? undefined : runtime.getMaterialShaderArtifact?.(smShaderId);
+  const selectedMediumShader =
+    smShaderId === 'forgeax::single-layer-medium' ||
+    selectedMaterialShaderArtifact?.receipt?.surface?.model === 'single-layer-medium';
+  let surfaceMediumResources: SurfaceMediumBindGroupResources | undefined;
+  if (selectedMediumShader) {
+    if (surfaceRawDepthView == null) {
+      throw new RhiError({
+        code: 'rhi-descriptor-invalid',
+        expected: 'single-layer medium material bind group has producer-owned raw depth',
+        hint: 'admit the Surface material only from a graph pass with an available raw-depth pair',
+      });
+    }
+    const nearestLayerView = surfaceNearestLayerView ?? transmissionBackdropView;
+    const nearestDepthView = surfaceNearestDepthView ?? pipelineState.shadowFallbackTextureView;
+    if (nearestLayerView == null || pipelineState.surfaceMediumDepthSampler === undefined) {
+      throw new RhiError({
+        code: 'rhi-descriptor-invalid',
+        expected:
+          'single-layer medium material bind group has paired nearest resources and depth sampler',
+        hint: 'publish the nearest-layer target and the non-filtering raw-depth sampler before recording the Surface pass',
+      });
+    }
+    surfaceMediumResources = {
+      rawDepthSampler: pipelineState.surfaceMediumDepthSampler,
+      rawDepthView: surfaceRawDepthView,
+      nearestLayerSampler: effectiveSkylightResources.prefilterSampler,
+      nearestLayerView,
+      nearestDepthSampler: pipelineState.surfaceMediumDepthSampler,
+      nearestDepthView,
+    };
+  }
   // The cooked shader schema owns the resource ABI. A material snapshot may
   // carry only the authored values (for example a clearcoat-only root omits
   // the standard emissive/occlusion maps), while the Standard template still
@@ -1100,6 +1153,7 @@ export function buildPerSubmeshMaterialBg(
         store.materialResourceEpoch,
         transmissionBackdropView,
         sceneMaterialBuffer,
+        surfaceRawDepthView,
       )
     ) {
       if (diagnosticsEnabled) {
@@ -1130,10 +1184,6 @@ export function buildPerSubmeshMaterialBg(
             },
             {
               binding: 6 + smUserRegionFields.length * 2,
-              resource: { kind: 'sampler', value: effectiveSkylightResources.brdfLutSampler },
-            },
-            {
-              binding: 7 + smUserRegionFields.length * 2,
               resource: {
                 kind: 'buffer',
                 value: { buffer: effectiveSkylightResources.intensityBuffer },
@@ -1232,7 +1282,7 @@ export function buildPerSubmeshMaterialBg(
   // Physical Standard maps are deliberately appended after the stable IBL /
   // transmission tail.  Keep their resource projection separate from the
   // user-region loop so the slot order is the same as
-  // `appendTextureInjection(afterTransmission, physicalFields)` in the
+  // `appendTextureInjection(afterSurfaceMedium, physicalFields)` in the
   // layout owner.
   const physicalTextureInjections: TextureInjectionResource[] = [];
   for (let slot = 0; slot < physicalFields.length; slot += 1) {
@@ -1271,18 +1321,27 @@ export function buildPerSubmeshMaterialBg(
     transmissionBackdropView != null
       ? effectiveSkylightResources.prefilterSampler
       : pipelineState.defaultSampler;
+  // The medium shader keeps the transmission backdrop pair in its fixed
+  // group(1) ABI even on a device that cannot admit the ordinary Standard
+  // transmission topology. Its Surface resources start at binding 10, so
+  // retain a real backdrop pair here whenever the medium resources exist;
+  // otherwise the raw-depth view would slide into binding 9 and Dawn would
+  // reject the unfilterable r32float view as a filtering float texture.
+  const keepMediumBackdropSlots = surfaceMediumResources !== undefined;
   const smMergedEntries = assembleMaterialWithSkylightEntries(
     smBaseEntries,
     effectiveSkylightResources,
-    transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)
+    transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage) ||
+      keepMediumBackdropSlots
       ? ({
           sampler: transmissionSampler,
           ...(transmissionBackdropView === undefined
-            ? {}
+            ? { backdropView: pipelineState.defaultWhiteTextureView }
             : { backdropView: transmissionBackdropView }),
         } satisfies TransmissionBindGroupResources)
       : null,
     physicalTextureInjections,
+    surfaceMediumResources,
   );
   // Storage-capable devices share one Standard material BGL with the
   // scene-index GPU lane. Even direct draws need a complete entry for
@@ -1321,6 +1380,14 @@ export function buildPerSubmeshMaterialBg(
         entityKey,
         materialHandle: smMaterialHandle,
         shader: smShaderId,
+        surfaceModel: submeshMaterial.surfaceModel,
+        layoutIdentity: getOpaqueResourceIdentity(smMaterialBgl as object),
+        bindings: smMergedEntries.map((entry) => entry.binding),
+        graphResources: {
+          rawDepth: surfaceRawDepthView != null,
+          nearestLayer: surfaceNearestLayerView != null,
+          nearestDepth: surfaceNearestDepthView != null,
+        },
         paramSnapshot: submeshMaterial.paramSnapshot,
         handleTypes: materialCacheHandles.map((handle) => typeof handle),
       })}`,
@@ -1367,6 +1434,7 @@ export function buildPerSubmeshMaterialBg(
   if (
     smMaterialHandle !== undefined &&
     !smHasVideoFields &&
+    (submeshMaterial.textureSources?.size ?? 0) === 0 &&
     materialResourcesResident &&
     !hasActiveTransmissionBackdrop
   ) {
@@ -1470,7 +1538,6 @@ export function resolveMaterialSkylight(
           prefilterView: activeViews.pref,
           prefilterSampler: skylightFallback.sampler,
           brdfLutView: activeViews.brdf,
-          brdfLutSampler: skylightFallback.sampler,
           intensityBuffer: skylightFallback.intensityBuffer,
         }
       : {
@@ -1479,7 +1546,6 @@ export function resolveMaterialSkylight(
           prefilterView: skylightFallback.prefilterView,
           prefilterSampler: skylightFallback.sampler,
           brdfLutView: skylightFallback.brdfLutView,
-          brdfLutSampler: skylightFallback.sampler,
           intensityBuffer: skylightFallback.intensityBuffer,
         };
   return { skylightResources, activeViews };

package/src/record/main-pass-sprite-draws.ts

@@ -1,8 +1,9 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { resolveSpriteInstancesBuffer } from './sprite-instance-buffer';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass sprite draws.
 // feat-20260704 M5/w31: further-split from main-pass.ts (AC-05 <=1500 lines/file).
 // recordSpritePass + sprite entity/transparent/instance-buffer helpers, moved verbatim.
 
-import type { World } from '@forgeax/engine-ecs';
 import {
   type BindGroup,
   type Buffer,
@@ -21,11 +22,8 @@ import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
 import { buildBeginRenderPassDescriptor, standardTopologyVariantSet } from '../pipeline-spec';
-import type {
-  DispatchEntry,
-  MaterialSnapshot,
-  SpriteInstancesSnapshot,
-} from '../render-system-extract';
+import type { DispatchEntry, MaterialSnapshot } from '../render-system-extract';
+import { resolveFoldInstanceBuffer } from './fold-instance-buffer';
 import { worldEntityKey } from './frame-snapshot';
 import { recordGeometryDraws, resolveGeometryInstancesBindGroup } from './main-pass-geometry';
 import {
@@ -36,55 +34,6 @@ import {
 import type { _InternalRenderPipelineContext } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 
-export type { SpriteInstancesSnapshot };
-
-/**
- * Build the interleaved sprite instance payload consumed by this record owner.
- * The extract stage validates the two packed arrays before they reach this
- * function, so the record path has one source of count-mismatch errors.
- */
-export function interleaveSpriteInstanceBuffer(
-  transforms: Float32Array,
-  regions: Float32Array,
-  includePrevious = false,
-): Float32Array {
-  const count = transforms.length / 16;
-  const stride = includePrevious ? 36 : 20;
-  const regionOffset = includePrevious ? 32 : 16;
-  const out = new Float32Array(count * stride);
-  for (let i = 0; i < count; i++) {
-    const dstBase = i * stride;
-    const transformBase = i * 16;
-    const regionBase = i * 4;
-    for (let k = 0; k < 16; k++) out[dstBase + k] = transforms[transformBase + k] ?? 0;
-    if (includePrevious) {
-      for (let k = 0; k < 16; k++) {
-        out[dstBase + 16 + k] = transforms[transformBase + k] ?? 0;
-      }
-    }
-    for (let k = 0; k < 4; k++) {
-      out[dstBase + regionOffset + k] = regions[regionBase + k] ?? 0;
-    }
-  }
-  return out;
-}
-
-/**
- * Check whether the existing per-entity sprite buffer still matches the
- * extract snapshot and interleaved byte count.
- */
-export function spriteInstancesCacheHit(
-  entry: InstanceBufferCacheEntry | undefined,
-  snapshot: SpriteInstancesSnapshot,
-  requestedBytes: number,
-): boolean {
-  return (
-    entry !== undefined &&
-    entry.uploadedArchVersion === snapshot.archVersion &&
-    entry.uploadedByteLength === requestedBytes
-  );
-}
-
 /**
  * Decide whether the LDR record needs the transparent sprite sub-pass. This
  * remains beside the sprite record owner so the frame stage and draw stage
@@ -143,7 +92,7 @@ export function recordSpritePass(
     materialSlot: number,
     submeshMaterial: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
     materialShaderId?: string,
   ) => BindGroup,
   graphPass?: RhiRenderPassEncoder,
@@ -381,7 +330,7 @@ function recordSpriteTransparentPbrDraws(
     slot: number,
     material: MaterialSnapshot,
     entityKey: number,
-    world: World,
+    world: RenderResourceScope,
     shader?: string,
   ) => BindGroup,
   meshGroup2: BindGroup | null,
@@ -454,7 +403,7 @@ function recordSpriteEntityDraws(
     materialSlot: number,
     material: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
   ) => BindGroup,
   spritePH: RenderPipeline | null,
   spritePH_withRegion: RenderPipeline | null,
@@ -589,69 +538,10 @@ function recordSpriteEntityDraws(
     const spriteInst = spriteEntry.source.instances;
     const useFold = foldHeadBucket !== undefined && spriteInst === undefined;
     if (useFold && foldHeadBucket !== undefined) {
-      // w6 (D-8): bucket transient buffer reuse — composite cacheKey from
-      // (materialHandle, layer, validatedOrdered head index) so the
-      // existing `frameState.instanceBuffers` byteLength/archVersion path
-      // covers static steady-state upload-skip. Numeric Map<number,…> key
-      // requires a 32-bit-safe fold; we use a negative number-space prefix
-      // (-1, -2, ...) by `((materialHandle << 16) | i)` shifted into the
-      // negative half so it never collides with positive entity-Instances
-      // cacheKeys (which are extracted from Instances component cacheKey
-      // numeric ids, always non-negative). The `archVersion` proxy is
-      // bucketSize (a structural-shape signal) so static frames hit the
-      // cache.
-      const bucketCacheKey = -1 - (((foldHeadBucket.materialHandle & 0xffff) << 16) | (i & 0xffff));
-      const uniformFallback = runtime.device.caps.storageBuffer === false;
-      const bucketPayload = uniformFallback
-        ? foldHeadBucket.transforms
-        : packInstanceStorageBuffer(foldHeadBucket.transforms);
-      const bucketBytes = bucketPayload.byteLength;
-      const bucketBufUsage = uniformFallback
-        ? GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST
-        : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
-      const cachedBucket = frameState.instanceBuffers.get(bucketCacheKey);
-      let activeBucket: InstanceBufferCacheEntry | null = null;
-      if (
-        cachedBucket !== undefined &&
-        cachedBucket.uploadedArchVersion === foldHeadBucket.bucketSize &&
-        cachedBucket.uploadedByteLength === bucketBytes
-      ) {
-        activeBucket = cachedBucket;
-      } else if (bucketBytes > 0) {
-        const bufRes = runtime.device.createBuffer({
-          size: bucketBytes,
-          usage: bucketBufUsage,
-          mappedAtCreation: false,
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-        } else {
-          if (cachedBucket !== undefined && !cachedBucket.buffer.isDestroyed) {
-            const r = cachedBucket.buffer.destroy();
-            if (!r.ok) runtime.errorRegistry.fire(r.error);
-          }
-          const newBuf = new GpuBuffer(runtime.device, bufRes.value);
-          activeBucket = {
-            buffer: newBuf,
-            uploadedArchVersion: foldHeadBucket.bucketSize,
-            uploadedByteLength: bucketBytes,
-          };
-          frameState.instanceBuffers.set(bucketCacheKey, activeBucket);
-        }
-      }
-      if (activeBucket !== null) {
-        const writeRes = runtime.device.queue.writeBuffer(
-          activeBucket.buffer.handle,
-          0,
-          bucketPayload,
-        );
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-        } else {
-          spriteInstanceBuffer = activeBucket.buffer.handle;
-          spriteInstanceCount = foldHeadBucket.bucketSize;
-        }
-      }
+      const buffer = resolveFoldInstanceBuffer(c, foldHeadBucket, i);
+      if (buffer === null) continue;
+      spriteInstanceBuffer = buffer;
+      spriteInstanceCount = foldHeadBucket.bucketSize;
     } else if (spriteInst !== undefined) {
       const uniformFallback = runtime.device.caps.storageBuffer === false;
       let spriteBufUsage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
@@ -681,7 +571,7 @@ function recordSpriteEntityDraws(
           );
           spritePass.setBindGroup(3, spriteInstBg);
           spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);
-          c.onRenderableDraw?.(spriteEntry);
+          c.onRenderableDraw?.(spriteEntry, 0);
           continue;
         }
         spriteBufUsage = GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST;
@@ -814,102 +704,8 @@ function recordSpriteEntityDraws(
     spritePass.setBindGroup(1, spritePassBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
     spritePass.setBindGroup(3, spriteInstancesBg);
     spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);
-    c.onRenderableDraw?.(spriteEntry);
-  }
-}
-
-/**
- * feat-20260704 M3/w19: resolve the interleaved SpriteInstances (@group(3))
- * buffer + instanceCount for a sprite entity in the LDR blend sub-pass,
- * extracted verbatim from recordSpriteEntityDraws. Uploads the interleaved
- * mat4 + per-instance UV region transforms (cache-keyed on the snapshot); on
- * over-cap fires the structured limit-exceeded error and leaves the passed-in
- * fallback buffer/count. Returns the resolved (or unchanged) buffer + count.
- *
- * @internal
- */
-function resolveSpriteInstancesBuffer(
-  c: _InternalRenderPipelineContext,
-  spriteEntry: _InternalRenderPipelineContext['validatedOrdered'][number],
-  fallbackBuffer: Buffer,
-  fallbackCount: number,
-): { buffer: Buffer; count: number } {
-  const { runtime, frameState } = c;
-  let buffer = fallbackBuffer;
-  let count = fallbackCount;
-  const spriteInstancesSnap: SpriteInstancesSnapshot | undefined =
-    spriteEntry.source.spriteInstances;
-  if (spriteInstancesSnap !== undefined) {
-    const uniformFallback = runtime.device.caps.storageBuffer === false;
-    const interleaved = interleaveSpriteInstanceBuffer(
-      spriteInstancesSnap.transforms,
-      spriteInstancesSnap.regions,
-      !uniformFallback,
-    );
-    const requestedBytes = interleaved.byteLength;
-    const cap = runtime.device.limits.maxStorageBufferBindingSize;
-    if (typeof cap === 'number' && requestedBytes > cap) {
-      runtime.errorRegistry.fire(
-        new RhiError({
-          code: 'limit-exceeded',
-          expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-          hint: 'reduce SpriteInstances instance count to fit within device.limits.maxStorageBufferBindingSize (144 bytes per instance: current mat4 64B + previous mat4 64B + region 16B)',
-          detail: {
-            maxStorageBufferBindingSize: cap,
-            requestedBytes,
-          },
-        }),
-      );
-    } else {
-      const cachedSpriteInst = frameState.instanceBuffers.get(
-        worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
-      );
-      let activeSpriteInst: InstanceBufferCacheEntry | null = null;
-      if (spriteInstancesCacheHit(cachedSpriteInst, spriteInstancesSnap, requestedBytes)) {
-        activeSpriteInst = cachedSpriteInst ?? null;
-      } else if (requestedBytes > 0) {
-        const bufRes = runtime.device.createBuffer({
-          size: requestedBytes,
-          usage:
-            (uniformFallback ? GPU_BUFFER_USAGE_UNIFORM : GPU_BUFFER_USAGE_STORAGE) |
-            GPU_BUFFER_USAGE_COPY_DST,
-          mappedAtCreation: false,
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-        } else {
-          if (cachedSpriteInst !== undefined && !cachedSpriteInst.buffer.isDestroyed) {
-            const r = cachedSpriteInst.buffer.destroy();
-            if (!r.ok) runtime.errorRegistry.fire(r.error);
-          }
-          const newBuf = new GpuBuffer(runtime.device, bufRes.value);
-          activeSpriteInst = {
-            buffer: newBuf,
-            uploadedArchVersion: spriteInstancesSnap.archVersion,
-            uploadedByteLength: requestedBytes,
-          };
-          frameState.instanceBuffers.set(
-            worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
-            activeSpriteInst,
-          );
-        }
-      }
-      if (activeSpriteInst !== null && requestedBytes > 0) {
-        const writeRes = runtime.device.queue.writeBuffer(
-          activeSpriteInst.buffer.handle,
-          0,
-          interleaved,
-        );
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-        } else {
-          buffer = activeSpriteInst.buffer.handle;
-          count = spriteInstancesSnap.instanceCount;
-        }
-      }
-    }
+    c.onRenderableDraw?.(spriteEntry, 0);
   }
-  return { buffer, count };
 }
 
 function transparentPassColorFormat(