@forgeax/engine-render 0.1.2

package/src/persistent-render-scene.ts

@@ -0,0 +1,1752 @@
+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,
+    };
+  }
+}