@forgeax/engine-render 0.1.33 → 0.1.35

package/src/instances.ts

@@ -1,52 +1,25 @@
+import { InstanceTransformsStrideMismatchError } from '@forgeax/engine-ecs/projection';
 import type { RhiErrorCode } from '@forgeax/engine-rhi';
-import { err, ok, type Result } from '@forgeax/engine-types';
 
 const MATRIX_STRIDE = 16;
-const INITIAL_CAPACITY = 1;
 
+/** Renderer projection identity; never stored in a World or SceneAsset. */
 export type InstanceCollectionId = number & {
   readonly __forgeaxInstanceCollectionId: unique symbol;
 };
-
-export interface InstanceCollectionData {
+export interface InstanceCollectionInfo {
   readonly collectionId: InstanceCollectionId;
-}
-
-export interface InstanceCollectionInfo extends InstanceCollectionData {
   readonly count: number;
-  readonly capacity: number;
   readonly revision: number;
 }
-
 export interface InstanceDirtyRange {
   start: number;
   end: number;
 }
-
-/**
- * Choose the ranges that initialize one resident GPU allocation.
- *
- * A cache miss is not a delta upload: recovery, reassociation, and any other
- * new resident has uninitialized device memory. The canonical collection must
- * therefore be copied in full even when the current authoring revision only
- * records a partial dirty range. Existing residents keep the narrower ranges.
- */
-export function instanceUploadRangesForResident(
-  activeIsNew: boolean,
-  dirtyRanges: readonly InstanceDirtyRange[],
-  fullRange: InstanceDirtyRange,
-): readonly InstanceDirtyRange[] {
-  return activeIsNew ? [fullRange] : dirtyRanges;
-}
-
 export interface InstanceCollectionSnapshot extends InstanceCollectionInfo {
   readonly transforms: Float32Array;
-  /** Unique identity generations that travel with an instance through reorder. */
   readonly generations: Uint32Array;
-  readonly dirtyRanges: readonly InstanceDirtyRange[];
 }
-
-/** The renderer-owned submission lane selected for one collection. */
 export type InstanceSubmissionLane =
   | 'unresident'
   | 'direct-storage'
@@ -54,14 +27,8 @@ export type InstanceSubmissionLane =
   | '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;
@@ -70,29 +37,9 @@ export interface InstanceCollectionFailureFacts {
   readonly cause: string;
   readonly recovery: string;
 }
-
-function instanceCollectionFailureFacts(
-  cause: string,
-  recovery: string,
-  requestedBytes = 0,
-  supportedBytes: number | undefined = undefined,
-  backend: InstanceBackendKind = 'unknown',
-): InstanceCollectionFailureFacts {
-  return {
-    requestedBytes,
-    supportedBytes,
-    backend,
-    owner: 'renderer.instances',
-    cause,
-    recovery,
-  };
-}
-
-/** Detached, bounded collection evidence exposed by Renderer.inspect(). */
 export interface InstanceCollectionInspection extends InstanceCollectionInfo {
   readonly residentGeneration: number | undefined;
   readonly lane: InstanceSubmissionLane;
-  readonly dirtyRanges: readonly InstanceDirtyRange[];
   readonly uploadRanges: readonly InstanceDirtyRange[];
   readonly uploadedBytes: number;
   readonly requestedBytes: number;
@@ -109,82 +56,46 @@ export interface InstanceCollectionInspection extends InstanceCollectionInfo {
     | undefined;
 }
 
-export interface InstanceCollectionCreateInput {
-  readonly transforms: Float32Array;
-}
-
-export interface InstanceCollectionUpdateInput {
-  /** Matrix ordinal of the first matrix to replace. */
-  readonly start: number;
-  readonly transforms: Float32Array;
-}
-
-export interface InstanceCollectionInvalidDetail {
-  readonly collectionId?: number;
-  readonly operation: 'create' | 'replace' | 'update' | 'inspect' | 'release';
-  readonly expected: string;
-  readonly actual: number | string;
-}
-
-export type InstanceCollectionErrorCode =
-  | 'instance-collection-invalid'
-  | 'instance-collection-not-found'
-  | 'instance-collection-released';
-
-export class InstanceCollectionError extends Error {
-  readonly code: InstanceCollectionErrorCode;
-  readonly expected: string;
-  readonly hint: string;
-  readonly detail: InstanceCollectionInvalidDetail | undefined;
-  readonly owner = 'renderer.instances' as const;
-  readonly recovery: string;
-  readonly facts: InstanceCollectionFailureFacts;
-
+export class InstanceTransformsError extends Error {
+  readonly code = 'instance-transforms-invalid' as const;
+  readonly expected = 'finite column-major mat4 values, with transforms.length a multiple of 16';
+  readonly hint = 'repair Instances.transforms in the World or source SceneAsset and retry';
   constructor(
-    code: InstanceCollectionErrorCode,
-    expected: string,
-    hint: string,
-    detail?: InstanceCollectionInvalidDetail,
-    facts?: InstanceCollectionFailureFacts,
+    readonly detail: { readonly actualLength: number; readonly nonFiniteIndex?: number },
   ) {
-    super(`${code}: ${expected}`);
-    this.name = 'InstanceCollectionError';
-    this.code = code;
-    this.expected = expected;
-    this.hint = hint;
-    this.detail = detail;
-    this.facts =
-      facts ??
-      instanceCollectionFailureFacts(
-        code,
-        hint,
-        detail?.operation === 'create' || detail?.operation === 'replace'
-          ? typeof detail.actual === 'number' && Number.isFinite(detail.actual)
-            ? detail.actual * Float32Array.BYTES_PER_ELEMENT
-            : 0
-          : 0,
-      );
-    this.recovery = this.facts.recovery;
+    super('Instances.transforms must contain complete finite matrices');
+    this.name = 'InstanceTransformsError';
   }
 }
+export function validateInstanceTransforms(
+  transforms: ArrayLike<number>,
+): InstanceTransformsError | InstanceTransformsStrideMismatchError | undefined {
+  if (transforms.length % MATRIX_STRIDE !== 0)
+    return new InstanceTransformsStrideMismatchError(transforms.length);
+  for (let index = 0; index < transforms.length; index++) {
+    if (!Number.isFinite(transforms[index]))
+      return new InstanceTransformsError({
+        actualLength: transforms.length,
+        nonFiniteIndex: index,
+      });
+  }
+  return undefined;
+}
 
-export type InstanceCollectionResult<T> = Result<T, InstanceCollectionError>;
-
-interface CollectionRecord {
-  readonly id: InstanceCollectionId;
-  transforms: Float32Array;
-  generations: Uint32Array;
-  count: number;
-  capacity: number;
-  revision: number;
-  dirtyRanges: InstanceDirtyRange[];
-  /** Last revision detached for extraction; repeated reads of that revision
-   * retain the same ranges for multiple entities sharing one collection. */
-  lastSnapshotRevision: number;
-  released: boolean;
+/** A new allocation must receive the complete payload, including after recovery. */
+export function instanceUploadRangesForResident(
+  activeIsNew: boolean,
+  dirtyRanges: readonly InstanceDirtyRange[],
+  fullRange: InstanceDirtyRange,
+): readonly InstanceDirtyRange[] {
+  return activeIsNew ? [fullRange] : dirtyRanges;
 }
 
-interface CollectionResidency {
+interface Projection extends InstanceCollectionSnapshot {
+  readonly world: object;
+  readonly entity: number;
+}
+interface Residency {
   readonly frameNumber: number;
   readonly residentGeneration: number | undefined;
   readonly lane: InstanceSubmissionLane;
@@ -196,300 +107,124 @@ interface CollectionResidency {
   readonly error: InstanceCollectionInspection['error'];
 }
 
-function nextCapacity(required: number): number {
-  let capacity = INITIAL_CAPACITY;
-  while (capacity < required) capacity *= 2;
-  return capacity;
-}
-
-function invalid(
-  operation: InstanceCollectionInvalidDetail['operation'],
-  expected: string,
-  actual: number | string,
-  collectionId?: number,
-  context?: {
-    readonly requestedBytes?: number;
-    readonly supportedBytes?: number;
-    readonly cause?: string;
-    readonly recovery?: string;
-  },
-): InstanceCollectionError {
-  const hint = 'repair the collection payload and retry the same authoring operation';
-  return new InstanceCollectionError(
-    'instance-collection-invalid',
-    expected,
-    hint,
-    { operation, expected, actual, ...(collectionId === undefined ? {} : { collectionId }) },
-    instanceCollectionFailureFacts(
-      context?.cause ?? `invalid-${operation}-authoring`,
-      context?.recovery ?? hint,
-      context?.requestedBytes ?? 0,
-      context?.supportedBytes,
-    ),
-  );
-}
-
-function validateTransforms(
-  operation: InstanceCollectionInvalidDetail['operation'],
-  transforms: Float32Array,
-  collectionId?: number,
-): InstanceCollectionError | undefined {
-  if (!(transforms instanceof Float32Array)) {
-    return invalid(operation, 'transforms is a Float32Array', typeof transforms, collectionId, {
-      cause: 'invalid-transform-type',
-    });
-  }
-  if (transforms.length % MATRIX_STRIDE !== 0) {
-    return invalid(
-      operation,
-      `transforms.length is a multiple of ${MATRIX_STRIDE}`,
-      transforms.length,
-      collectionId,
-      {
-        requestedBytes: transforms.byteLength,
-        cause: 'invalid-transform-stride',
-      },
-    );
-  }
-  for (const value of transforms) {
-    if (!Number.isFinite(value)) {
-      return invalid(operation, 'every transform value is finite', value, collectionId, {
-        requestedBytes: transforms.byteLength,
-        cause: 'invalid-transform-value',
-      });
-    }
-  }
-  return undefined;
-}
-
-function appendRange(ranges: InstanceDirtyRange[], 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 });
-}
-
-function appendDirtyRange(record: CollectionRecord, start: number, end: number): void {
-  appendRange(record.dirtyRanges, start, end);
-}
-
-function missing(
-  operation: InstanceCollectionInvalidDetail['operation'],
-  id: InstanceCollectionId,
-): InstanceCollectionError {
-  return new InstanceCollectionError(
-    'instance-collection-not-found',
-    `instance collection ${Number(id)} is live and owned by this Renderer`,
-    'create a collection with renderer.instances.create or retain the original collection id',
-    { operation, expected: 'a live instance collection id', actual: Number(id), collectionId: id },
-  );
-}
-
-/**
- * Renderer-owned canonical storage for explicit instance transforms.
- *
- * ECS carries only `Instances.collectionId`; this owner keeps the copied
- * matrices, revision and dirty intervals independent of archetype capacity.
- * Snapshots are detached before they cross into extraction, so callers cannot
- * mutate the canonical source behind the revision protocol.
- */
-export class InstanceCollectionStore {
+/** Rebuildable renderer projection. All authoring and entity lifetime belong to World. */
+export class InstanceProjectionStore {
   private nextId = 1;
-  private nextInstanceGeneration = 1;
-  private epochValue = 0;
-  private disposed = false;
-  private readonly records = new Map<InstanceCollectionId, CollectionRecord>();
-  private readonly residency = new Map<InstanceCollectionId, CollectionResidency>();
-
-  get epoch(): number {
-    return this.epochValue;
-  }
-
-  create(input: InstanceCollectionCreateInput): InstanceCollectionResult<InstanceCollectionInfo> {
-    if (this.disposed) {
-      return err(
-        new InstanceCollectionError(
-          'instance-collection-released',
-          'the Renderer-owned instance collection store is live',
-          'create a new Renderer before authoring instance collections',
-        ),
-      );
-    }
-    const invalidPayload = validateTransforms('create', input.transforms);
-    if (invalidPayload !== undefined) return err(invalidPayload);
-    const id = this.nextId++ as InstanceCollectionId;
-    const count = input.transforms.length / MATRIX_STRIDE;
-    const generations = this.allocateGenerations(count);
-    const record: CollectionRecord = {
-      id,
-      transforms: new Float32Array(input.transforms),
+  private nextGeneration = 1;
+  private identities = new WeakMap<object, Map<number, InstanceCollectionId>>();
+  private readonly records = new Map<InstanceCollectionId, Projection>();
+  private readonly residency = new Map<InstanceCollectionId, Residency>();
+
+  project(
+    world: object,
+    entity: number,
+    transforms: ArrayLike<number>,
+  ): InstanceCollectionSnapshot {
+    const collectionId =
+      this.identities.get(world)?.get(entity) ?? (this.nextId++ as InstanceCollectionId);
+    const previous = this.records.get(collectionId);
+    if (
+      previous !== undefined &&
+      previous.transforms.length === transforms.length &&
+      previous.transforms.every((value, index) => Object.is(value, transforms[index]))
+    )
+      return previous;
+    const count = transforms.length / MATRIX_STRIDE;
+    // Ordinals are identities within the authored array. Pose edits retain them;
+    // resizing seeds topology anew so new instances cannot inherit old motion.
+    const generations =
+      previous?.count === count
+        ? previous.generations
+        : Uint32Array.from({ length: count }, () => this.nextGeneration++);
+    const record: Projection = {
+      collectionId,
+      world,
+      entity,
+      transforms: new Float32Array(transforms),
       generations,
       count,
-      capacity: nextCapacity(Math.max(INITIAL_CAPACITY, count)),
-      revision: 1,
-      dirtyRanges: count === 0 ? [] : [{ start: 0, end: count }],
-      lastSnapshotRevision: 0,
-      released: false,
+      revision: (previous?.revision ?? 0) + 1,
     };
-    this.records.set(id, record);
-    this.epochValue += 1;
-    return ok(this.info(record));
+    return record;
   }
 
-  replace(
-    id: InstanceCollectionId,
-    transforms: Float32Array,
-    /** Prior identity generations in the replacement order; omitted rows are new. */
-    generations?: Uint32Array,
-  ): InstanceCollectionResult<InstanceCollectionInfo> {
-    const record = this.live('replace', id);
-    if (!record.ok) return record;
-    const invalidPayload = validateTransforms('replace', transforms, id);
-    if (invalidPayload !== undefined) return err(invalidPayload);
-    const count = transforms.length / MATRIX_STRIDE;
-    const generationResult =
-      generations === undefined
-        ? ok(this.allocateGenerations(count))
-        : this.validateReplacementGenerations(generations, count, id);
-    if (!generationResult.ok) return generationResult;
-    // Replacement is a topology boundary by default. A producer that keeps
-    // logical instance identity through compaction/reorder may pass the prior
-    // generation tokens in their new order; the record stage then maps the
-    // real previous transform by token instead of by draw ordinal.
-    const replacementGenerations = generationResult.value;
-    record.value.transforms = new Float32Array(transforms);
-    record.value.generations = replacementGenerations;
-    record.value.count = count;
-    record.value.capacity = Math.max(record.value.capacity, nextCapacity(Math.max(1, count)));
-    record.value.revision += 1;
-    record.value.dirtyRanges = count === 0 ? [] : [{ start: 0, end: count }];
-    record.value.lastSnapshotRevision = record.value.revision - 1;
-    this.epochValue += 1;
-    return ok(this.info(record.value));
+  /** Called only after the owning RenderScene accepts its prepared changes. */
+  accept(
+    world: object,
+    entity: number,
+    snapshot: {
+      readonly collectionId?: InstanceCollectionId;
+      readonly revision?: number;
+      readonly transforms: Float32Array;
+      readonly generations?: Uint32Array;
+    },
+  ): void {
+    const { collectionId, revision, transforms, generations } = snapshot;
+    if (collectionId === undefined || revision === undefined || generations === undefined) return;
+    let entities = this.identities.get(world);
+    if (entities === undefined) {
+      entities = new Map();
+      this.identities.set(world, entities);
+    }
+    entities.set(entity, collectionId);
+    this.records.set(collectionId, {
+      collectionId,
+      revision,
+      transforms,
+      generations,
+      count: transforms.length / MATRIX_STRIDE,
+      world,
+      entity,
+    });
   }
 
-  update(
-    id: InstanceCollectionId,
-    input: InstanceCollectionUpdateInput,
-  ): InstanceCollectionResult<InstanceCollectionInfo> {
-    const record = this.live('update', id);
-    if (!record.ok) return record;
-    const invalidPayload = validateTransforms('update', input.transforms, id);
-    if (invalidPayload !== undefined) return err(invalidPayload);
-    if (!Number.isInteger(input.start) || input.start < 0) {
-      return err(
-        invalid('update', 'start is a non-negative matrix ordinal', input.start, id, {
-          requestedBytes: input.transforms.byteLength,
-          supportedBytes: record.value.capacity * MATRIX_STRIDE * Float32Array.BYTES_PER_ELEMENT,
-          cause: 'invalid-update-range-start',
-        }),
-      );
-    }
-    const span = input.transforms.length / MATRIX_STRIDE;
-    const attemptedEnd = input.start + span;
-    if (attemptedEnd > record.value.count) {
-      return err(
-        invalid(
-          'update',
-          `start + matrix count is <= collection count (${record.value.count})`,
-          attemptedEnd,
-          id,
-          {
-            requestedBytes: attemptedEnd * MATRIX_STRIDE * Float32Array.BYTES_PER_ELEMENT,
-            supportedBytes: record.value.count * MATRIX_STRIDE * Float32Array.BYTES_PER_ELEMENT,
-            cause: 'invalid-update-range-end',
-          },
-        ),
-      );
-    }
-    if (record.value.lastSnapshotRevision === record.value.revision) {
-      record.value.dirtyRanges = [];
+  release(world: object, entity: number): void {
+    const entities = this.identities.get(world);
+    const id = entities?.get(entity);
+    if (id === undefined) return;
+    entities?.delete(entity);
+    this.records.delete(id);
+    this.residency.delete(id);
+  }
+  retain(ids: ReadonlySet<InstanceCollectionId>): void {
+    for (const record of this.records.values()) {
+      if (!ids.has(record.collectionId)) this.release(record.world, record.entity);
     }
-    record.value.transforms.set(input.transforms, input.start * MATRIX_STRIDE);
-    // An update changes a pose while retaining the same ordinal identity.
-    // Keep its generation stable so the record stage can pair this current
-    // transform with the last submitted transform and expose real velocity.
-    // `replace` is the explicit topology boundary that advances generations
-    // for compaction, reorder, retirement, and newly occupied ordinals.
-    record.value.revision += 1;
-    appendDirtyRange(record.value, input.start, input.start + span);
-    this.epochValue += 1;
-    return ok(this.info(record.value));
   }
-
-  inspect(id: InstanceCollectionId): InstanceCollectionResult<InstanceCollectionInfo> {
-    const record = this.live('inspect', id);
-    return record.ok ? ok(this.info(record.value)) : record;
+  dispose(): void {
+    this.records.clear();
+    this.residency.clear();
+    this.identities = new WeakMap();
   }
-
-  /**
-   * Return detached residency facts for every live collection.
-   *
-   * @internal Record-stage evidence is reported through the two methods below;
-   * callers only receive immutable PODs and never GPU handles.
-   */
-  _inspections(): readonly InstanceCollectionInspection[] {
-    return Object.freeze(
-      [...this.records.values()].map((record) => this.projectInspection(record)),
-    );
+  _resetResidency(): void {
+    this.residency.clear();
   }
 
-  /** @internal Renderer record owner reports the accepted collection lane. */
-  _reportResidency(input: {
-    readonly collectionId: InstanceCollectionId;
-    readonly frameNumber: number;
-    readonly residentGeneration: number;
-    readonly lane: Exclude<InstanceSubmissionLane, 'unresident' | 'unavailable'>;
-    readonly uploadRanges: readonly InstanceDirtyRange[];
-    readonly uploadedBytes: number;
-    readonly requestedBytes: number;
-    readonly supportedBytes: number | undefined;
-    readonly backend: InstanceBackendKind;
-  }): void {
+  _reportResidency(
+    input: Omit<Residency, 'error' | 'lane'> & {
+      readonly collectionId: InstanceCollectionId;
+      readonly lane: Exclude<InstanceSubmissionLane, 'unresident' | 'unavailable'>;
+    },
+  ): void {
     if (!this.records.has(input.collectionId)) return;
     const previous = this.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 }));
+    const sameFrame = previous?.frameNumber === input.frameNumber && previous.error === undefined;
+    const ranges = [...(sameFrame ? previous.uploadRanges : []), ...input.uploadRanges]
+      .map((range) => ({ ...range }))
+      .sort((a, b) => a.start - b.start);
+    const uploadRanges: InstanceDirtyRange[] = [];
+    for (const range of ranges) {
+      const last = uploadRanges.at(-1);
+      if (last !== undefined && range.start <= last.end) last.end = Math.max(last.end, range.end);
+      else uploadRanges.push(range);
+    }
     this.residency.set(input.collectionId, {
-      frameNumber: input.frameNumber,
-      residentGeneration: input.residentGeneration,
-      lane: input.lane,
+      ...input,
       uploadRanges,
-      uploadedBytes: sameFrame ? previous.uploadedBytes + input.uploadedBytes : input.uploadedBytes,
-      requestedBytes: input.requestedBytes,
-      supportedBytes: input.supportedBytes,
-      backend: input.backend,
+      uploadedBytes: input.uploadedBytes + (sameFrame ? previous.uploadedBytes : 0),
       error: undefined,
     });
   }
-
-  /** @internal Renderer record owner reports a typed admission failure. */
   _reportFailure(input: {
     readonly collectionId: InstanceCollectionId;
     readonly code: InstanceCollectionFailureCode;
@@ -515,176 +250,24 @@ export class InstanceCollectionStore {
       },
     });
   }
-
-  /** @internal A lost device invalidates every renderer-owned GPU resident. */
-  _resetResidency(): void {
-    this.residency.clear();
-  }
-
-  snapshot(id: InstanceCollectionId): InstanceCollectionResult<InstanceCollectionSnapshot> {
-    const record = this.live('inspect', id);
-    if (!record.ok) return record;
-    const value = record.value;
-    value.lastSnapshotRevision = value.revision;
-    const result = {
-      ...this.info(value),
-      transforms: new Float32Array(value.transforms),
-      generations: new Uint32Array(value.generations),
-      dirtyRanges: value.dirtyRanges.map((range) => ({ ...range })),
-    };
-    // Keep the current ranges stable for repeated reads by entities sharing
-    // this collection. The next authoring mutation starts a fresh interval
-    // set once this revision has been observed.
-    return ok(result);
-  }
-
-  /**
-   * Read a detached matrix view without advancing the render-consumption
-   * cursor. Inspection and picking may call this between authoring updates;
-   * the next renderer snapshot must still receive the complete dirty union.
-   */
-  peek(id: InstanceCollectionId): InstanceCollectionResult<InstanceCollectionSnapshot> {
-    const record = this.live('inspect', id);
-    return record.ok ? ok(this.detachedSnapshot(record.value)) : record;
-  }
-
-  release(id: InstanceCollectionId): InstanceCollectionResult<void> {
-    const record = this.records.get(id);
-    if (record === undefined) return err(missing('release', id));
-    if (record.released) {
-      return err(
-        new InstanceCollectionError(
-          'instance-collection-released',
-          `instance collection ${Number(id)} has not already been released`,
-          'do not reuse a released collection id; create a new collection',
-          {
-            operation: 'release',
-            expected: 'a live instance collection id',
-            actual: Number(id),
-            collectionId: id,
-          },
-        ),
-      );
-    }
-    record.released = true;
-    this.records.delete(id);
-    this.residency.delete(id);
-    this.epochValue += 1;
-    return ok(undefined);
-  }
-
-  /** Drop all canonical matrices during Renderer disposal. */
-  dispose(): void {
-    if (this.disposed) return;
-    this.disposed = true;
-    for (const record of this.records.values()) record.released = true;
-    this.records.clear();
-    this.residency.clear();
-    this.epochValue += 1;
-  }
-
-  private live(
-    operation: InstanceCollectionInvalidDetail['operation'],
-    id: InstanceCollectionId,
-  ): InstanceCollectionResult<CollectionRecord> {
-    if (!Number.isInteger(id) || id <= 0) {
-      return err(invalid(operation, 'collectionId is a positive integer', id, id));
-    }
-    if (this.disposed) {
-      return err(
-        new InstanceCollectionError(
-          'instance-collection-released',
-          'the Renderer-owned instance collection store is live',
-          'create a new Renderer before using instance collections',
-          { operation, expected: 'a live collection store', actual: 'disposed', collectionId: id },
-        ),
-      );
-    }
-    const record = this.records.get(id);
-    return record === undefined ? err(missing(operation, id)) : ok(record);
-  }
-
-  private detachedSnapshot(record: CollectionRecord): InstanceCollectionSnapshot {
-    return {
-      ...this.info(record),
-      transforms: new Float32Array(record.transforms),
-      generations: new Uint32Array(record.generations),
-      dirtyRanges: record.dirtyRanges.map((range) => ({ ...range })),
-    };
-  }
-
-  private info(record: CollectionRecord): InstanceCollectionInfo {
-    return Object.freeze({
-      collectionId: record.id,
-      count: record.count,
-      capacity: record.capacity,
-      revision: record.revision,
-    });
-  }
-
-  private allocateGenerations(count: number): Uint32Array {
-    const generations = new Uint32Array(count);
-    for (let index = 0; index < count; index += 1) {
-      generations[index] = this.nextInstanceGeneration;
-      this.nextInstanceGeneration = (this.nextInstanceGeneration + 1) >>> 0 || 1;
-    }
-    return generations;
-  }
-
-  private validateReplacementGenerations(
-    generations: Uint32Array,
-    count: number,
-    collectionId: InstanceCollectionId,
-  ): InstanceCollectionResult<Uint32Array> {
-    if (!(generations instanceof Uint32Array) || generations.length !== count) {
-      return err(
-        invalid(
-          'replace',
-          `generations is a Uint32Array with ${count} entries`,
-          generations instanceof Uint32Array ? generations.length : typeof generations,
-          collectionId,
-          { requestedBytes: generations?.byteLength ?? 0, cause: 'invalid-generation-shape' },
-        ),
-      );
-    }
-    const seen = new Set<number>();
-    for (const generation of generations) {
-      if (generation === 0 || seen.has(generation)) {
-        return err(
-          invalid(
-            'replace',
-            'generations contain unique non-zero identity tokens',
-            generation,
-            collectionId,
-            {
-              requestedBytes: generations.byteLength,
-              cause: 'invalid-generation-identity',
-            },
-          ),
-        );
-      }
-      seen.add(generation);
-      if (generation >= this.nextInstanceGeneration) {
-        this.nextInstanceGeneration = (generation + 1) >>> 0 || 1;
-      }
-    }
-    return ok(new Uint32Array(generations));
-  }
-
-  private projectInspection(record: CollectionRecord): InstanceCollectionInspection {
-    const residency = this.residency.get(record.id);
-    return Object.freeze({
-      ...this.info(record),
-      residentGeneration: residency?.residentGeneration,
-      lane: residency?.lane ?? 'unresident',
-      dirtyRanges: Object.freeze(record.dirtyRanges.map((range) => ({ ...range }))),
-      uploadRanges: Object.freeze(residency?.uploadRanges.map((range) => ({ ...range })) ?? []),
-      uploadedBytes: residency?.uploadedBytes ?? 0,
-      requestedBytes: residency?.requestedBytes ?? record.count * MATRIX_STRIDE * 4,
-      supportedBytes: residency?.supportedBytes,
-      backend: residency?.backend ?? 'unknown',
-      owner: 'renderer.instances',
-      error: residency?.error,
+  _inspections(frameNumber: number): readonly InstanceCollectionInspection[] {
+    return [...this.records.values()].map((record) => {
+      const resident = this.residency.get(record.collectionId);
+      const current = resident?.frameNumber === frameNumber;
+      return {
+        collectionId: record.collectionId,
+        count: record.count,
+        revision: record.revision,
+        residentGeneration: resident?.residentGeneration,
+        lane: resident?.lane ?? 'unresident',
+        uploadRanges: current ? resident.uploadRanges.map((range) => ({ ...range })) : [],
+        uploadedBytes: current ? resident.uploadedBytes : 0,
+        requestedBytes: resident?.requestedBytes ?? record.transforms.byteLength,
+        supportedBytes: resident?.supportedBytes,
+        backend: resident?.backend ?? 'unknown',
+        owner: 'renderer.instances',
+        error: resident?.error,
+      };
     });
   }
 }