@forgeax/engine-render 0.1.28 → 0.1.30

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

@@ -10,7 +10,9 @@ import {
   RhiError,
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
+import { STANDARD_TEXTURE_MASK_OVERRIDE } from '@forgeax/engine-shader';
 import type { ParamSchemaEntry, PassKind, PrimitiveTopology } from '@forgeax/engine-types';
+import { gpuDrivenDrawKey, gpuDrivenSourceDrawItemIndex } from '../extract/gpu-driven';
 import { GpuBuffer } from '../gpu-resource';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
@@ -19,11 +21,7 @@ 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 { type InstanceCollectionFailureCode, instanceUploadRangesForResident } from '../instances';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import {
   createPbrSkinMeshBindGroupEntries,
@@ -75,6 +73,23 @@ import type { _InternalRenderPipelineContext, MaterialShaderPipelineEntry } from
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 import { POINTS_LINES_VIEW_SLOT_STRIDE, writePointsLinesViewUbo } from './view-ubo';
 
+/** Temporal ignores authored color entry points; opaque duplicates are idempotent. */
+export function sameOpaqueTemporalDraw(a: DispatchEntry, b: DispatchEntry): boolean {
+  return (
+    (isStandardPbrMaterialShader(a.materialShaderId) ||
+      (a.tags.SurfaceKind === 'standard' &&
+        b.tags.SurfaceKind === 'standard' &&
+        a.tags.SurfaceModule === b.tags.SurfaceModule)) &&
+    a.materialShaderId === b.materialShaderId &&
+    a.renderState?.blend === undefined &&
+    b.renderState?.blend === undefined &&
+    a.renderState?.stencil === undefined &&
+    b.renderState?.stencil === undefined &&
+    a.stencilReference === b.stencilReference &&
+    renderStateHash(a.renderState) === renderStateHash(b.renderState)
+  );
+}
+
 type GeometryInstanceDraw = {
   readonly instanceBuffer: Buffer;
   readonly instanceBindGroup: BindGroup;
@@ -127,6 +142,7 @@ type MaterialPipelineLookup = {
   readonly sampleCount: number;
   readonly colorFormatOverride: GPUTextureFormat | undefined;
   readonly additionalColorFormats: readonly GPUTextureFormat[] | undefined;
+  readonly textureMask: number | undefined;
   readonly handle: MaterialShaderPipelineEntry | null;
 };
 
@@ -134,6 +150,86 @@ type GeometryRecordProfileSegment = 'material-bind-groups' | 'pipeline-selection
 
 type GeometryRenderState = ReturnType<typeof geometryRenderStateForTopology>;
 
+/** Coverage is a dedicated temporal material variant, not a color/alpha tap. */
+export function variantSetForCoveragePass(
+  variantSet: string | undefined,
+  coverageOnly: boolean,
+): string | undefined {
+  if (!coverageOnly) return variantSet;
+  if (variantSet?.includes('COVERAGE_ONLY=')) return variantSet;
+  return variantSet === undefined || variantSet === ''
+    ? 'COVERAGE_ONLY=true'
+    : `${variantSet}+COVERAGE_ONLY=true`;
+}
+
+export function isHdrGeometryTarget(
+  tonemapActive: boolean,
+  colorFormatOverride: GPUTextureFormat | undefined,
+): boolean {
+  return colorFormatOverride === undefined ? tonemapActive : colorFormatOverride === 'rgba16float';
+}
+
+function gpuDrivenDrawIndicesBySubmesh(
+  source: RenderableSnapshot,
+  mesh: _InternalRenderPipelineContext['validatedOrdered'][number]['mesh'],
+): ReadonlyMap<number, number> {
+  const draws = source.gpuDrivenDraws;
+  if (draws === undefined || draws.length === 0) return new Map();
+  const indices = new Map<number, number>();
+  let hasStableSourceIdentity = false;
+  for (const [compactIndex, draw] of draws.entries()) {
+    const drawItemIndex = draw.drawItemIndex;
+    if (drawItemIndex === undefined) continue;
+    hasStableSourceIdentity = true;
+    if (mesh.submeshes[drawItemIndex] !== undefined) indices.set(drawItemIndex, compactIndex);
+  }
+  if (hasStableSourceIdentity) return indices;
+
+  // Legacy snapshots predating drawItemIndex are matched by their compact
+  // geometry facts. New extracted snapshots never take this path.
+  let nonIndexedFirst = 0;
+  let drawCursor = 0;
+  for (const [submeshIndex, submesh] of mesh.submeshes.entries()) {
+    const first = mesh.indexed ? submesh.indexOffset : nonIndexedFirst;
+    const count = mesh.indexed ? submesh.indexCount : submesh.vertexCount;
+    if (!mesh.indexed) nonIndexedFirst += submesh.vertexCount;
+    const draw = draws[drawCursor];
+    if (
+      draw !== undefined &&
+      draw.first === first &&
+      draw.count === count &&
+      draw.materialSlot === submesh.materialSlot &&
+      draw.topology === submesh.topology
+    ) {
+      indices.set(submeshIndex, drawCursor);
+      drawCursor += 1;
+    }
+  }
+  return indices;
+}
+
+function isGpuDrivenMainClaimedSubmesh(
+  c: _InternalRenderPipelineContext,
+  source: RenderableSnapshot,
+  submeshIndex: number,
+  drawIndices: ReadonlyMap<number, number>,
+): boolean {
+  const drawItemIndex = drawIndices.get(submeshIndex);
+  const draw = drawItemIndex === undefined ? undefined : source.gpuDrivenDraws?.[drawItemIndex];
+  if (drawItemIndex === undefined || draw === undefined) return false;
+  const material = source.materials[draw.materialSlot] ?? source.material;
+  const sourceDrawItemIndex = gpuDrivenSourceDrawItemIndex(draw, drawItemIndex);
+  return (
+    c.gpuDrivenDrawKeys?.has(
+      gpuDrivenDrawKey(
+        worldEntityKey(source.worldId, source.entityKey),
+        material.materialHandle ?? -1,
+        sourceDrawItemIndex,
+      ),
+    ) === true
+  );
+}
+
 /**
  * Select the transmission shader axis from authored material data, not the
  * canonical boot schema.  The latter reserves transmission fields for the
@@ -252,18 +348,19 @@ export function effectiveMaterialLayoutIdentity(
 /**
  * Resolve the depth contract for a geometry pass without changing the base
  * material state. Temporal scene-data shares the main pass depth attachment:
- * it is read-only and accepts the equal depth produced by the unjittered
- * temporal projection, while still rejecting fragments behind the visible
+ * it is read-only and accepts the equal depth produced by the shared raster
+ * projection, while motion varyings remain unjittered. It rejects fragments behind the visible
  * surface.
  */
 export function geometryRenderStateForPass(
   base: GeometryRenderState,
   passKind: PassKind,
+  coverageOnly = false,
 ): GeometryRenderState {
   if (passKind !== 'temporal') return base;
   return {
     ...base,
-    depthWriteEnabled: false,
+    depthWriteEnabled: coverageOnly,
     depthCompare: 'less-equal' as const,
   };
 }
@@ -373,6 +470,8 @@ export function recordGeometryDraws(
   ) => BindGroup,
   passKind: PassKind = 'forward',
   selectedDispatch?: readonly DispatchEntry[],
+  colorFormats: readonly GPUTextureFormat[] = [],
+  coverageOnly = false,
 ): void {
   const {
     runtime,
@@ -396,7 +495,11 @@ export function recordGeometryDraws(
     }
     const passes = byMaterial.get(dispatch.materialHandle);
     if (passes === undefined) byMaterial.set(dispatch.materialHandle, [dispatch]);
-    else passes.push(dispatch);
+    else if (
+      passKind !== 'temporal' ||
+      !passes.some((previous) => sameOpaqueTemporalDraw(previous, dispatch))
+    )
+      passes.push(dispatch);
   }
   const diagnosticsEnabled = materialDiagnosticsEnabled();
   const colorFormatOverride = c.transparentColorFormat as GPUTextureFormat | undefined;
@@ -409,7 +512,9 @@ export function recordGeometryDraws(
   // numeric domain rather than the camera's tone-map switch, otherwise the
   // LDR/OETF fragment entry point is encoded once here and again by the
   // output transform.
-  const isHdrTarget = tonemapActive || colorFormatOverride === 'rgba16float';
+  const isHdrTarget = isHdrGeometryTarget(tonemapActive, colorFormatOverride);
+  const withCoverageVariant = (variantSet: string | undefined): string | undefined =>
+    variantSetForCoveragePass(variantSet, coverageOnly);
   let lastVertexBuffer: GpuBuffer | null = null;
   let lastIndexBuffer: GpuBuffer | null = null;
   const bindingState: GeometryBindingState = {
@@ -457,7 +562,9 @@ export function recordGeometryDraws(
     layoutProjection: import('@forgeax/engine-geometry').VertexLayoutProjection,
     vertexEntry?: string,
     fragmentEntry?: string,
+    textureMask?: number,
   ): MaterialShaderPipelineEntry | null => {
+    const pipelineVariantSet = withCoverageVariant(variantSet);
     // The fallback MRT is an extension of the built-in Standard PBR output
     // contract only.  The render pass may carry a second attachment whenever
     // another renderable needs S_fallback, but shaders such as unlit, sprite,
@@ -469,7 +576,9 @@ export function recordGeometryDraws(
     const reflectionFallbackFormats =
       materialShaderId === 'forgeax::default-standard-pbr' &&
       c.reflectionFallbackColorFormat !== undefined
-        ? [c.reflectionFallbackColorFormat]
+        ? passKind === 'deferred'
+          ? colorFormats.slice(1)
+          : [c.reflectionFallbackColorFormat]
         : undefined;
     const renderStateKey = renderStateHash(renderState);
     const shaderLookupCache = materialPipelineLookupCache.get(materialShaderId);
@@ -481,9 +590,10 @@ export function recordGeometryDraws(
           cached.renderStateKey === renderStateKey &&
           cached.topology === topology &&
           cached.indexFormat === indexFormat &&
-          cached.variantSet === variantSet &&
+          cached.variantSet === pipelineVariantSet &&
           cached.vertexEntry === vertexEntry &&
           cached.fragmentEntry === fragmentEntry &&
+          cached.textureMask === textureMask &&
           cached.passKind === passKind &&
           cached.layoutProjection.digest === layoutProjection.digest &&
           cached.sampleCount === sampleCount &&
@@ -497,10 +607,10 @@ export function recordGeometryDraws(
     const resolvedVariantSetResult =
       runtime.getMaterialArtifact?.(materialShaderId) !== undefined
         ? ({ ok: true, value: undefined } as const)
-        : variantSet === undefined &&
+        : pipelineVariantSet === undefined &&
             (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
           ? ({ ok: true, value: undefined } as const)
-          : variantSetFromVertexLayoutProjection(layoutProjection, variantSet);
+          : variantSetFromVertexLayoutProjection(layoutProjection, pipelineVariantSet);
     if (!resolvedVariantSetResult.ok) {
       runtime.errorRegistry.fire(resolvedVariantSetResult.error);
       return null;
@@ -530,9 +640,12 @@ export function recordGeometryDraws(
         layoutProjection,
         undefined,
         undefined,
+        undefined,
         reflectionFallbackFormats,
         vertexEntry,
         fragmentEntry,
+        undefined,
+        textureMask === undefined ? undefined : { [STANDARD_TEXTURE_MASK_OVERRIDE]: textureMask },
       ) ?? null;
     const handle =
       profilePhase === undefined
@@ -552,7 +665,7 @@ export function recordGeometryDraws(
         renderStateKey,
         topology,
         indexFormat,
-        variantSet,
+        variantSet: pipelineVariantSet,
         vertexEntry,
         fragmentEntry,
         passKind,
@@ -560,6 +673,7 @@ export function recordGeometryDraws(
         sampleCount,
         colorFormatOverride: colorFormat,
         additionalColorFormats: reflectionFallbackFormats,
+        textureMask,
         handle,
       };
       if (shaderLookupCache === undefined) {
@@ -579,7 +693,6 @@ export function recordGeometryDraws(
   for (let i = 0; i < validatedOrdered.length; i++) {
     const entry = validatedOrdered[i];
     if (entry === undefined) 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.
@@ -587,18 +700,6 @@ export function recordGeometryDraws(
     if (entry.source.pointsLines !== undefined && pointsLinesSubmission?.plan.drawCount !== 1)
       continue;
 
-    if (
-      passKind === 'forward' &&
-      c.gpuDrivenEntityKeys.has(
-        worldEntityKey(
-          c.gpuDrivenWorldKeys?.[entry.source.worldId] ?? entry.source.worldId,
-          entry.source.entityKey,
-        ),
-      )
-    ) {
-      continue;
-    }
-
     // feat-20260609 M2: skip entities that don't match the pass selector.
     if (matchedMaterials !== null && !matchedMaterials.has(entry.renderableIndex)) continue;
 
@@ -822,7 +923,9 @@ export function recordGeometryDraws(
       ),
     );
     if (!skinVariantSetResult.ok) runtime.errorRegistry.fire(skinVariantSetResult.error);
-    const skinVariantSet = skinVariantSetResult.ok ? skinVariantSetResult.value : undefined;
+    const skinVariantSet = skinVariantSetResult.ok
+      ? withCoverageVariant(skinVariantSetResult.value)
+      : undefined;
     const skinPsoProbe =
       skinResources !== null && skinVariantSetResult.ok
         ? (runtime.getMaterialShaderPipeline?.(
@@ -987,6 +1090,7 @@ export function recordGeometryDraws(
     // — the same placeholders the unlit path already used. The generic
     // branch below builds the per-submesh BG.
     let perSubmeshBg: BindGroup | null = null;
+    const gpuDrivenDrawIndices = gpuDrivenDrawIndicesBySubmesh(entry.source, entry.mesh);
     // feat-20260608 M4 / w16: per-submesh pipeline selection + draw loop.
     // Each submesh carries its own topology, so pipeline selection is per-submesh.
     // Vertex/index buffers and bind groups are set once (shared across all submeshes).
@@ -1004,6 +1108,12 @@ export function recordGeometryDraws(
         const materialHandle = submeshMaterial.materialHandle ?? 0;
         if (materialHandles === undefined || !materialHandles.has(materialHandle)) continue;
       }
+      if (
+        passKind === 'forward' &&
+        isGpuDrivenMainClaimedSubmesh(c, entry.source, smIdx, gpuDrivenDrawIndices)
+      ) {
+        continue;
+      }
       const draws: readonly (DispatchEntry | undefined)[] =
         selectedDispatch === undefined
           ? [undefined]
@@ -1133,7 +1243,11 @@ export function recordGeometryDraws(
               blend: selectedRenderState?.blend ?? SPRITE_PREMULTIPLIED_ALPHA_BLEND,
             }
           : geometryRenderStateForTopology(smTopology, selectedRenderState);
-        const pipelineRenderState = geometryRenderStateForPass(basePipelineRenderState, passKind);
+        const pipelineRenderState = geometryRenderStateForPass(
+          basePipelineRenderState,
+          passKind,
+          coverageOnly,
+        );
         let smPipelineHandle: typeof pipelineState.unlitPipeline;
         let materialGroup2Contract: 'mesh' | 'skin' | 'cluster' | 'skin-cluster' | undefined;
         let materialPipelineEntry: MaterialShaderPipelineEntry | null = null;
@@ -1163,6 +1277,7 @@ export function recordGeometryDraws(
             entry.mesh.layoutProjection,
             vertexEntry,
             fragmentEntry,
+            submeshMaterial.standardTextureMask,
           );
           materialPipelineEntry = unlitRsp;
           smPipelineHandle =
@@ -1202,7 +1317,7 @@ export function recordGeometryDraws(
           const transmissionAvailable = requestsStandardTransmissionVariant(submeshMaterial);
           const materialCapabilityVariantSet =
             transmissionAvailable && !capabilityVariantSet.includes('TRANSMISSION_AVAILABLE=')
-              ? `${capabilityVariantSet === '' ? '' : `${capabilityVariantSet}+`}TRANSMISSION_AVAILABLE=true`
+              ? `${capabilityVariantSet}+TRANSMISSION_AVAILABLE=true`
               : capabilityVariantSet;
           // Sprite's base request must retain the boot-selected artifact. Only
           // SpriteInstances uses the explicit empty key for the
@@ -1215,9 +1330,7 @@ export function recordGeometryDraws(
               : undefined
             : entry.variantSet === undefined
               ? materialCapabilityVariantSet
-              : capabilityVariantSet === ''
-                ? entry.variantSet
-                : `${capabilityVariantSet}+${entry.variantSet}`;
+              : `${materialCapabilityVariantSet}+${entry.variantSet}`;
           const cachedPipeline = resolveMaterialPipeline(
             smMaterialShaderId,
             pipelineRenderState,
@@ -1228,6 +1341,7 @@ export function recordGeometryDraws(
             entry.mesh.layoutProjection,
             vertexEntry,
             fragmentEntry,
+            submeshMaterial.standardTextureMask,
           );
           // feat-20260615-pipeline-spec-ssot M6-T1: cache miss resolves to
           // null uniformly across URP / HDRP / skin shaders. Charter P3
@@ -1361,10 +1475,7 @@ export function recordGeometryDraws(
  * @internal
  */
 function uploadInstanceRanges(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
+  c: _InternalRenderPipelineContext,
   inst: NonNullable<RenderableSnapshot['instances']>,
   buffer: Buffer,
   ranges: readonly { readonly start: number; readonly end: number }[],
@@ -1396,10 +1507,7 @@ function uploadInstanceRanges(
 }
 
 export function reportInstanceResidency(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
+  c: _InternalRenderPipelineContext,
   inst: NonNullable<RenderableSnapshot['instances']>,
   input: {
     readonly lane: 'direct-storage' | 'chunked-storage' | 'direct-uniform' | 'chunked-uniform';
@@ -1409,8 +1517,8 @@ export function reportInstanceResidency(
     readonly uploadedBytes: number;
   },
 ): void {
-  if (inst.collectionId === undefined || c.frameState.instanceResidency === undefined) return;
-  recordInstanceResidency(c.frameState.instanceResidency, {
+  if (inst.collectionId === undefined) return;
+  c.frameState.instanceCollections?._reportResidency({
     collectionId: inst.collectionId,
     frameNumber: c.frameState.frameNumber,
     residentGeneration: c.runtime.deviceScope.generation,
@@ -1424,10 +1532,7 @@ export function reportInstanceResidency(
 }
 
 function reportInstanceFailure(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
+  c: _InternalRenderPipelineContext,
   inst: NonNullable<RenderableSnapshot['instances']>,
   error: {
     readonly code: InstanceCollectionFailureCode;
@@ -1437,8 +1542,8 @@ function reportInstanceFailure(
   requestedBytes: number,
   supportedBytes: number | undefined,
 ): void {
-  if (inst.collectionId === undefined || c.frameState.instanceResidency === undefined) return;
-  recordInstanceFailure(c.frameState.instanceResidency, {
+  if (inst.collectionId === undefined) return;
+  c.frameState.instanceCollections?._reportFailure({
     collectionId: inst.collectionId,
     code: error.code,
     expected: error.expected,
@@ -1454,13 +1559,7 @@ function reportInstanceFailure(
   });
 }
 
-function clearInstanceChunksForOwner(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
-  ownerKey: number,
-): void {
+function clearInstanceChunksForOwner(c: _InternalRenderPipelineContext, ownerKey: number): void {
   const chunks = c.frameState.instanceBufferChunks;
   if (chunks === undefined) return;
   const prefix = `${ownerKey}:`;
@@ -1475,10 +1574,7 @@ function clearInstanceChunksForOwner(
 }
 
 export function resolveStorageInstanceChunks(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
+  c: _InternalRenderPipelineContext,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
   inst: NonNullable<RenderableSnapshot['instances']>,
   cap: number,
@@ -1516,6 +1612,7 @@ export function resolveStorageInstanceChunks(
   const draws: GeometryInstanceDraw[] = [];
   const uploadedRanges: { start: number; end: number }[] = [];
   let uploadedBytes = 0;
+  const dirtyRanges = inst.dirtyRanges ?? [{ start: 0, end: inst.instanceCount } as const];
   for (let start = 0; start < inst.instanceCount; start += chunkCapacity) {
     const end = Math.min(inst.instanceCount, start + chunkCapacity);
     const count = end - start;
@@ -1557,14 +1654,17 @@ export function resolveStorageInstanceChunks(
       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,
-      },
-    ];
+    const localRanges = dirtyRanges
+      .map((range) => ({
+        start: Math.max(start, range.start) - start,
+        end: Math.min(end, range.end) - start,
+      }))
+      .filter((range) => range.end > range.start);
+    const needsUpload = activeIsNew || active.uploadedRevision !== inst.revision;
+    const rangesToUpload = instanceUploadRangesForResident(activeIsNew, localRanges, {
+      start: 0,
+      end: count,
+    });
     if (needsUpload && rangesToUpload.length > 0) {
       const upload = uploadInstanceRanges(
         c,
@@ -1584,8 +1684,7 @@ export function resolveStorageInstanceChunks(
           inst,
           {
             code: 'queue-write-buffer-failed',
-            expected:
-              'the renderer-owned instance storage buffer accepts the complete instance payload',
+            expected: 'the renderer-owned instance storage buffer accepts the dirty range',
             hint: 'retry after the active device is healthy or recover the renderer',
           },
           inst.instanceCount * strideBytes,
@@ -1595,8 +1694,8 @@ export function resolveStorageInstanceChunks(
       }
     }
     if (needsUpload) {
-      {
-        const published = { ...active, uploadedRevision: inst.revision ?? inst.archVersion };
+      if (inst.revision !== undefined) {
+        const published = { ...active, uploadedRevision: inst.revision };
         active = published;
         chunks?.set(chunkKey, published);
       }
@@ -1634,11 +1733,8 @@ export function resolveStorageInstanceChunks(
   return draws;
 }
 
-export function resolveGeometryInstanceBuffer(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
+function resolveGeometryInstanceBuffer(
+  c: _InternalRenderPipelineContext,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
   identityInstanceDraws: readonly GeometryInstanceDraw[],
   useProbeBlend: boolean,
@@ -1674,9 +1770,12 @@ export function resolveGeometryInstanceBuffer(
   // 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 revision = inst.revision;
+  const dirtyRanges = inst.dirtyRanges;
   const sameRevision = (cached: InstanceBufferCacheEntry): boolean =>
-    cached.uploadedRevision === revision;
+    revision === undefined
+      ? cached.uploadedRevision === undefined
+      : cached.uploadedRevision === revision;
   const fullRange = [{ start: 0, end: inst.instanceCount }] as const;
   let instanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
   let instanceCount = 1;
@@ -1694,6 +1793,7 @@ export function resolveGeometryInstanceBuffer(
       const activeKeys = new Set<string>();
       const draws: GeometryInstanceDraw[] = [];
       const uniformStrideBytes = 16 * Float32Array.BYTES_PER_ELEMENT;
+      const dirty = inst.dirtyRanges ?? fullRange;
       const uploadedRanges: { start: number; end: number }[] = [];
       let uploadedBytes = 0;
       for (let start = 0; start < inst.instanceCount; start += MAX_UNIFORM_INSTANCES) {
@@ -1739,13 +1839,17 @@ export function resolveGeometryInstanceBuffer(
           chunks?.set(chunkKey, active);
           if (chunks === undefined) frameState.transientInstanceBuffers.push(active);
         }
+        const localRanges = dirty
+          .map((range) => ({
+            start: Math.max(start, range.start) - start,
+            end: Math.min(start + count, range.end) - start,
+          }))
+          .filter((range) => range.end > range.start);
         const needsUpload = activeIsNew || !sameRevision(active);
-        const rangesToUpload = [
-          {
-            start: 0,
-            end: count,
-          },
-        ];
+        const rangesToUpload = instanceUploadRangesForResident(activeIsNew, localRanges, {
+          start: 0,
+          end: count,
+        });
         if (needsUpload && rangesToUpload.length > 0) {
           const upload = uploadInstanceRanges(
             c,
@@ -1765,8 +1869,7 @@ export function resolveGeometryInstanceBuffer(
               inst,
               {
                 code: 'queue-write-buffer-failed',
-                expected:
-                  'the renderer-owned instance uniform buffer accepts the complete instance payload',
+                expected: 'the renderer-owned instance uniform buffer accepts the dirty range',
                 hint: 'retry after the active device is healthy or recover the renderer',
               },
               inst.instanceCount * uniformStrideBytes,
@@ -1776,7 +1879,8 @@ export function resolveGeometryInstanceBuffer(
           }
         }
         if (needsUpload) {
-          const published = { ...active, uploadedRevision: revision };
+          const published =
+            revision === undefined ? active : { ...active, uploadedRevision: revision };
           active = published;
           chunks?.set(chunkKey, published);
         }
@@ -1857,7 +1961,6 @@ export 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).
@@ -1880,7 +1983,11 @@ export function resolveGeometryInstanceBuffer(
         }
         if (active !== null) {
           const needsUpload = activeIsNew || !sameRevision(active);
-          const ranges = [fullRange[0]];
+          const ranges = instanceUploadRangesForResident(
+            activeIsNew,
+            dirtyRanges ?? fullRange,
+            fullRange[0],
+          );
           let uploadRanges: readonly { readonly start: number; readonly end: number }[] = [];
           let uploadedBytes = 0;
           if (needsUpload && ranges.length > 0) {
@@ -1899,8 +2006,7 @@ export function resolveGeometryInstanceBuffer(
                 inst,
                 {
                   code: 'queue-write-buffer-failed',
-                  expected:
-                    'the renderer-owned instance buffer accepts the complete instance payloads',
+                  expected: 'the renderer-owned instance buffer accepts the dirty ranges',
                   hint: 'retry after the active device is healthy or recover the renderer',
                 },
                 requestedBytes,
@@ -1914,7 +2020,8 @@ export function resolveGeometryInstanceBuffer(
             }
           }
           if (needsUpload) {
-            const published = { ...active, uploadedRevision: revision };
+            const published =
+              revision === undefined ? active : { ...active, uploadedRevision: revision };
             frameState.instanceBuffers.set(entityCacheKey, published);
             active = published;
           }
@@ -1949,10 +2056,7 @@ export function resolveGeometryInstanceBuffer(
 }
 
 export function resolveProbeBlendBuffer(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
+  c: _InternalRenderPipelineContext,
   record: import('../scene/probe-blend-record').ProbeBlendRecord | undefined,
   entityKey?: number,
 ): { readonly buffer: Buffer; readonly offset: number } {
@@ -2000,10 +2104,7 @@ export function resolveProbeBlendBuffer(
 }
 
 export function resolveGeometryInstancesBindGroup(
-  c: Pick<
-    _InternalRenderPipelineContext,
-    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
-  >,
+  c: _InternalRenderPipelineContext,
   instanceBuffer: Buffer,
   probeBuffer?: Buffer,
 ): BindGroup {
@@ -2013,8 +2114,13 @@ export function resolveGeometryInstancesBindGroup(
       ? pipelineState.instancesBindGroupLayout
       : pipelineState.probeInstancesBindGroupLayout;
   if (layout === undefined) throw new Error('probe instances bind-group layout is unavailable');
+  // A few record-only fixtures construct a minimal frame state and omit the
+  // shared bind-group cache. Production frames always provide it, but keeping
+  // this resolver total lets those fixtures exercise the same binding path
+  // without weakening the production cache contract.
+  const instancesBgShared = frameState.instancesBgShared ?? new WeakMap<object, unknown>();
   return getOrCreateFromChain(
-    frameState.instancesBgShared,
+    instancesBgShared,
     probeBuffer === undefined ? [layout, instanceBuffer] : [layout, instanceBuffer, probeBuffer],
     probeBuffer === undefined ? 'instances-no-probe' : 'instances-probe',
     () => {