@forgeax/engine-render 0.1.24 → 0.1.25

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

@@ -19,6 +19,11 @@ import {
 } from '../gpu-usage';
 import { createHdrpSkinUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
+import {
+  type InstanceCollectionFailureCode,
+  recordInstanceFailure,
+  recordInstanceResidency,
+} from '../instances';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import {
   createPbrSkinMeshBindGroupEntries,
@@ -39,13 +44,17 @@ import {
 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 { MaterialSnapshot } from '../render-system-extract';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import {
   PROBE_BLEND_RECORD_BYTE_SIZE,
   PROBE_BLEND_RECORD_STRIDE,
   probeBlendRecordOffset,
 } from '../scene/probe-blend-record';
-import { getOpaqueResourceIdentity, worldEntityKey } from './frame-snapshot';
+import {
+  getOpaqueResourceIdentity,
+  instanceCollectionCacheKey,
+  worldEntityKey,
+} from './frame-snapshot';
 import {
   geometryRenderStateForTopology,
   isEntityFullyTransparent,
@@ -54,6 +63,7 @@ import {
 } from './main-pass-material';
 import {
   getOrCreateFromChain,
+  INSTANCE_STORAGE_STRIDE_FLOATS,
   INSTANCE_UBO_FULL_ARRAY_BYTES,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
@@ -73,6 +83,18 @@ type GeometryInstanceDraw = {
   readonly instanceCount: number;
 };
 
+type InstanceUploadResult =
+  | {
+      readonly ok: true;
+      readonly ranges: readonly { readonly start: number; readonly end: number }[];
+      readonly bytes: number;
+    }
+  | {
+      readonly ok: false;
+      readonly ranges: readonly { readonly start: number; readonly end: number }[];
+      readonly bytes: number;
+    };
+
 type GeometryBindingState = {
   pipeline: RenderPipeline | null;
   instancesBuffer: Buffer | null;
@@ -1268,8 +1290,285 @@ export function recordGeometryDraws(
  *
  * @internal
  */
-function resolveGeometryInstanceBuffer(
-  c: _InternalRenderPipelineContext,
+function uploadInstanceRanges(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  buffer: Buffer,
+  ranges: readonly { readonly start: number; readonly end: number }[],
+  storageBacked: boolean,
+  sourceOffsetInstances = 0,
+): InstanceUploadResult {
+  const strideBytes =
+    (storageBacked ? INSTANCE_STORAGE_STRIDE_FLOATS : 16) * Float32Array.BYTES_PER_ELEMENT;
+  const uploadedRanges: { start: number; end: number }[] = [];
+  let uploadedBytes = 0;
+  for (const range of ranges) {
+    const start = Math.max(0, Math.min(inst.instanceCount, range.start));
+    const end = Math.max(start, Math.min(inst.instanceCount, range.end));
+    if (end <= start) continue;
+    const source = inst.transforms.subarray(
+      (sourceOffsetInstances + start) * 16,
+      (sourceOffsetInstances + end) * 16,
+    );
+    const payload = storageBacked ? packInstanceStorageBuffer(source) : source;
+    const written = c.runtime.device.queue.writeBuffer(buffer, start * strideBytes, payload);
+    if (!written.ok) {
+      c.runtime.errorRegistry.fire(written.error);
+      return { ok: false, ranges: uploadedRanges, bytes: uploadedBytes };
+    }
+    uploadedRanges.push({ start, end });
+    uploadedBytes += payload.byteLength;
+  }
+  return { ok: true, ranges: uploadedRanges, bytes: uploadedBytes };
+}
+
+export function reportInstanceResidency(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  input: {
+    readonly lane: 'direct-storage' | 'chunked-storage' | 'direct-uniform' | 'chunked-uniform';
+    readonly requestedBytes: number;
+    readonly supportedBytes: number | undefined;
+    readonly uploadRanges: readonly { readonly start: number; readonly end: number }[];
+    readonly uploadedBytes: number;
+  },
+): void {
+  if (inst.collectionId === undefined || c.frameState.instanceResidency === undefined) return;
+  recordInstanceResidency(c.frameState.instanceResidency, {
+    collectionId: inst.collectionId,
+    frameNumber: c.frameState.frameNumber,
+    residentGeneration: c.runtime.deviceScope.generation,
+    lane: input.lane,
+    requestedBytes: input.requestedBytes,
+    supportedBytes: input.supportedBytes,
+    uploadRanges: input.uploadRanges,
+    uploadedBytes: input.uploadedBytes,
+    backend: c.runtime.device.caps.backendKind,
+  });
+}
+
+function reportInstanceFailure(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  error: {
+    readonly code: InstanceCollectionFailureCode;
+    readonly expected: string;
+    readonly hint: string;
+  },
+  requestedBytes: number,
+  supportedBytes: number | undefined,
+): void {
+  if (inst.collectionId === undefined || c.frameState.instanceResidency === undefined) return;
+  recordInstanceFailure(c.frameState.instanceResidency, {
+    collectionId: inst.collectionId,
+    code: error.code,
+    expected: error.expected,
+    hint: error.hint,
+    facts: {
+      requestedBytes,
+      supportedBytes,
+      backend: c.runtime.device.caps.backendKind,
+      owner: 'renderer.instances',
+      cause: error.code,
+      recovery: error.hint,
+    },
+  });
+}
+
+function clearInstanceChunksForOwner(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  ownerKey: number,
+): void {
+  const chunks = c.frameState.instanceBufferChunks;
+  if (chunks === undefined) return;
+  const prefix = `${ownerKey}:`;
+  for (const [key, entry] of chunks.entries()) {
+    if (!key.startsWith(prefix)) continue;
+    if (!entry.buffer.isDestroyed) {
+      const destroyed = entry.buffer.destroy();
+      if (!destroyed.ok) c.runtime.errorRegistry.fire(destroyed.error);
+    }
+    chunks.delete(key);
+  }
+}
+
+export function resolveStorageInstanceChunks(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  entry: _InternalRenderPipelineContext['validatedOrdered'][number],
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  cap: number,
+  probeBuffer: Buffer | undefined,
+  probeOffset: number,
+): readonly GeometryInstanceDraw[] | null {
+  const { runtime, frameState } = c;
+  const strideBytes = INSTANCE_STORAGE_STRIDE_FLOATS * Float32Array.BYTES_PER_ELEMENT;
+  const chunkCapacity = Math.floor(cap / strideBytes);
+  if (chunkCapacity < 1) {
+    reportInstanceFailure(
+      c,
+      inst,
+      {
+        code: 'limit-exceeded',
+        expected: `maxStorageBufferBindingSize (${cap}) >= ${strideBytes}`,
+        hint: 'use a backend with storage-buffer bindings large enough for one InstanceData record',
+      },
+      inst.instanceCount * strideBytes,
+      cap,
+    );
+    runtime.errorRegistry.fire(
+      new RhiError({
+        code: 'limit-exceeded',
+        expected: `maxStorageBufferBindingSize (${cap}) >= ${strideBytes}`,
+        hint: 'use a backend with storage-buffer bindings large enough for one InstanceData record',
+        detail: { maxStorageBufferBindingSize: cap, requestedBytes: strideBytes },
+      }),
+    );
+    return null;
+  }
+  const ownerKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+  const chunks = frameState.instanceBufferChunks;
+  const activeKeys = new Set<string>();
+  const draws: GeometryInstanceDraw[] = [];
+  const uploadedRanges: { start: number; end: number }[] = [];
+  let uploadedBytes = 0;
+  for (let start = 0; start < inst.instanceCount; start += chunkCapacity) {
+    const end = Math.min(inst.instanceCount, start + chunkCapacity);
+    const count = end - start;
+    const chunkKey = `${ownerKey}:${start}`;
+    activeKeys.add(chunkKey);
+    // Keep stable-resident checks arithmetic-only; packing is deferred to the
+    // upload path below, where a new or dirty range actually needs payload.
+    const payloadBytes = count * strideBytes;
+    const previous = chunks?.get(chunkKey);
+    let active =
+      previous !== undefined &&
+      previous.uploadedArchVersion === inst.archVersion &&
+      previous.uploadedByteLength === payloadBytes
+        ? previous
+        : undefined;
+    let activeIsNew = false;
+    if (active === undefined) {
+      const created = runtime.device.createBuffer({
+        size: payloadBytes,
+        usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+        mappedAtCreation: false,
+      });
+      if (!created.ok) {
+        runtime.errorRegistry.fire(created.error);
+        reportInstanceFailure(c, inst, created.error, inst.instanceCount * strideBytes, cap);
+        return null;
+      }
+      if (previous !== undefined && !previous.buffer.isDestroyed) {
+        const destroyed = previous.buffer.destroy();
+        if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+      }
+      active = {
+        buffer: new GpuBuffer(runtime.device, created.value),
+        uploadedArchVersion: inst.archVersion,
+        uploadedByteLength: payloadBytes,
+      };
+      activeIsNew = true;
+      chunks?.set(chunkKey, active);
+      if (chunks === undefined) frameState.transientInstanceBuffers.push(active);
+    }
+    if (active === undefined) return null;
+    const needsUpload =
+      activeIsNew || active.uploadedRevision !== (inst.revision ?? inst.archVersion);
+    const rangesToUpload = [
+      {
+        start: 0,
+        end: count,
+      },
+    ];
+    if (needsUpload && rangesToUpload.length > 0) {
+      const upload = uploadInstanceRanges(
+        c,
+        inst,
+        active.buffer.handle,
+        rangesToUpload,
+        true,
+        start,
+      );
+      for (const range of upload.ranges) {
+        uploadedRanges.push({ start: range.start + start, end: range.end + start });
+      }
+      uploadedBytes += upload.bytes;
+      if (!upload.ok) {
+        reportInstanceFailure(
+          c,
+          inst,
+          {
+            code: 'queue-write-buffer-failed',
+            expected:
+              'the renderer-owned instance storage buffer accepts the complete instance payload',
+            hint: 'retry after the active device is healthy or recover the renderer',
+          },
+          inst.instanceCount * strideBytes,
+          cap,
+        );
+        return null;
+      }
+    }
+    if (needsUpload) {
+      {
+        const published = { ...active, uploadedRevision: inst.revision ?? inst.archVersion };
+        active = published;
+        chunks?.set(chunkKey, published);
+      }
+    }
+    const activeBuffer = active;
+    draws.push({
+      instanceBuffer: activeBuffer.buffer.handle,
+      instanceBindGroup: resolveGeometryInstancesBindGroup(
+        c,
+        activeBuffer.buffer.handle,
+        probeBuffer,
+      ),
+      probeOffset,
+      instanceCount: count,
+    });
+  }
+  if (chunks !== undefined) {
+    const prefix = `${ownerKey}:`;
+    for (const [key, stale] of chunks.entries()) {
+      if (!key.startsWith(prefix) || activeKeys.has(key)) continue;
+      if (!stale.buffer.isDestroyed) {
+        const destroyed = stale.buffer.destroy();
+        if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+      }
+      chunks.delete(key);
+    }
+  }
+  reportInstanceResidency(c, inst, {
+    lane: 'chunked-storage',
+    requestedBytes: inst.instanceCount * strideBytes,
+    supportedBytes: cap,
+    uploadRanges: uploadedRanges,
+    uploadedBytes,
+  });
+  return draws;
+}
+
+export function resolveGeometryInstanceBuffer(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
   identityInstanceDraws: readonly GeometryInstanceDraw[],
   useProbeBlend: boolean,
@@ -1304,6 +1603,11 @@ function resolveGeometryInstanceBuffer(
   // A present, empty Instances array means zero draws. Do not fall back to
   // the shared identity buffer, which would silently render one instance.
   if (inst.instanceCount === 0) return [];
+  const entityCacheKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+  const revision = inst.revision ?? inst.archVersion;
+  const sameRevision = (cached: InstanceBufferCacheEntry): boolean =>
+    cached.uploadedRevision === revision;
+  const fullRange = [{ start: 0, end: inst.instanceCount }] as const;
   let instanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
   let instanceCount = 1;
   {
@@ -1315,41 +1619,126 @@ function resolveGeometryInstanceBuffer(
     let instanceBufferUsage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
 
     if (uniformFallback && inst.instanceCount > MAX_UNIFORM_INSTANCES) {
+      const ownerKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+      const chunks = frameState.instanceBufferChunks;
+      const activeKeys = new Set<string>();
       const draws: GeometryInstanceDraw[] = [];
+      const uniformStrideBytes = 16 * Float32Array.BYTES_PER_ELEMENT;
+      const uploadedRanges: { start: number; end: number }[] = [];
+      let uploadedBytes = 0;
       for (let start = 0; start < inst.instanceCount; start += MAX_UNIFORM_INSTANCES) {
         const count = Math.min(MAX_UNIFORM_INSTANCES, inst.instanceCount - start);
-        const chunk = inst.transforms.subarray(start * 16, (start + count) * 16);
-        const bufRes = runtime.device.createBuffer({
-          size: INSTANCE_UBO_FULL_ARRAY_BYTES,
-          usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
-          mappedAtCreation: false,
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-          return null;
+        const chunkKey = `${ownerKey}:${start}`;
+        activeKeys.add(chunkKey);
+        const payloadBytes = count * uniformStrideBytes;
+        const previous = chunks?.get(chunkKey);
+        let active =
+          previous !== undefined &&
+          previous.uploadedArchVersion === inst.archVersion &&
+          previous.uploadedByteLength === payloadBytes
+            ? previous
+            : undefined;
+        let activeIsNew = false;
+        if (active === undefined) {
+          const created = runtime.device.createBuffer({
+            size: INSTANCE_UBO_FULL_ARRAY_BYTES,
+            usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!created.ok) {
+            runtime.errorRegistry.fire(created.error);
+            reportInstanceFailure(
+              c,
+              inst,
+              created.error,
+              inst.instanceCount * uniformStrideBytes,
+              MAX_UNIFORM_INSTANCES * uniformStrideBytes,
+            );
+            return null;
+          }
+          if (previous !== undefined && !previous.buffer.isDestroyed) {
+            const destroyed = previous.buffer.destroy();
+            if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+          }
+          active = {
+            buffer: new GpuBuffer(runtime.device, created.value),
+            uploadedArchVersion: inst.archVersion,
+            uploadedByteLength: payloadBytes,
+          };
+          activeIsNew = true;
+          chunks?.set(chunkKey, active);
+          if (chunks === undefined) frameState.transientInstanceBuffers.push(active);
         }
-        const buffer = new GpuBuffer(runtime.device, bufRes.value);
-        frameState.transientInstanceBuffers.push({
-          buffer,
-          uploadedArchVersion: inst.archVersion,
-          uploadedByteLength: chunk.byteLength,
-        });
-        const writeRes = runtime.device.queue.writeBuffer(buffer.handle, 0, chunk);
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-          return null;
+        const needsUpload = activeIsNew || !sameRevision(active);
+        const rangesToUpload = [
+          {
+            start: 0,
+            end: count,
+          },
+        ];
+        if (needsUpload && rangesToUpload.length > 0) {
+          const upload = uploadInstanceRanges(
+            c,
+            inst,
+            active.buffer.handle,
+            rangesToUpload,
+            false,
+            start,
+          );
+          for (const range of upload.ranges) {
+            uploadedRanges.push({ start: range.start + start, end: range.end + start });
+          }
+          uploadedBytes += upload.bytes;
+          if (!upload.ok) {
+            reportInstanceFailure(
+              c,
+              inst,
+              {
+                code: 'queue-write-buffer-failed',
+                expected:
+                  'the renderer-owned instance uniform buffer accepts the complete instance payload',
+                hint: 'retry after the active device is healthy or recover the renderer',
+              },
+              inst.instanceCount * uniformStrideBytes,
+              MAX_UNIFORM_INSTANCES * uniformStrideBytes,
+            );
+            return null;
+          }
+        }
+        if (needsUpload) {
+          const published = { ...active, uploadedRevision: revision };
+          active = published;
+          chunks?.set(chunkKey, published);
         }
         draws.push({
-          instanceBuffer: buffer.handle,
+          instanceBuffer: active.buffer.handle,
           instanceBindGroup: resolveGeometryInstancesBindGroup(
             c,
-            buffer.handle,
+            active.buffer.handle,
             probeBinding?.buffer,
           ),
           probeOffset: probeBinding?.offset ?? -1,
           instanceCount: count,
         });
       }
+      if (chunks !== undefined) {
+        const prefix = `${ownerKey}:`;
+        for (const [key, stale] of chunks.entries()) {
+          if (!key.startsWith(prefix) || activeKeys.has(key)) continue;
+          if (!stale.buffer.isDestroyed) {
+            const destroyed = stale.buffer.destroy();
+            if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+          }
+          chunks.delete(key);
+        }
+      }
+      reportInstanceResidency(c, inst, {
+        lane: 'chunked-uniform',
+        requestedBytes: inst.instanceCount * uniformStrideBytes,
+        supportedBytes: MAX_UNIFORM_INSTANCES * uniformStrideBytes,
+        uploadRanges: uploadedRanges,
+        uploadedBytes,
+      });
       return draws;
     }
     if (uniformFallback) {
@@ -1359,31 +1748,30 @@ function resolveGeometryInstanceBuffer(
     {
       // Cap-gate (LimitExceededDetail single emit point — feat-20260514
       // M3 / w15 anchor): `requestedBytes <= maxStorageBufferBindingSize`.
-      const instancePayload = uniformFallback
-        ? inst.transforms
-        : packInstanceStorageBuffer(inst.transforms);
-      const requestedBytes = instancePayload.byteLength;
+      // Derive the size from the authoring count; storage packing is deferred
+      // until uploadInstanceRanges confirms a new or dirty resident.
+      const requestedBytes =
+        inst.instanceCount *
+        (uniformFallback ? 16 : INSTANCE_STORAGE_STRIDE_FLOATS) *
+        Float32Array.BYTES_PER_ELEMENT;
       const cap = runtime.device.limits.maxStorageBufferBindingSize;
       if (!uniformFallback && typeof cap === 'number' && cap > 0 && requestedBytes > cap) {
-        runtime.errorRegistry.fire(
-          new RhiError({
-            code: 'limit-exceeded',
-            expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-            hint: 'reduce instance count to fit within device.limits.maxStorageBufferBindingSize, or split transforms across multiple Instances entries',
-            detail: {
-              maxStorageBufferBindingSize: cap,
-              requestedBytes,
-            },
-          }),
+        const chunked = resolveStorageInstanceChunks(
+          c,
+          entry,
+          inst,
+          cap,
+          probeBinding?.buffer,
+          probeBinding?.offset ?? -1,
         );
-        return null;
+        return chunked;
       } else {
         // Look up the cached GPU buffer or create a fresh one when the
         // archetype version bumped or the byte length changed.
-        const cached = frameState.instanceBuffers.get(
-          worldEntityKey(entry.source.worldId, inst.cacheKey),
-        );
+        // entityCacheKey is the worldEntityKey + collectionId namespace.
+        const cached = frameState.instanceBuffers.get(entityCacheKey);
         let active: InstanceBufferCacheEntry | null = null;
+        let activeIsNew = false;
         if (
           cached !== undefined &&
           cached.uploadedArchVersion === inst.archVersion &&
@@ -1398,6 +1786,8 @@ 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).
@@ -1411,24 +1801,67 @@ function resolveGeometryInstanceBuffer(
               uploadedArchVersion: inst.archVersion,
               uploadedByteLength: requestedBytes,
             };
-            frameState.instanceBuffers.set(
-              worldEntityKey(entry.source.worldId, inst.cacheKey),
-              active,
-            );
+            activeIsNew = true;
+            if (active !== null) {
+              // Keep the collection identity in the worldEntityKey namespace.
+              frameState.instanceBuffers.set(entityCacheKey, active);
+            }
           }
         }
         if (active !== null) {
-          const writeRes = runtime.device.queue.writeBuffer(
-            active.buffer.handle,
-            0,
-            instancePayload,
-          );
-          if (!writeRes.ok) {
-            runtime.errorRegistry.fire(writeRes.error);
-          } else {
-            instanceBuffer = active.buffer.handle;
-            instanceCount = Math.max(1, inst.instanceCount);
+          const needsUpload = activeIsNew || !sameRevision(active);
+          const ranges = [fullRange[0]];
+          let uploadRanges: readonly { readonly start: number; readonly end: number }[] = [];
+          let uploadedBytes = 0;
+          if (needsUpload && ranges.length > 0) {
+            const upload = uploadInstanceRanges(
+              c,
+              inst,
+              active.buffer.handle,
+              ranges,
+              !uniformFallback,
+            );
+            uploadRanges = upload.ranges;
+            uploadedBytes = upload.bytes;
+            if (!upload.ok) {
+              reportInstanceFailure(
+                c,
+                inst,
+                {
+                  code: 'queue-write-buffer-failed',
+                  expected:
+                    'the renderer-owned instance buffer accepts the complete instance payloads',
+                  hint: 'retry after the active device is healthy or recover the renderer',
+                },
+                requestedBytes,
+                uniformFallback
+                  ? MAX_UNIFORM_INSTANCES * Float32Array.BYTES_PER_ELEMENT * 16
+                  : typeof cap === 'number'
+                    ? cap
+                    : undefined,
+              );
+              return null;
+            }
+          }
+          if (needsUpload) {
+            const published = { ...active, uploadedRevision: revision };
+            frameState.instanceBuffers.set(entityCacheKey, published);
+            active = published;
           }
+          instanceBuffer = active.buffer.handle;
+          instanceCount = Math.max(1, inst.instanceCount);
+          reportInstanceResidency(c, inst, {
+            lane: uniformFallback ? 'direct-uniform' : 'direct-storage',
+            requestedBytes,
+            supportedBytes: uniformFallback
+              ? MAX_UNIFORM_INSTANCES * Float32Array.BYTES_PER_ELEMENT * 16
+              : typeof cap === 'number'
+                ? cap
+                : undefined,
+            uploadRanges,
+            uploadedBytes,
+          });
+          clearInstanceChunksForOwner(c, entityCacheKey);
         }
       }
       // The cache write above is keyed by worldEntityKey(worldId, cacheKey)
@@ -1446,7 +1879,10 @@ function resolveGeometryInstanceBuffer(
 }
 
 export function resolveProbeBlendBuffer(
-  c: _InternalRenderPipelineContext,
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
   record: import('../scene/probe-blend-record').ProbeBlendRecord | undefined,
   entityKey?: number,
 ): { readonly buffer: Buffer; readonly offset: number } {
@@ -1494,7 +1930,10 @@ export function resolveProbeBlendBuffer(
 }
 
 export function resolveGeometryInstancesBindGroup(
-  c: _InternalRenderPipelineContext,
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
   instanceBuffer: Buffer,
   probeBuffer?: Buffer,
 ): BindGroup {

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

@@ -856,7 +856,7 @@ function recordSpriteEntityDraws(
             new RhiError({
               code: 'limit-exceeded',
               expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-              hint: 'reduce instance count to fit within device.limits.maxStorageBufferBindingSize, or split transforms across multiple Instances entries',
+              hint: 'reduce the sprite batch to fit within device.limits.maxStorageBufferBindingSize or use a storage-capable backend',
               detail: {
                 maxStorageBufferBindingSize: cap,
                 requestedBytes,