@forgeax/engine-render 0.1.23 → 0.1.25

package/src/scene/render-scene.ts

@@ -1,9 +1,9 @@
-import type { Query, World } from '@forgeax/engine-ecs';
+import type { EntityHandle, Query, World } from '@forgeax/engine-ecs';
 import { componentId } from '@forgeax/engine-ecs/internal';
 import type { RenderReadLease, RenderReadVersion } from '@forgeax/engine-ecs/projection';
 import { box3, frustum, mat4 } from '@forgeax/engine-math';
 import { type RhiDevice, RhiError } from '@forgeax/engine-rhi';
-import { ChildOf, GlobalTransform, Transform } from '@forgeax/engine-scene';
+import { ChildOf, GlobalTransform, MorphWeights, Transform } from '@forgeax/engine-scene';
 import { Skin } from '@forgeax/engine-skinning';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import {
@@ -12,20 +12,24 @@ import {
   Instances,
   Layer,
   LightProbe,
+  Lines,
   MeshFilter,
   MeshRenderer,
   MotionBlur,
   PointLight,
   PointLightShadow,
+  Points,
   PostProcessParams,
   ReflectionProbe,
   SkyboxBackground,
   Skylight,
+  SortKey,
   SpotLight,
   SpriteInstances,
   SpriteRegionOverride,
   Visibility,
 } from '../components';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
 import {
   BatchTopology,
   type BatchTopologyInspection,
@@ -33,6 +37,7 @@ import {
 } from '../gpu-driven/batch-topology';
 import { GpuScene } from '../gpu-scene';
 import type { PersistentRenderSceneInspection } from '../inspection-types';
+import type { InstanceProjectionStore } from '../instances';
 import { fingerprintNumericArray, InstanceBoundsCache } from '../instances-derived-bounds';
 import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRetainedSnapshot } from '../points-lines/snapshot';
@@ -52,6 +57,7 @@ import type {
   RenderableSnapshot,
   RenderableTemporalSnapshot,
 } from '../render-system-extract';
+import type { SkinPaletteAllocator } from '../systems/skin-palette-allocator';
 import {
   PersistentTransmissionDemandProjection,
   type TransmissionDemand,
@@ -96,6 +102,7 @@ interface PendingIdentity {
   readonly initial: RenderSceneSlot | undefined;
   current: RenderableSnapshot | undefined;
   removed: boolean;
+  contentChanged: boolean;
 }
 
 interface WorldTransformSpan {
@@ -106,6 +113,16 @@ interface WorldTransformSpan {
 
 type GlobalTransformChangeQuery = Query<readonly [typeof GlobalTransform]>;
 
+/** The normal extract request used by the persistent scene owner. */
+export type PersistentRenderCandidateRequest =
+  | 'full'
+  | 'none'
+  | {
+      readonly kind: 'partial';
+      /** Entity keys are local to the corresponding World entry. */
+      readonly entitiesByWorld: readonly (ReadonlySet<number> | undefined)[];
+    };
+
 export interface RenderSceneSubmissionCapture {
   readonly revision: number;
   readonly slots: readonly {
@@ -187,6 +204,9 @@ function ownSnapshot(snapshot: RenderableSnapshot): RenderableSnapshot {
     ...(snapshot.pointsLines === undefined
       ? {}
       : { pointsLines: ownPointsLinesSnapshot(snapshot.pointsLines) }),
+    ...(snapshot.skinJointEntities === undefined
+      ? {}
+      : { skinJointEntities: [...snapshot.skinJointEntities] }),
   };
 }
 
@@ -356,6 +376,7 @@ export class RenderScene {
         initial,
         current: initial?.snapshot,
         removed: false,
+        contentChanged: false,
       };
       entities.set(entityKey, pending);
       pendingOrder.push(pending);
@@ -367,6 +388,7 @@ export class RenderScene {
         const { worldId, entityKey } = operation.snapshot;
         const pending = pendingFor(worldId, entityKey);
         pending.current = ownSnapshot(operation.snapshot);
+        pending.contentChanged = true;
         continue;
       }
       const pending = pendingFor(operation.worldId, operation.entityKey);
@@ -388,6 +410,7 @@ export class RenderScene {
     let recreated = 0;
     const createdSlots: RenderSceneSlot[] = [];
     const updatedSlots: RenderSceneSlot[] = [];
+    const contentUpdatedSlots: RenderSceneSlot[] = [];
     const removedSlots: RenderSceneRecord[] = [];
     const recreatedSlots: RenderSceneSlot[] = [];
     for (const pending of pendingOrder) {
@@ -425,6 +448,7 @@ export class RenderScene {
       this.indexMaterials(updatedSlot);
       this.dirtySinceSubmitted.add(updatedSlot.slot);
       updatedSlots.push(updatedSlot);
+      if (pending.contentChanged) contentUpdatedSlots.push(updatedSlot);
       updated += 1;
     }
 
@@ -441,6 +465,7 @@ export class RenderScene {
       ignoredLateUpdates,
       createdSlots,
       updatedSlots,
+      contentUpdatedSlots,
       removedSlots,
       recreatedSlots,
       resynced: 0,
@@ -865,7 +890,7 @@ export class RenderScene {
         entityKey: snapshot.entityKey,
         meshGeneration: fingerprintNumericArray(snapshot.localAabb) ^ (snapshot.assetHandle >>> 0),
         transformGeneration: fingerprintNumericArray(snapshot.transform.world),
-        matrixGeneration: snapshot.instances.archVersion,
+        matrixGeneration: snapshot.instances.revision ?? snapshot.instances.archVersion,
         meshAabb: snapshot.localAabb,
         entityWorld: snapshot.transform.world,
         transforms: snapshot.instances.transforms,
@@ -889,6 +914,9 @@ export interface PersistentRenderSceneOptions {
   readonly onGpuError?: ((error: RhiError) => void) | undefined;
   readonly onSharedRefMutation?: ((worldId: number, handle: number) => void) | undefined;
   readonly configuredQueryBudget?: number | undefined;
+  /** Rebuildable projection of World-owned instance matrices. */
+  readonly instanceCollections?: InstanceProjectionStore | undefined;
+  readonly getSkinPaletteAllocator?: (() => SkinPaletteAllocator | null) | undefined;
 }
 
 export interface PersistentGpuDrivenState {
@@ -943,6 +971,23 @@ export function projectCpuDirectCandidates(
   return candidates;
 }
 
+/** Detached GPU scene prepared from the retained CPU composition. */
+export interface PersistentGpuDrivenCandidate {
+  readonly state: PersistentGpuDrivenState | undefined;
+  /** Candidate-owned scene root; never references the active GPU scene. */
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown>;
+  publish(): void;
+  discard(): void;
+  /** Release the candidate scene even after it has crossed publication. */
+  release(): void;
+}
+
+export interface RenderSceneRecoveryRoot {
+  readonly generation: number;
+  readonly revision: number;
+  readonly visibleSlots: number;
+}
+
 type PersistentGpuSceneInspection = PersistentRenderSceneInspection['gpu'];
 
 interface PersistentCompositionEntry {
@@ -953,7 +998,7 @@ interface PersistentCompositionEntry {
   readonly projection: RenderScene;
   readonly topology: BatchTopology;
   readonly transmissionDemand: PersistentTransmissionDemandProjection;
-  readonly structure: Pick<
+  structure: Pick<
     ExtractedFrame,
     | 'dispatch'
     | 'visibilityStats'
@@ -966,15 +1011,24 @@ interface PersistentCompositionEntry {
   readonly readVersions: RenderReadVersion[];
   readonly leaseIdentities: readonly string[];
   readonly transformQueries: readonly GlobalTransformChangeQuery[];
+  readonly renderChangeQueries: readonly ReadonlyMap<number, Query>[];
+  readonly dispatchBySlot: Map<number, readonly DispatchEntry[]>;
+  dispatchRevision: number;
+  dispatchCache:
+    | { readonly revision: number; readonly value: readonly DispatchEntry[] }
+    | undefined;
+  readonly skinConsumersByJoint: Map<string, Set<number>>;
+  /** Renderable identities whose partial producer still needs a successful publish. */
+  readonly pendingRenderableEntitiesByWorld: Set<number>[];
+  /** Slots retained for recovery but excluded from direct and indirect submission. */
+  readonly unavailableSlots: Set<number>;
   catalogEpoch: number;
-  readonly rigidOnly: boolean;
   readonly probeProjection: ProbeBlendSceneProjection;
   temporalDemanded: boolean;
   gpuDrivenSceneRequired: boolean;
 }
 
 const RENDER_RELEVANT_COMPONENT_IDS = new Set([
-  componentId(Transform),
   componentId(GlobalTransform),
   componentId(ChildOf),
   componentId(MeshFilter),
@@ -985,6 +1039,10 @@ const RENDER_RELEVANT_COMPONENT_IDS = new Set([
   componentId(Skin),
   componentId(Layer),
   componentId(Visibility),
+  componentId(MorphWeights),
+  componentId(Points),
+  componentId(Lines),
+  componentId(SortKey),
   componentId(Camera),
   componentId(MotionBlur),
   componentId(DirectionalLight),
@@ -999,6 +1057,41 @@ const RENDER_RELEVANT_COMPONENT_IDS = new Set([
   componentId(VolumetricFog),
 ]);
 
+// These components can change the retained renderable source. Other relevant
+// components affect frame resources and still require a composition rebuild;
+// they must not cause a renderable-only partial extraction to silently retain
+// stale lights, cameras, or environment facts.
+const RENDERABLE_SOURCE_COMPONENTS = [
+  GlobalTransform,
+  ChildOf,
+  MeshFilter,
+  MeshRenderer,
+  Instances,
+  SpriteInstances,
+  SpriteRegionOverride,
+  Skin,
+  Layer,
+  Visibility,
+  MorphWeights,
+  Points,
+  Lines,
+  SortKey,
+] as const;
+const RENDERABLE_SOURCE_COMPONENT_IDS = new Set(
+  RENDERABLE_SOURCE_COMPONENTS.map((component) => componentId(component)),
+);
+const VISIBILITY_DEPENDENCY_COMPONENT_IDS = new Set([
+  componentId(ChildOf),
+  componentId(Visibility),
+]);
+const STRUCTURAL_MEMBERSHIP_SCAN_COMPONENT_IDS = new Set([
+  componentId(ChildOf),
+  componentId(Layer),
+  componentId(Visibility),
+  componentId(SpriteRegionOverride),
+  componentId(SortKey),
+]);
+
 function createGlobalTransformChangeQuery(world: World): GlobalTransformChangeQuery {
   const result = world.query({ read: [GlobalTransform], changed: [GlobalTransform] });
   if (!result.ok) throw result.error;
@@ -1009,6 +1102,149 @@ function createGlobalTransformChangeQuery(world: World): GlobalTransformChangeQu
   return query;
 }
 
+function createRenderChangeQueries(world: World): ReadonlyMap<number, Query> {
+  const queries = new Map<number, Query>();
+  for (const component of RENDERABLE_SOURCE_COMPONENTS) {
+    const result = world.query({ read: [component], changed: [component] });
+    if (!result.ok) throw result.error;
+    const query = result.value as Query;
+    // The initial full extraction has already consumed this change evidence.
+    // Keep the query compiled so subsequent frames iterate only rows whose
+    // component version changed.
+    for (const _span of query.spans().unwrap()) {
+      // Establish the observation baseline.
+    }
+    queries.set(componentId(component), query);
+  }
+  return queries;
+}
+
+function collectRenderableEntities(world: World): ReadonlySet<number> {
+  const result = new Set<number>();
+  const query = world.query({ read: [MeshRenderer], with: [Transform, MeshFilter] }).unwrap();
+  for (const row of query) result.add(row.entity as number);
+  return result;
+}
+
+function sourceMembershipChanged(world: World, slot: RenderSceneSlot): boolean {
+  const entity = slot.entityKey as EntityHandle;
+  const snapshot = slot.snapshot;
+  return (
+    !world.hasComponent(entity, GlobalTransform) ||
+    (snapshot.instances !== undefined) !== world.hasComponent(entity, Instances) ||
+    (snapshot.spriteInstances !== undefined) !== world.hasComponent(entity, SpriteInstances) ||
+    (snapshot.skin !== undefined) !== world.hasComponent(entity, Skin) ||
+    (snapshot.morph !== undefined) !== world.hasComponent(entity, MorphWeights) ||
+    (snapshot.pointsLines?.component === 'Points') !== world.hasComponent(entity, Points) ||
+    (snapshot.pointsLines?.component === 'Lines') !== world.hasComponent(entity, Lines)
+  );
+}
+
+function skinJointKey(worldId: number, jointEntity: number): string {
+  return `${worldId}:${jointEntity}`;
+}
+
+function addSkinConsumer(index: Map<string, Set<number>>, snapshot: RenderableSnapshot): void {
+  for (const jointEntity of snapshot.skinJointEntities ?? []) {
+    const key = skinJointKey(snapshot.worldId, jointEntity);
+    let consumers = index.get(key);
+    if (consumers === undefined) {
+      consumers = new Set<number>();
+      index.set(key, consumers);
+    }
+    consumers.add(snapshot.entityKey);
+  }
+}
+
+function removeSkinConsumer(index: Map<string, Set<number>>, snapshot: RenderableSnapshot): void {
+  for (const jointEntity of snapshot.skinJointEntities ?? []) {
+    const key = skinJointKey(snapshot.worldId, jointEntity);
+    const consumers = index.get(key);
+    consumers?.delete(snapshot.entityKey);
+    if (consumers?.size === 0) index.delete(key);
+  }
+}
+
+function dispatchEntriesBySlot(
+  frame: ExtractedFrame,
+  projection: RenderScene,
+): Map<number, readonly DispatchEntry[]> {
+  const bySlot = new Map<number, DispatchEntry[]>();
+  const byRenderable = new Map<number, DispatchEntry[]>();
+  for (const entry of frame.dispatch) {
+    const list = byRenderable.get(entry.renderableIndex);
+    if (list === undefined) byRenderable.set(entry.renderableIndex, [entry]);
+    else list.push(entry);
+  }
+  for (let index = 0; index < frame.renderables.length; index += 1) {
+    const renderable = frame.renderables[index];
+    if (renderable === undefined) continue;
+    const slot = projection.slot(renderable.worldId, renderable.entityKey);
+    if (slot === undefined) continue;
+    bySlot.set(slot.slot, byRenderable.get(index) ?? []);
+  }
+  return bySlot;
+}
+
+function dispatchForProjection(
+  dispatchBySlot: ReadonlyMap<number, readonly DispatchEntry[]>,
+  projection: RenderScene,
+  unavailableSlots: ReadonlySet<number>,
+): readonly DispatchEntry[] {
+  const dispatch: DispatchEntry[] = [];
+  const renderables = projection.materialize();
+  for (let renderableIndex = 0; renderableIndex < renderables.length; renderableIndex += 1) {
+    const renderable = renderables[renderableIndex];
+    if (renderable === undefined) continue;
+    const slot = projection.slot(renderable.worldId, renderable.entityKey);
+    if (slot === undefined) continue;
+    if (unavailableSlots.has(slot.slot)) continue;
+    for (const entry of dispatchBySlot.get(slot.slot) ?? []) {
+      dispatch.push({ ...entry, renderableIndex });
+    }
+  }
+  return dispatch;
+}
+
+function topologyDeltaForAvailable(
+  delta: RenderSceneApplyResult,
+  unavailableSlots: ReadonlySet<number>,
+  newlyUnavailable: readonly RenderSceneSlot[],
+): RenderSceneApplyResult {
+  const updatedSlots = delta.updatedSlots.filter((slot) => !unavailableSlots.has(slot.slot));
+  const contentUpdatedSlots = delta.contentUpdatedSlots?.filter(
+    (slot) => !unavailableSlots.has(slot.slot),
+  );
+  return {
+    ...delta,
+    updatedSlots: [
+      ...updatedSlots,
+      ...newlyUnavailable.map((slot) => ({
+        ...slot,
+        snapshot: { ...slot.snapshot, gpuDrivenDraws: [] },
+      })),
+    ],
+    ...(contentUpdatedSlots === undefined ? {} : { contentUpdatedSlots }),
+  };
+}
+
+function addSharedRefConsumers(
+  projection: RenderScene,
+  worldId: number,
+  handle: number,
+  target: Set<number>,
+): void {
+  for (const slot of projection.slotsSnapshot()) {
+    if (
+      slot.worldId === worldId &&
+      (slot.snapshot.assetHandle === handle ||
+        slot.snapshot.materials.some((material) => material.materialHandle === handle))
+    ) {
+      target.add(slot.entityKey);
+    }
+  }
+}
+
 function frameDemandsTemporal(frame: ExtractedFrame): boolean {
   const camera = frame.cameras[0];
   return camera?.antialias === 'taa' || (camera?.motionBlur?.shutterAngle ?? 0) > 0;
@@ -1030,8 +1266,8 @@ function cameraFrusta(cameras: readonly CameraSnapshot[]): readonly Float32Array
         projection,
         camera.orthoLeft,
         camera.orthoRight,
-        camera.orthoBottom,
         camera.orthoTop,
+        camera.orthoBottom,
         camera.near,
         camera.far,
       );
@@ -1072,6 +1308,10 @@ function cullPersistentFrame(
   for (let index = 0; index < candidates.length; index += 1) {
     const candidate = candidates[index];
     if (candidate === undefined) continue;
+    if (candidate.authorVisible === false) {
+      culled += 1;
+      continue;
+    }
     let isVisible = true;
     const candidateBounds = boundsOf(candidate, index);
     if (candidateBounds !== undefined) {
@@ -1377,7 +1617,7 @@ export class PersistentRenderScene {
           bounds.length >= 6 &&
           [...bounds].every((value) => Number.isFinite(value));
         draw = decideVisibility({
-          authorVisible: true,
+          authorVisible: renderable.authorVisible !== false,
           validBounds,
           frustumVisible: true,
           lodReady: true,
@@ -1481,7 +1721,7 @@ export class PersistentRenderScene {
     worlds: readonly World[],
     owner: { readonly cameraOwner: number; readonly resourceOwner: number },
     catalogEpoch: number,
-    buildCandidateFrame: (renderables: 'full' | 'none') => ExtractedFrame,
+    buildCandidateFrame: (request: PersistentRenderCandidateRequest) => ExtractedFrame,
     leases?: readonly RenderReadLease[],
   ): ExtractedFrame {
     this.worldEntitiesScanned = 0;
@@ -1526,11 +1766,16 @@ export class PersistentRenderScene {
         preserveVisibilityOnReorder,
       );
     }
-    if (!entry.rigidOnly) {
-      return this.rebuildComposition(worlds, owner, catalogEpoch, buildCandidateFrame, leases);
-    }
-
     let requiresRebuild = false;
+    const changedEntitiesByWorld = worlds.map(
+      (_, worldId) => new Set(entry.pendingRenderableEntitiesByWorld[worldId] ?? []),
+    );
+    const nextReadVersions = entry.readVersions.slice();
+    const structureChangedWorlds = new Set<number>();
+    const structuralComponentIdsByWorld = worlds.map(() => new Set<number>());
+    let refreshStructureFacts = false;
+    let currentRenderableEntitiesByWorld: readonly (ReadonlySet<number> | undefined)[] | undefined;
+    const removedSlots: RenderSceneSlot[] = [];
     for (let worldId = 0; worldId < worlds.length; worldId += 1) {
       const world = worlds[worldId];
       if (world === undefined) continue;
@@ -1551,35 +1796,294 @@ export class PersistentRenderScene {
         requiresRebuild = true;
         break;
       }
-      if (read.status !== 'ok') {
-        requiresRebuild = true;
-        break;
+      if (read.status === 'rebuild') {
+        structureChangedWorlds.add(worldId);
+        refreshStructureFacts = true;
       }
       const changes = read.world;
       const shared = read.sharedRefs;
       if (shared.records.length > 0) {
         for (const record of shared.records) {
           this.options.onSharedRefMutation?.(worldId, record.handle);
+          const changed = changedEntitiesByWorld[worldId];
+          if (changed !== undefined)
+            addSharedRefConsumers(entry.projection, worldId, record.handle, changed);
         }
-        requiresRebuild = true;
-        break;
       }
       for (const changedComponentId of changes.changedComponentIds) {
+        if (read.status === 'rebuild') {
+          structuralComponentIdsByWorld[worldId]?.add(changedComponentId);
+        }
         if (!RENDER_RELEVANT_COMPONENT_IDS.has(changedComponentId)) continue;
-        if (
-          changedComponentId !== componentId(Transform) &&
-          changedComponentId !== componentId(GlobalTransform)
-        ) {
+        if (!RENDERABLE_SOURCE_COMPONENT_IDS.has(changedComponentId)) {
           requiresRebuild = true;
           break;
         }
+        const changed = changedEntitiesByWorld[worldId];
+        if (changed === undefined) continue;
+        if (VISIBILITY_DEPENDENCY_COMPONENT_IDS.has(changedComponentId)) {
+          refreshStructureFacts = true;
+          // Visibility and parent changes affect the effective state of a
+          // subtree. The normal update path evaluates the current rows; the
+          // set is deliberately allowed to be broad, while empty work still
+          // exits naturally without a candidate loop.
+          for (const entity of collectRenderableEntities(world)) changed.add(entity);
+          continue;
+        }
+        if (changedComponentId === componentId(GlobalTransform)) {
+          const query = entry.renderChangeQueries[worldId]?.get(changedComponentId);
+          for (const row of query ?? []) {
+            const consumers = entry.skinConsumersByJoint.get(
+              skinJointKey(worldId, row.entity as number),
+            );
+            for (const consumer of consumers ?? []) changed.add(consumer);
+          }
+          continue;
+        }
+        const query = entry.renderChangeQueries[worldId]?.get(changedComponentId);
+        if (query !== undefined) {
+          for (const row of query) changed.add(row.entity as number);
+        }
       }
       if (requiresRebuild) break;
-      entry.readVersions[worldId] = read.version;
+      nextReadVersions[worldId] = read.version;
     }
     if (requiresRebuild) {
       return this.rebuildComposition(worlds, owner, catalogEpoch, buildCandidateFrame, leases);
     }
+
+    if (structureChangedWorlds.size > 0) {
+      this.visibilityFacets.clear();
+      this.invalidateActiveEntityRevision();
+      const currentByWorld = worlds.map((world) => collectRenderableEntities(world));
+      currentRenderableEntitiesByWorld = currentByWorld;
+      for (let worldId = 0; worldId < currentByWorld.length; worldId += 1) {
+        const world = worlds[worldId];
+        const current = currentByWorld[worldId];
+        if (world === undefined || current === undefined) continue;
+        const changed = changedEntitiesByWorld[worldId];
+        if (changed !== undefined && structureChangedWorlds.has(worldId)) {
+          // A joint can disappear without leaving a row in the joint's
+          // GlobalTransform change query. Wake every dependent renderable so
+          // the next partial extraction validates the dangling reference and
+          // either republishes or retires its palette data.
+          for (const [jointKey, consumers] of entry.skinConsumersByJoint) {
+            const separator = jointKey.indexOf(':');
+            const indexedWorldId = Number(jointKey.slice(0, separator));
+            if (indexedWorldId !== worldId) continue;
+            const jointEntity = Number(jointKey.slice(separator + 1));
+            if (world.hasComponent(jointEntity as EntityHandle, GlobalTransform)) continue;
+            for (const consumer of consumers) changed.add(consumer);
+          }
+          for (const entity of current) {
+            if (entry.projection.slot(worldId, entity) === undefined) changed.add(entity);
+          }
+          const structuralComponentIds = structuralComponentIdsByWorld[worldId];
+          const scanAllMembership =
+            structuralComponentIds !== undefined &&
+            [...structuralComponentIds].some((id) =>
+              STRUCTURAL_MEMBERSHIP_SCAN_COMPONENT_IDS.has(id),
+            );
+          for (const slot of entry.projection.slotsSnapshot()) {
+            if (slot.worldId !== worldId || !current.has(slot.entityKey)) continue;
+            const membershipChanged = sourceMembershipChanged(world, slot);
+            if (scanAllMembership || membershipChanged) {
+              changed.add(slot.entityKey);
+              if (
+                slot.snapshot.instances !== undefined &&
+                !world.hasComponent(slot.entityKey as EntityHandle, Instances)
+              ) {
+                this.options.instanceCollections?.release(world, slot.entityKey);
+              }
+              if (
+                slot.snapshot.skin !== undefined &&
+                !world.hasComponent(slot.entityKey as EntityHandle, Skin)
+              ) {
+                this.options
+                  .getSkinPaletteAllocator?.()
+                  ?.releaseSliceFor(`${world.identity}:${slot.entityKey}`);
+              }
+            }
+          }
+        }
+        for (const slot of entry.projection.slotsSnapshot()) {
+          if (slot.worldId !== worldId || current.has(slot.entityKey)) continue;
+          removedSlots.push(slot);
+        }
+        this.worldEntitiesScanned += current.size;
+      }
+    }
+
+    // Query iteration is an observation step, not publication. Persist every
+    // requested identity before invoking any producer so a thrown or omitted
+    // partial extraction is retried even after ECS change evidence is drained.
+    for (let worldId = 0; worldId < changedEntitiesByWorld.length; worldId += 1) {
+      const pending = entry.pendingRenderableEntitiesByWorld[worldId];
+      if (pending === undefined) continue;
+      for (const entityKey of changedEntitiesByWorld[worldId] ?? []) pending.add(entityKey);
+    }
+
+    let changedDelta: RenderSceneApplyResult | undefined;
+    const hasChangedEntities = changedEntitiesByWorld.some((entities) => entities.size > 0);
+    if (hasChangedEntities || removedSlots.length > 0) {
+      const operations: RenderSceneOperation[] = [];
+      const removedDemand: TransmissionDemandOperation[] = [];
+      const replacedSkinSnapshots: RenderableSnapshot[] = [];
+      for (let worldId = 0; worldId < changedEntitiesByWorld.length; worldId += 1) {
+        for (const entityKey of changedEntitiesByWorld[worldId] ?? []) {
+          const slot = entry.projection.slot(worldId, entityKey);
+          if (slot !== undefined) replacedSkinSnapshots.push(slot.snapshot);
+        }
+      }
+      for (const slot of removedSlots) {
+        operations.push({ kind: 'remove', worldId: slot.worldId, entityKey: slot.entityKey });
+        if (slot.snapshot.skinJointEntities !== undefined) {
+          removeSkinConsumer(entry.skinConsumersByJoint, slot.snapshot);
+        }
+        const world = worlds[slot.worldId];
+        if (world !== undefined) this.options.instanceCollections?.release(world, slot.entityKey);
+        this.options
+          .getSkinPaletteAllocator?.()
+          ?.releaseSliceFor(`${world?.identity ?? slot.worldId}:${slot.entityKey}`);
+        for (
+          let materialIndex = 0;
+          materialIndex < slot.snapshot.materials.length;
+          materialIndex += 1
+        ) {
+          removedDemand.push({
+            kind: 'remove',
+            key: `${slot.worldId}:${slot.entityKey}:${materialIndex}`,
+          });
+        }
+      }
+      for (let worldId = 0; worldId < changedEntitiesByWorld.length; worldId += 1) {
+        for (const entityKey of changedEntitiesByWorld[worldId] ?? []) {
+          const slot = entry.projection.slot(worldId, entityKey);
+          if (slot === undefined) continue;
+          for (
+            let materialIndex = 0;
+            materialIndex < slot.snapshot.materials.length;
+            materialIndex += 1
+          ) {
+            removedDemand.push({ kind: 'remove', key: `${worldId}:${entityKey}:${materialIndex}` });
+          }
+        }
+      }
+      const partial = hasChangedEntities
+        ? buildCandidateFrame({ kind: 'partial', entitiesByWorld: changedEntitiesByWorld })
+        : undefined;
+      const publishedEntitiesByWorld = worlds.map(() => new Set<number>());
+      for (const snapshot of partial?.renderables ?? []) {
+        operations.push({ kind: 'create', snapshot });
+        publishedEntitiesByWorld[snapshot.worldId]?.add(snapshot.entityKey);
+      }
+      changedDelta = entry.projection.apply(operations);
+      const publishedSkinKeys = new Set<string>();
+      for (const snapshot of partial?.renderables ?? []) {
+        publishedSkinKeys.add(`${snapshot.worldId}:${snapshot.entityKey}`);
+      }
+      for (const snapshot of replacedSkinSnapshots) {
+        // Keep the old dependency while a failed/omitted partial publication
+        // retains its CPU slot.  The pending identity must still be woken by
+        // a later joint transform change so the producer gets another chance.
+        if (
+          snapshot.skinJointEntities !== undefined &&
+          publishedSkinKeys.has(`${snapshot.worldId}:${snapshot.entityKey}`)
+        ) {
+          removeSkinConsumer(entry.skinConsumersByJoint, snapshot);
+        }
+      }
+      for (const snapshot of partial?.renderables ?? []) {
+        if (snapshot.skinJointEntities !== undefined) {
+          addSkinConsumer(entry.skinConsumersByJoint, snapshot);
+        }
+      }
+      entry.transmissionDemand.apply([
+        ...removedDemand,
+        ...transmissionDemandOperations(partial?.renderables ?? []),
+      ]);
+      for (const removed of changedDelta.removedSlots) entry.dispatchBySlot.delete(removed.slot);
+      for (const recreated of changedDelta.recreatedSlots)
+        entry.dispatchBySlot.delete(recreated.slot);
+      if (partial !== undefined) {
+        if (refreshStructureFacts) {
+          entry.structure = {
+            ...entry.structure,
+            dispatch: partial.dispatch,
+            visibilityStats: partial.visibilityStats,
+            visibilitySnapshots: partial.visibilitySnapshots,
+            featureVisibilitySnapshots: partial.featureVisibilitySnapshots,
+            hiddenEntityReports: partial.hiddenEntityReports,
+          };
+        }
+        const partialDispatch = dispatchEntriesBySlot(partial, entry.projection);
+        for (const [slot, dispatch] of partialDispatch) entry.dispatchBySlot.set(slot, dispatch);
+        // A changed renderable which now fails producer validation still owns
+        // its retained identity; replace its old dispatch with an empty list.
+        for (const snapshot of partial.renderables) {
+          const slot = entry.projection.slot(snapshot.worldId, snapshot.entityKey);
+          if (slot !== undefined && !partialDispatch.has(slot.slot))
+            entry.dispatchBySlot.set(slot.slot, []);
+        }
+      }
+      for (let worldId = 0; worldId < changedEntitiesByWorld.length; worldId += 1) {
+        const requested = changedEntitiesByWorld[worldId];
+        const published = publishedEntitiesByWorld[worldId];
+        if (requested === undefined || published === undefined) continue;
+        const pending = entry.pendingRenderableEntitiesByWorld[worldId];
+        for (const entityKey of requested) {
+          const slot = entry.projection.slot(worldId, entityKey);
+          if (published.has(entityKey)) {
+            pending?.delete(entityKey);
+            continue;
+          }
+          if (slot === undefined) {
+            const current = currentRenderableEntitiesByWorld?.[worldId];
+            if (current !== undefined && !current.has(entityKey)) pending?.delete(entityKey);
+            continue;
+          }
+          // The producer did not publish this requested identity. Keep the
+          // old CPU slot for recovery, but stop submitting stale dispatch and
+          // retry the same identity even if its World version stays still.
+          pending?.add(entityKey);
+          if (slot !== undefined) entry.dispatchBySlot.set(slot.slot, []);
+        }
+      }
+      const newlyUnavailable: RenderSceneSlot[] = [];
+      for (let worldId = 0; worldId < changedEntitiesByWorld.length; worldId += 1) {
+        const requested = changedEntitiesByWorld[worldId];
+        const published = publishedEntitiesByWorld[worldId];
+        if (requested === undefined || published === undefined) continue;
+        for (const entityKey of requested) {
+          const slot = entry.projection.slot(worldId, entityKey);
+          if (slot === undefined || published.has(entityKey)) {
+            if (slot !== undefined) entry.unavailableSlots.delete(slot.slot);
+            continue;
+          }
+          if (!entry.unavailableSlots.has(slot.slot)) newlyUnavailable.push(slot);
+          entry.unavailableSlots.add(slot.slot);
+        }
+      }
+      for (const removed of changedDelta.removedSlots) entry.unavailableSlots.delete(removed.slot);
+      for (const recreated of changedDelta.recreatedSlots)
+        entry.unavailableSlots.delete(recreated.slot);
+      entry.dispatchRevision += 1;
+      entry.dispatchCache = undefined;
+      entry.topology.apply(
+        topologyDeltaForAvailable(changedDelta, entry.unavailableSlots, newlyUnavailable),
+      );
+      this.syncGpuOwner(entry.token, entry.projection, changedDelta);
+      this.deltaFrames +=
+        changedDelta.created +
+          changedDelta.updated +
+          changedDelta.removed +
+          changedDelta.recreated >
+        0
+          ? 1
+          : 0;
+      this.transformUpdates += changedDelta.updated;
+    }
+
     const transformSpans: WorldTransformSpan[] = [];
     for (let worldId = 0; worldId < entry.transformQueries.length; worldId += 1) {
       const query = entry.transformQueries[worldId];
@@ -1597,17 +2101,29 @@ export class PersistentRenderScene {
     if (requiresRebuild) {
       return this.rebuildComposition(worlds, owner, catalogEpoch, buildCandidateFrame, leases);
     }
-    if (transformSpans.length === 0) {
+    if (transformSpans.length === 0 && changedDelta === undefined) {
       this.noChangeFrames += 1;
       this.syncGpuOwner(entry.token, entry.projection);
-      return this.deriveFramePlan(entry, buildCandidateFrame);
+      const result = this.deriveFramePlan(entry, buildCandidateFrame);
+      for (let worldId = 0; worldId < nextReadVersions.length; worldId += 1) {
+        const version = nextReadVersions[worldId];
+        if (version !== undefined) entry.readVersions[worldId] = version;
+      }
+      return result;
     }
-    const delta = entry.projection.applyTransformSpans(transformSpans);
-    entry.topology.apply(delta);
-    this.syncGpuOwner(entry.token, entry.projection, delta);
-    this.deltaFrames += 1;
-    this.transformUpdates += delta.updated;
-    return this.deriveFramePlan(entry, buildCandidateFrame);
+    if (transformSpans.length > 0) {
+      const delta = entry.projection.applyTransformSpans(transformSpans);
+      entry.topology.apply(topologyDeltaForAvailable(delta, entry.unavailableSlots, []));
+      this.syncGpuOwner(entry.token, entry.projection, delta);
+      this.deltaFrames += 1;
+      this.transformUpdates += delta.updated;
+    }
+    const result = this.deriveFramePlan(entry, buildCandidateFrame);
+    for (let worldId = 0; worldId < nextReadVersions.length; worldId += 1) {
+      const version = nextReadVersions[worldId];
+      if (version !== undefined) entry.readVersions[worldId] = version;
+    }
+    return result;
   }
 
   invalidate(): void {
@@ -1633,6 +2149,16 @@ export class PersistentRenderScene {
     const detachedComposition = this.composition?.worlds.includes(world)
       ? this.composition
       : undefined;
+    if (detachedComposition !== undefined) {
+      for (const slot of detachedComposition.projection.slotsSnapshot()) {
+        if (detachedComposition.worlds[slot.worldId] !== world) continue;
+        this.options.instanceCollections?.release(world, slot.entityKey);
+        if (slot.snapshot.skin === undefined) continue;
+        this.options
+          .getSkinPaletteAllocator?.()
+          ?.releaseSliceFor(`${world.identity}:${slot.entityKey}`);
+      }
+    }
     if (detachedComposition !== undefined) this.composition = undefined;
     if (detachedComposition !== undefined) this.temporalCapture = undefined;
     if (detachedComposition !== undefined) {
@@ -1661,6 +2187,111 @@ export class PersistentRenderScene {
     this.gpuStatus = this.options.getDevice === undefined ? 'inactive' : 'rebuild-pending';
   }
 
+  /** Prepare a detached GPU scene without changing the active scene owner. */
+  prepareRecoveryGpuDrivenCandidate(
+    device: RhiDevice,
+  ): Result<PersistentGpuDrivenCandidate, RhiError> {
+    const composition = this.composition;
+    if (composition === undefined) {
+      return ok({
+        state: undefined,
+        createRecoveryRoot: (scope) => ({
+          kind: 'scene-table',
+          create: () => {
+            if (!scope.isAlive()) throw new Error('GPU-driven candidate scope is not active.');
+            throw new Error('GPU-driven candidate has no scene resource.');
+          },
+          cleanup: () => undefined,
+        }),
+        publish: () => undefined,
+        discard: () => undefined,
+        release: () => undefined,
+      });
+    }
+    const created = GpuScene.create(
+      device,
+      Math.max(256, composition.projection.inspect().slotCapacity),
+    );
+    if (!created.ok) return created;
+    if (created.value.status === 'unavailable') {
+      return ok({
+        state: undefined,
+        createRecoveryRoot: (scope) => ({
+          kind: 'scene-table',
+          create: () => {
+            if (!scope.isAlive()) throw new Error('GPU-driven candidate scope is not active.');
+            throw new Error('GPU-driven candidate has no scene resource.');
+          },
+          cleanup: () => undefined,
+        }),
+        publish: () => undefined,
+        discard: () => undefined,
+        release: () => undefined,
+      });
+    }
+    const scene = created.value.scene;
+    const slots = composition.projection.slotsSnapshot();
+    const rebuilt = scene.rebuild(slots);
+    if (!rebuilt.ok) {
+      scene.dispose();
+      return rebuilt;
+    }
+    const state: PersistentGpuDrivenState = Object.freeze({
+      scene,
+      plan: composition.topology.plan(),
+      slots,
+    });
+    let published = false;
+    let released = false;
+    return ok({
+      state,
+      createRecoveryRoot: (scope) => ({
+        kind: 'scene-table',
+        create: () => {
+          if (!scope.isAlive()) throw new Error('GPU-driven candidate scope is not active.');
+          return scene;
+        },
+        cleanup: () => undefined,
+      }),
+      publish: () => {
+        if (published || released) return;
+        published = true;
+        this.gpuScene = scene;
+        this.gpuOwner = composition.token;
+        this.gpuDevice = device;
+        this.gpuStatus = 'resident';
+      },
+      discard: () => {
+        if (published || released) return;
+        released = true;
+        scene.dispose();
+      },
+      release: () => {
+        if (published || released) return;
+        released = true;
+        scene.dispose();
+      },
+    });
+  }
+
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'scene-table',
+      create: () => {
+        const composition = this.composition;
+        if (!scope.isAlive() || composition === undefined) {
+          throw new Error('RenderScene CPU projection is not ready for recovery.');
+        }
+        return Object.freeze({
+          generation: scope.generation,
+          revision: composition.projection.inspect().revision,
+          visibleSlots: composition.projection.slotsSnapshot().length,
+        });
+      },
+      cleanup: () => undefined,
+    };
+  }
+
   setPointsLinesInspections(inspections: readonly PointsLinesInspection[]): void {
     this.pointsLinesInspections = inspections.map((inspection) => ({
       ...inspection,
@@ -1781,7 +2412,7 @@ export class PersistentRenderScene {
     worlds: readonly World[],
     owner: { readonly cameraOwner: number; readonly resourceOwner: number },
     catalogEpoch: number,
-    buildCandidateFrame: (renderables: 'full' | 'none') => ExtractedFrame,
+    buildCandidateFrame: (request: PersistentRenderCandidateRequest) => ExtractedFrame,
     leases?: readonly RenderReadLease[],
     preserveVisibilityOnReorder = false,
   ): ExtractedFrame {
@@ -1851,6 +2482,10 @@ export class PersistentRenderScene {
     transmissionDemand.apply(transmissionDemandOperations(candidateFrame.renderables));
     const topology = new BatchTopology();
     topology.rebuild(projection.slotsSnapshot());
+    const skinConsumersByJoint = new Map<string, Set<number>>();
+    for (const snapshot of stableCandidateFrame.renderables) {
+      if (snapshot.skinJointEntities !== undefined) addSkinConsumer(skinConsumersByJoint, snapshot);
+    }
     const token = {};
     const entry: PersistentCompositionEntry = {
       token,
@@ -1880,8 +2515,17 @@ export class PersistentRenderScene {
         leases === undefined || leases.length !== worlds.length
           ? []
           : worlds.map(createGlobalTransformChangeQuery),
+      renderChangeQueries:
+        leases === undefined || leases.length !== worlds.length
+          ? []
+          : worlds.map(createRenderChangeQueries),
+      dispatchBySlot: dispatchEntriesBySlot(stableCandidateFrame, projection),
+      dispatchRevision: 0,
+      dispatchCache: undefined,
+      skinConsumersByJoint,
+      pendingRenderableEntitiesByWorld: worlds.map(() => new Set<number>()),
+      unavailableSlots: new Set<number>(),
       catalogEpoch,
-      rigidOnly: candidateFrame.renderables.every((renderable) => renderable.skin === undefined),
       probeProjection: new ProbeBlendSceneProjection(),
       temporalDemanded: frameDemandsTemporal(candidateFrame),
       gpuDrivenSceneRequired: true,
@@ -1941,10 +2585,23 @@ export class PersistentRenderScene {
    */
   private deriveFramePlan(
     entry: PersistentCompositionEntry,
-    buildCandidateFrame: (renderables: 'full' | 'none') => ExtractedFrame,
+    buildCandidateFrame: (request: PersistentRenderCandidateRequest) => ExtractedFrame,
   ): ExtractedFrame {
     const resourceFrame = buildCandidateFrame('none');
-    const candidateFrame: ExtractedFrame = { ...resourceFrame, ...entry.structure };
+    const cachedDispatch = entry.dispatchCache;
+    const dispatch: DispatchEntry[] = [
+      ...(cachedDispatch?.revision === entry.dispatchRevision
+        ? cachedDispatch.value
+        : dispatchForProjection(entry.dispatchBySlot, entry.projection, entry.unavailableSlots)),
+    ];
+    if (cachedDispatch?.revision !== entry.dispatchRevision) {
+      entry.dispatchCache = { revision: entry.dispatchRevision, value: dispatch };
+    }
+    const candidateFrame: ExtractedFrame = {
+      ...resourceFrame,
+      ...entry.structure,
+      dispatch,
+    };
     entry.temporalDemanded = frameDemandsTemporal(candidateFrame);
     entry.projection.setTemporalTracking(entry.temporalDemanded);
     this.projectProbes(entry, candidateFrame);
@@ -1953,9 +2610,18 @@ export class PersistentRenderScene {
     const candidates = entry.temporalDemanded
       ? materialized.map((snapshot) => entry.projection.withTemporal(snapshot))
       : materialized;
+    const drawableCandidates =
+      entry.unavailableSlots.size === 0
+        ? candidates
+        : candidates.map((snapshot) => {
+            const slot = entry.projection.slot(snapshot.worldId, snapshot.entityKey);
+            return slot !== undefined && entry.unavailableSlots.has(slot.slot)
+              ? { ...snapshot, authorVisible: false }
+              : snapshot;
+          });
     const frameWithProbes = attachProbeRecords(
-      { ...candidateFrame, renderables: candidates },
-      candidates,
+      { ...candidateFrame, renderables: drawableCandidates },
+      drawableCandidates,
       entry.projection.slotsSnapshot(),
       entry.probeProjection,
     );