@forgeax/engine-render 0.1.24 → 0.1.25

package/src/record/render-context.ts

@@ -26,6 +26,7 @@ import {
   type MaterialShaderArtifact,
 } from '@forgeax/engine-shader';
 import type {
+  MaterialAsset,
   MaterialRenderState,
   ParamSchemaEntry,
   PassKind,
@@ -155,6 +156,9 @@ export interface RenderSystemRuntime {
   readonly errorRegistry: RhiErrorListenerRegistry;
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly healthRegistry: HealthListenerRegistry;
+  readonly getMaterialProjectionForPayload?: (
+    material: MaterialAsset,
+  ) => MaterialRenderProjection | undefined;
   readonly getMaterialProjection?: (materialGuid: string) => MaterialRenderProjection | undefined;
   readonly getMaterialArtifact?: (specializationKey: string) => MaterialRuntimeArtifact | undefined;
   /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */

package/src/record/shadow-pass.ts

@@ -8,14 +8,8 @@ import {
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
 import type { MaterialRenderState, PassSelector } from '@forgeax/engine-types';
-import { GpuBuffer } from '../gpu-resource';
-import {
-  GPU_BUFFER_USAGE_COPY_DST,
-  GPU_BUFFER_USAGE_STORAGE,
-  GPU_BUFFER_USAGE_UNIFORM,
-} from '../gpu-usage';
+import type { GpuBuffer } from '../gpu-resource';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
-import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import {
   buildPbrMaterialUserRegionEntries,
   createPbrSkinMeshBindGroupEntries,
@@ -26,15 +20,15 @@ import {
 import { COOKIE_MATRIX_BYTES } from '../prepare/extended-lighting/resources';
 import type { DispatchEntry, ExtractedLights } from '../render-system-extract';
 import { matchPass } from '../systems/pass-selector';
-import { worldEntityKey } from './frame-snapshot';
-import { resolveGeometryInstancesBindGroup } from './main-pass-geometry';
+import {
+  resolveGeometryInstanceBuffer,
+  resolveGeometryInstancesBindGroup,
+} from './main-pass-geometry';
 import {
   getOrCreateFromChain,
-  MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
   MESH_SSBO_BYTES,
   MESH_UBO_FULL_ARRAY_BYTES,
-  packInstanceStorageBuffer,
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
 import { STANDARD_PBR_UBO_SIZE } from './render-context';
@@ -253,13 +247,16 @@ function ensureTypedShadowViewBg(
 }
 
 interface ShadowDispatch {
+  readonly materialHandle: number;
   readonly materialShaderId: string;
   readonly renderState: MaterialRenderState | undefined;
+  readonly materialSlot: number | undefined;
+  readonly paramSnapshot: DispatchEntry['paramSnapshot'];
 }
 
 type ShadowDispatchMap = ReadonlyMap<number, ReadonlyMap<number, ShadowDispatch>>;
 
-function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
+export function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
   const shaders = new Map<number, Map<number, ShadowDispatch>>();
   for (const entry of c.dispatch) {
     if (entry.tags.LightMode === 'ShadowCaster' && entry.materialShaderId !== undefined) {
@@ -268,9 +265,20 @@ function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
         byMaterial = new Map<number, ShadowDispatch>();
         shaders.set(entry.renderableIndex, byMaterial);
       }
+      const candidateSlots =
+        c.materialSlotIndices[entry.renderableIndex] ?? c.materialSlotIndices.flat();
+      const materialSlot = candidateSlots.find(
+        (slot) => c.materialSlots[slot]?.materialHandle === entry.materialHandle,
+      );
       byMaterial.set(entry.materialHandle, {
-        materialShaderId: entry.materialShaderId,
+        materialHandle: entry.materialHandle,
+        materialShaderId:
+          entry.materialShaderId === 'forgeax::default-standard-pbr'
+            ? SHADOW_CASTER_SHADER_ID
+            : entry.materialShaderId,
         renderState: entry.renderState,
+        materialSlot,
+        paramSnapshot: entry.paramSnapshot,
       });
     }
   }
@@ -640,89 +648,25 @@ function recordShadowCasterDraws(
       shadowPass.setBindGroup(2, shadowMeshBindGroup, [i * MESH_PER_ENTITY_STRIDE]);
     }
 
-    // C1 + C2 (w12): per-entity instance buffer + instanceCount
-    let shadowInstanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
-    let shadowInstanceCount = 1;
-    const shadowInst = entry.source.instances;
-    if (shadowInst?.instanceCount === 0) continue;
-    if (shadowInst !== undefined) {
-      const uniformFallback = runtime.device.caps.storageBuffer === false;
-      // Over-cap uniform fallback can't fit the per-instance window — bind
-      // identity and let the shader collapse (same semantics as the main
-      // pass). Otherwise build/upload the per-entity instance buffer: storage
-      // by default, uniform when the device lacks storage buffers.
-      if (uniformFallback && shadowInst.instanceCount > MAX_UNIFORM_INSTANCES) {
-        shadowInstanceCount = shadowInst.instanceCount;
-        shadowInstanceBuffer = pipelineState.identityInstanceBuffer;
-      } else {
-        const bufUsage = uniformFallback
-          ? GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST
-          : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
-        const instancePayload = uniformFallback
-          ? shadowInst.transforms
-          : packInstanceStorageBuffer(shadowInst.transforms);
-        const requestedBytes = instancePayload.byteLength;
-        const cached = c.frameState.instanceBuffers.get(
-          worldEntityKey(entry.source.worldId, shadowInst.cacheKey),
-        );
-        let active: InstanceBufferCacheEntry | null = null;
-        if (
-          cached !== undefined &&
-          cached.uploadedArchVersion === shadowInst.archVersion &&
-          cached.uploadedByteLength === requestedBytes
-        ) {
-          active = cached;
-        } else if (requestedBytes > 0) {
-          const bufRes = runtime.device.createBuffer({
-            size: requestedBytes,
-            usage: bufUsage,
-            mappedAtCreation: false,
-          });
-          if (!bufRes.ok) {
-            runtime.errorRegistry.fire(bufRes.error);
-          } else {
-            // feat-20260619 M4 / F12: destroy the old cached buffer
-            // before replacing it with the new one (D-6).
-            if (cached !== undefined && !cached.buffer.isDestroyed) {
-              const r = cached.buffer.destroy();
-              if (!r.ok) runtime.errorRegistry.fire(r.error);
-            }
-            const newBuffer = new GpuBuffer(runtime.device, bufRes.value);
-            active = {
-              buffer: newBuffer,
-              uploadedArchVersion: shadowInst.archVersion,
-              uploadedByteLength: requestedBytes,
-            };
-            c.frameState.instanceBuffers.set(
-              worldEntityKey(entry.source.worldId, shadowInst.cacheKey),
-              active,
-            );
-          }
-        }
-        if (active !== null) {
-          const writeRes = runtime.device.queue.writeBuffer(
-            active.buffer.handle,
-            0,
-            instancePayload,
-          );
-          if (!writeRes.ok) {
-            runtime.errorRegistry.fire(writeRes.error);
-          } else {
-            shadowInstanceBuffer = active.buffer.handle;
-            shadowInstanceCount = Math.max(1, shadowInst.instanceCount);
-          }
-        }
-      }
-    }
+    // Main and shadow passes share one instance residency owner and upload receipt.
+    const shadowInstanceDraws = resolveGeometryInstanceBuffer(
+      c,
+      entry,
+      [
+        {
+          instanceBuffer: pipelineState.identityInstanceBuffer,
+          instanceBindGroup: resolveGeometryInstancesBindGroup(
+            c,
+            pipelineState.identityInstanceBuffer,
+          ),
+          instanceCount: 1,
+          probeOffset: -1,
+        },
+      ],
+      false,
+    );
+    if (shadowInstanceDraws === null) continue;
 
-    // Bind per-entity instances BG for @group(3) (or fallback identity).
-    // D-4: write end of the HDRP shadow-instances producer/consumer pair.
-    // outerKey = worldEntityKey(entry.source.worldId, entry.source.entityKey),
-    // handle = shadowInstanceBuffer; the HDRP main pass read end (:3820 below)
-    // must look up the same (compositeKey, instBuffer) leaf or the shadow
-    // instances silently drop.
-    const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);
-    shadowPass.setBindGroup(3, shadowInstancesBg);
     // feat-20260608 M4 / w16: per-submesh shadow draw loop.
     // Only draw submeshes whose topology is triangle-list or triangle-strip
     // (line-list / point-list submeshes cast no shadow and are skipped).
@@ -772,10 +716,13 @@ function recordShadowCasterDraws(
         shadowPass.setPipeline(entryShadowPipeline);
         shadowLastPipeline = entryShadowPipeline;
       }
-      if (entry.mesh.indexed) {
-        shadowPass.drawIndexed(sm.indexCount, shadowInstanceCount, sm.indexOffset, 0, 0);
-      } else {
-        shadowPass.draw(sm.vertexCount, shadowInstanceCount, 0, 0);
+      for (const instanceDraw of shadowInstanceDraws) {
+        shadowPass.setBindGroup(3, instanceDraw.instanceBindGroup);
+        if (entry.mesh.indexed) {
+          shadowPass.drawIndexed(sm.indexCount, instanceDraw.instanceCount, sm.indexOffset, 0, 0);
+        } else {
+          shadowPass.draw(sm.vertexCount, instanceDraw.instanceCount, 0, 0);
+        }
       }
     }
   }

package/src/recovery/render-system-candidate.ts

@@ -28,6 +28,7 @@ import {
   postProcessShaderEntrySignature,
 } from '../fullscreen-post-process-pass';
 import { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import { disposeInstanceBufferChunks, disposeInstanceBuffers } from '../instance-buffer-cache';
 import { inspectStandardLighting } from '../pipeline/standard-lighting/inspection';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import { inspectPointShadow } from '../point-shadow-inspection';
@@ -35,6 +36,7 @@ import type { PreparedGraphicsResolver } from '../prepare/prepared-graphics-reso
 import { validateRenderables } from '../record/frame';
 import { prepareFrameLighting } from '../record/frame-lighting';
 import type { RenderFrameState, ValidatedRenderable } from '../record/frame-snapshot';
+import { resolveGeometryInstanceBuffer } from '../record/main-pass-geometry';
 import { computeSplitLdrSprite } from '../record/main-pass-sprite-draws';
 import {
   prepareRecoveryPipelineReadiness,
@@ -121,7 +123,7 @@ export interface RenderSystemRecoveryOwner {
   setLastSuccessfulFrameSeed(seed: RecoveryFrameSeed): void;
   prepareRecoveryGraphCandidate(
     runtime: RecoveryGraphCandidateRuntime,
-  ): RecoveryGraphCandidatePreparation;
+  ): Promise<RecoveryGraphCandidatePreparation>;
   submitCandidateSetup(
     candidate: RecoveryGraphCandidate,
     isValid: () => boolean,
@@ -225,6 +227,8 @@ export function createRenderSystemRecovery(
       currentDirectionalShadowView: null,
       currentSpotShadowView: null,
       instanceBuffers: new Map(),
+      instanceBufferChunks: new Map(),
+      instanceResidency: new Map(),
       morphBuffers: new Map(),
       hdrpClusterBinScratch: createClusterBinScratch(),
       hdrpClusterGridScratch: null,
@@ -313,9 +317,9 @@ export function createRenderSystemRecovery(
     candidate.release();
   };
 
-  const prepareRecoveryGraphCandidate = (
+  const prepareRecoveryGraphCandidate = async (
     runtime: RecoveryGraphCandidateRuntime,
-  ): RecoveryGraphCandidatePreparation => {
+  ): Promise<RecoveryGraphCandidatePreparation> => {
     const seed = lastSuccessfulFrameSeed;
     if (seed === undefined) return { kind: 'no-seed' };
     const camera = seed.frame.cameras[0];
@@ -382,6 +386,13 @@ export function createRenderSystemRecovery(
       candidateGpuDrivenScene = undefined;
       candidatePointsLines?.release();
       candidatePointsLines = undefined;
+      disposeInstanceBuffers(candidateFrameState.instanceBuffers, runtime.internals.errorRegistry);
+      if (candidateFrameState.instanceBufferChunks !== undefined) {
+        disposeInstanceBufferChunks(
+          candidateFrameState.instanceBufferChunks,
+          runtime.internals.errorRegistry,
+        );
+      }
       candidateGpuStore.destroyAll();
     };
     const markPublished = (): void => {
@@ -403,10 +414,17 @@ export function createRenderSystemRecovery(
       if (!gpuScene.ok) return failed('candidate GPU scene preparation failed', gpuScene.error);
       candidateGpuDrivenScene = gpuScene.value;
       if (candidateGpuDrivenScene.state !== undefined) {
-        candidateGpuDrivenProduction = GpuDrivenProduction.forDevice(
+        const production = await GpuDrivenProduction.forRecoveryDevice(
           runtime.internals.device,
           gpuDrivenShaderFactory,
+          (descriptor) =>
+            internals.createShaderModule === undefined
+              ? Promise.resolve(gpuDrivenShaderFactory.createShaderModule(descriptor))
+              : internals.createShaderModule(runtime.internals.device, descriptor),
         );
+        if (!production.ok)
+          return failed('candidate GPU-driven shader preparation failed', production.error);
+        candidateGpuDrivenProduction = production.value;
         const prepared = candidateGpuDrivenProduction.prepare({
           scene: candidateGpuDrivenScene.state,
           camera,
@@ -578,6 +596,25 @@ export function createRenderSystemRecovery(
       if (candidateValidated.length !== seed.frame.renderables.length) {
         return failed('candidate validation did not retain every LKG-visible renderable');
       }
+      for (const entry of candidateValidated) {
+        if (entry.source.instances === undefined) continue;
+        const prepared = resolveGeometryInstanceBuffer(
+          {
+            runtime: runtime.internals,
+            pipelineState: runtime.pipelineState,
+            frameState: candidateFrameState,
+            bindGroupCounts: { createBindGroup: 0, keys: [] },
+          },
+          entry,
+          [],
+          false,
+        );
+        if (prepared === null) return failed('candidate instance preparation failed');
+      }
+      // These uploads belong to recovery preparation, never to a rendered frame.
+      for (const [id, residency] of candidateFrameState.instanceResidency ?? []) {
+        candidateFrameState.instanceResidency?.set(id, { ...residency, frameNumber: -1 });
+      }
       const lighting = prepareFrameLighting(
         runtime.internals,
         candidateFrameState,

package/src/render-contract.ts

@@ -42,6 +42,7 @@ import type {
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types';
+import type { InstanceCollectionInspection } from './instances';
 import type { SsrAdmissionIdentity } from './ssr/identity';
 import type {
   RenderTarget,
@@ -294,6 +295,7 @@ export interface SpotLightProjectorFrameContext {
  * leases, receipts, inspection PODs, and recovery Result values.
  */
 export interface Renderer {
+  /** Renderer-owned authoring and update path for large instance collections. */
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
@@ -509,6 +511,8 @@ export interface RenderInspection {
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
   readonly frustumStats: { readonly culled: number; readonly total: number };
   readonly visibilityStats: { readonly explicitlyHidden: number };
+  /** Renderer-owned large-instance residency and upload facts. */
+  readonly instanceCollections: readonly InstanceCollectionInspection[];
   readonly renderScene: RenderSceneInspection;
   readonly reflectionProbes: ReflectionProbeInspection;
   /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */

package/src/render-system-extract-tail.ts

@@ -88,7 +88,8 @@ import type {
 } from './features/types';
 import { ensureGlyphMeshMaterialSlots } from './glyph-text-layout-system';
 import type { GpuDrivenGeometryReceipt } from './gpu-driven/prepared-draw';
-import { deriveInstancesUnionBounds } from './instances-derived-bounds';
+import type { InstanceProjectionStore } from './instances';
+import { deriveInstancesUnionBounds, fingerprintNumericArray } from './instances-derived-bounds';
 import {
   type MeshMaterialBindingDiagnostic,
   type MeshMaterialBindingSource,
@@ -156,7 +157,7 @@ import {
   readStablePersistentMaterialSnapshot,
   resolveMaterialSnapshot,
   resolveVideoFieldHandle,
-  runtimeMaterialShaderId,
+  runtimeMaterialShaderIdForMaterial,
   Severity,
   selectCameraRoles,
   selectFogFrame,
@@ -175,9 +176,12 @@ export function extractFrames(
   options: {
     readonly cull?: 'normal' | 'none';
     readonly renderables?: 'full' | 'none';
+    readonly renderableEntitiesByWorld?: readonly (ReadonlySet<number> | undefined)[];
+    readonly retainHidden?: boolean;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
     ) => MaterialShaderArtifact | undefined;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): ExtractedFrame {
   // w4: normalize the owner argument. A bare number is the legacy single-owner
@@ -249,9 +253,16 @@ export function extractFrames(
             }),
         cull: options.cull === 'none' ? 'none' : isCameraOwner ? 'self' : 'external',
         renderables: options.renderables ?? 'full',
+        ...(options.renderableEntitiesByWorld?.[wi] === undefined
+          ? {}
+          : { renderableEntities: options.renderableEntitiesByWorld[wi] }),
+        retainHidden: options.retainHidden ?? false,
         ...(options.getMaterialShaderArtifact === undefined
           ? {}
           : { getMaterialShaderArtifact: options.getMaterialShaderArtifact }),
+        ...(options.instanceCollections === undefined
+          ? {}
+          : { instanceCollections: options.instanceCollections }),
         ...(cameraOwnerFrame === undefined ? {} : { cullCameras: cameraOwnerFrame.cameras }),
       });
       const frame = extractFrame(world, prepared);
@@ -495,6 +506,30 @@ export function extractFrames(
     return (f.reflectionProbes ?? []).map((probe) => ({ ...probe, worldId }));
   });
 
+  if (options.renderables !== 'none' && options.renderableEntitiesByWorld === undefined) {
+    options.instanceCollections?.retain(
+      new Set(
+        renderables.flatMap((row) =>
+          row.instances?.collectionId === undefined ? [] : [row.instances.collectionId],
+        ),
+      ),
+    );
+    if (
+      skinPaletteAllocator !== null &&
+      typeof skinPaletteAllocator.retainSliceKeys === 'function'
+    ) {
+      skinPaletteAllocator.retainSliceKeys(
+        new Set(
+          renderables.flatMap((row) =>
+            row.skin === undefined
+              ? []
+              : [`${worlds[row.worldId]?.identity ?? row.worldId}:${row.entityKey}`],
+          ),
+        ),
+      );
+    }
+  }
+
   return {
     cameras,
     auxiliaryCameras,
@@ -604,6 +639,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     cull: cullMode,
     resourceOwnerFog,
     getMaterialShaderArtifact,
+    instanceCollections,
+    renderableEntities,
+    retainHidden,
   } = context;
   // Environment reads are owned by the retained resource projection and are
   // established at the frame boundary; record never revisits World state.
@@ -1525,18 +1563,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // through one World-owned Query. K-2 sniffing scheme B
   // (`row.get(X) !== undefined` edge sniff) replaces the prior
   // `arch.components.some` row-internal back-door. K-3 invariant: the
-  // variable-length array reads (`MeshRenderer.materials`,
-  // `Instances.transforms`) still flow through `_getArrayView` /
-  // `world.get(e, Instances)` -- only the `entity` source switches to
-  // `row.entity`.
+  // variable-length array reads (`MeshRenderer.materials`, SpriteInstances
+  // arrays) still flow through `_getArrayView`; explicit Instances bytes also come
+  // from World, before projection into renderer-owned snapshots.
   //
-  // archVersion plumbing exception: the `RenderableSnapshot.instances
-  // .archVersion` cache key is keyed off the live archetype's mutation
-  // counter (record stage `instanceBuffers` cache invalidation). The
-  // QueryRow does not surface this number, so a single archetype
-  // graph access is retained for instance-bearing rows -- match by entity
-  // packed handle. AC-01 grep ≤ current - 1 still holds: the stale
-  // archetype-graph traversal commentary at the prior call site is gone.
+  // archVersion remains the content fingerprint for SpriteInstances' managed
+  // arrays; explicit Instances use the collection revision below and never
+  // need an archetype graph access for their matrix bytes.
   // feat-20260521-sprite-atlas-animation M3 / T-16: SpriteRegionOverride
   // column id for the sprite-bucket per-entity region override read
   void SpriteRegionOverride;
@@ -1564,11 +1597,10 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           })
           .unwrap();
   // QueryRow deliberately exposes component data, not an archetype version.
-  // The optimized ECS owner keeps table storage private, so instance-buffer
-  // invalidation uses a content fingerprint of the managed arrays instead.
+  // SpriteInstances still uses a content fingerprint for its managed arrays;
+  // explicit Instances use the renderer-owned collection revision below.
   const resolveArchVersion = (entity: EntityHandle): number => {
     const values = [
-      worldInternal._getArrayView(entity, Instances, 'transforms'),
       worldInternal._getArrayView(entity, SpriteInstances, 'transforms'),
       worldInternal._getArrayView(entity, SpriteInstances, 'regions'),
     ];
@@ -1591,6 +1623,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     for (const entry of pending) dispatch.push(entry);
   };
   for (const row of meshRendererQuery) {
+    if (
+      context.renderables === 'full' &&
+      renderableEntities !== undefined &&
+      !renderableEntities.has(row.entity)
+    ) {
+      continue;
+    }
     // K-2 archetype-edge sniff (scheme B): a missing optional component
     // surfaces as an absent bundle key, not a row-internal optional chain.
     // Presence-only checks use QueryRow.has so large array-bearing components
@@ -1687,8 +1726,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     {
       // feat-20260608 M2 / w11: read materials array via _getArrayView
       const entity = row.entity;
-      if (isRenderable && visibility?.effective(entity) === 'hidden') {
-        explicitlyHidden.add(entity);
+      const authorVisible = !(isRenderable && visibility?.effective(entity) === 'hidden');
+      if (!authorVisible) explicitlyHidden.add(entity);
+      if (!authorVisible && !retainHidden) {
         continue;
       }
       const layerVal = fLayerValue ?? 0;
@@ -1886,6 +1926,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             renderables.length,
             layerVal,
             materialSnap.paramSnapshot,
+            0,
+            materialSnap.materialShaderId,
           );
         }
       } else if (handleRaw === 0 || assets === undefined || assets === null) {
@@ -1913,6 +1955,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               renderables.length,
               layerVal,
               materialSnap.paramSnapshot,
+              0,
+              materialSnap.materialShaderId,
             );
           }
         } else {
@@ -1976,10 +2020,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             }
             const resolved = resolvedResult.value;
             const allPasses = resolved.passes;
-            const firstPassShader =
-              allPasses.length > 0
-                ? runtimeMaterialShaderId(allPasses[0]?.program.module, allPasses[0]?.name)
-                : undefined;
+            const firstPassShader = runtimeMaterialShaderIdForMaterial(asset, allPasses, assets);
             const pv = materialValuesToLinearRuntime(
               resolved.values,
               materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assets),
@@ -2357,6 +2398,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 renderables.length,
                 layerVal,
                 paramSnap,
+                0,
+                firstPassShader,
               );
             }
           }
@@ -2512,7 +2555,18 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             // surface is absent (test fixtures that pass undefined) the
             // hasSkin segment is skipped silently — bind-pose equivalent.
             if (skinPaletteAllocator !== null) {
-              const slice = skinPaletteAllocator.allocateSlice(skeleton.jointCount);
+              // Keep the narrow extraction seam compatible with older test or
+              // host-owned allocator doubles while the real renderer uses the
+              // stable-key path. The fallback is frame-local and therefore
+              // cannot affect production allocators that implement the new
+              // method.
+              const slice =
+                typeof skinPaletteAllocator.allocateSliceFor === 'function'
+                  ? skinPaletteAllocator.allocateSliceFor(
+                      `${world.identity}:${entity}`,
+                      skeleton.jointCount,
+                    )
+                  : skinPaletteAllocator.allocateSlice(skeleton.jointCount);
               skinPaletteAllocator.writeJointPalette(slice, ibms, jointWorlds);
               skinSlice = {
                 jointCount: slice.jointCount,
@@ -2584,6 +2638,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               renderables.length,
               layerVal,
               materialsArr[mi]?.paramSnapshot,
+              0,
+              materialsArr[mi]?.materialShaderId,
             );
           }
         }
@@ -2727,39 +2783,35 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // Instances are snapshotted before the CPU visibility decision so the
         // culling owner can derive the union of every instance's transformed
         // mesh bounds. The same detached snapshot is then carried to record;
-        // do not re-read the ECS array after culling (a structural write must
-        // not make the cull and draw disagree within one frame).
+        // do not re-read the collection after culling (a mutation must not
+        // make the cull and draw disagree within one frame).
         let instancesSnap: InstancesSnapshot | undefined;
         if (hasInstances) {
-          const transforms = worldInternal._getArrayView(entity, Instances, 'transforms');
-          if (transforms === undefined) {
-            // A present component with an unavailable array is an empty
-            // instance contribution, not an absent component. Preserve the
-            // zero-draw contract so the record stage cannot synthesize one
-            // identity instance from an incomplete row.
-            instancesSnap = {
-              transforms: new Float32Array(),
-              instanceCount: 0,
-              cacheKey: entity,
-              archVersion,
-            };
-          } else {
-            const actualLength = transforms.length;
-            if (actualLength % 16 !== 0) {
-              worldInternal._routeError(new InstanceTransformsStrideMismatchError(actualLength), {
+          const transforms =
+            worldInternal._getArrayView(entity, Instances, 'transforms') ?? new Float32Array();
+          if (transforms.length % 16 !== 0) {
+            worldInternal._routeError(
+              new InstanceTransformsStrideMismatchError(transforms.length),
+              {
                 severity: Severity.Error,
                 systemName: 'RenderSystem.extract (Instances stride)',
-              });
-              continue;
-            }
-            const snapshotCopy = new Float32Array(transforms);
-            instancesSnap = {
-              transforms: snapshotCopy,
-              instanceCount: actualLength / 16,
-              cacheKey: entity,
-              archVersion,
-            };
+              },
+            );
+            continue;
           }
+          const projected = instanceCollections?.project(world, entity, transforms);
+          instancesSnap = {
+            transforms: projected?.transforms ?? new Float32Array(transforms),
+            instanceCount: transforms.length / 16,
+            cacheKey: entity,
+            archVersion: projected === undefined ? fingerprintNumericArray(transforms) : 0,
+            ...(projected === undefined
+              ? {}
+              : {
+                  collectionId: projected.collectionId,
+                  revision: projected.revision,
+                }),
+          };
         }
 
         const baseRenderable: RenderableSnapshot = {
@@ -2774,7 +2826,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           materialBindingDiagnostics,
           worldId: 0,
           entityKey: entity,
+          ...(authorVisible ? {} : { authorVisible: false }),
           ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
+          ...(skin?.joints === undefined
+            ? {}
+            : { skinJointEntities: Array.from(skin.joints, (joint) => Number(joint)) }),
           ...(morph !== undefined ? { morph } : {}),
           ...(instancesSnap !== undefined ? { instances: instancesSnap } : {}),
           ...(spriteInstancesSnap !== undefined ? { spriteInstances: spriteInstancesSnap } : {}),