@forgeax/engine-render 0.1.24 → 0.1.25

package/src/instances.ts

@@ -0,0 +1,288 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { RhiErrorCode } from '@forgeax/engine-rhi';
+
+const MATRIX_STRIDE = 16;
+
+export type InstanceCollectionId = number & {
+  readonly __forgeaxInstanceCollectionId: unique symbol;
+};
+
+export interface InstanceCollectionInfo {
+  readonly collectionId: InstanceCollectionId;
+  readonly count: number;
+  readonly revision: number;
+}
+
+export interface InstanceUploadRange {
+  start: number;
+  end: number;
+}
+
+export interface InstanceCollectionSnapshot extends InstanceCollectionInfo {
+  readonly transforms: Float32Array;
+}
+
+/** The renderer-owned submission lane selected for one collection. */
+export type InstanceSubmissionLane =
+  | 'unresident'
+  | 'direct-storage'
+  | 'chunked-storage'
+  | 'direct-uniform'
+  | 'chunked-uniform'
+  | 'unavailable';
+
+/** Backend identity carried by collection residency and failure facts. */
+export type InstanceBackendKind = 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null' | 'unknown';
+
+/** Closed record-stage failure vocabulary for collection residency. */
+export type InstanceCollectionFailureCode = RhiErrorCode | 'queue-write-buffer-failed';
+
+/** Typed producer facts retained when a collection cannot be admitted. */
+export interface InstanceCollectionFailureFacts {
+  readonly requestedBytes: number;
+  readonly supportedBytes: number | undefined;
+  readonly backend: InstanceBackendKind;
+  readonly owner: 'renderer.instances';
+  readonly cause: string;
+  readonly recovery: string;
+}
+
+/** Detached, bounded collection evidence exposed by Renderer.inspect(). */
+export interface InstanceCollectionInspection extends InstanceCollectionInfo {
+  readonly residentGeneration: number | undefined;
+  readonly lane: InstanceSubmissionLane;
+  readonly uploadRanges: readonly InstanceUploadRange[];
+  readonly uploadedBytes: number;
+  readonly requestedBytes: number;
+  readonly supportedBytes: number | undefined;
+  readonly backend: InstanceBackendKind;
+  readonly owner: 'renderer.instances';
+  readonly error:
+    | {
+        readonly code: InstanceCollectionFailureCode;
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: InstanceCollectionFailureFacts;
+      }
+    | undefined;
+}
+
+export interface InstanceResidency {
+  readonly frameNumber: number;
+  readonly residentGeneration: number | undefined;
+  readonly lane: InstanceSubmissionLane;
+  readonly uploadRanges: readonly InstanceUploadRange[];
+  readonly uploadedBytes: number;
+  readonly requestedBytes: number;
+  readonly supportedBytes: number | undefined;
+  readonly backend: InstanceBackendKind;
+  readonly error: InstanceCollectionInspection['error'];
+}
+
+function appendRange(ranges: InstanceUploadRange[], start: number, end: number): void {
+  if (start >= end) return;
+  // Updates are allowed to arrive in any order. Insert at the first range
+  // whose end reaches the new interval, then consume every range that starts
+  // before the merged end. This preserves the complete union for both
+  // adjacent and overlapping writes (for example [10, 12) then [8, 11)).
+  let index = 0;
+  while (index < ranges.length) {
+    const existing = ranges[index];
+    if (existing === undefined || existing.end >= start) break;
+    index += 1;
+  }
+  while (index < ranges.length) {
+    const existing = ranges[index];
+    if (existing === undefined || existing.start > end) break;
+    start = Math.min(start, existing.start);
+    end = Math.max(end, existing.end);
+    ranges.splice(index, 1);
+  }
+  ranges.splice(index, 0, { start, end });
+}
+
+interface CollectionRecord extends InstanceCollectionInfo {
+  readonly world: World;
+  readonly entity: number;
+  readonly transforms: Float32Array;
+}
+
+/** Rebuildable per-renderer projection. World remains the authoring authority. */
+export class InstanceProjectionStore {
+  private nextId = 1;
+  private identities = new WeakMap<World, Map<number, InstanceCollectionId>>();
+  private readonly records = new Map<InstanceCollectionId, CollectionRecord>();
+
+  project(world: World, entity: number, transforms: ArrayLike<number>): InstanceCollectionSnapshot {
+    let entities = this.identities.get(world);
+    if (entities === undefined) {
+      entities = new Map();
+      this.identities.set(world, entities);
+    }
+    let collectionId = entities.get(entity);
+    if (collectionId === undefined) {
+      collectionId = this.nextId++ as InstanceCollectionId;
+      entities.set(entity, collectionId);
+    }
+    const previous = this.records.get(collectionId);
+    const unchanged =
+      previous !== undefined &&
+      previous.transforms.length === transforms.length &&
+      previous.transforms.every((value, index) => Object.is(value, transforms[index]));
+    const record: CollectionRecord = unchanged
+      ? previous
+      : {
+          collectionId,
+          world,
+          entity,
+          transforms: new Float32Array(transforms),
+          count: transforms.length / MATRIX_STRIDE,
+          revision: (previous?.revision ?? 0) + 1,
+        };
+    this.records.set(collectionId, record);
+    // Every consumer gets a complete snapshot. Reading never acknowledges an
+    // upload; each GPU resident records its own successfully uploaded revision.
+    return { ...this.info(record), transforms: record.transforms };
+  }
+
+  retain(ids: ReadonlySet<InstanceCollectionId>): void {
+    for (const [id, record] of this.records) {
+      if (ids.has(id)) continue;
+      this.identities.get(record.world)?.delete(record.entity);
+      this.records.delete(id);
+    }
+  }
+
+  /** Release one producer-owned collection when its render identity is removed. */
+  release(world: World, entity: number): void {
+    const entities = this.identities.get(world);
+    const collectionId = entities?.get(entity);
+    if (collectionId === undefined) return;
+    entities?.delete(entity);
+    this.records.delete(collectionId);
+  }
+
+  dispose(): void {
+    this.records.clear();
+    this.identities = new WeakMap();
+  }
+
+  /**
+   * Return detached residency facts for every live collection.
+   *
+   * @internal Joins CPU projection identity with the active device residency;
+   * callers only receive immutable PODs and never GPU handles.
+   */
+  _inspections(
+    residency: ReadonlyMap<InstanceCollectionId, InstanceResidency> | undefined,
+    frameNumber: number,
+  ): readonly InstanceCollectionInspection[] {
+    return Object.freeze(
+      [...this.records.values()].map((record) =>
+        this.projectInspection(record, residency?.get(record.collectionId), frameNumber),
+      ),
+    );
+  }
+
+  private info(record: CollectionRecord): InstanceCollectionInfo {
+    return Object.freeze({
+      collectionId: record.collectionId,
+      count: record.count,
+      revision: record.revision,
+    });
+  }
+
+  private projectInspection(
+    record: CollectionRecord,
+    residency: InstanceResidency | undefined,
+    frameNumber: number,
+  ): InstanceCollectionInspection {
+    return Object.freeze({
+      ...this.info(record),
+      residentGeneration: residency?.residentGeneration,
+      lane: residency?.lane ?? 'unresident',
+      uploadRanges: Object.freeze(
+        residency?.frameNumber === frameNumber
+          ? residency.uploadRanges.map((range) => ({ ...range }))
+          : [],
+      ),
+      uploadedBytes: residency?.frameNumber === frameNumber ? residency.uploadedBytes : 0,
+      requestedBytes: residency?.requestedBytes ?? record.count * MATRIX_STRIDE * 4,
+      supportedBytes: residency?.supportedBytes,
+      backend: residency?.backend ?? 'unknown',
+      owner: 'renderer.instances',
+      error: residency?.error,
+    });
+  }
+}
+
+/** @internal Renderer record owner reports the accepted collection lane. */
+export function recordInstanceResidency(
+  residency: Map<InstanceCollectionId, InstanceResidency>,
+  input: {
+    readonly collectionId: InstanceCollectionId;
+    readonly frameNumber: number;
+    readonly residentGeneration: number;
+    readonly lane: Exclude<InstanceSubmissionLane, 'unresident' | 'unavailable'>;
+    readonly uploadRanges: readonly InstanceUploadRange[];
+    readonly uploadedBytes: number;
+    readonly requestedBytes: number;
+    readonly supportedBytes: number | undefined;
+    readonly backend: InstanceBackendKind;
+  },
+): void {
+  const previous = residency.get(input.collectionId);
+  const sameFrame =
+    previous !== undefined &&
+    previous.frameNumber === input.frameNumber &&
+    previous.error === undefined;
+  const uploadRanges = sameFrame
+    ? [...previous.uploadRanges].reduce(
+        (ranges, range) => {
+          appendRange(ranges, range.start, range.end);
+          return ranges;
+        },
+        input.uploadRanges.map((range) => ({ ...range })),
+      )
+    : input.uploadRanges.map((range) => ({ ...range }));
+  residency.set(input.collectionId, {
+    frameNumber: input.frameNumber,
+    residentGeneration: input.residentGeneration,
+    lane: input.lane,
+    uploadRanges,
+    uploadedBytes: sameFrame ? previous.uploadedBytes + input.uploadedBytes : input.uploadedBytes,
+    requestedBytes: input.requestedBytes,
+    supportedBytes: input.supportedBytes,
+    backend: input.backend,
+    error: undefined,
+  });
+}
+
+/** @internal Renderer record owner reports a typed admission failure. */
+export function recordInstanceFailure(
+  residency: Map<InstanceCollectionId, InstanceResidency>,
+  input: {
+    readonly collectionId: InstanceCollectionId;
+    readonly code: InstanceCollectionFailureCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly facts: InstanceCollectionFailureFacts;
+  },
+): void {
+  residency.set(input.collectionId, {
+    frameNumber: -1,
+    residentGeneration: undefined,
+    lane: 'unavailable',
+    uploadRanges: [],
+    uploadedBytes: 0,
+    requestedBytes: input.facts.requestedBytes,
+    supportedBytes: input.facts.supportedBytes,
+    backend: input.facts.backend,
+    error: {
+      code: input.code,
+      expected: input.expected,
+      hint: input.hint,
+      detail: { ...input.facts },
+    },
+  });
+}

package/src/materials.ts

@@ -9,6 +9,10 @@ import type {
   MaterialValue,
 } from '@forgeax/engine-types';
 import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import {
+  DEFAULT_STANDARD_SURFACE_MODULE,
+  projectStandardSurfacePasses,
+} from './assembly/material/surface-projection';
 
 export type MaterialTransmissionValidationReason =
   | 'non-finite'
@@ -58,7 +62,6 @@ export const SPRITE_PREMULTIPLIED_ALPHA_BLEND: GPUBlendState = {
   alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
 };
 
-const STANDARD_MODULE = 'forgeax_material::standard';
 const UNLIT_MODULE = 'forgeax_material::unlit';
 const SPRITE_MODULE = 'forgeax_material::sprite';
 
@@ -389,6 +392,70 @@ interface StandardOpts {
   readonly queue?: number;
 }
 
+/** Built-in Standard authoring surface with engine-owned parameter defaults. */
+export interface DefaultStandardOptions extends StandardOpts {
+  readonly surfaceModule?: never;
+  readonly parameters?: never;
+  readonly values?: never;
+}
+
+/** Import-first Standard Surface authoring; the root parameter contract stays caller-owned. */
+export interface CustomStandardSurfaceOptions {
+  readonly surfaceModule: string;
+  readonly parameters: readonly MaterialParameter[];
+  readonly values: Readonly<Record<string, MaterialValue>>;
+  readonly colorSpace?: MaterialColorSpace;
+  readonly renderState?: MaterialRenderState;
+  readonly castShadow?: boolean;
+  readonly queue?: number;
+  readonly baseColor?: never;
+  readonly metallic?: never;
+  readonly roughness?: never;
+  readonly metallicChannel?: never;
+  readonly roughnessChannel?: never;
+  readonly clearcoat?: never;
+  readonly clearcoatRoughness?: never;
+  readonly clearcoatTexture?: never;
+  readonly clearcoatRoughnessTexture?: never;
+  readonly clearcoatNormalTexture?: never;
+  readonly clearcoatNormalScale?: never;
+  readonly anisotropyStrength?: never;
+  readonly anisotropyRotation?: never;
+  readonly anisotropyTexture?: never;
+  readonly sheenColor?: never;
+  readonly sheenRoughness?: never;
+  readonly sheenColorTexture?: never;
+  readonly sheenRoughnessTexture?: never;
+  readonly iridescence?: never;
+  readonly iridescenceIor?: never;
+  readonly iridescenceThicknessMinimum?: never;
+  readonly iridescenceThicknessMaximum?: never;
+  readonly iridescenceTexture?: never;
+  readonly iridescenceThicknessTexture?: never;
+  readonly specular?: never;
+  readonly specularColor?: never;
+  readonly specularTexture?: never;
+  readonly specularColorTexture?: never;
+  readonly emissive?: never;
+  readonly emissiveIntensity?: never;
+  readonly emissiveTexture?: never;
+  readonly baseColorTexture?: never;
+  readonly metallicRoughnessTexture?: never;
+  readonly normalTexture?: never;
+  readonly occlusionTexture?: never;
+  readonly occlusionStrength?: never;
+  readonly alphaCutoff?: never;
+  readonly transmission?: never;
+  readonly transmissionTexture?: never;
+  readonly ior?: never;
+  readonly thickness?: never;
+  readonly thicknessTexture?: never;
+  readonly attenuationColor?: never;
+  readonly attenuationDistance?: never;
+}
+
+export type StandardOptions = DefaultStandardOptions | CustomStandardSurfaceOptions;
+
 function validateChannel(
   name: 'metallicChannel' | 'roughnessChannel',
   value: number | undefined,
@@ -413,7 +480,7 @@ function validateFiniteRange(
   }
 }
 
-function standard(opts: StandardOpts): MaterialAsset {
+function standardDefault(opts: DefaultStandardOptions): MaterialAsset {
   const occlusionStrength = opts.occlusionStrength ?? 1;
   if (occlusionStrength < 0 || occlusionStrength > 1) {
     throw new Error(
@@ -516,16 +583,18 @@ function standard(opts: StandardOpts): MaterialAsset {
   for (const name of Object.keys(values)) {
     if (!declaredNames.has(name)) delete values[name];
   }
-  const physical = deriveStandardLayerPlan(parameters).mode === 'physical';
-  const passes: [MaterialPass, ...MaterialPass[]] = [
-    pass('forward', STANDARD_MODULE, forwardRenderState, 'fs_main', opts.queue),
-  ];
-  if (!physical && transmission === 0) {
-    passes.push(pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue));
-  }
-  if (opts.castShadow !== false) {
-    passes.push(pass('shadow-caster', STANDARD_MODULE, shadowCasterRenderState(opts.renderState)));
-  }
+  const layerPlan = deriveStandardLayerPlan(parameters);
+  const projected = projectStandardSurfacePasses({
+    surfaceModule: DEFAULT_STANDARD_SURFACE_MODULE,
+    values,
+    ...(forwardRenderState === undefined ? {} : { renderState: forwardRenderState }),
+    ...(opts.castShadow === undefined ? {} : { castShadow: opts.castShadow }),
+    ...(opts.queue === undefined ? {} : { queue: opts.queue }),
+    layerPlan,
+  });
+  const passes = (
+    transmission > 0 ? projected.filter((entry) => entry.name !== 'deferred') : projected
+  ) as [MaterialPass, ...MaterialPass[]];
   return {
     kind: 'material',
     colorSpace: 'linear',
@@ -535,6 +604,32 @@ function standard(opts: StandardOpts): MaterialAsset {
   };
 }
 
+function standardCustom(opts: CustomStandardSurfaceOptions): MaterialAsset {
+  const layerPlan = deriveStandardLayerPlan(
+    opts.parameters.filter((parameter) => parameter.optional !== true),
+  );
+  return {
+    kind: 'material',
+    ...(opts.colorSpace === undefined || opts.colorSpace === 'srgb'
+      ? {}
+      : { colorSpace: opts.colorSpace }),
+    passes: projectStandardSurfacePasses({
+      surfaceModule: opts.surfaceModule,
+      values: opts.values,
+      ...(opts.renderState === undefined ? {} : { renderState: opts.renderState }),
+      ...(opts.castShadow === undefined ? {} : { castShadow: opts.castShadow }),
+      ...(opts.queue === undefined ? {} : { queue: opts.queue }),
+      layerPlan,
+    }),
+    parameters: opts.parameters,
+    values: opts.values,
+  };
+}
+
+export function standard(options: StandardOptions): MaterialAsset {
+  return options.surfaceModule === undefined ? standardDefault(options) : standardCustom(options);
+}
+
 export const Materials = { unlit, standard, srgb } as const;
 
 export { SPRITE_MODULE };

package/src/pipeline-builder.ts

@@ -277,7 +277,13 @@ export function buildPipelineForMaterialShader(
   const vsEntry = vertexEntry ?? (passKind === 'temporal' ? 'vs_temporal' : 'vs_main');
   const fsEntry =
     fragmentEntry ??
-    (passKind === 'temporal' ? 'fs_temporal' : passKind === 'deferred' ? 'fs_gbuffer' : 'fs_main');
+    (passKind === 'temporal'
+      ? 'fs_temporal'
+      : passKind === 'deferred'
+        ? 'fs_gbuffer'
+        : passKind === 'shadow-caster'
+          ? 'fs_shadow'
+          : 'fs_main');
 
   let source = entry.source;
   if (defines !== undefined && Object.keys(defines).length > 0) {
@@ -345,15 +351,13 @@ export function buildPipelineForMaterialShader(
       vertex: {
         module: shaderModule,
         entryPoint: vsEntry,
-        buffers:
-          ctx.layoutKind === 'pbr-skin'
-            ? [...ctx.vertexBuffers]
-            : [
-                {
-                  arrayStride: 12 * 4,
-                  attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as const }],
-                },
-              ],
+        // Surface-backed Standard shadow entries evaluate the same material
+        // surface as Forward/Deferred, so their vertex stage consumes normal,
+        // UV, and tangent inputs in addition to position. Keep the complete
+        // derived mesh layout here; extra attributes remain legal for legacy
+        // position-only custom casters, while trimming to position would make
+        // the built-in Surface shadow shader fail WebGPU validation.
+        buffers: [...ctx.vertexBuffers],
       },
       // Vertex-only depth pass writes `fragment: undefined` (GPU derives
       // depth from gl_Position.z). A custom ShadowCaster shader with a

package/src/pipeline-spec.ts

@@ -19,6 +19,7 @@
 
 import {
   deriveVertexBufferLayout,
+  deriveVertexBufferLayoutFromProjection,
   deriveVertexLayoutProjection,
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
@@ -407,20 +408,11 @@ export function buildPipelineDescriptor(
             ? { shaderUvSetCount: geometry.shaderUvSetCount }
             : {}),
         })
-      : geometry.vertexLayoutProjection.attributes.length === 0
-        ? []
-        : [
-            {
-              arrayStride: geometry.vertexLayoutProjection.arrayStride,
-              attributes: geometry.vertexLayoutProjection.attributes.map(
-                ({ shaderLocation, offset, format }) => ({
-                  shaderLocation,
-                  offset,
-                  format,
-                }),
-              ),
-            },
-          ];
+      : deriveVertexBufferLayoutFromProjection(geometry.vertexLayoutProjection, {
+          ...(geometry.shaderUvSetCount !== undefined
+            ? { shaderUvSetCount: geometry.shaderUvSetCount }
+            : {}),
+        });
 
   const descriptor: Record<string, unknown> = {
     vertex: {

package/src/record/frame-snapshot.ts

@@ -18,6 +18,7 @@ import type { DirectionalShadowQuality } from '../components/directional-shadow-
 import type { EnvironmentGeneration } from '../environment/generation';
 import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import type { GpuBuffer } from '../gpu-resource';
+import type { InstanceCollectionId, InstanceResidency } from '../instances';
 import type { IblBindingInspection } from '../mesh-material-bindings';
 import type { StandardLightingInspection } from '../pipeline/standard-lighting/inspection';
 import type { PointShadowInspection } from '../point-shadow-inspection';
@@ -52,6 +53,17 @@ export function worldEntityKey(worldId: number, entityKey: number): number {
   return worldId * 4294967296 + entityKey; // 2^32 = 4294967296
 }
 
+/** Per-renderer projection identity, with entity keys for sprite/fold snapshots. */
+export function instanceCollectionCacheKey(
+  worldId: number,
+  instance: { readonly cacheKey: number; readonly collectionId?: number },
+): number {
+  // Keep collection entries in a disjoint numeric namespace from the shared
+  // legacy sprite/fold cache. Fold keys occupy -1..-(2^32), while ordinary
+  // world/entity keys are non-negative; this range starts below both.
+  return -(0x1_0000_0000 + worldEntityKey(worldId, instance.collectionId ?? instance.cacheKey));
+}
+
 /**
  * Cross-frame cache entry for a material bind group whose source material and
  * all resolved GPU resources are stable. The material snapshot identity is
@@ -289,8 +301,9 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
  * Owned by the `createRenderSystem` closure; advanced once per
  * `recordFrame` invocation. The `instanceBuffers` map holds the per-entity
  * GPU storage buffers for Instances-bearing entities (cache key = the
- * packed Entity u32 surfaced via `InstancesSnapshot.cacheKey`); entries
- * are recreated when the `archVersion` bumps or `byteLength` changes.
+ * renderer-owned collection id, with the packed Entity u32 retained only for
+ * legacy snapshots); entries are recreated when the `archVersion` bumps or
+ * `byteLength` changes.
  *
  * feat-20260518-pbr-direct-lighting-mvp M3 / w14 (AC-17 a): the
  * `warnedZeroLightStandard` flag latches the first-frame warning that
@@ -390,6 +403,10 @@ export interface RenderFrameState {
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
+  /** Renderer-owned collection owner used for record-stage residency facts. */
+  readonly instanceResidency?: Map<InstanceCollectionId, InstanceResidency>;
+  /** Stable buffers for renderer-owned collections split by device cap. */
+  readonly instanceBufferChunks?: Map<string, InstanceBufferCacheEntry>;
   /** Per-object ProbeBlendRecord buffers; upload is one atomic 160B write. */
   readonly probeBlendBuffers: Map<number, ProbeBlendBufferCacheEntry>;
   /** One renderer-owned record array; each object selects its 256B-aligned lane. */

package/src/record/frame.ts

@@ -86,6 +86,7 @@ import {
   type DispatchCounts,
   type FrameObservationSource,
   getTextureIdentity,
+  instanceCollectionCacheKey,
   makeZeroCameraFallbackSnapshot,
   type ReflectionFallbackReadbackRequest,
   type RenderFrameState,
@@ -2993,8 +2994,14 @@ function cleanPerFrameCaches(
   // composites matching the write-side keys of #1-#3 — cross-world false eviction
   // is prevented because worldEntityKey(0, k) !== worldEntityKey(1, k).
   const validatedEntityKeys = new Set<number>(retainedEntityKeys);
+  const validatedInstanceKeys = new Set<number>(retainedEntityKeys);
   for (const v of validated) {
-    validatedEntityKeys.add(worldEntityKey(v.source.worldId, v.source.entityKey));
+    const entityKey = worldEntityKey(v.source.worldId, v.source.entityKey);
+    validatedEntityKeys.add(entityKey);
+    validatedInstanceKeys.add(entityKey);
+    if (v.source.instances !== undefined) {
+      validatedInstanceKeys.add(instanceCollectionCacheKey(v.source.worldId, v.source.instances));
+    }
   }
 
   // Clean per-entity material BG cache: drop outer-Map entries whose
@@ -3018,7 +3025,7 @@ function cleanPerFrameCaches(
   // material-handle-based and cross-world collision is semantically
   // correct (same material renders in same fold bucket).
   for (const [key, entry] of frameState.instanceBuffers.entries()) {
-    if (!validatedEntityKeys.has(key)) {
+    if (!validatedInstanceKeys.has(key)) {
       if (!entry.buffer.isDestroyed) {
         const r = entry.buffer.destroy();
         if (!r.ok) internals.errorRegistry.fire(r.error);
@@ -3027,6 +3034,28 @@ function cleanPerFrameCaches(
     }
   }
 
+  if (frameState.instanceResidency !== undefined) {
+    const liveCollections = new Set(validated.map((entry) => entry.source.instances?.collectionId));
+    for (const id of frameState.instanceResidency.keys()) {
+      if (!liveCollections.has(id)) frameState.instanceResidency.delete(id);
+    }
+  }
+
+  // Chunk keys are `${worldEntityKey}:${chunkStart}`. Keep the key opaque to
+  // the authoring API, but retain the numeric owner prefix for eviction.
+  if (frameState.instanceBufferChunks !== undefined) {
+    for (const [key, entry] of frameState.instanceBufferChunks.entries()) {
+      const separator = key.indexOf(':');
+      const ownerKey = separator < 0 ? Number.NaN : Number(key.slice(0, separator));
+      if (validatedInstanceKeys.has(ownerKey)) continue;
+      if (!entry.buffer.isDestroyed) {
+        const r = entry.buffer.destroy();
+        if (!r.ok) internals.errorRegistry.fire(r.error);
+      }
+      frameState.instanceBufferChunks.delete(key);
+    }
+  }
+
   if (frameState.morphBuffers !== undefined) {
     for (const [key, entry] of frameState.morphBuffers.entries()) {
       if (validatedEntityKeys.has(key)) continue;