@forgeax/engine-render 0.1.24 → 0.1.26

package/src/render-system-extract.ts

@@ -1,3 +1,4 @@
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
 // @forgeax/engine-runtime - RenderSystem Extract stage (D-S2 + plan-strategy R-15
 // fallback split). Pure ECS query phase: walks Camera / DirectionalLight /
 // the merged-MeshRenderer renderable archetype and produces SoA-free snapshot
@@ -75,31 +76,15 @@
 //                               `MeshFilter.assetHandle` dangling path
 //                               (charter proposition 5; AC-11).
 //
-// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w15:
-//   The legacy `Instances { buffer, count }` form (cross-coupled with the
-//   deleted `AssetRegistry.createInstancedBuffer` triplet + the retired
-//   `InstancedBufferAsset` POD) is gone. Per-entity instance transforms now
-//   live inside the ECS `Instances { transforms: 'array<f32>' }` column;
-//   extract materialises a `Float32Array` snapshot per Instances-bearing
-//   entity (via `world.get(e, Instances).transforms`) so the record stage
-//   can upload to a per-entity GPU storage buffer cached by entity packed
-//   u32.
-//
-// feat-20260515-buffer-array-vocab-collapse M3 / w15: the component-level
-// `arrayStride` hook on `Instances.transforms` was retired (decision section
-// 2.3 stride responsibility migration -- AI users gate at the set / push
-// call sites + RenderSystem extract entry holds a defensive fail-fast).
-// The extract entry checks `transforms.length % 16 === 0` directly after
-// the `world.get(entity, Instances)` snapshot is taken; violations route
-// `InstanceTransformsStrideMismatchError`
-// (`code: 'instance-transforms-stride-mismatch'`,
-// `detail: { actualLength, expectedStride: 16 }`) through the World
-// Layer-3 ErrorHandler and the renderable is skipped. The record stage
-// trusts the invariant and does not re-check.
+// World owns explicit Instances transforms. Extraction makes a detached
+// per-renderer projection; GPU residents acknowledge complete snapshots only
+// after successful uploads. Reading a snapshot never changes author state.
 
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
+  materialParametersToParamSchema as projectMaterialParametersToParamSchema,
   resolveAssetHandle,
+  selectMaterialPassProgram,
   walkMaterialPassesOverSharedRefs,
 } from '@forgeax/engine-assets-runtime';
 import type { Component, ComponentSchema, EntityHandle, Query, World } from '@forgeax/engine-ecs';
@@ -166,6 +151,7 @@ import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
+import type { InstanceCollectionId, InstanceProjectionStore } from './instances';
 import type {
   MeshMaterialBindingDiagnostic,
   MeshMaterialBindingSource,
@@ -696,6 +682,8 @@ export interface RenderableSnapshot {
   readonly materialBindingSources: readonly MeshMaterialBindingSource[];
   /** Active structured override diagnostics for this renderable. */
   readonly materialBindingDiagnostics?: readonly MeshMaterialBindingDiagnostic[];
+  /** Effective authored visibility retained by the persistent scene owner. */
+  readonly authorVisible?: boolean;
   /**
    * feat-20260708-composited-multi-world-rendering M1 / D-1: the worldId
    * of the world this renderable was extracted from. Defaults to 0 in
@@ -761,6 +749,8 @@ export interface RenderableSnapshot {
    * Absent (`undefined`) means the entity is not skinned.
    */
   readonly skin?: SkinPaletteSlice;
+  /** Joint entity identities used by the persistent skin dependency index. */
+  readonly skinJointEntities?: readonly number[];
   /**
    * ECS-owned morph weights. Presence selects the Standard Pipeline CPU
    * specialized deformation lane; the asset remains the source of target
@@ -822,10 +812,14 @@ export interface GpuDrivenDrawSnapshot {
 }
 
 export interface InstancesSnapshot {
+  /** Renderer-owned collection identity. */
+  readonly collectionId?: InstanceCollectionId;
   /** Packed column-major mat4 transforms (16 f32 per instance). */
   readonly transforms: Float32Array;
   /** Number of instances (transforms.length / 16). */
   readonly instanceCount: number;
+  /** Collection revision captured by this detached frame snapshot. */
+  readonly revision?: number;
   /** Stable per-entity GPU buffer cache key (the packed Entity u32). */
   readonly cacheKey: number;
   /**
@@ -918,6 +912,7 @@ export interface MaterialSnapshot {
    * discriminator (M4-T06).
    */
   readonly materialShaderId?: string | undefined;
+  readonly materialProgramKeys?: Readonly<Record<string, string>> | undefined;
   /**
    * Stable source handle for the material asset. Record uses this only for
    * same-frame assembly reuse; GPU bind-group validity still comes from the
@@ -1024,12 +1019,9 @@ export interface MaterialSnapshot {
    * from the legacy `shadingModel` discriminant (feat-20260625 M2 D-3,
    * finalised in w15; `shadingModel` field removed in tweak-20260701 M1).
    *
-   * Extract derives this from the first pass's `renderState.blend !==
-   * undefined` (post-feat-20260626-collapse: blend presence is the
-   * single SSOT for "this material is transparent on the geometry
-   * pipeline cache key"). Multi-pass materials whose mix of opaque +
-   * transparent passes need finer routing should split into separate
-   * MaterialAsset entries (the normal forgeax pattern).
+   * This describes the primary-pass snapshot for consumers that need a
+   * material summary. Actual draw routing and the LDR split read the selected
+   * DispatchEntry.renderState, so mixed opaque/transparent Passes remain valid.
    *
    * Type is `boolean | undefined` (derived): `undefined` means "no
    * passes / unknown"; consumers must read `=== true` / `!== true` to
@@ -1134,6 +1126,7 @@ export function appendMaterialDispatchEntries(
   layer: number,
   paramSnapshot: Readonly<Record<string, number | number[] | string>> | undefined,
   passIndexOffset = 0,
+  materialProgramKeys?: Readonly<Record<string, string>>,
 ): void {
   const matchedPasses = selectPasses(passes, {});
   for (let pIdx = 0; pIdx < matchedPasses.length; pIdx++) {
@@ -1144,6 +1137,11 @@ export function appendMaterialDispatchEntries(
       readonly queue?: number;
       readonly stencilReference?: number;
     };
+    const authoredShaderId = runtimeMaterialShaderId(pass.program.module, pass.name);
+    const dispatchShaderId =
+      materialProgramKeys === undefined ? authoredShaderId : materialProgramKeys[pass.name];
+    if (materialProgramKeys !== undefined && dispatchShaderId === undefined)
+      throw new Error(`Missing published material program for Pass ${pass.name}`);
     pendingDispatch.push({
       entityIndex: entity,
       materialHandle,
@@ -1158,7 +1156,7 @@ export function appendMaterialDispatchEntries(
       defines: undefined,
       vertexEntry: pass.program.vertexEntry,
       fragmentEntry: pass.program.fragmentEntry,
-      materialShaderId: runtimeMaterialShaderId(pass.program.module, pass.name),
+      materialShaderId: dispatchShaderId,
       paramSnapshot,
       ...(passState.stencilReference !== undefined && {
         stencilReference: passState.stencilReference,
@@ -1410,6 +1408,57 @@ export function runtimeMaterialShaderId(
   }
 }
 
+/**
+ * Select the runtime identity for one resolved material. A cooked publication
+ * owns the composed material artifact identity; the authored pass module is
+ * the built-in fallback used before that publication is ready.
+ */
+export function materialProgramKeysForMaterial(
+  material: MaterialAsset,
+  assets: AssetRegistry,
+  context: MaterialCookProgramContext | undefined,
+): Readonly<Record<string, string>> | undefined {
+  const projection = assets.getMaterialProjectionForPayload(material);
+  if (projection === undefined) return undefined;
+  if (context === undefined)
+    throw new Error('Published material selection requires renderer-owned compiler context');
+  return Object.fromEntries(
+    projection.passes.map((pass) => {
+      const mode = String(
+        (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+      );
+      const selectedContext: MaterialCookProgramContext = {
+        ...context,
+        pass: /shadow/i.test(mode) ? 'shadow' : /depth/i.test(mode) ? 'depth' : 'forward',
+        pipeline: /deferred|gbuffer/i.test(mode) ? 'deferred' : context.pipeline,
+      };
+      return [
+        pass.name,
+        selectMaterialPassProgram(projection, pass.name, selectedContext).specializationKey,
+      ];
+    }),
+  );
+}
+
+export function runtimeMaterialShaderIdForMaterial(
+  passes: readonly MaterialPass[],
+  programs: Readonly<Record<string, string>> | undefined,
+): string | undefined {
+  const pass =
+    passes.find(
+      (pass) =>
+        !/shadow|depth/i.test(
+          String(
+            (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+          ),
+        ),
+    ) ?? passes[0];
+  if (pass === undefined) return undefined;
+  return programs === undefined
+    ? runtimeMaterialShaderId(pass.program.module, pass.name)
+    : programs[pass.name];
+}
+
 export function pipelineRenderState(
   renderState:
     | (MaterialRenderState & {
@@ -1714,49 +1763,21 @@ export function isEngineInjectedTextureField(
   return isStandardPbrMaterialShader(shaderId) && ENGINE_INJECTED_TEXTURE_FIELDS.has(fieldName);
 }
 
+/**
+ * Project one material's authoring parameters into the runtime ABI.
+ *
+ * Engine-owned Standard roots are compiled against the canonical superset
+ * schema even when the authoring asset omits optional physical fields. A
+ * compact authored schema would move later UBO members (for example `ior`)
+ * into the wrong slots. Custom material roots keep their own published
+ * parameter projection.
+ */
 export function materialParametersToParamSchema(
   parameters: readonly MaterialParameter[],
-  shaderId: string | undefined,
+  shaderId?: string,
 ): readonly ParamSchemaEntry[] {
-  // Engine-owned Standard modules are compiled once against the canonical
-  // boot schema. Materials.standard() exposes a smaller authoring projection,
-  // but using that compact projection as the runtime UBO schema would shift
-  // every field after an omitted physical entry.
-  if (isCanonicalStandardPbrMaterialShader(shaderId)) {
-    return STANDARD_PIPELINE_PARAM_SCHEMA;
-  }
-  const engineInjectedTextureFields = isStandardPbrMaterialShader(shaderId)
-    ? ENGINE_INJECTED_TEXTURE_FIELDS
-    : undefined;
-  return parameters.flatMap((parameter): ParamSchemaEntry[] => {
-    // Boolean material values are runtime-only and have no UBO representation.
-    if (parameter.type === 'bool') return [];
-    if (parameter.type === 'texture' || parameter.type === 'texture_cube') {
-      if (engineInjectedTextureFields?.has(parameter.name) === true) return [];
-      return [
-        {
-          name: parameter.name,
-          type: parameter.type === 'texture_cube' ? 'texture_cube' : 'texture2d',
-          default: parameter.default,
-        },
-      ];
-    }
-    const numericDefault =
-      typeof parameter.default === 'number'
-        ? parameter.default
-        : Array.isArray(parameter.default) &&
-            parameter.default.every((entry) => typeof entry === 'number')
-          ? parameter.default
-          : undefined;
-    const numericEntry = {
-      name: parameter.name,
-      type: parameter.type,
-      ...(parameter.colorSpace === undefined ? {} : { colorSpace: parameter.colorSpace }),
-    };
-    return numericDefault === undefined
-      ? [numericEntry]
-      : [{ ...numericEntry, default: numericDefault }];
-  });
+  if (isCanonicalStandardPbrMaterialShader(shaderId)) return STANDARD_PIPELINE_PARAM_SCHEMA;
+  return projectMaterialParametersToParamSchema(parameters);
 }
 
 /**
@@ -1903,6 +1924,7 @@ export function resolveMaterialSnapshot(
   assetsRef: AssetRegistry,
   materialSnapshotCache?: MaterialSnapshotCache,
   persistentMaterialSnapshotCache?: MaterialSnapshotCache,
+  materialContext?: MaterialCookProgramContext,
 ): MaterialSnapshot {
   if (handleRaw === 0) return defaultMaterialSnapshot(handleRaw);
   const cached = materialSnapshotCache?.get(handleRaw);
@@ -1934,10 +1956,9 @@ export function resolveMaterialSnapshot(
   if (!resolvedResult.ok) return defaultMaterialSnapshot(handleRaw);
   const resolved = resolvedResult.value;
   const allPasses = resolved.passes;
-  const firstPassShader =
-    allPasses.length > 0
-      ? runtimeMaterialShaderId(allPasses[0]?.program.module, allPasses[0]?.name)
-      : undefined;
+  const materialProgramKeys = materialProgramKeysForMaterial(asset, assetsRef, materialContext);
+  const authoredFirstPassShader = runtimeMaterialShaderIdForMaterial(allPasses, undefined);
+  const firstPassShader = runtimeMaterialShaderIdForMaterial(allPasses, materialProgramKeys);
   const pv = materialValuesToLinearRuntime(
     resolved.values,
     materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assetsRef),
@@ -1964,7 +1985,7 @@ export function resolveMaterialSnapshot(
   }
   const materialParamSchema = materialParametersToParamSchema(
     resolved.parameters ?? [],
-    firstPassShader,
+    authoredFirstPassShader,
   );
   // feat-20260614 M8 (D-19): texture / sampler values are embedded GUIDs
   // (dash-form strings) after loadByGuid. Resolve each to a user-tier column
@@ -2032,6 +2053,7 @@ export function resolveMaterialSnapshot(
     }),
     normalScale: normalScalePv,
     materialShaderId: firstPassShader,
+    materialProgramKeys,
     materialHandle: handleRaw,
     renderState: pipelineRenderState(allPasses[0]?.renderState),
     paramSnapshot: paramSnap,
@@ -2533,6 +2555,7 @@ export interface ExtractFramesOwner {
 }
 
 export interface PreparedExtractContext {
+  readonly materialContext?: MaterialCookProgramContext | undefined;
   readonly assets: AssetRegistry | null | undefined;
   readonly pipelineState: ExtractPipelineSurface | null | undefined;
   readonly materialSnapshotCache: MaterialSnapshotCache | undefined;
@@ -2542,11 +2565,17 @@ export interface PreparedExtractContext {
   readonly cull: 'self' | 'none' | 'external';
   readonly cullCameras: readonly CameraSnapshot[] | undefined;
   readonly renderables: 'full' | 'none';
+  /** Restrict renderable extraction to these entities while still reading frame resources. */
+  readonly renderableEntities: ReadonlySet<number> | undefined;
+  /** Keep authored-hidden renderables in the persistent source projection. */
+  readonly retainHidden: boolean;
   readonly visibility: VisibilitySnapshot;
   /** Producer-owned artifact lookup; extraction only, never record-time asset reads. */
   readonly getMaterialShaderArtifact:
     | ((materialShaderId: string) => MaterialShaderArtifact | undefined)
     | undefined;
+  /** Renderer-owned canonical source for explicit large instance collections. */
+  readonly instanceCollections: InstanceProjectionStore | undefined;
 }
 
 const ALL_VISIBLE: VisibilitySnapshot = {
@@ -2727,6 +2756,7 @@ export function tonemapParams(camera: CameraSnapshot): Uint8Array {
 export function prepareExtractContext(
   world: World,
   options: {
+    readonly materialContext?: MaterialCookProgramContext;
     readonly assets?: AssetRegistry | null;
     readonly pipelineState?: ExtractPipelineSurface | null;
     readonly materialSnapshotCache?: MaterialSnapshotCache;
@@ -2734,13 +2764,17 @@ export function prepareExtractContext(
     readonly cull?: 'self' | 'none' | 'external';
     readonly cullCameras?: readonly CameraSnapshot[];
     readonly renderables?: 'full' | 'none';
+    readonly renderableEntities?: ReadonlySet<number>;
+    readonly retainHidden?: boolean;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
     ) => MaterialShaderArtifact | undefined;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): PreparedExtractContext {
   const renderables = options.renderables ?? 'full';
   return {
+    materialContext: options.materialContext,
     assets: options.assets,
     pipelineState: options.pipelineState,
     materialSnapshotCache: options.materialSnapshotCache,
@@ -2748,8 +2782,11 @@ export function prepareExtractContext(
     cull: options.cull ?? 'self',
     cullCameras: options.cullCameras,
     renderables,
+    renderableEntities: options.renderableEntities,
+    retainHidden: options.retainHidden ?? false,
     visibility: renderables === 'none' ? ALL_VISIBLE : resolveVisibility(world),
     getMaterialShaderArtifact: options.getMaterialShaderArtifact,
+    instanceCollections: options.instanceCollections,
   };
 }
 

package/src/render-system.ts

@@ -118,7 +118,13 @@ import type { EnvironmentInspection } from './environment/inspection';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from './gpu-usage';
 import { resetHdrpBuffers } from './hdrp-buffers';
 import { assembleMaterialWithSkylightEntries } from './ibl/skylight-bind-group';
-import { disposeInstanceBuffers, disposeTransientInstanceBuffers } from './instance-buffer-cache';
+import {
+  disposeInstanceBufferChunks,
+  disposeInstanceBuffers,
+  disposeTransientInstanceBuffers,
+} from './instance-buffer-cache';
+import type { InstanceCollectionInspection } from './instances';
+import { InstanceProjectionStore } from './instances';
 import {
   type MeshMaterialBindingObservation,
   type MeshMaterialBindingPreparationFailure,
@@ -182,7 +188,11 @@ import type {
   RenderableSnapshot,
 } from './render-system-extract';
 import { extractFrames } from './render-system-extract';
-import { type PersistentGpuDrivenCandidate, PersistentRenderScene } from './scene/render-scene';
+import {
+  type PersistentGpuDrivenCandidate,
+  type PersistentRenderCandidateRequest,
+  PersistentRenderScene,
+} from './scene/render-scene';
 import { inspectLodOcclusion } from './scene/visibility/inspection';
 import { resolveSsaoParameters } from './ssao-config';
 import { projectSsrDependencies, resolveSsrAdmissionGeneration } from './ssr/admission';
@@ -660,7 +670,7 @@ export interface RenderSystem {
   /** Prepare a detached graph candidate without entering the frame record path. */
   prepareRecoveryGraphCandidate(
     runtime: RecoveryGraphCandidateRuntime,
-  ): RecoveryGraphCandidatePreparation;
+  ): Promise<RecoveryGraphCandidatePreparation>;
   /** Finish and submit detached candidate setup, never a frame receipt. */
   submitCandidateSetup(
     candidate: RecoveryGraphCandidate,
@@ -686,6 +696,8 @@ export interface RenderSystem {
   readonly pipelineDispatchCounts: {
     readonly unlit: number;
   };
+  /** Detached residency and upload facts for explicit instance collections. */
+  readonly instanceCollectionsInspection: readonly InstanceCollectionInspection[];
   /**
    * feat-20260528-frustum-culling M5 / w14: per-frame frustum-culling counters.
    * Updated by `draw([world], { cameraOwner: 0, resourceOwner: 0 })` on every call from the Extract stage.
@@ -1071,6 +1083,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
   let preparedWorlds: readonly World[] = [];
   let latestCamera: CameraSnapshot | undefined;
   const pointsLinesOwner = new StandardPointsLinesOwner(internals);
+  const instanceCollections = new InstanceProjectionStore();
   const reflectionProbeOwner = new ReflectionProbeRecordOwner(internals);
   let ssrFormatReceipt: import('@forgeax/engine-rhi').RhiTextureFormatCapabilityReceipt | undefined;
   let ssrFormatProbeGeneration = -1;
@@ -1112,6 +1125,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     onSharedRefMutation: (worldId, handle) => {
       internals.gpuStore.invalidateMesh(handle, preparedWorlds[worldId] ?? worldId);
     },
+    instanceCollections,
+    getSkinPaletteAllocator: () => internals.getPipelineState()?.skinPaletteAllocator ?? null,
   });
   let environmentLifecycle = new EnvironmentLifecycle(internals.deviceScope);
   const transmissionAdmission = new TransmissionCandidateAdmission();
@@ -1362,6 +1377,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     currentDirectionalShadowView: null,
     currentSpotShadowView: null,
     instanceBuffers: new Map(),
+    instanceResidency: new Map(),
+    instanceBufferChunks: new Map(),
     probeBlendBuffers: new Map(),
     probeBlendRecordBufferCapacity: 0,
     morphBuffers: new Map(),
@@ -2294,6 +2311,12 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     createPreparedResolverCaches,
   });
   return {
+    get instanceCollectionsInspection(): readonly InstanceCollectionInspection[] {
+      return instanceCollections._inspections(
+        frameState.instanceResidency,
+        frameState.frameNumber - 1,
+      );
+    },
     releaseProfilerCatalog(): void {
       releaseProfilerCatalog?.();
       releaseProfilerCatalog = undefined;
@@ -2555,7 +2578,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             compositionWorlds,
             { cameraOwner, resourceOwner },
             internals.assets.catalogEpoch,
-            (renderables) =>
+            (request: PersistentRenderCandidateRequest) =>
               extractFrames(
                 compositionWorlds,
                 { cameraOwner, resourceOwner },
@@ -2563,8 +2586,32 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
                 internals.getPipelineState(),
                 persistentRenderScene.materialSnapshotCacheStore(),
                 {
+                  ...(internals.device.caps.backendKind === 'null'
+                    ? {}
+                    : {
+                        materialContext: {
+                          backend:
+                            internals.device.caps.backendKind === 'wgpu-webgl2'
+                              ? ('webgl2' as const)
+                              : internals.device.caps.backendKind,
+                          capability: internals.device.caps.storageBuffer
+                            ? ('storage-buffer' as const)
+                            : ('uniform-fallback' as const),
+                          pipeline: 'forward' as const,
+                          geometry: 'mesh' as const,
+                          pass: 'forward' as const,
+                          profile: 'forgeax-material-wgsl-v1' as const,
+                          toolchain: 'naga-oil' as const,
+                          instrumentation: 'none' as const,
+                        },
+                      }),
                   cull: 'none',
-                  renderables,
+                  renderables: request === 'none' ? 'none' : 'full',
+                  ...(request === 'none' || request === 'full'
+                    ? {}
+                    : { renderableEntitiesByWorld: request.entitiesByWorld }),
+                  retainHidden: true,
+                  instanceCollections,
                   ...(internals.getMaterialShaderArtifact === undefined
                     ? {}
                     : { getMaterialShaderArtifact: internals.getMaterialShaderArtifact }),
@@ -3496,6 +3543,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       (internals as TimingSessionHost).gpuPassTimingBeginReason = undefined;
       pointsLinesOwner.dispose();
       persistentRenderScene.dispose();
+      instanceCollections.dispose();
       gpuDrivenProduction.dispose();
       occlusionRuntime?.dispose();
       disposeFeatureGpuWork();
@@ -3565,6 +3613,10 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       // so destroy failures fire structured errors (unified per-frame +
       // dispose error strategy).
       disposeInstanceBuffers(frameState.instanceBuffers, internals.errorRegistry);
+      frameState.instanceResidency?.clear();
+      if (frameState.instanceBufferChunks !== undefined) {
+        disposeInstanceBufferChunks(frameState.instanceBufferChunks, internals.errorRegistry);
+      }
       disposeTransientInstanceBuffers(frameState.transientInstanceBuffers, internals.errorRegistry);
       if (frameState.probeBlendRecordBuffer !== undefined) {
         if (!frameState.probeBlendRecordBuffer.isDestroyed) {
@@ -3706,6 +3758,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       }
       frameState.retiredCompiledFrameGraphs.clear();
       frameState.instanceBuffers.clear();
+      frameState.instanceBufferChunks?.clear();
+      frameState.instanceResidency?.clear();
       delete frameState.probeBlendRecordBuffer;
       frameState.probeBlendRecordBufferCapacity = 0;
       frameState.probeBlendBuffers.clear();

package/src/scene/render-scene-types.ts

@@ -36,6 +36,8 @@ export interface RenderSceneApplyResult {
   readonly ignoredLateUpdates: number;
   readonly createdSlots: readonly RenderSceneSlot[];
   readonly updatedSlots: readonly RenderSceneSlot[];
+  /** Full retained-snapshot updates; transform spans stay in updatedSlots only. */
+  readonly contentUpdatedSlots?: readonly RenderSceneSlot[];
   readonly removedSlots: readonly RenderSceneRecord[];
   readonly recreatedSlots: readonly RenderSceneSlot[];
   readonly resynced: number;