@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/render-scene-projection.unit.test.ts

@@ -1,17 +1,38 @@
 import { World } from '@forgeax/engine-ecs';
 import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import { vec3 } from '@forgeax/engine-math';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
-import { Transform } from '@forgeax/engine-scene';
-import { describe, expect, it } from 'vitest';
-import { Camera, MotionBlur } from '../components';
+import { GlobalTransform, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  Camera,
+  DirectionalLight,
+  Instances,
+  LightProbe,
+  MeshFilter,
+  MeshRenderer,
+  MotionBlur,
+  PointLight,
+  PointLightShadow,
+  SpotLight,
+} from '../components';
+import { InstanceCollectionStore } from '../instances';
 import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
 import type {
+  DispatchEntry,
   ExtractedFrame,
   MaterialSnapshot,
   RenderableSnapshot,
+  ShadowCasterMembership,
 } from '../render-system-extract';
-import { PersistentRenderScene, RenderScene } from '../scene/render-scene';
+import { extractFrames } from '../render-system-extract';
+import {
+  type PersistentRenderCandidateRequest,
+  PersistentRenderScene,
+  RenderScene,
+} from '../scene/render-scene';
 import { primitiveKey, viewKey } from '../scene/visibility/types';
+import type { SkinPaletteReceipt } from '../systems/skin-palette-types';
 import { classifySceneDataCoverage } from '../temporal/coverage';
 
 const material = {} as MaterialSnapshot;
@@ -24,6 +45,19 @@ function guid(value: string) {
 
 const LOD_MESH_GUID = guid('019d0000-0000-7000-8000-000000000001');
 
+const SKIN_RECEIPT = {
+  identity: 'skin:0:1',
+  generation: 1,
+  fence: 1,
+  customDataStart: 0,
+  storageOrUniform: 'storage',
+  jointCount: 1,
+  byteOffset: 0,
+  buffer: {} as never,
+  dirtyRanges: [],
+  uploadBytes: 0,
+} satisfies SkinPaletteReceipt;
+
 function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
   const world = new Float32Array(16);
   world[0] = 1;
@@ -42,7 +76,67 @@ function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
   };
 }
 
+function updateSnapshot(value: RenderableSnapshot) {
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    snapshot: value,
+  };
+}
+
+function updateInstances(value: RenderableSnapshot) {
+  if (value.instances === undefined) throw new Error('expected Instances payload');
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    instances: value.instances,
+  };
+}
+
+function instancesSnapshot(
+  entityKey: number,
+  translationX: number,
+  instanceCount = 1,
+): RenderableSnapshot {
+  const base = snapshot(entityKey, 0);
+  const transforms = new Float32Array(instanceCount * 16);
+  for (let index = 0; index < instanceCount; index += 1) {
+    const offset = index * 16;
+    transforms[offset] = 1;
+    transforms[offset + 5] = 1;
+    transforms[offset + 10] = 1;
+    transforms[offset + 15] = 1;
+    transforms[offset + 12] = translationX + index;
+  }
+  return {
+    ...base,
+    instances: {
+      transforms,
+      instanceCount,
+      cacheKey: entityKey,
+      archVersion: 0,
+      revision: translationX + instanceCount,
+    },
+  };
+}
+
 describe('RenderScene canonical owner', () => {
+  it('rejects a mismatched source identity before publishing any operation', () => {
+    const scene = new RenderScene();
+    scene.apply([updateSnapshot(snapshot(1, 0))]);
+    expect(() =>
+      scene.apply([
+        updateSnapshot(snapshot(1, 3)),
+        { kind: 'update', worldId: 0, entityKey: 2, snapshot: snapshot(3, 4) },
+      ]),
+    ).toThrow('identity must match');
+    expect(scene.slot(0, 1)?.snapshot.transform.world[12]).toBe(0);
+    expect(scene.slot(0, 2)).toBeUndefined();
+    expect(scene.slot(0, 3)).toBeUndefined();
+  });
+
   it('rebuilds the retained composition when Motion Blur is toggled', () => {
     const world = new World();
     const camera = world
@@ -66,6 +160,7 @@ describe('RenderScene canonical owner', () => {
       cameras: [{ ...makeZeroCameraFallbackSnapshot(), worldId: 0, entityKey: camera as number }],
       renderables: [],
       dispatch: [],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
     const persistent = new PersistentRenderScene();
     let builds = 0;
@@ -105,6 +200,7 @@ describe('RenderScene canonical owner', () => {
       cameras: [camera],
       renderables,
       dispatch: [],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
     const persistent = new PersistentRenderScene();
     let builds = 0;
@@ -154,8 +250,8 @@ describe('RenderScene canonical owner', () => {
     updatedWorld[12] = 9;
 
     const result = projection.apply([
-      { kind: 'create', snapshot: initial },
-      { kind: 'update-transform', worldId: 0, entityKey: 7, world: updatedWorld },
+      updateSnapshot(initial),
+      { kind: 'update', worldId: 0, entityKey: 7, world: updatedWorld },
     ]);
 
     expect(result).toMatchObject({ created: 1, updated: 0, removed: 0, recreated: 0 });
@@ -165,20 +261,136 @@ describe('RenderScene canonical owner', () => {
     expect(projection.materialize()[0]?.transform.world[12]).toBe(9);
   });
 
+  it('keeps mixed Instances and transform updates on the instance lane', () => {
+    const initial = instancesSnapshot(7, 1);
+    const nextInstances = instancesSnapshot(7, 4);
+    const nextWorld = new Float32Array(initial.transform.world);
+    nextWorld[12] = 9;
+    nextInstances.transform.world[12] = 9;
+
+    for (const operations of [
+      [
+        updateInstances(nextInstances),
+        { kind: 'update' as const, worldId: 0, entityKey: 7, world: nextWorld },
+      ],
+      [
+        { kind: 'update' as const, worldId: 0, entityKey: 7, world: nextWorld },
+        updateInstances(nextInstances),
+      ],
+    ]) {
+      const projection = new RenderScene();
+      projection.apply([updateSnapshot(initial)]);
+      const result = projection.apply(operations);
+      expect(result.instanceUpdatedSlots).toHaveLength(1);
+      expect(result.contentUpdatedSlots).toHaveLength(0);
+      expect(projection.materialize()[0]?.transform.world[12]).toBe(9);
+      expect(projection.materialize()[0]?.instances?.transforms[12]).toBe(4);
+    }
+  });
+
+  it('does not downgrade a full update followed by an Instances update', () => {
+    const projection = new RenderScene();
+    projection.apply([updateSnapshot(instancesSnapshot(7, 1))]);
+    const result = projection.apply([
+      updateSnapshot(instancesSnapshot(7, 2)),
+      updateInstances(instancesSnapshot(7, 3)),
+    ]);
+
+    expect(result.instanceUpdatedSlots).toHaveLength(0);
+    expect(result.contentUpdatedSlots).toHaveLength(1);
+  });
+
+  it('classifies an Instances-only collection revision without widening the content update', () => {
+    const world = new World();
+    const instanceCollections = new InstanceCollectionStore();
+    const initialTransforms = new Float32Array(16);
+    initialTransforms[0] = 1;
+    initialTransforms[5] = 1;
+    initialTransforms[10] = 1;
+    initialTransforms[15] = 1;
+    const collection = instanceCollections.create({ transforms: initialTransforms }).unwrap();
+    const entity = world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+        },
+        { component: MeshFilter, data: { assetHandle: 1 as never } },
+        { component: MeshRenderer, data: { materials: [] } },
+        { component: Instances, data: { collectionId: collection.collectionId } },
+      )
+      .unwrap();
+    const lease = createRenderReadLease(world);
+    const requests: PersistentRenderCandidateRequest[] = [];
+    const build = (request: PersistentRenderCandidateRequest): ExtractedFrame => {
+      requests.push(request);
+      const detached = instanceCollections.snapshot(collection.collectionId).unwrap();
+      return {
+        cameras: [{ ...makeZeroCameraFallbackSnapshot(), worldId: 0, entityKey: 1 }],
+        renderables: [
+          {
+            ...snapshot(entity as number, 0),
+            instances: {
+              ...detached,
+              instanceCount: detached.count,
+              cacheKey: entity as number,
+              archVersion: 0,
+            },
+          },
+        ],
+        dispatch: [],
+        hiddenEntityReports: [],
+      } as unknown as ExtractedFrame;
+    };
+    const persistent = new PersistentRenderScene({ instanceCollections });
+    try {
+      persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [
+        lease,
+      ]);
+      const nextTransforms = new Float32Array(initialTransforms);
+      nextTransforms[12] = 4;
+      instanceCollections.replace(collection.collectionId, nextTransforms).unwrap();
+      persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [
+        lease,
+      ]);
+
+      let partial: Extract<PersistentRenderCandidateRequest, { kind: 'partial' }> | undefined;
+      for (let index = requests.length - 1; index >= 0; index -= 1) {
+        const request = requests[index];
+        if (
+          request !== undefined &&
+          request !== 'full' &&
+          request !== 'none' &&
+          request.kind === 'partial'
+        ) {
+          partial = request;
+          break;
+        }
+      }
+      expect(partial?.kind).toBe('partial');
+      if (partial?.kind !== 'partial') return;
+      expect(partial.entitiesByWorld?.[0]?.has(entity as number)).toBe(true);
+    } finally {
+      lease.dispose();
+      persistent.dispose();
+      instanceCollections.dispose();
+    }
+  });
+
   it('updates cached dynamic world bounds without replacing the bounds object', () => {
     const projection = new RenderScene();
     const initial = {
       ...snapshot(7, 1),
       localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
     };
-    projection.apply([{ kind: 'create', snapshot: initial }]);
+    projection.apply([updateSnapshot(initial)]);
     const retained = projection.materialize()[0];
     if (retained === undefined) throw new Error('expected retained snapshot');
     const first = projection.cullingWorldBounds(retained);
     const moved = new Float32Array(initial.transform.world);
     moved[12] = 9;
 
-    projection.applyTransformSpans([{ worldId: 0, entities: new Uint32Array([7]), worlds: moved }]);
+    projection.apply([], [{ worldId: 0, entities: new Uint32Array([7]), worlds: moved }]);
 
     const next = projection.cullingWorldBounds(retained);
     expect(next).toBe(first);
@@ -190,7 +402,7 @@ describe('RenderScene canonical owner', () => {
     const projection = new RenderScene();
 
     const result = projection.apply([
-      { kind: 'create', snapshot: snapshot(3, 1) },
+      updateSnapshot(snapshot(3, 1)),
       { kind: 'remove', worldId: 0, entityKey: 3 },
     ]);
 
@@ -200,13 +412,13 @@ describe('RenderScene canonical owner', () => {
 
   it('bumps generation when remove and recreate reuse a slot', () => {
     const projection = new RenderScene();
-    projection.apply([{ kind: 'create', snapshot: snapshot(5, 1) }]);
+    projection.apply([updateSnapshot(snapshot(5, 1))]);
     const before = projection.inspect().records[0];
 
     const result = projection.apply([
       { kind: 'remove', worldId: 0, entityKey: 5 },
-      { kind: 'create', snapshot: snapshot(5, 2) },
-      { kind: 'update-transform', worldId: 0, entityKey: 5, world: snapshot(5, 7).transform.world },
+      updateSnapshot(snapshot(5, 2)),
+      { kind: 'update', worldId: 0, entityKey: 5, world: snapshot(5, 7).transform.world },
     ]);
 
     const after = projection.inspect().records[0];
@@ -218,11 +430,11 @@ describe('RenderScene canonical owner', () => {
 
   it('ignores an update that arrives after removal', () => {
     const projection = new RenderScene();
-    projection.apply([{ kind: 'create', snapshot: snapshot(9, 1) }]);
+    projection.apply([updateSnapshot(snapshot(9, 1))]);
 
     const result = projection.apply([
       { kind: 'remove', worldId: 0, entityKey: 9 },
-      { kind: 'update-transform', worldId: 0, entityKey: 9, world: snapshot(9, 4).transform.world },
+      { kind: 'update', worldId: 0, entityKey: 9, world: snapshot(9, 4).transform.world },
     ]);
 
     expect(result).toMatchObject({ removed: 1, ignoredLateUpdates: 1 });
@@ -232,8 +444,8 @@ describe('RenderScene canonical owner', () => {
   it('keeps identical entity handles isolated by World identity', () => {
     const projection = new RenderScene();
     projection.apply([
-      { kind: 'create', snapshot: snapshot(1, 3) },
-      { kind: 'create', snapshot: { ...snapshot(1, 8), worldId: 1 } },
+      updateSnapshot(snapshot(1, 3)),
+      updateSnapshot({ ...snapshot(1, 8), worldId: 1 }),
     ]);
 
     expect(projection.materialize().map((record) => record.transform.world[12])).toEqual([3, 8]);
@@ -270,6 +482,7 @@ describe('RenderScene canonical owner', () => {
       cameras: [camera],
       dispatch: [dispatch],
       renderables: [candidate],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
     const persistent = new PersistentRenderScene();
     const lease = createRenderReadLease(world);
@@ -364,6 +577,7 @@ describe('RenderScene canonical owner', () => {
       cameras: [cameraA],
       dispatch: [dispatchFor(1)],
       renderables: [ordinaryA, candidateB],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
     const persistent = new PersistentRenderScene();
     persistent.extractComposition(
@@ -405,6 +619,7 @@ describe('RenderScene canonical owner', () => {
       cameras: [cameraAReordered],
       dispatch: [dispatchFor(0)],
       renderables: [reorderedCandidateB, reorderedOrdinaryA],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
     persistent.extractComposition(
       [worldB, worldA],
@@ -455,6 +670,7 @@ describe('RenderScene canonical owner', () => {
       cameras: [camera],
       dispatch: [dispatch],
       renderables: [candidate],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
     const persistent = new PersistentRenderScene();
     persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, () => frame, [
@@ -499,6 +715,7 @@ describe('RenderScene canonical owner', () => {
       cameras: [camera],
       dispatch: [dispatch, { ...dispatch, entityIndex: 8, renderableIndex: 1 }],
       renderables: [candidate, extra],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
     persistent.extractComposition(
       [world],
@@ -513,6 +730,623 @@ describe('RenderScene canonical owner', () => {
     );
     lease.dispose();
   });
+  it('notifies the GPU residency owner for shared-ref payload mutations', () => {
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const handle = world.allocSharedRef('MeshAsset', { kind: 'mesh' });
+    const onSharedRefMutation = vi.fn();
+    const persistent = new PersistentRenderScene({ onSharedRefMutation });
+    const frame = {
+      cameras: [],
+      renderables: [],
+      dispatch: [],
+      hiddenEntityReports: [],
+    } as unknown as ExtractedFrame;
+
+    persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, () => frame, [
+      lease,
+    ]);
+    world.sharedRefs.markChanged(handle).unwrap();
+    persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, () => frame, [
+      lease,
+    ]);
+
+    expect(onSharedRefMutation).toHaveBeenCalledWith(0, handle);
+    lease.dispose();
+    persistent.dispose();
+  });
+
+  it('reuses a stable skinned composition and rebuilds when a joint changes', () => {
+    const world = new World();
+    const renderable = world
+      .spawn({
+        component: Transform,
+        data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+      })
+      .unwrap();
+    const joint = world
+      .spawn({
+        component: Transform,
+        data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+      })
+      .unwrap();
+    const lease = createRenderReadLease(world);
+    const candidate = {
+      ...snapshot(renderable as number, 0),
+      skin: SKIN_RECEIPT,
+      skinJointEntities: [joint as number],
+    } satisfies RenderableSnapshot;
+    const frame = (): ExtractedFrame =>
+      ({
+        cameras: [],
+        auxiliaryCameras: [],
+        cubeCameras: [],
+        lights: {
+          directional: undefined,
+          directionalCount: 0,
+          point: [],
+          spot: [],
+          pointShadow: [],
+        },
+        environment: undefined,
+        environmentReady: true,
+        renderables: [candidate],
+        dispatch: [],
+        shadowCasterEntityKeys: new Set<number>(),
+        shadowCasterDrawKeys: new Set<string>(),
+        skylight: undefined,
+        skylightCount: 0,
+        skybox: undefined,
+        skyboxCount: 0,
+        fog: undefined,
+        frustumStats: { culled: 0, total: 1 },
+        visibilityStats: { explicitlyHidden: 0 },
+        postProcessParams: new Map(),
+        visibilitySnapshots: [],
+        featureVisibilitySnapshots: [],
+        hiddenEntityReports: [],
+      }) as unknown as ExtractedFrame;
+    const persistent = new PersistentRenderScene();
+    let builds = 0;
+    const buildCandidate = (): ExtractedFrame => {
+      builds += 1;
+      return frame();
+    };
+
+    persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      buildCandidate,
+      [lease],
+    );
+    persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      buildCandidate,
+      [lease],
+    );
+    expect(builds).toBe(2);
+    expect(persistent.inspect()).toMatchObject({
+      fullRebuilds: 1,
+      worldEntitiesScanned: 0,
+    });
+
+    world.set(joint, Transform, { pos: [1, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+    world.update().unwrap();
+    persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      buildCandidate,
+      [lease],
+    );
+    expect(builds).toBe(4);
+    expect(persistent.inspect()).toMatchObject({
+      fullRebuilds: 1,
+      worldEntitiesScanned: 0,
+    });
+    lease.dispose();
+    persistent.dispose();
+  });
+
+  it('refreshes camera and light facts through normal extraction with stable scene identity', () => {
+    const world = new World();
+    const renderable = world.spawn({ component: Transform, data: { pos: [0, 0, 0] } }).unwrap();
+    const light = world
+      .spawn(
+        { component: Transform, data: { pos: [1, 2, 3] } },
+        { component: PointLight, data: { intensity: 1, range: 10 } },
+      )
+      .unwrap();
+    const camera = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 5] } },
+        { component: Camera, data: { fov: Math.PI / 3, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    propagateTransforms(world).unwrap();
+    const lease = createRenderReadLease(world);
+    const candidate = {
+      ...snapshot(renderable as number, 0),
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    } satisfies RenderableSnapshot;
+    let builds = 0;
+    const buildCandidate = (): ExtractedFrame => {
+      builds += 1;
+      const lightTransform = world.get(light, GlobalTransform).unwrap();
+      const cameraTransform = world.get(camera, GlobalTransform).unwrap();
+      return {
+        cameras: [
+          {
+            ...makeZeroCameraFallbackSnapshot(),
+            worldId: 0,
+            entityKey: camera as number,
+            world: new Float32Array(cameraTransform.world),
+          },
+        ],
+        auxiliaryCameras: [],
+        cubeCameras: [],
+        lights: {
+          directional: undefined,
+          directionalCount: 0,
+          point: [
+            {
+              kind: 'point',
+              entity: light,
+              worldId: 0,
+              position: new Float32Array([
+                lightTransform.world[12] ?? 0,
+                lightTransform.world[13] ?? 0,
+                lightTransform.world[14] ?? 0,
+              ]),
+              color: new Float32Array([1, 1, 1]),
+              intensity: 1,
+              invRangeSquared: 0.01,
+            },
+          ],
+          spot: [],
+          pointShadow: [],
+          rect: [],
+        },
+        environment: undefined,
+        environmentReady: true,
+        renderables: [candidate],
+        dispatch: [],
+        shadowCasterEntityKeys: new Set<number>(),
+        shadowCasterDrawKeys: new Set<string>(),
+        skylight: undefined,
+        skylightCount: 0,
+        skybox: undefined,
+        skyboxCount: 0,
+        fog: undefined,
+        frustumStats: { culled: 0, total: 1 },
+        visibilityStats: { explicitlyHidden: 0 },
+        postProcessParams: new Map(),
+        visibilitySnapshots: [],
+        featureVisibilitySnapshots: [],
+        hiddenEntityReports: [],
+      } as unknown as ExtractedFrame;
+    };
+    const persistent = new PersistentRenderScene();
+    try {
+      const initial = persistent.extractComposition(
+        [world],
+        { cameraOwner: 0, resourceOwner: 0 },
+        0,
+        buildCandidate,
+        [lease],
+      );
+      const before = persistent.compositionSlots()[0];
+      expect(before).toBeDefined();
+      world.set(light, Transform, { pos: [4, 2, 3] }).unwrap();
+      propagateTransforms(world).unwrap();
+      const moved = persistent.extractComposition(
+        [world],
+        { cameraOwner: 0, resourceOwner: 0 },
+        0,
+        buildCandidate,
+        [lease],
+      );
+      expect(moved.lights.point[0]?.position[0]).toBeCloseTo(4);
+      expect(builds).toBe(2);
+
+      world.set(camera, Transform, { pos: [0, 1, 5] }).unwrap();
+      propagateTransforms(world).unwrap();
+      const cameraMoved = persistent.extractComposition(
+        [world],
+        { cameraOwner: 0, resourceOwner: 0 },
+        0,
+        buildCandidate,
+        [lease],
+      );
+      expect(cameraMoved.cameras[0]?.world[13]).toBeCloseTo(1);
+      const after = persistent.compositionSlots()[0];
+      expect(after).toMatchObject({ slot: before?.slot, generation: before?.generation });
+      const projected = persistent.projectVisibility(
+        [world],
+        cameraMoved.cameras[0],
+        cameraMoved.renderables,
+        cameraMoved.dispatch,
+      );
+      expect(projected.renderables).toEqual(cameraMoved.renderables);
+      expect(projected.dispatch).toEqual(cameraMoved.dispatch);
+      expect(initial.renderables).toHaveLength(1);
+      expect(persistent.inspect()).toMatchObject({ fullRebuilds: 1, worldEntitiesScanned: 0 });
+    } finally {
+      lease.dispose();
+      persistent.dispose();
+    }
+  });
+
+  it('refreshes camera, light, and shadow facts through normal extraction per World identity', () => {
+    const makeWorld = (position: [number, number, number]) => {
+      const world = new World();
+      const entity = world
+        .spawn(
+          { component: Transform, data: { pos: position } },
+          { component: Camera, data: { fov: Math.PI / 3, aspect: 1, near: 0.1, far: 100 } },
+          { component: DirectionalLight, data: { direction: [0.2, -1, 0.3] } },
+          { component: PointLight, data: {} },
+          { component: PointLightShadow, data: {} },
+          { component: SpotLight, data: { direction: [0, -1, 0] } },
+          {
+            component: LightProbe,
+            data: { irradiance: new Float32Array(27).fill(0.25), radius: 10 },
+          },
+        )
+        .unwrap();
+      propagateTransforms(world).unwrap();
+      world.update().unwrap();
+      return { world, entity };
+    };
+    const first = makeWorld([1, 2, 3]);
+    const second = makeWorld([20, 2, 3]);
+    expect(Number(first.entity)).toBe(Number(second.entity));
+    const worlds = [first.world, second.world] as const;
+    const leases = [
+      createRenderReadLease(first.world),
+      createRenderReadLease(second.world),
+    ] as const;
+    const persistent = new PersistentRenderScene();
+    const build = (request: PersistentRenderCandidateRequest) =>
+      extractFrames(worlds, { cameraOwner: 0, resourceOwner: 0 }, undefined, undefined, undefined, {
+        cull: 'none',
+        renderables: request,
+      });
+    try {
+      const previous = persistent.extractComposition(
+        worlds,
+        { cameraOwner: 0, resourceOwner: 0 },
+        0,
+        build,
+        leases,
+      );
+      const previousPointShadow = previous.lights.pointShadow.find(
+        (shadow) => shadow.worldId === 0,
+      );
+      const previousSpot = previous.lights.spot.find((light) => light.worldId === 0);
+      const previousProbe = previous.lightProbes?.find((probe) => probe.worldId === 0);
+      const previousWorldOnePoint = previous.lights.point.find((light) => light.worldId === 1);
+      expect(previousPointShadow).toBeDefined();
+      expect(previousSpot).toBeDefined();
+      expect(previousProbe).toBeDefined();
+      expect(previous.cameras[0]).toBeDefined();
+      expect(previous.lights.lightViewProj).toBeDefined();
+      expect(previousWorldOnePoint).toBeDefined();
+
+      first.world.set(first.entity, Transform, { pos: [4, 5, 6] }).unwrap();
+      propagateTransforms(first.world).unwrap();
+      first.world.update().unwrap();
+      const refreshed = persistent.extractComposition(
+        worlds,
+        { cameraOwner: 0, resourceOwner: 0 },
+        0,
+        build,
+        leases,
+      );
+      const point = refreshed.lights.point.find((light) => light.worldId === 0);
+      const pointShadow = refreshed.lights.pointShadow.find((shadow) => shadow.worldId === 0);
+      const spot = refreshed.lights.spot.find((light) => light.worldId === 0);
+      const probe = refreshed.lightProbes?.find((candidate) => candidate.worldId === 0);
+      const worldOnePoint = refreshed.lights.point.find((light) => light.worldId === 1);
+      expect(point?.position).toEqual(new Float32Array([4, 5, 6]));
+      expect(pointShadow?.position).toEqual(new Float32Array([4, 5, 6]));
+      expect(pointShadow?.shadowMatrices).not.toEqual(previousPointShadow?.shadowMatrices);
+      expect(spot?.position).toEqual(new Float32Array([4, 5, 6]));
+      expect(spot?.lightViewProj).not.toEqual(previousSpot?.lightViewProj);
+      expect(probe?.position).toEqual([4, 5, 6]);
+      expect(refreshed.cameras[0]?.world[12]).toBeCloseTo(4);
+      expect(refreshed.cameras[0]?.world[13]).toBeCloseTo(5);
+      expect(refreshed.lights.lightViewProj).not.toEqual(previous.lights.lightViewProj);
+      expect(worldOnePoint?.position).toEqual(previousWorldOnePoint?.position);
+      expect(refreshed.lights.point.find((light) => light.worldId === 1)?.position).not.toEqual(
+        point?.position,
+      );
+    } finally {
+      leases[0].dispose();
+      leases[1].dispose();
+      persistent.dispose();
+    }
+  });
+
+  it('retains the complete shadow dispatch across mixed camera and renderable refresh', () => {
+    const world = new World();
+    const camera = world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [0, 0, 5], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+        },
+        {
+          component: Camera,
+          data: { fov: Math.PI / 3, aspect: 1, near: 0.1, far: 100 },
+        },
+      )
+      .unwrap();
+    const visibleEntity = world
+      .spawn({
+        component: Transform,
+        data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+      })
+      .unwrap();
+    const hiddenEntity = world
+      .spawn({
+        component: Transform,
+        data: { pos: [100, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+      })
+      .unwrap();
+    propagateTransforms(world).unwrap();
+    world.update().unwrap();
+
+    const cameraSnapshot = (): ExtractedFrame['cameras'][number] => {
+      const transform = world.get(camera, GlobalTransform).unwrap();
+      return {
+        ...makeZeroCameraFallbackSnapshot(),
+        worldId: 0,
+        entityKey: camera as number,
+        position: vec3.create(
+          transform.world[12] ?? 0,
+          transform.world[13] ?? 0,
+          transform.world[14] ?? 0,
+        ),
+        world: new Float32Array(transform.world),
+        fov: Math.PI / 3,
+        aspect: 1,
+        near: 0.1,
+        far: 100,
+      };
+    };
+    const renderables = [
+      {
+        ...snapshot(visibleEntity as number, 0),
+        localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+      },
+      {
+        ...snapshot(hiddenEntity as number, 100),
+        localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+      },
+    ];
+    const dispatch: DispatchEntry[] = renderables.map((entry, renderableIndex) => ({
+      entityIndex: entry.entityKey,
+      materialHandle: 0,
+      renderableIndex,
+      passIndex: 0,
+      queue: 2000,
+      layer: 0,
+      tags: { LightMode: 'ShadowCaster' },
+      renderState: undefined,
+      defines: undefined,
+      vertexEntry: 'vs_main',
+      fragmentEntry: undefined,
+      materialShaderId: 'forgeax::default-shadow-caster',
+      paramSnapshot: {},
+    }));
+    const shadowCasterMembership: ShadowCasterMembership[] = renderables.map(
+      (entry, renderableIndex) => ({
+        worldEntity: entry.entityKey,
+        renderableIndex,
+        drawItemIndex: 0,
+        materialHandle: 0,
+        passIndex: 0,
+      }),
+    );
+    const frame = (): ExtractedFrame =>
+      ({
+        cameras: [cameraSnapshot()],
+        auxiliaryCameras: [],
+        cubeCameras: [],
+        lights: {
+          directional: undefined,
+          directionalCount: 0,
+          point: [],
+          spot: [],
+          pointShadow: [],
+        },
+        environment: undefined,
+        environmentReady: true,
+        renderables,
+        dispatch,
+        shadowCasterEntityKeys: new Set(renderables.map((entry) => entry.entityKey)),
+        shadowCasterDrawKeys: new Set(
+          shadowCasterMembership.map(
+            (entry) =>
+              `${entry.worldEntity}:${entry.materialHandle}:${entry.drawItemIndex}:${entry.passIndex}`,
+          ),
+        ),
+        shadowCasterMembership,
+        skylight: undefined,
+        skylightCount: 0,
+        skybox: undefined,
+        skyboxCount: 0,
+        fog: undefined,
+        frustumStats: { culled: 0, total: 2 },
+        visibilityStats: { explicitlyHidden: 0 },
+        postProcessParams: new Map(),
+        visibilitySnapshots: [],
+        featureVisibilitySnapshots: [],
+        hiddenEntityReports: [],
+      }) as unknown as ExtractedFrame;
+    const lease = createRenderReadLease(world);
+    const persistent = new PersistentRenderScene();
+    const initial = persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      frame,
+      [lease],
+    );
+    expect(initial.renderables).toHaveLength(1);
+    expect(initial.dispatch).toHaveLength(1);
+    expect(persistent.shadowCasterProjection()?.dispatch).toHaveLength(2);
+
+    world.set(camera, Transform, { pos: [0, 0, 4] }).unwrap();
+    propagateTransforms(world).unwrap();
+    world.update().unwrap();
+    const moved = persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      frame,
+      [lease],
+    );
+
+    expect(moved.renderables).toHaveLength(1);
+    expect(moved.dispatch).toHaveLength(1);
+    expect(persistent.shadowCasterProjection()?.dispatch).toHaveLength(2);
+
+    // A renderable and the camera can change in the same ECS tick. Normal
+    // extraction updates both through the retained projection, so the complete
+    // shadow dispatch remains available after the delta updates the slot.
+    world.set(camera, Transform, { pos: [0, 0, 3] }).unwrap();
+    world.set(visibleEntity, Transform, { pos: [1, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+    world.update().unwrap();
+    const mixed = persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      frame,
+      [lease],
+    );
+
+    expect(mixed.renderables).toHaveLength(1);
+    expect(mixed.dispatch).toHaveLength(1);
+    expect(persistent.shadowCasterProjection()?.dispatch).toHaveLength(2);
+    lease.dispose();
+    persistent.dispose();
+  });
+
+  it('rebuilds probe records when a LightProbe transform changes', () => {
+    const world = new World();
+    const renderableEntity = world
+      .spawn({
+        component: Transform,
+        data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+      })
+      .unwrap();
+    const nearProbe = world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+        },
+        {
+          component: LightProbe,
+          data: { irradiance: new Float32Array(27).fill(1), radius: 2 },
+        },
+      )
+      .unwrap();
+    const farProbe = world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [4, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+        },
+        {
+          component: LightProbe,
+          data: { irradiance: new Float32Array(27), radius: 10 },
+        },
+      )
+      .unwrap();
+    propagateTransforms(world).unwrap();
+    const lease = createRenderReadLease(world);
+    const renderable = {
+      ...snapshot(renderableEntity as number, 0),
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    };
+    const probeFact = (entity: typeof nearProbe | typeof farProbe) => {
+      const transform = world.get(entity, GlobalTransform).unwrap();
+      const probe = world.get(entity, LightProbe).unwrap();
+      return {
+        identity: String(entity),
+        worldId: 0,
+        position: [
+          transform.world[12] ?? 0,
+          transform.world[13] ?? 0,
+          transform.world[14] ?? 0,
+        ] as [number, number, number],
+        radius: probe.radius,
+        irradiance: new Float32Array(probe.irradiance),
+        admitted: true,
+      };
+    };
+    const buildFrame = (): ExtractedFrame =>
+      ({
+        cameras: [],
+        lights: {
+          directional: undefined,
+          directionalCount: 0,
+          point: [],
+          spot: [],
+          pointShadow: [],
+        },
+        environment: undefined,
+        environmentReady: true,
+        renderables: [renderable],
+        dispatch: [],
+        lightProbes: [probeFact(nearProbe), probeFact(farProbe)],
+        skylight: undefined,
+        skylightCount: 0,
+        skybox: undefined,
+        skyboxCount: 0,
+        fog: undefined,
+        frustumStats: { culled: 0, total: 1 },
+        visibilityStats: { explicitlyHidden: 0 },
+        postProcessParams: new Map(),
+        visibilitySnapshots: [],
+        featureVisibilitySnapshots: [],
+        hiddenEntityReports: [],
+      }) as unknown as ExtractedFrame;
+    const persistent = new PersistentRenderScene();
+    const initial = persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      buildFrame,
+      [lease],
+    );
+    const initialRecord = initial.renderables[0]?.probeBlendRecord;
+    expect(initialRecord).toBeDefined();
+
+    world.set(nearProbe, Transform, { pos: [4, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+    world.update().unwrap();
+    const moved = persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      buildFrame,
+      [lease],
+    );
+
+    expect(persistent.inspect()).toMatchObject({ fullRebuilds: 1 });
+    expect(moved.renderables[0]?.probeBlendRecord?.bytes).not.toEqual(initialRecord?.bytes);
+    lease.dispose();
+    persistent.dispose();
+  });
 });
 
 describe('RenderScene', () => {
@@ -535,6 +1369,7 @@ describe('RenderScene', () => {
           admitted: true,
         },
       ],
+      hiddenEntityReports: [],
     } as unknown as ExtractedFrame;
 
     const projected = scene.extractComposition(
@@ -573,8 +1408,8 @@ describe('RenderScene', () => {
   it('keeps one stable slot across reorder and reports no-change without scanning', () => {
     const scene = new RenderScene();
     scene.apply([
-      { kind: 'create', snapshot: snapshot(7, 1) },
-      { kind: 'create', snapshot: { ...snapshot(8, 2), worldId: 1 } },
+      updateSnapshot(snapshot(7, 1)),
+      updateSnapshot({ ...snapshot(8, 2), worldId: 1 }),
     ]);
 
     const before = scene.slot(0, 7);
@@ -589,13 +1424,12 @@ describe('RenderScene', () => {
     const scene = new RenderScene();
     scene.apply([
       {
-        kind: 'create',
-        snapshot: {
+        ...updateSnapshot({
           ...snapshot(11, 4),
           localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
           material: { ...material, materialHandle: 42 },
           materials: [{ ...material, materialHandle: 42 }],
-        },
+        }),
       },
     ]);
 
@@ -611,15 +1445,72 @@ describe('RenderScene', () => {
       ...snapshot(12, 0),
       localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
     };
-    scene.apply([{ kind: 'create', snapshot: initial }]);
+    scene.apply([updateSnapshot(initial)]);
 
     expect(scene.querySpatial({ min: [-2, -2, -2], max: [2, 2, 2] })).toHaveLength(1);
 
     const moved = new Float32Array(initial.transform.world);
     moved[12] = 10;
-    scene.apply([{ kind: 'update-transform', worldId: 0, entityKey: 12, world: moved }]);
+    scene.apply([{ kind: 'update', worldId: 0, entityKey: 12, world: moved }]);
 
     expect(scene.querySpatial({ min: [-2, -2, -2], max: [2, 2, 2] })).toEqual([]);
     expect(scene.querySpatial({ min: [9, -2, -2], max: [11, 2, 2] })).toHaveLength(1);
   });
 });
+
+describe('projected bounds query', () => {
+  it('uses World identity, instance transforms, and detached current projection data', () => {
+    const scene = new PersistentRenderScene(),
+      worldA = new World(),
+      worldB = new World();
+    const a = { ...snapshot(7, 10), localAabb: new Float32Array([100, -1, -2, 102, 1, 2]) };
+    const b = {
+      ...snapshot(7, 900),
+      worldId: 1,
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    };
+    const frame = (renderables: RenderableSnapshot[]) =>
+      ({ cameras: [], renderables, dispatch: [] }) as unknown as ExtractedFrame;
+    expect(scene.bounds(worldA, 7)).toBeUndefined();
+    scene.extractComposition([worldA, worldB], { cameraOwner: 0, resourceOwner: 0 }, 0, () =>
+      frame([a, b]),
+    );
+    expect(scene.bounds(worldA, 7)).toEqual({ min: [110, -1, -2], max: [112, 1, 2] });
+    expect(scene.bounds(worldB, 7)).toEqual({ min: [899, -1, -1], max: [901, 1, 1] });
+    expect(scene.bounds(new World(), 7)).toBeUndefined();
+    expect(scene.bounds(worldA, 99)).toBeUndefined();
+    const first = scene.bounds(worldA, 7);
+    if (first === undefined) throw new Error('expected projected bounds');
+    (first.min as number[])[0] = -999;
+    expect(scene.bounds(worldA, 7)?.min[0]).toBe(110);
+    const instanceA = snapshot(1, 0).transform.world,
+      instanceB = snapshot(2, 20).transform.world;
+    const instanced = {
+      ...a,
+      instances: {
+        transforms: new Float32Array([...instanceA, ...instanceB]),
+        instanceCount: 2,
+        cacheKey: 7,
+        archVersion: 1,
+      },
+    };
+    scene.extractComposition([worldA, worldB], { cameraOwner: 0, resourceOwner: 0 }, 1, () =>
+      frame([instanced, b]),
+    );
+    expect(scene.bounds(worldA, 7)).toEqual({ min: [110, -1, -2], max: [132, 1, 2] });
+    scene.extractComposition([worldB, worldA], { cameraOwner: 0, resourceOwner: 0 }, 2, () =>
+      frame([
+        { ...b, worldId: 0 },
+        { ...instanced, worldId: 1 },
+      ]),
+    );
+    expect(scene.bounds(worldA, 7)?.max[0]).toBe(132);
+    expect(scene.bounds(worldB, 7)?.max[0]).toBe(901);
+    scene.extractComposition([worldA], { cameraOwner: 0, resourceOwner: 0 }, 3, () =>
+      frame([{ ...a, localAabb: undefined }]),
+    );
+    expect(scene.bounds(worldA, 7)).toBeUndefined();
+    expect(scene.bounds(worldB, 7)).toBeUndefined();
+    scene.dispose();
+  });
+});