@forgeax/engine-render 0.1.3 → 0.1.6

package/src/persistent-render-scene.ts

@@ -1,1752 +0,0 @@
-import type { Component, EntityHandle, World } from '@forgeax/engine-ecs';
-import { Disabled } from '@forgeax/engine-ecs';
-import { createWorldProjection, type WorldProjection } from '@forgeax/engine-ecs/projection';
-import { box3, frustum, mat4 } from '@forgeax/engine-math';
-import type { RhiDevice, RhiError } from '@forgeax/engine-rhi';
-import { ChildOf, MorphWeights, Transform } from '@forgeax/engine-scene';
-import { Skin } from '@forgeax/engine-skinning';
-import {
-  Camera,
-  DirectionalLight,
-  Fog,
-  Instances,
-  Layer,
-  MeshFilter,
-  MeshRenderer,
-  PointLight,
-  PointLightShadow,
-  PostProcessParams,
-  SkyboxBackground,
-  Skylight,
-  SpotLight,
-  SpriteInstances,
-  SpriteRegionOverride,
-  Visibility,
-} from './components';
-import {
-  type CsmCameraData,
-  computeDirectionalCsm,
-  type DirectionalCsmCandidateBroadphase,
-} from './extract/directional-csm';
-import {
-  BatchTopology,
-  type BatchTopologyInspection,
-  type SubmissionPlan,
-} from './gpu-driven/batch-topology';
-import { GpuScene, type GpuSceneInspection } from './gpu-scene';
-import {
-  buildRenderCandidateDomain,
-  buildRenderCandidateIdentityIndex,
-  type RenderCandidateDomain,
-  renderCandidateCsmCandidates,
-  reuseRenderCandidateDomain,
-} from './render-dispatch-membership';
-import type {
-  RenderSceneApplyResult,
-  RenderSceneOperation,
-  RenderSceneSubmissionDelta,
-} from './render-scene-projection';
-import { RenderSceneProjection } from './render-scene-projection';
-import type {
-  CameraSnapshot,
-  DispatchEntry,
-  ExtractedFrame,
-  FogSelection,
-  FogSnapshot,
-  RenderableSnapshot,
-} from './render-system-extract';
-import { sortDispatchByQueue } from './render-system-extract';
-import { ACTIVE_CAMERA_KEY } from './systems/active-camera';
-
-export type RenderSceneResyncReason =
-  | 'attach'
-  | 'asset-catalog-changed'
-  | 'shared-ref-changed'
-  | 'journal-overflow'
-  | 'unsupported-change'
-  | 'non-rigid-lane'
-  | 'explicit-invalidate';
-
-export type PersistentFogFailureCode = 'fog-owner-conflict' | 'fog-parameters-invalid';
-
-export interface PersistentFogInspection {
-  readonly enabled: boolean;
-  readonly resourceOwner: number | undefined;
-  readonly entity: number | undefined;
-  readonly revision: number | undefined;
-  readonly reactive: boolean;
-  readonly failure: PersistentFogFailureCode | undefined;
-}
-
-export interface PersistentFogFailure {
-  readonly code: PersistentFogFailureCode;
-  readonly resourceOwner: number;
-}
-
-export interface PersistentRenderSceneInspection {
-  readonly worldEntitiesScanned: number;
-  readonly fullRebuilds: number;
-  readonly noChangeFrames: number;
-  readonly deltaFrames: number;
-  readonly transformUpdates: number;
-  readonly materialUpdates: number;
-  readonly instanceUpdates: number;
-  readonly cameraUpdates: number;
-  readonly resourceUpdates: number;
-  /** Number of journal entities admitted to the local topology reconciler. */
-  readonly topologyEntitiesReconciled: number;
-  /** Number of identity-addressed production render extractions requested. */
-  readonly singleEntityExtractions: number;
-  readonly removals: number;
-  readonly lastResyncReason: RenderSceneResyncReason | undefined;
-  /** @internal M0 attribution for a rebuild that otherwise only says unsupported-change. */
-  readonly lastResyncDetail: string | undefined;
-  readonly cursor: number | undefined;
-  readonly projectionRecords: number;
-  readonly spatialIndex: import('./render-scene-projection').SpatialIndexInspection | undefined;
-  readonly topology: BatchTopologyInspection;
-  readonly gpu:
-    | { readonly status: 'inactive' }
-    | { readonly status: 'unsupported'; readonly reason: 'storage-buffer-unavailable' }
-    | ({ readonly status: 'resident' } & GpuSceneInspection)
-    | { readonly status: 'rebuild-pending' }
-    | { readonly status: 'error' };
-  readonly fog: PersistentFogInspection;
-}
-
-export interface PersistentRenderSceneOptions {
-  readonly getDevice?: (() => RhiDevice) | undefined;
-  readonly onGpuError?: ((error: RhiError) => void) | undefined;
-  /** @internal Collect complete per-candidate CSM decisions for debug capture. */
-  readonly collectShadowDebugCandidates?: (() => boolean) | undefined;
-}
-
-/**
- * Complete facts produced by the render-domain admission owner for one ECS
- * entity. Dispatch entries use the local candidate index from that extraction;
- * PersistentRenderScene rebases them onto its slot-owned candidate domain.
- */
-export interface PersistentRenderableExtraction {
-  readonly snapshot: RenderableSnapshot;
-  readonly candidateDispatch: readonly DispatchEntry[];
-}
-
-export interface PersistentGpuDrivenState {
-  readonly scene: GpuScene;
-  readonly plan: SubmissionPlan;
-  readonly slots: readonly import('./render-scene-projection').RenderSceneProjectionSlot[];
-  /**
-   * The same projection that owns `slots` and the spatial index. Visibility
-   * must query this owner; a revision number copied into GpuScene is only
-   * diagnostic metadata and cannot select a candidate domain by itself.
-   */
-  /** Present for the production owner; optional keeps older test doubles honest. */
-  readonly projection?: RenderSceneProjection;
-}
-
-type PersistentGpuSceneInspection = PersistentRenderSceneInspection['gpu'];
-
-interface PersistentWorldEntry {
-  readonly worldId: number;
-  readonly projection: RenderSceneProjection;
-  readonly topology: BatchTopology;
-  candidateFrame: ExtractedFrame;
-  visibleFrame: ExtractedFrame;
-  readonly changeProjection: WorldProjection;
-  cursor: number;
-  catalogEpoch: number;
-  sharedRefEpoch: number;
-  activeCameraEpoch: number;
-  cameraEntities: ReadonlySet<EntityHandle>;
-  readonly rigidOnly: boolean;
-  gpuDrivenCoverageKey: string | undefined;
-  gpuDrivenOwnsAll: boolean;
-}
-
-interface PersistentCompositionEntry {
-  readonly token: object;
-  readonly worlds: readonly World[];
-  readonly worldIds: readonly number[];
-  readonly cameraOwner: number;
-  readonly resourceOwner: number;
-  readonly projection: RenderSceneProjection;
-  readonly topology: BatchTopology;
-  readonly changeProjections: readonly WorldProjection[];
-  candidateFrame: ExtractedFrame;
-  visibleFrame: ExtractedFrame;
-  readonly cursors: number[];
-  readonly sharedRefEpochs: number[];
-  readonly cameraEntities: readonly ReadonlySet<EntityHandle>[];
-  catalogEpoch: number;
-  readonly rigidOnly: boolean;
-  gpuDrivenCoverageKey: string | undefined;
-  gpuDrivenOwnsAll: boolean;
-}
-
-const RENDER_RELEVANT_COMPONENTS = [
-  Transform,
-  ChildOf,
-  MeshFilter,
-  MeshRenderer,
-  Instances,
-  SpriteInstances,
-  SpriteRegionOverride,
-  Skin,
-  MorphWeights,
-  Layer,
-  Visibility,
-  Disabled,
-  Camera,
-  DirectionalLight,
-  PointLight,
-  PointLightShadow,
-  SpotLight,
-  Skylight,
-  Fog,
-  SkyboxBackground,
-  PostProcessParams,
-] as const;
-const RENDER_RELEVANT_COMPONENT_SET = new Set<Component>(RENDER_RELEVANT_COMPONENTS);
-
-const NON_RENDERABLE_TRANSFORM_CONSUMERS = [
-  Camera,
-  DirectionalLight,
-  PointLight,
-  SpotLight,
-] as const;
-
-function cameraFrusta(cameras: readonly CameraSnapshot[]): readonly Float32Array[] {
-  const planes: Float32Array[] = [];
-  for (const camera of cameras) {
-    if (
-      (camera.projection === 'perspective' && (camera.fov <= 0 || camera.aspect <= 0)) ||
-      camera.near >= camera.far
-    ) {
-      planes.push(new Float32Array(0));
-      continue;
-    }
-    const projection = mat4.create();
-    if (camera.projection === 'orthographic') {
-      mat4.orthographic(
-        projection,
-        camera.orthoLeft,
-        camera.orthoRight,
-        camera.orthoBottom,
-        camera.orthoTop,
-        camera.near,
-        camera.far,
-      );
-    } else {
-      mat4.perspective(projection, camera.fov, camera.aspect, camera.near, camera.far);
-    }
-    const view = mat4.create();
-    mat4.invert(view, camera.world as unknown as mat4.Mat4Like);
-    const viewProjection = mat4.create();
-    mat4.multiply(viewProjection, projection, view);
-    const cameraPlanes = frustum.create();
-    frustum.fromViewProjection(cameraPlanes, viewProjection);
-    planes.push(cameraPlanes);
-  }
-  return planes;
-}
-
-function candidateBroadphaseForProjection(
-  projection: RenderSceneProjection,
-  candidateDomain: RenderCandidateDomain,
-): DirectionalCsmCandidateBroadphase {
-  return (worldAabb) =>
-    projection.querySpatialIndex(worldAabb).hits.flatMap((hit) => {
-      const candidateIndex = candidateDomain.indexByIdentity.get(`${hit.worldId}:${hit.entityKey}`);
-      return candidateIndex === undefined ? [] : [candidateIndex];
-    });
-}
-
-function rebaseCandidateDomain(
-  frame: ExtractedFrame,
-  candidates: readonly RenderableSnapshot[],
-  patch?: {
-    readonly worldId: number;
-    readonly dispatch: readonly DispatchEntry[];
-    readonly replaceIdentities: ReadonlySet<string>;
-  },
-): ExtractedFrame {
-  const previousCandidates =
-    frame.candidateDomain?.renderables ?? frame.candidateRenderables ?? frame.renderables;
-  const previousDispatch =
-    frame.candidateDomain?.dispatch ?? frame.candidateDispatch ?? frame.dispatch;
-  const previousDomain =
-    frame.candidateDomain ?? buildRenderCandidateDomain(previousCandidates, previousDispatch);
-  const candidateDomainUnchanged =
-    previousCandidates.length === candidates.length &&
-    previousCandidates.every(
-      (candidate, candidateIndex) =>
-        candidate === candidates[candidateIndex] &&
-        (candidate.candidateIndex === undefined || candidate.candidateIndex === candidateIndex),
-    );
-  if (candidateDomainUnchanged && frame.candidateDomain !== undefined) {
-    // Camera-only refreshes must not manufacture a new candidate array, index
-    // map, dispatch array, or membership Set when the domain is unchanged.
-    return frame;
-  }
-  const candidateRenderables = candidates.map((candidate, candidateIndex) =>
-    candidate.candidateIndex === candidateIndex ? candidate : { ...candidate, candidateIndex },
-  );
-  const nextIndexByIdentity = buildRenderCandidateIdentityIndex(candidateRenderables);
-
-  const candidateDispatch = previousDomain.dispatch.flatMap((entry) => {
-    const previousCandidate = previousCandidates[entry.renderableIndex];
-    if (previousCandidate === undefined) return [];
-    if (
-      patch?.replaceIdentities.has(
-        `${previousCandidate.worldId}:${previousCandidate.entityKey}`,
-      ) === true
-    ) {
-      return [];
-    }
-    const candidateIndex = nextIndexByIdentity.get(
-      `${previousCandidate.worldId}:${previousCandidate.entityKey}`,
-    );
-    return candidateIndex === undefined ? [] : [{ ...entry, renderableIndex: candidateIndex }];
-  });
-  if (patch !== undefined) {
-    for (const entry of patch.dispatch) {
-      const candidateIndex = nextIndexByIdentity.get(`${patch.worldId}:${entry.entityIndex}`);
-      if (candidateIndex === undefined) continue;
-      candidateDispatch.push({ ...entry, renderableIndex: candidateIndex });
-    }
-  }
-  const candidateDomain = buildRenderCandidateDomain(
-    candidateRenderables,
-    sortDispatchByQueue(candidateDispatch),
-    nextIndexByIdentity,
-  );
-
-  return {
-    ...frame,
-    candidateRenderables: candidateDomain.renderables,
-    candidateDispatch: candidateDomain.dispatch,
-    candidateDispatchMembership: candidateDomain.membership,
-    candidateDomain,
-  };
-}
-
-function cullPersistentFrame(
-  frame: ExtractedFrame,
-  candidates: readonly RenderableSnapshot[],
-  collectShadowDebugCandidates = false,
-  projection?: RenderSceneProjection,
-): ExtractedFrame {
-  const planes = cameraFrusta(frame.cameras);
-  const candidateSnapshots =
-    frame.candidateDomain?.renderables ?? frame.candidateRenderables ?? candidates;
-  const candidateDispatch =
-    frame.candidateDomain?.dispatch ?? frame.candidateDispatch ?? frame.dispatch;
-  const candidateDomain = reuseRenderCandidateDomain(
-    candidateSnapshots,
-    candidateDispatch,
-    frame.candidateDomain,
-  );
-  const mainVisible = new Set<number>();
-  let total = 0;
-  let culled = 0;
-
-  for (let index = 0; index < candidateSnapshots.length; index += 1) {
-    const candidate = candidateSnapshots[index];
-    if (candidate === undefined) continue;
-    let isVisible = true;
-    if (candidate.localAabb !== undefined) {
-      total += 1;
-      const worldAabb = box3.create();
-      box3.transformBox3(
-        worldAabb,
-        candidate.localAabb,
-        candidate.transform.world as unknown as Parameters<typeof box3.transformBox3>[2],
-      );
-      isVisible = planes.length === 0;
-      for (const cameraPlanes of planes) {
-        if (
-          cameraPlanes.length === 0 ||
-          frustum.intersectsBox(cameraPlanes as frustum.Frustum, worldAabb as box3.Box3Like)
-        ) {
-          isVisible = true;
-          break;
-        }
-      }
-    }
-    if (!isVisible) {
-      culled += 1;
-      continue;
-    }
-    mainVisible.add(index);
-  }
-
-  const camera = frame.cameras[0];
-  const csmConfig = frame.lights.directionalCsmConfig;
-  const csmDirection = frame.lights.directionalCsmDirection;
-  const csmCamera: CsmCameraData | undefined =
-    camera === undefined
-      ? undefined
-      : {
-          world: camera.world,
-          fov: camera.fov,
-          aspect: camera.aspect,
-          near: camera.near,
-          far: camera.far,
-          projection: camera.projection,
-          orthoLeft: camera.orthoLeft,
-          orthoRight: camera.orthoRight,
-          orthoBottom: camera.orthoBottom,
-          orthoTop: camera.orthoTop,
-        };
-  const candidateDispatchMembership = candidateDomain.membership;
-  const recomputedCsm =
-    csmConfig !== undefined && csmDirection !== undefined
-      ? computeDirectionalCsm(
-          csmDirection,
-          { ...csmConfig, collectCandidateDecisions: collectShadowDebugCandidates },
-          csmCamera,
-          renderCandidateCsmCandidates(candidateDomain),
-          projection === undefined
-            ? undefined
-            : candidateBroadphaseForProjection(projection, candidateDomain),
-        )
-      : undefined;
-  const csm = recomputedCsm ?? frame.lights.directionalCsm;
-  if (csm !== undefined) {
-    for (const cascade of csm.cascades) {
-      for (const index of cascade.casterRenderableIndices) {
-        // Keep the candidate index stable across main-view culling.
-        if (index >= 0) mainVisible.add(index);
-      }
-    }
-  }
-
-  const unionIndices = [...mainVisible].sort((left, right) => left - right);
-  const projectedIndex = new Int32Array(candidateSnapshots.length);
-  projectedIndex.fill(-1);
-  const visible: RenderableSnapshot[] = [];
-  for (const candidateIndex of unionIndices) {
-    const candidate = candidateSnapshots[candidateIndex];
-    if (candidate === undefined) continue;
-    projectedIndex[candidateIndex] = visible.length;
-    visible.push(candidate);
-  }
-
-  const dispatch: DispatchEntry[] = [];
-  for (const entry of candidateDispatch) {
-    const renderableIndex = projectedIndex[entry.renderableIndex];
-    if (renderableIndex === undefined || renderableIndex < 0) continue;
-    dispatch.push({ ...entry, renderableIndex });
-  }
-  const finalizedCsm = csm;
-  const nextLights =
-    finalizedCsm === undefined
-      ? frame.lights
-      : {
-          ...frame.lights,
-          // The CSM plan owns receiver matrices and cascade volumes. Camera
-          // refresh can first produce a no-candidate fit; once the candidate
-          // domain is available here, publish every light field from the same
-          // finalized plan so four-view visibility and the View UBO cannot use
-          // different cascade spaces.
-          lightViewProj: finalizedCsm.lightViewProj,
-          splitPlanes: finalizedCsm.splitPlanes,
-          cascadeCount: finalizedCsm.cascadeCount,
-          cascadeBlend: finalizedCsm.cascadeBlend,
-          shadowMapSize: finalizedCsm.shadowMapSize,
-          directionalCsm: finalizedCsm,
-          cascades: finalizedCsm.cascades,
-        };
-  return {
-    ...frame,
-    renderables: visible,
-    dispatch,
-    candidateRenderables: candidateDomain.renderables,
-    candidateDispatch: candidateDomain.dispatch,
-    candidateDispatchMembership,
-    candidateDomain,
-    lights: nextLights,
-    frustumStats: { culled, total },
-  };
-}
-
-/** Persistent single-World rigid scene used by the renderer's ordinary path. */
-export class PersistentRenderScene {
-  private readonly entries = new WeakMap<World, PersistentWorldEntry>();
-  private readonly worldIds = new WeakMap<World, number>();
-  private readonly worldsById = new Map<number, World>();
-  private nextWorldId = 0;
-  private fullRebuilds = 0;
-  private worldEntitiesScanned = 0;
-  private noChangeFrames = 0;
-  private deltaFrames = 0;
-  private transformUpdates = 0;
-  private materialUpdates = 0;
-  private instanceUpdates = 0;
-  private cameraUpdates = 0;
-  private resourceUpdates = 0;
-  private topologyEntitiesReconciled = 0;
-  private singleEntityExtractions = 0;
-  private removals = 0;
-  private lastResyncReason: RenderSceneResyncReason | undefined;
-  private lastResyncDetail: string | undefined;
-  private lastWorld: World | undefined;
-  private composition: PersistentCompositionEntry | undefined;
-  private gpuScene: GpuScene | undefined;
-  private gpuOwner: object | undefined;
-  private gpuDevice: RhiDevice | undefined;
-  private gpuStatus: 'inactive' | 'unsupported' | 'resident' | 'rebuild-pending' | 'error' =
-    'inactive';
-  private fogCandidate: FogSelection | undefined;
-  private fogLastKnownGood: FogSelection | undefined;
-  private fogFailure: PersistentFogFailureCode | undefined;
-  private fogFailureOwner: number | undefined;
-  private fogReactive = false;
-
-  constructor(private readonly options: PersistentRenderSceneOptions = {}) {}
-
-  readonly worldForRenderId = (worldId: number): World | undefined => this.worldsById.get(worldId);
-
-  extract(
-    world: World,
-    catalogEpoch: number,
-    buildCandidateFrame: () => ExtractedFrame,
-    refreshMaterial?: (
-      snapshot: RenderableSnapshot,
-      materialHandle: number,
-    ) => RenderableSnapshot | undefined,
-    refreshCameras?: (frame: ExtractedFrame) => ExtractedFrame,
-    gpuDrivenCoverageKey?: string,
-    refreshPostProcessParams?: (frame: ExtractedFrame) => ExtractedFrame,
-    refreshLights?: (frame: ExtractedFrame) => ExtractedFrame,
-    refreshRenderable?: (
-      entity: EntityHandle,
-      currentFrame: ExtractedFrame,
-    ) => PersistentRenderableExtraction | undefined,
-  ): ExtractedFrame {
-    this.worldEntitiesScanned = 0;
-    this.lastWorld = world;
-    this.attachWorld(world);
-    const entry = this.entries.get(world);
-    if (entry === undefined) {
-      return this.rebuild(world, catalogEpoch, buildCandidateFrame, 'attach');
-    }
-    if (entry.catalogEpoch !== catalogEpoch) {
-      return this.rebuild(world, catalogEpoch, buildCandidateFrame, 'asset-catalog-changed');
-    }
-    const sharedRefChanges = world.sharedRefs.readChangesSince(entry.sharedRefEpoch);
-    if (sharedRefChanges.status === 'overflow') {
-      return this.rebuild(world, catalogEpoch, buildCandidateFrame, 'shared-ref-changed');
-    }
-
-    const changes = entry.changeProjection.poll();
-    if (changes.status === 'rebuild') {
-      return this.rebuild(world, catalogEpoch, buildCandidateFrame, 'journal-overflow');
-    }
-    const refreshedBySlot = new Map<number, RenderableSnapshot>();
-    for (const change of sharedRefChanges.records) {
-      const affected = entry.projection.slotsForMaterial(change.handle);
-      if (affected.length > 0 && refreshMaterial === undefined) {
-        return this.rebuild(world, catalogEpoch, buildCandidateFrame, 'shared-ref-changed');
-      }
-      for (const slot of affected) {
-        const current = refreshedBySlot.get(slot.slot) ?? slot.snapshot;
-        const refreshed = refreshMaterial?.(current, change.handle);
-        if (refreshed === undefined) {
-          return this.rebuild(world, catalogEpoch, buildCandidateFrame, 'shared-ref-changed');
-        }
-        refreshedBySlot.set(slot.slot, refreshed);
-      }
-    }
-    const materialOperations: RenderSceneOperation[] = [...refreshedBySlot.entries()].map(
-      ([slot, snapshot]) => {
-        const liveSlot = entry.projection.slotByIndex(slot);
-        return {
-          kind: 'create',
-          snapshot,
-          ...(liveSlot === undefined ? {} : { expectedGeneration: liveSlot.generation }),
-        };
-      },
-    );
-    let postProcessParamsChanged = false;
-    let lightsChanged = false;
-    const activeCameraEpoch = world.getResourceChange(ACTIVE_CAMERA_KEY)?.changed ?? 0;
-    let cameraChanged = activeCameraEpoch !== entry.activeCameraEpoch;
-    if (
-      !entry.rigidOnly &&
-      (changes.changes.length > 0 || materialOperations.length > 0 || cameraChanged)
-    ) {
-      return this.rebuild(world, catalogEpoch, buildCandidateFrame, 'non-rigid-lane');
-    }
-    if (changes.changes.length === 0 && materialOperations.length === 0 && !cameraChanged) {
-      entry.cursor = changes.cursor;
-      entry.sharedRefEpoch = sharedRefChanges.cursor;
-      this.noChangeFrames += 1;
-      this.syncGpu(world, entry.projection);
-      return entry.visibleFrame;
-    }
-
-    const derivedTransforms = new Set<EntityHandle>();
-    const removedRenderables = new Set<EntityHandle>();
-    const instanceOperations: RenderSceneOperation[] = [];
-    const topologyEntities = new Set<EntityHandle>();
-    const topologyDispatch: DispatchEntry[] = [];
-    const topologyIdentities = new Set<string>();
-    for (const record of changes.changes) {
-      if (record.kind === 'derived-component-changed' && record.component === Transform) {
-        derivedTransforms.add(record.entity as EntityHandle);
-      }
-    }
-    for (const record of changes.changes) {
-      const authoredTransform =
-        record.kind === 'component-changed' && record.component === Transform;
-      const derivedTransform =
-        record.kind === 'derived-component-changed' && record.component === Transform;
-      const wasCamera = entry.cameraEntities.has(record.entity as EntityHandle);
-      const isCamera = world.hasComponent(record.entity as EntityHandle, Camera);
-      if (
-        record.component === Camera ||
-        ((authoredTransform || derivedTransform) && (wasCamera || isCamera))
-      ) {
-        cameraChanged = true;
-        continue;
-      }
-      if (record.component === PostProcessParams && record.kind !== 'entity-removed') {
-        if (refreshPostProcessParams === undefined) {
-          return this.rebuild(
-            world,
-            catalogEpoch,
-            buildCandidateFrame,
-            'unsupported-change',
-            'post-process-refresh-unavailable',
-          );
-        }
-        // PostProcessParams is a resource-owner input, not a render-domain
-        // slot. Refresh its compact map without invalidating the candidate,
-        // dispatch, topology, or GPU scene owner.
-        postProcessParamsChanged = true;
-        continue;
-      }
-      if (record.kind === 'entity-removed' && wasCamera) {
-        cameraChanged = true;
-        if (refreshLights !== undefined) lightsChanged = true;
-        if (entry.projection.has(entry.worldId, record.entity)) {
-          removedRenderables.add(record.entity as EntityHandle);
-        }
-        continue;
-      }
-      if (record.kind === 'entity-removed') {
-        if (refreshLights !== undefined) lightsChanged = true;
-        if (entry.projection.has(entry.worldId, record.entity)) {
-          removedRenderables.add(record.entity as EntityHandle);
-        }
-        continue;
-      }
-      if (
-        record.component === DirectionalLight ||
-        record.component === PointLight ||
-        record.component === PointLightShadow ||
-        record.component === SpotLight ||
-        record.component === Skylight ||
-        record.component === Fog ||
-        record.component === SkyboxBackground
-      ) {
-        if (refreshLights === undefined) {
-          return this.rebuild(
-            world,
-            catalogEpoch,
-            buildCandidateFrame,
-            'unsupported-change',
-            `light-refresh-unavailable:${record.kind}:${record.componentId}:${record.entity}`,
-          );
-        }
-        // Light and shadow components feed compact extracted resources. A
-        // mutation there must not invalidate render-domain slots, dispatch,
-        // candidate membership, topology, or the GPU scene owner.
-        lightsChanged = true;
-        continue;
-      }
-      if (derivedTransform) continue;
-      if (authoredTransform && derivedTransforms.has(record.entity as EntityHandle)) continue;
-      if (record.component === Instances && entry.projection.has(entry.worldId, record.entity)) {
-        const current = entry.projection.snapshot(entry.worldId, record.entity);
-        if (current === undefined) continue;
-        const instances = world.get(record.entity, Instances);
-        const transforms = instances.ok ? instances.value.transforms : undefined;
-        if (transforms === undefined) {
-          const { instances: _instances, ...withoutInstances } = current;
-          const liveRecord = entry.projection.record(entry.worldId, record.entity);
-          instanceOperations.push({
-            kind: 'create',
-            snapshot: withoutInstances,
-            ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-          });
-          continue;
-        }
-        if (transforms.length % 16 !== 0) {
-          return this.rebuild(
-            world,
-            catalogEpoch,
-            buildCandidateFrame,
-            'unsupported-change',
-            `instance-transform-length:${record.entity}:${transforms.length}`,
-          );
-        }
-        const liveRecord = entry.projection.record(entry.worldId, record.entity);
-        instanceOperations.push({
-          kind: 'create',
-          snapshot: {
-            ...current,
-            instances: {
-              transforms: new Float32Array(transforms),
-              instanceCount: Math.max(1, transforms.length / 16),
-              cacheKey: record.entity,
-              archVersion: (current.instances?.archVersion ?? 0) + 1,
-            },
-          },
-          ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-        });
-        continue;
-      }
-      if (record.component !== undefined && !RENDER_RELEVANT_COMPONENT_SET.has(record.component)) {
-        continue;
-      }
-      if (
-        refreshRenderable !== undefined &&
-        record.component !== ChildOf &&
-        record.component !== Visibility &&
-        record.component !== Skin
-      ) {
-        // Reconcile the final entity state once after all journal records have
-        // been classified. This is the generic admission path for a new or
-        // materially changed renderable; hierarchy, inherited visibility, and
-        // skin changes stay on their existing conservative lanes.
-        topologyEntities.add(record.entity as EntityHandle);
-        continue;
-      }
-      return this.rebuild(
-        world,
-        catalogEpoch,
-        buildCandidateFrame,
-        'unsupported-change',
-        `change-record:${record.kind}:${record.componentId ?? 'none'}:${record.entity}`,
-      );
-    }
-
-    const operations: RenderSceneOperation[] = [
-      ...materialOperations,
-      ...instanceOperations.filter((operation) => {
-        return !(
-          operation.kind === 'create' &&
-          topologyEntities.has(operation.snapshot.entityKey as EntityHandle)
-        );
-      }),
-      ...[...removedRenderables].map((entity): RenderSceneOperation => {
-        const liveRecord = entry.projection.record(entry.worldId, entity);
-        return {
-          kind: 'remove',
-          worldId: entry.worldId,
-          entityKey: entity,
-          ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-        };
-      }),
-    ];
-    let transformOperationCount = 0;
-    for (const entity of derivedTransforms) {
-      if (topologyEntities.has(entity)) continue;
-      // A FixedUpdate can derive Transform and despawn the same entity before
-      // the render projection polls its journal. The entity-removed record is
-      // already authoritative for the projection; do not turn that stale
-      // derived record into a full rebuild or read a component that no longer
-      // exists.
-      if (removedRenderables.has(entity)) continue;
-      if (!entry.projection.has(entry.worldId, entity)) {
-        if (entry.cameraEntities.has(entity) || world.hasComponent(entity, Camera)) continue;
-        if (
-          NON_RENDERABLE_TRANSFORM_CONSUMERS.some((component) =>
-            world.hasComponent(entity, component),
-          )
-        ) {
-          if (refreshLights === undefined) {
-            return this.rebuild(
-              world,
-              catalogEpoch,
-              buildCandidateFrame,
-              'unsupported-change',
-              `non-renderable-transform-consumer:${entity}`,
-            );
-          }
-          lightsChanged = true;
-          continue;
-        }
-        continue;
-      }
-      const transform = world.get(entity, Transform);
-      if (!transform.ok) {
-        return this.rebuild(
-          world,
-          catalogEpoch,
-          buildCandidateFrame,
-          'unsupported-change',
-          `derived-transform-unavailable:${entity}`,
-        );
-      }
-      const liveRecord = entry.projection.record(entry.worldId, entity);
-      operations.push({
-        kind: 'update-transform',
-        worldId: entry.worldId,
-        entityKey: entity,
-        world: new Float32Array(transform.value.world),
-        ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-      });
-      transformOperationCount += 1;
-    }
-    if (refreshRenderable !== undefined) {
-      this.topologyEntitiesReconciled += topologyEntities.size;
-      for (const entity of topologyEntities) {
-        const liveRecord = entry.projection.record(entry.worldId, entity);
-        topologyIdentities.add(`${entry.worldId}:${entity}`);
-        const hasRenderableComponents =
-          world.hasComponent(entity, Transform) &&
-          world.hasComponent(entity, MeshFilter) &&
-          world.hasComponent(entity, MeshRenderer) &&
-          !world.hasComponent(entity, Disabled);
-        const extracted = hasRenderableComponents
-          ? (() => {
-              this.singleEntityExtractions += 1;
-              return refreshRenderable(entity, entry.candidateFrame);
-            })()
-          : undefined;
-        if (extracted === undefined) {
-          if (liveRecord !== undefined && !removedRenderables.has(entity)) {
-            operations.push({
-              kind: 'remove',
-              worldId: entry.worldId,
-              entityKey: entity,
-              expectedGeneration: liveRecord.generation,
-            });
-          }
-          continue;
-        }
-        const snapshot =
-          extracted.snapshot.worldId === entry.worldId
-            ? extracted.snapshot
-            : { ...extracted.snapshot, worldId: entry.worldId };
-        operations.push({
-          kind: 'create',
-          snapshot,
-          ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-        });
-        topologyDispatch.push(...extracted.candidateDispatch);
-      }
-    }
-    // A stale derived Transform record can discover that the Transform column
-    // disappeared after the initial operation list was assembled. Materialize
-    // that late remove before the projection apply; otherwise the diagnostic
-    // set says "removed" while the retained slot remains live for one frame.
-    const removeOperations = new Set(
-      operations.flatMap((operation) =>
-        operation.kind === 'remove' ? [`${operation.worldId}:${operation.entityKey}`] : [],
-      ),
-    );
-    for (const entity of removedRenderables) {
-      const liveRecord = entry.projection.record(entry.worldId, entity);
-      const identity = `${entry.worldId}:${entity}`;
-      if (liveRecord === undefined || removeOperations.has(identity)) continue;
-      operations.push({
-        kind: 'remove',
-        worldId: entry.worldId,
-        entityKey: entity,
-        expectedGeneration: liveRecord.generation,
-      });
-      removeOperations.add(identity);
-    }
-    if (operations.length === 0 && !cameraChanged && !postProcessParamsChanged && !lightsChanged) {
-      entry.cursor = changes.cursor;
-      entry.sharedRefEpoch = sharedRefChanges.cursor;
-      this.noChangeFrames += 1;
-      this.syncGpu(world, entry.projection);
-      return entry.visibleFrame;
-    }
-    if (operations.length > 0) {
-      const delta = entry.projection.apply(operations);
-      entry.topology.apply(delta);
-      this.syncGpu(world, entry.projection, delta);
-      const candidates = entry.projection.materialize();
-      const rebased = rebaseCandidateDomain(
-        entry.candidateFrame,
-        candidates,
-        topologyEntities.size === 0
-          ? undefined
-          : {
-              worldId: entry.worldId,
-              dispatch: topologyDispatch,
-              replaceIdentities: topologyIdentities,
-            },
-      );
-      entry.candidateFrame = { ...rebased, renderables: [...candidates] };
-    } else {
-      this.syncGpu(world, entry.projection);
-    }
-    if (cameraChanged) {
-      if (refreshCameras === undefined) {
-        return this.rebuild(
-          world,
-          catalogEpoch,
-          buildCandidateFrame,
-          'unsupported-change',
-          'camera-refresh-unavailable',
-        );
-      }
-      const candidates = entry.projection.materialize();
-      const refreshed = rebaseCandidateDomain(refreshCameras(entry.candidateFrame), candidates);
-      entry.candidateFrame = { ...refreshed, renderables: [...candidates] };
-      entry.cameraEntities = this.cameraEntities(world);
-      entry.activeCameraEpoch = activeCameraEpoch;
-      this.cameraUpdates += 1;
-    }
-    if (postProcessParamsChanged && refreshPostProcessParams !== undefined) {
-      // Refresh candidate and visible frames separately because the latter is
-      // the cull projection of the former and may be returned without a cull
-      // pass when this is the only changed lane.
-      entry.candidateFrame = refreshPostProcessParams(entry.candidateFrame);
-      entry.visibleFrame = refreshPostProcessParams(entry.visibleFrame);
-    }
-    if (lightsChanged && refreshLights !== undefined) {
-      // Refresh candidate and visible frames separately so a light-only
-      // update preserves the existing visible projection while publishing
-      // the new light/CSM/point-shadow snapshot to both frame owners.
-      entry.candidateFrame = refreshLights(entry.candidateFrame);
-      entry.visibleFrame = refreshLights(entry.visibleFrame);
-    }
-    if (postProcessParamsChanged || lightsChanged) this.resourceUpdates += 1;
-    if (operations.length > 0 || cameraChanged) {
-      const candidates = entry.projection.materialize();
-      entry.visibleFrame =
-        operations.length === 0 &&
-        cameraChanged &&
-        entry.gpuDrivenOwnsAll &&
-        entry.gpuDrivenCoverageKey === gpuDrivenCoverageKey
-          ? entry.candidateFrame
-          : cullPersistentFrame(
-              entry.candidateFrame,
-              candidates,
-              this.options.collectShadowDebugCandidates?.() === true,
-              entry.projection,
-            );
-    }
-    entry.cursor = changes.cursor;
-    entry.sharedRefEpoch = sharedRefChanges.cursor;
-    this.deltaFrames += 1;
-    this.transformUpdates += transformOperationCount;
-    this.materialUpdates += materialOperations.length;
-    this.instanceUpdates += instanceOperations.length;
-    this.removals += removedRenderables.size;
-    return entry.visibleFrame;
-  }
-
-  extractComposition(
-    worlds: readonly World[],
-    owner: { readonly cameraOwner: number; readonly resourceOwner: number },
-    catalogEpoch: number,
-    buildCandidateFrame: () => ExtractedFrame,
-    refreshRenderable?: (
-      world: World,
-      worldId: number,
-      entity: EntityHandle,
-      currentFrame: ExtractedFrame,
-    ) => PersistentRenderableExtraction | undefined,
-  ): ExtractedFrame {
-    this.worldEntitiesScanned = 0;
-    const worldIds = worlds.map((world) => this.attachWorld(world));
-    const entry = this.composition;
-    if (
-      entry === undefined ||
-      entry.catalogEpoch !== catalogEpoch ||
-      entry.cameraOwner !== owner.cameraOwner ||
-      entry.resourceOwner !== owner.resourceOwner ||
-      entry.worlds.length !== worlds.length ||
-      entry.worlds.some((world, index) => world !== worlds[index]) ||
-      entry.worldIds.some((worldId, index) => worldId !== worldIds[index])
-    ) {
-      return this.rebuildComposition(worlds, worldIds, owner, catalogEpoch, buildCandidateFrame);
-    }
-    if (!entry.rigidOnly) {
-      return this.rebuildComposition(worlds, worldIds, owner, catalogEpoch, buildCandidateFrame);
-    }
-
-    const operations: RenderSceneOperation[] = [];
-    const topologyEntities = new Map<
-      string,
-      { readonly world: World; readonly worldId: number; readonly entity: EntityHandle }
-    >();
-    const topologyDispatchByWorld = new Map<number, DispatchEntry[]>();
-    const topologyIdentitiesByWorld = new Map<number, Set<string>>();
-    const removalIdentities = new Set<string>();
-    let transformOperationCount = 0;
-    let removalOperationCount = 0;
-    let requiresRebuild = false;
-    for (let worldId = 0; worldId < worlds.length; worldId += 1) {
-      const world = worlds[worldId];
-      if (world === undefined) continue;
-      const renderWorldId = entry.worldIds[worldId];
-      if (renderWorldId === undefined) {
-        requiresRebuild = true;
-        break;
-      }
-      const changeProjection = entry.changeProjections[worldId];
-      if (changeProjection === undefined) {
-        requiresRebuild = true;
-        break;
-      }
-      const changes = changeProjection.poll();
-      const shared = world.sharedRefs.readChangesSince(entry.sharedRefEpochs[worldId] ?? 0);
-      if (changes.status === 'rebuild' || shared.status === 'overflow') {
-        requiresRebuild = true;
-        break;
-      }
-      if (shared.records.length > 0) {
-        requiresRebuild = true;
-        break;
-      }
-      const derivedTransforms = new Set<EntityHandle>();
-      for (const record of changes.changes) {
-        if (record.kind === 'derived-component-changed' && record.component === Transform) {
-          derivedTransforms.add(record.entity as EntityHandle);
-        }
-      }
-      for (const record of changes.changes) {
-        if (
-          record.kind !== 'entity-removed' &&
-          record.component !== undefined &&
-          !RENDER_RELEVANT_COMPONENT_SET.has(record.component)
-        ) {
-          continue;
-        }
-        const authoredTransform =
-          record.kind === 'component-changed' && record.component === Transform;
-        const derivedTransform =
-          record.kind === 'derived-component-changed' && record.component === Transform;
-        if (derivedTransform) continue;
-        if (authoredTransform && derivedTransforms.has(record.entity as EntityHandle)) continue;
-        const entity = record.entity as EntityHandle;
-        const identity = `${renderWorldId}:${entity}`;
-        const wasCamera = entry.cameraEntities[worldId]?.has(entity) === true;
-        if (record.kind === 'entity-removed') {
-          // Camera/light/resource removal changes the composed frame-level
-          // owner. Keep that path conservative; ordinary renderable removal
-          // can be addressed directly by the projection owner.
-          if (wasCamera || !entry.projection.has(renderWorldId, entity)) {
-            if (wasCamera) requiresRebuild = true;
-            continue;
-          }
-          if (!removalIdentities.has(identity)) {
-            const liveRecord = entry.projection.record(renderWorldId, entity);
-            operations.push({
-              kind: 'remove',
-              worldId: renderWorldId,
-              entityKey: entity,
-              ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-            });
-            removalIdentities.add(identity);
-            removalOperationCount += 1;
-          }
-          continue;
-        }
-        if (
-          record.component === Camera ||
-          record.component === DirectionalLight ||
-          record.component === PointLight ||
-          record.component === PointLightShadow ||
-          record.component === SpotLight ||
-          record.component === Skylight ||
-          record.component === Fog ||
-          record.component === SkyboxBackground ||
-          record.component === PostProcessParams ||
-          wasCamera
-        ) {
-          requiresRebuild = true;
-          break;
-        }
-        if (
-          (authoredTransform || record.component === Transform) &&
-          entry.projection.has(renderWorldId, entity)
-        ) {
-          const transform = world.get(record.entity, Transform);
-          if (!transform.ok) {
-            requiresRebuild = true;
-            break;
-          }
-          const liveRecord = entry.projection.record(renderWorldId, entity);
-          operations.push({
-            kind: 'update-transform',
-            worldId: renderWorldId,
-            entityKey: record.entity,
-            world: new Float32Array(transform.value.world),
-            ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-          });
-          transformOperationCount += 1;
-          continue;
-        }
-        if (
-          refreshRenderable !== undefined &&
-          record.component !== ChildOf &&
-          record.component !== Visibility &&
-          record.component !== Skin
-        ) {
-          topologyEntities.set(identity, { world, worldId: renderWorldId, entity });
-          continue;
-        }
-        requiresRebuild = true;
-        break;
-      }
-      if (!requiresRebuild) {
-        for (const entity of derivedTransforms) {
-          const identity = `${renderWorldId}:${entity}`;
-          if (topologyEntities.has(identity)) continue;
-          if (entry.projection.has(renderWorldId, entity)) {
-            const transform = world.get(entity, Transform);
-            if (!transform.ok) {
-              requiresRebuild = true;
-              break;
-            }
-            const liveRecord = entry.projection.record(renderWorldId, entity);
-            operations.push({
-              kind: 'update-transform',
-              worldId: renderWorldId,
-              entityKey: entity,
-              world: new Float32Array(transform.value.world),
-              ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-            });
-            transformOperationCount += 1;
-            continue;
-          }
-          if (
-            NON_RENDERABLE_TRANSFORM_CONSUMERS.some((component) =>
-              world.hasComponent(entity, component),
-            )
-          ) {
-            requiresRebuild = true;
-            break;
-          }
-        }
-      }
-      if (requiresRebuild) break;
-      entry.cursors[worldId] = changes.cursor;
-      entry.sharedRefEpochs[worldId] = shared.cursor;
-    }
-    if (requiresRebuild) {
-      return this.rebuildComposition(worlds, worldIds, owner, catalogEpoch, buildCandidateFrame);
-    }
-    if (refreshRenderable !== undefined && topologyEntities.size > 0) {
-      this.topologyEntitiesReconciled += topologyEntities.size;
-      for (const { world, worldId, entity } of topologyEntities.values()) {
-        const identity = `${worldId}:${entity}`;
-        const identities = topologyIdentitiesByWorld.get(worldId) ?? new Set<string>();
-        identities.add(identity);
-        topologyIdentitiesByWorld.set(worldId, identities);
-        const hasRenderableComponents =
-          world.hasComponent(entity, Transform) &&
-          world.hasComponent(entity, MeshFilter) &&
-          world.hasComponent(entity, MeshRenderer) &&
-          !world.hasComponent(entity, Disabled);
-        const extracted = hasRenderableComponents
-          ? (() => {
-              this.singleEntityExtractions += 1;
-              return refreshRenderable(world, worldId, entity, entry.candidateFrame);
-            })()
-          : undefined;
-        const liveRecord = entry.projection.record(worldId, entity);
-        if (extracted === undefined) {
-          if (liveRecord !== undefined && !removalIdentities.has(identity)) {
-            operations.push({
-              kind: 'remove',
-              worldId,
-              entityKey: entity,
-              expectedGeneration: liveRecord.generation,
-            });
-            removalIdentities.add(identity);
-            removalOperationCount += 1;
-          }
-          continue;
-        }
-        const snapshot =
-          extracted.snapshot.worldId === worldId
-            ? extracted.snapshot
-            : { ...extracted.snapshot, worldId };
-        operations.push({
-          kind: 'create',
-          snapshot,
-          ...(liveRecord === undefined ? {} : { expectedGeneration: liveRecord.generation }),
-        });
-        const dispatch = topologyDispatchByWorld.get(worldId) ?? [];
-        dispatch.push(...extracted.candidateDispatch);
-        topologyDispatchByWorld.set(worldId, dispatch);
-      }
-    }
-    if (topologyEntities.size > 0) {
-      const topologyIdentitySet = new Set(topologyEntities.keys());
-      for (let index = operations.length - 1; index >= 0; index -= 1) {
-        const operation = operations[index];
-        if (
-          operation?.kind === 'update-transform' &&
-          topologyIdentitySet.has(`${operation.worldId}:${operation.entityKey}`)
-        ) {
-          operations.splice(index, 1);
-        }
-      }
-    }
-    if (operations.length === 0) {
-      this.noChangeFrames += 1;
-      this.syncGpuOwner(entry.token, entry.projection);
-      return entry.visibleFrame;
-    }
-    const delta = entry.projection.apply(operations);
-    entry.topology.apply(delta);
-    this.syncGpuOwner(entry.token, entry.projection, delta);
-    const candidates = entry.projection.materialize();
-    let rebased = entry.candidateFrame;
-    for (const [worldId, dispatch] of topologyDispatchByWorld) {
-      rebased = rebaseCandidateDomain(rebased, candidates, {
-        worldId,
-        dispatch,
-        replaceIdentities: topologyIdentitiesByWorld.get(worldId) ?? new Set<string>(),
-      });
-    }
-    if (topologyDispatchByWorld.size === 0 && topologyEntities.size > 0) {
-      for (const [worldId, replaceIdentities] of topologyIdentitiesByWorld) {
-        rebased = rebaseCandidateDomain(rebased, candidates, {
-          worldId,
-          dispatch: [],
-          replaceIdentities,
-        });
-      }
-    }
-    entry.candidateFrame = { ...rebased, renderables: [...candidates] };
-    entry.visibleFrame = cullPersistentFrame(
-      entry.candidateFrame,
-      candidates,
-      this.options.collectShadowDebugCandidates?.() === true,
-      entry.projection,
-    );
-    this.deltaFrames += 1;
-    this.transformUpdates += transformOperationCount;
-    this.removals += removalOperationCount;
-    return entry.visibleFrame;
-  }
-
-  invalidate(world?: World): void {
-    if (world !== undefined) this.entries.delete(world);
-    else if (this.lastWorld !== undefined) this.entries.delete(this.lastWorld);
-    this.composition = undefined;
-    this.lastResyncReason = 'explicit-invalidate';
-    this.lastResyncDetail = undefined;
-  }
-
-  setGpuDrivenCoverage(world: World, key: string, ownsAll: boolean): void {
-    const entry = this.entries.get(world);
-    if (entry === undefined) return;
-    entry.gpuDrivenCoverageKey = key;
-    entry.gpuDrivenOwnsAll = ownsAll;
-  }
-
-  setCompositionGpuDrivenCoverage(key: string, ownsAll: boolean): void {
-    const entry = this.composition;
-    if (entry === undefined) return;
-    entry.gpuDrivenCoverageKey = key;
-    entry.gpuDrivenOwnsAll = ownsAll;
-  }
-
-  detach(world: World): void {
-    const detachedEntry = this.entries.get(world);
-    detachedEntry?.projection.reset([]);
-    this.entries.delete(world);
-    const worldId = this.worldIds.get(world);
-    if (worldId !== undefined) {
-      this.worldIds.delete(world);
-      this.worldsById.delete(worldId);
-    }
-    const detachedComposition = this.composition?.worlds.includes(world)
-      ? this.composition
-      : undefined;
-    if (detachedComposition !== undefined) this.composition = undefined;
-    if (this.fogLastKnownGood?.resourceOwner === worldId) {
-      this.fogCandidate = undefined;
-      this.fogLastKnownGood = undefined;
-      this.fogFailure = undefined;
-      this.fogFailureOwner = undefined;
-      this.fogReactive = false;
-    }
-    if (this.lastWorld === world) this.lastWorld = undefined;
-    if (this.gpuOwner !== world && this.gpuOwner !== detachedComposition?.token) return;
-    this.gpuScene?.dispose();
-    this.gpuScene = undefined;
-    this.gpuOwner = undefined;
-    this.gpuDevice = undefined;
-    this.gpuStatus = 'inactive';
-  }
-
-  /** Drop only device-owned tables; the CPU projection remains the recovery authority. */
-  resetGpuForRecover(): void {
-    if (this.lastWorld !== undefined) {
-      const entry = this.entries.get(this.lastWorld);
-      if (entry !== undefined) entry.gpuDrivenOwnsAll = false;
-    }
-    if (this.composition !== undefined) this.composition.gpuDrivenOwnsAll = false;
-    this.gpuScene = undefined;
-    this.gpuOwner = undefined;
-    this.gpuDevice = undefined;
-    this.gpuStatus = this.options.getDevice === undefined ? 'inactive' : 'rebuild-pending';
-  }
-
-  dispose(): void {
-    this.gpuScene?.dispose();
-    this.gpuScene = undefined;
-    this.gpuOwner = undefined;
-    this.gpuDevice = undefined;
-    this.gpuStatus = 'inactive';
-    this.composition = undefined;
-    this.fogCandidate = undefined;
-    this.fogLastKnownGood = undefined;
-    this.fogFailure = undefined;
-    this.fogFailureOwner = undefined;
-    this.fogReactive = false;
-  }
-
-  inspect(world = this.lastWorld): PersistentRenderSceneInspection {
-    const entry = (world === undefined ? undefined : this.entries.get(world)) ?? this.composition;
-    return {
-      worldEntitiesScanned: this.worldEntitiesScanned,
-      fullRebuilds: this.fullRebuilds,
-      noChangeFrames: this.noChangeFrames,
-      deltaFrames: this.deltaFrames,
-      transformUpdates: this.transformUpdates,
-      materialUpdates: this.materialUpdates,
-      instanceUpdates: this.instanceUpdates,
-      cameraUpdates: this.cameraUpdates,
-      resourceUpdates: this.resourceUpdates,
-      topologyEntitiesReconciled: this.topologyEntitiesReconciled,
-      singleEntityExtractions: this.singleEntityExtractions,
-      removals: this.removals,
-      lastResyncReason: this.lastResyncReason,
-      lastResyncDetail: this.lastResyncDetail,
-      cursor: 'cursor' in (entry ?? {}) ? (entry as PersistentWorldEntry).cursor : undefined,
-      projectionRecords: entry?.projection.inspect().current.length ?? 0,
-      spatialIndex: entry?.projection.inspect().spatialIndex,
-      topology:
-        entry?.topology.inspect() ??
-        ({
-          revision: 0,
-          batchCount: 0,
-          candidateCount: 0,
-          rebuilds: 0,
-          patches: 0,
-          ineligible: 0,
-        } satisfies BatchTopologyInspection),
-      gpu: this.inspectGpu(),
-      fog: this.inspectFog(),
-    };
-  }
-
-  /** Stage a resource-owner Fog candidate; publication waits for submit. */
-  stageFogCandidate(candidate: FogSelection): void {
-    this.fogCandidate = candidate;
-    this.fogFailure = undefined;
-    this.fogFailureOwner = undefined;
-    this.fogReactive = false;
-  }
-
-  /** Return the accepted Fog payload for failed-candidate frame reuse. */
-  fogSnapshot(): FogSnapshot | undefined {
-    return this.fogLastKnownGood?.snapshot;
-  }
-
-  /** Retain the previous accepted Fog when extraction or validation fails. */
-  stageFogFailure(failure: PersistentFogFailure): void {
-    this.fogCandidate = undefined;
-    this.fogFailure = failure.code;
-    this.fogFailureOwner = failure.resourceOwner;
-    this.fogReactive = false;
-  }
-
-  /** Drop an unsubmitted candidate without mutating the accepted snapshot. */
-  discardFogCandidate(): void {
-    this.fogCandidate = undefined;
-    this.fogReactive = false;
-  }
-
-  /** Commit the staged Fog candidate at the existing successful-submit seam. */
-  stageFogSubmission(): void {
-    const candidate = this.fogCandidate;
-    if (candidate === undefined) return;
-    const previous = this.fogLastKnownGood;
-    this.fogReactive =
-      previous === undefined || previous.snapshot?.revision !== candidate.snapshot?.revision;
-    this.fogLastKnownGood = candidate;
-    this.fogCandidate = undefined;
-    this.fogFailure = undefined;
-    this.fogFailureOwner = undefined;
-  }
-
-  private inspectFog(): PersistentFogInspection {
-    const accepted = this.fogLastKnownGood;
-    return {
-      enabled: accepted?.snapshot !== undefined,
-      resourceOwner: accepted?.resourceOwner ?? this.fogFailureOwner,
-      entity: accepted?.entity as number | undefined,
-      revision: accepted?.snapshot?.revision,
-      reactive: this.fogReactive,
-      failure: this.fogFailure,
-    };
-  }
-
-  gpuDrivenState(world = this.lastWorld): PersistentGpuDrivenState | undefined {
-    if (world === undefined || world !== this.gpuOwner || this.gpuScene === undefined) {
-      return undefined;
-    }
-    const entry = this.entries.get(world);
-    if (entry === undefined) return undefined;
-    return {
-      scene: this.gpuScene,
-      plan: entry.topology.plan(),
-      slots: entry.projection.slotsSnapshot(),
-      projection: entry.projection,
-    };
-  }
-
-  compositionGpuDrivenState(): PersistentGpuDrivenState | undefined {
-    const entry = this.composition;
-    if (entry === undefined || this.gpuOwner !== entry.token || this.gpuScene === undefined) {
-      return undefined;
-    }
-    return {
-      scene: this.gpuScene,
-      plan: entry.topology.plan(),
-      slots: entry.projection.slotsSnapshot(),
-      projection: entry.projection,
-    };
-  }
-
-  temporalProjection(worlds: readonly World[]): RenderSceneProjection | undefined {
-    if (worlds.length === 1) {
-      const world = worlds[0];
-      return world === undefined ? undefined : this.entries.get(world)?.projection;
-    }
-    const composition = this.composition;
-    if (
-      composition === undefined ||
-      composition.worlds.length !== worlds.length ||
-      composition.worlds.some((world, index) => world !== worlds[index])
-    ) {
-      return undefined;
-    }
-    return composition.projection;
-  }
-
-  stageTemporalSubmission(delta: RenderSceneSubmissionDelta): void {
-    this.gpuScene?.stageSubmitted(delta);
-    this.stageFogSubmission();
-  }
-
-  private inspectGpu(): PersistentGpuSceneInspection {
-    if (this.gpuStatus === 'resident' && this.gpuScene !== undefined) {
-      return { status: 'resident', ...this.gpuScene.inspect() };
-    }
-    if (this.gpuStatus === 'unsupported') {
-      return { status: 'unsupported', reason: 'storage-buffer-unavailable' };
-    }
-    if (this.gpuStatus === 'rebuild-pending') return { status: 'rebuild-pending' };
-    if (this.gpuStatus === 'error') return { status: 'error' };
-    return { status: 'inactive' };
-  }
-
-  private rebuild(
-    world: World,
-    catalogEpoch: number,
-    buildCandidateFrame: () => ExtractedFrame,
-    reason: RenderSceneResyncReason,
-    detail?: string,
-  ): ExtractedFrame {
-    const worldId = this.attachWorld(world);
-    const previousEntry = this.entries.get(world);
-    const sourceCandidateFrame = this.remapWorldIds(buildCandidateFrame(), [worldId]);
-    const projectionCandidates =
-      sourceCandidateFrame.candidateRenderables ?? sourceCandidateFrame.renderables;
-    this.worldEntitiesScanned = projectionCandidates.length;
-    const projection = previousEntry?.projection ?? new RenderSceneProjection();
-    if (previousEntry === undefined) projection.reset(projectionCandidates);
-    else projection.replaceCurrent(projectionCandidates);
-    const topology = new BatchTopology();
-    topology.rebuild(projection.slotsSnapshot());
-    const candidates = projection.materialize();
-    const candidateFrame = {
-      ...rebaseCandidateDomain(sourceCandidateFrame, candidates),
-      renderables: [...candidates],
-    };
-    const visibleFrame = cullPersistentFrame(
-      candidateFrame,
-      candidates,
-      this.options.collectShadowDebugCandidates?.() === true,
-      projection,
-    );
-    const changeProjection = createWorldProjection(world, {
-      components: RENDER_RELEVANT_COMPONENTS,
-    });
-    this.entries.set(world, {
-      worldId,
-      projection,
-      topology,
-      candidateFrame,
-      visibleFrame,
-      changeProjection,
-      cursor: changeProjection.cursor,
-      catalogEpoch,
-      sharedRefEpoch: world.sharedRefs.getMutationEpoch(),
-      activeCameraEpoch: world.getResourceChange(ACTIVE_CAMERA_KEY)?.changed ?? 0,
-      cameraEntities: this.cameraEntities(world),
-      rigidOnly: candidates.every(
-        (renderable) => renderable.skin === undefined && renderable.morphWeights === undefined,
-      ),
-      gpuDrivenCoverageKey: undefined,
-      gpuDrivenOwnsAll: false,
-    });
-    this.syncGpu(world, projection, undefined, true);
-    this.fullRebuilds += 1;
-    this.lastResyncReason = reason;
-    this.lastResyncDetail = detail;
-    return visibleFrame;
-  }
-
-  private rebuildComposition(
-    worlds: readonly World[],
-    worldIds: readonly number[],
-    owner: { readonly cameraOwner: number; readonly resourceOwner: number },
-    catalogEpoch: number,
-    buildCandidateFrame: () => ExtractedFrame,
-  ): ExtractedFrame {
-    const previousComposition = this.composition;
-    const canReuseProjection =
-      previousComposition !== undefined &&
-      previousComposition.cameraOwner === owner.cameraOwner &&
-      previousComposition.resourceOwner === owner.resourceOwner &&
-      previousComposition.worlds.length === worlds.length &&
-      previousComposition.worlds.every((world, index) => world === worlds[index]) &&
-      previousComposition.worldIds.every((worldId, index) => worldId === worldIds[index]);
-    const sourceCandidateFrame = this.remapWorldIds(buildCandidateFrame(), worldIds);
-    const projectionCandidates =
-      sourceCandidateFrame.candidateRenderables ?? sourceCandidateFrame.renderables;
-    this.worldEntitiesScanned = projectionCandidates.length;
-    const projection = canReuseProjection
-      ? previousComposition.projection
-      : new RenderSceneProjection();
-    if (canReuseProjection) projection.replaceCurrent(projectionCandidates);
-    else projection.reset(projectionCandidates);
-    const topology = new BatchTopology();
-    topology.rebuild(projection.slotsSnapshot());
-    const candidates = projection.materialize();
-    const candidateFrame = {
-      ...rebaseCandidateDomain(sourceCandidateFrame, candidates),
-      renderables: [...candidates],
-    };
-    const visibleFrame = cullPersistentFrame(
-      candidateFrame,
-      candidates,
-      this.options.collectShadowDebugCandidates?.() === true,
-      projection,
-    );
-    const token = {};
-    const changeProjections = worlds.map((world) =>
-      createWorldProjection(world, { components: RENDER_RELEVANT_COMPONENTS }),
-    );
-    const entry: PersistentCompositionEntry = {
-      token,
-      worlds: [...worlds],
-      worldIds: [...worldIds],
-      cameraOwner: owner.cameraOwner,
-      resourceOwner: owner.resourceOwner,
-      projection,
-      topology,
-      candidateFrame,
-      visibleFrame,
-      changeProjections,
-      cursors: changeProjections.map((projection) => projection.cursor),
-      sharedRefEpochs: worlds.map((world) => world.sharedRefs.getMutationEpoch()),
-      cameraEntities: worlds.map((world) => this.cameraEntities(world)),
-      catalogEpoch,
-      rigidOnly: candidates.every(
-        (renderable) => renderable.skin === undefined && renderable.morphWeights === undefined,
-      ),
-      gpuDrivenCoverageKey: undefined,
-      gpuDrivenOwnsAll: false,
-    };
-    this.composition = entry;
-    this.syncGpuOwner(token, projection, undefined, true);
-    this.fullRebuilds += 1;
-    this.lastResyncReason = 'attach';
-    return visibleFrame;
-  }
-
-  private syncGpu(
-    world: World,
-    projection: RenderSceneProjection,
-    delta?: RenderSceneApplyResult,
-    full = false,
-  ): void {
-    this.syncGpuOwner(world, projection, delta, full);
-  }
-
-  private syncGpuOwner(
-    owner: object,
-    projection: RenderSceneProjection,
-    delta?: RenderSceneApplyResult,
-    full = false,
-  ): void {
-    const acquired = this.acquireGpuScene(owner, projection);
-    if (acquired === undefined || acquired.rebuilt) return;
-    const result = full
-      ? acquired.scene.rebuild(projection)
-      : delta === undefined
-        ? acquired.scene.sync(projection, {
-            created: 0,
-            updated: 0,
-            removed: 0,
-            recreated: 0,
-            ignoredLateUpdates: 0,
-            createdSlots: [],
-            updatedSlots: [],
-            removedSlots: [],
-            recreatedSlots: [],
-            factDeltas: [],
-            diagnostics: [],
-          })
-        : acquired.scene.sync(projection, delta);
-    if (!result.ok) this.failGpu(result.error);
-  }
-
-  private acquireGpuScene(
-    owner: object,
-    projection: RenderSceneProjection,
-  ): { readonly scene: GpuScene; readonly rebuilt: boolean } | undefined {
-    const getDevice = this.options.getDevice;
-    if (getDevice === undefined) return undefined;
-    const device = getDevice();
-    if (this.gpuDevice !== undefined && this.gpuDevice !== device) {
-      this.gpuScene = undefined;
-      this.gpuOwner = undefined;
-      this.gpuStatus = 'rebuild-pending';
-    }
-    if (this.gpuStatus === 'error' && this.gpuDevice === device) return undefined;
-    if (this.gpuStatus === 'unsupported' && this.gpuDevice === device) return undefined;
-    if (this.gpuScene !== undefined && this.gpuOwner === owner) {
-      return { scene: this.gpuScene, rebuilt: false };
-    }
-    if (this.gpuScene !== undefined) this.gpuScene.dispose();
-    this.gpuScene = undefined;
-    this.gpuOwner = undefined;
-    this.gpuDevice = device;
-    const created = GpuScene.create(device, Math.max(256, projection.inspect().slotCapacity));
-    if (!created.ok) {
-      this.failGpu(created.error);
-      return undefined;
-    }
-    if (created.value.status === 'unavailable') {
-      this.gpuStatus = 'unsupported';
-      return undefined;
-    }
-    const scene = created.value.scene;
-    const rebuilt = scene.rebuild(projection);
-    if (!rebuilt.ok) {
-      scene.dispose();
-      this.failGpu(rebuilt.error);
-      return undefined;
-    }
-    this.gpuScene = scene;
-    this.gpuOwner = owner;
-    this.gpuStatus = 'resident';
-    return { scene, rebuilt: true };
-  }
-
-  private failGpu(error: RhiError): void {
-    this.gpuScene?.dispose();
-    this.gpuScene = undefined;
-    this.gpuOwner = undefined;
-    this.gpuStatus = 'error';
-    this.options.onGpuError?.(error);
-  }
-
-  private cameraEntities(world: World): ReadonlySet<EntityHandle> {
-    const entities = new Set<EntityHandle>();
-    for (const row of world.query({ read: [Camera], with: [Transform] }).unwrap()) {
-      entities.add(row.entity as EntityHandle);
-    }
-    return entities;
-  }
-
-  private attachWorld(world: World): number {
-    const attached = this.worldIds.get(world);
-    if (attached !== undefined) return attached;
-    if (this.nextWorldId >= 0x20_0000) {
-      throw new RangeError('renderer exhausted the 21-bit WorldRenderId space');
-    }
-    const worldId = this.nextWorldId;
-    this.nextWorldId += 1;
-    this.worldIds.set(world, worldId);
-    this.worldsById.set(worldId, world);
-    return worldId;
-  }
-
-  private remapWorldIds(frame: ExtractedFrame, worldIds: readonly number[]): ExtractedFrame {
-    let changed = false;
-    const cameras = frame.cameras.map((camera) => {
-      const worldId = worldIds[camera.worldId];
-      if (worldId === undefined) {
-        throw new RangeError(`camera references unattached world index ${camera.worldId}`);
-      }
-      if (worldId === camera.worldId) return camera;
-      changed = true;
-      return { ...camera, worldId };
-    });
-    const renderables = frame.renderables.map((renderable) => {
-      const worldId = worldIds[renderable.worldId];
-      if (worldId === undefined) {
-        throw new RangeError(`renderable references unattached world index ${renderable.worldId}`);
-      }
-      if (worldId === renderable.worldId) return renderable;
-      changed = true;
-      return { ...renderable, worldId };
-    });
-    const sourceCandidateRenderables =
-      frame.candidateDomain?.renderables ?? frame.candidateRenderables;
-    const candidateRenderables = sourceCandidateRenderables?.map((renderable) => {
-      const worldId = worldIds[renderable.worldId];
-      if (worldId === undefined) {
-        throw new RangeError(`candidate references unattached world index ${renderable.worldId}`);
-      }
-      if (worldId === renderable.worldId) return renderable;
-      changed = true;
-      return { ...renderable, worldId };
-    });
-    if (!changed) return frame;
-    if (frame.candidateDomain === undefined || candidateRenderables === undefined) {
-      return {
-        ...frame,
-        cameras,
-        renderables,
-        ...(candidateRenderables === undefined ? {} : { candidateRenderables }),
-      };
-    }
-    const candidateDomain = buildRenderCandidateDomain(
-      candidateRenderables,
-      frame.candidateDomain.dispatch,
-    );
-    return {
-      ...frame,
-      cameras,
-      renderables,
-      candidateRenderables: candidateDomain.renderables,
-      candidateDispatch: candidateDomain.dispatch,
-      candidateDispatchMembership: candidateDomain.membership,
-      candidateDomain,
-    };
-  }
-}