@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/render-graph-hzb-gpu.ts

@@ -0,0 +1,239 @@
+import { type CompiledRenderGraphInfo, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type {
+  BindGroupLayout,
+  ComputePipeline,
+  RhiCommandEncoder,
+  RhiDevice,
+} from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const HZB_SIZE = 8;
+const HZB_MIPS = 4;
+
+const SEED_WGSL = /* wgsl */ `
+@group(0) @binding(0) var outputTexture: texture_storage_2d<r32float, write>;
+
+@compute @workgroup_size(1)
+fn seed(@builtin(global_invocation_id) id: vec3<u32>) {
+  let value = f32(id.x + id.y * 8u) / 63.0;
+  textureStore(outputTexture, vec2<i32>(id.xy), vec4<f32>(value, 0.0, 0.0, 1.0));
+}
+`;
+
+const REDUCE_WGSL = /* wgsl */ `
+@group(0) @binding(0) var source: texture_2d<f32>;
+@group(0) @binding(1) var outputTexture: texture_storage_2d<r32float, write>;
+
+@compute @workgroup_size(1)
+fn reduce(@builtin(global_invocation_id) id: vec3<u32>) {
+  let sourceSize = textureDimensions(source);
+  let base = vec2<i32>(id.xy * 2u);
+  var maximum = 0.0;
+  for (var y = 0; y < 2; y = y + 1) {
+    for (var x = 0; x < 2; x = x + 1) {
+      let coord = min(base + vec2<i32>(x, y), vec2<i32>(sourceSize) - vec2<i32>(1));
+      maximum = max(maximum, textureLoad(source, coord, 0).x);
+    }
+  }
+  textureStore(outputTexture, vec2<i32>(id.xy), vec4<f32>(maximum, 0.0, 0.0, 1.0));
+}
+`;
+
+interface ComputeResources {
+  readonly layout: BindGroupLayout;
+  readonly pipeline: ComputePipeline;
+}
+
+async function computeResources(
+  device: RhiDevice,
+  code: string,
+  entries: Parameters<RhiDevice['createBindGroupLayout']>[0]['entries'],
+  entryPoint: string,
+): Promise<ComputeResources> {
+  const module = (await createShaderModule(device, { code })).unwrap();
+  const layout = device.createBindGroupLayout({ entries }).unwrap();
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] }).unwrap();
+  const pipeline = device
+    .createComputePipeline({ layout: pipelineLayout, compute: { module, entryPoint } })
+    .unwrap();
+  return { layout, pipeline };
+}
+
+export interface HzbGraphEvidence {
+  readonly graph: CompiledRenderGraphInfo;
+  readonly finalDepth: number;
+}
+
+export async function runHzbGraph(): Promise<HzbGraphEvidence> {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  if (!device.caps.compute || !device.caps.storageTexture) {
+    throw new Error(`required HZB capabilities unavailable: ${JSON.stringify(device.caps)}`);
+  }
+  const seed = await computeResources(
+    device,
+    SEED_WGSL,
+    [
+      {
+        binding: 0,
+        visibility: 0x4,
+        storageTexture: { access: 'write-only', format: 'r32float', viewDimension: '2d' },
+      },
+    ],
+    'seed',
+  );
+  const reduce = await computeResources(
+    device,
+    REDUCE_WGSL,
+    [
+      {
+        binding: 0,
+        visibility: 0x4,
+        texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+      },
+      {
+        binding: 1,
+        visibility: 0x4,
+        storageTexture: { access: 'write-only', format: 'r32float', viewDimension: '2d' },
+      },
+    ],
+    'reduce',
+  );
+  const readbackBuffer = device
+    .createBuffer({
+      label: 'hzb-readback',
+      size: 256,
+      usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+
+  const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+  const hierarchy = graph
+    .createTexture('hzb', {
+      format: 'r32float',
+      size: { width: HZB_SIZE, height: HZB_SIZE },
+      mipLevelCount: HZB_MIPS,
+    })
+    .unwrap();
+  const mips = Array.from({ length: HZB_MIPS }, (_, level) =>
+    graph
+      .view(hierarchy, {
+        label: `hzb.mip-${level}`,
+        baseMipLevel: level,
+        mipLevelCount: 1,
+      })
+      .unwrap(),
+  );
+  const readback = graph
+    .importBuffer(
+      'hzb-readback',
+      { size: 256, usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST },
+      () => readbackBuffer,
+    )
+    .unwrap();
+  const mip0 = mips[0];
+  if (mip0 === undefined) throw new Error('HZB mip 0 is missing');
+  graph
+    .addComputePass('hzb-seed', {
+      accesses: [{ resource: mip0, usage: 'storage-write' }],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout: seed.layout,
+            entries: [
+              {
+                binding: 0,
+                resource: { kind: 'textureView', value: resources.textureView(mip0).unwrap() },
+              },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(seed.pipeline);
+        pass.setBindGroup(0, bindings);
+        pass.dispatchWorkgroups(HZB_SIZE, HZB_SIZE, 1);
+      },
+    })
+    .unwrap();
+  for (let level = 1; level < HZB_MIPS; level += 1) {
+    const source = mips[level - 1];
+    const target = mips[level];
+    if (source === undefined || target === undefined) throw new Error(`HZB mip ${level} missing`);
+    const extent = HZB_SIZE >> level;
+    graph
+      .addComputePass(`hzb-reduce-${level}`, {
+        accesses: [
+          { resource: source, usage: 'sampled-read' },
+          { resource: target, usage: 'storage-write' },
+        ],
+        encode: ({ pass, resources }) => {
+          const bindings = device
+            .createBindGroup({
+              layout: reduce.layout,
+              entries: [
+                {
+                  binding: 0,
+                  resource: {
+                    kind: 'textureView',
+                    value: resources.textureView(source).unwrap(),
+                  },
+                },
+                {
+                  binding: 1,
+                  resource: {
+                    kind: 'textureView',
+                    value: resources.textureView(target).unwrap(),
+                  },
+                },
+              ],
+            })
+            .unwrap();
+          pass.setPipeline(reduce.pipeline);
+          pass.setBindGroup(0, bindings);
+          pass.dispatchWorkgroups(extent, extent, 1);
+        },
+      })
+      .unwrap();
+  }
+  const lastMip = mips[HZB_MIPS - 1];
+  if (lastMip === undefined) throw new Error('HZB final mip is missing');
+  graph
+    .addCopyPass('hzb-readback', {
+      accesses: [
+        { resource: lastMip, usage: 'copy-src' },
+        { resource: readback, usage: 'copy-dst' },
+      ],
+      encode: ({ encoder, resources }) => {
+        encoder.copyTextureToBuffer(
+          {
+            texture: resources.texture(hierarchy).unwrap() as unknown as GPUTexture,
+            mipLevel: HZB_MIPS - 1,
+          },
+          {
+            buffer: resources.buffer(readback).unwrap() as unknown as GPUBuffer,
+            bytesPerRow: 256,
+            rowsPerImage: 1,
+          },
+          { width: 1, height: 1, depthOrArrayLayers: 1 },
+        );
+      },
+    })
+    .unwrap();
+
+  const compiled = graph
+    .compile({ device, surfaceSize: { width: HZB_SIZE, height: HZB_SIZE } })
+    .unwrap();
+  const encoder = device.createCommandEncoder({ label: 'hzb-frame' }).unwrap();
+  compiled.execute({ encoder }).unwrap();
+  device.queue.submit([encoder.finish().unwrap()]).unwrap();
+  await device.queue.onSubmittedWorkDone();
+  const mapped = (await readbackBuffer.mapAsync(BUFFER_USAGE_MAP_READ)).unwrap();
+  const range = mapped.getMappedRange().unwrap();
+  const finalDepth = new Float32Array(range.slice(0, 4))[0] ?? Number.NaN;
+  mapped.unmap();
+  const inspected = compiled.inspect();
+  (await compiled.retire()).unwrap();
+  device.destroyBuffer(readbackBuffer).unwrap();
+  return { graph: inspected, finalDepth };
+}

package/src/__tests__/render-graph-hzb.browser.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { runHzbGraph } from './render-graph-hzb-gpu';
+
+describe('RenderGraph HZB mip chain in Chromium WebGPU', () => {
+  it('executes the same subresource chain through the browser driver path', async () => {
+    const evidence = await runHzbGraph();
+    expect(evidence.graph.passes.map((pass) => pass.kind)).toEqual([
+      'compute',
+      'compute',
+      'compute',
+      'compute',
+      'copy',
+    ]);
+    expect(evidence.finalDepth).toBeCloseTo(1, 6);
+  });
+});

package/src/__tests__/render-graph-hzb.dawn.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { runHzbGraph } from './render-graph-hzb-gpu';
+
+describe('RenderGraph HZB mip chain on Dawn', () => {
+  it('orders writes and reads by texture subresource and preserves the maximum depth', async () => {
+    const evidence = await runHzbGraph();
+    expect(evidence.graph.passes.map((pass) => pass.name)).toEqual([
+      'hzb-seed',
+      'hzb-reduce-1',
+      'hzb-reduce-2',
+      'hzb-reduce-3',
+      'hzb-readback',
+    ]);
+    expect(evidence.graph.passes.map((pass) => pass.dependencies)).toEqual([
+      [],
+      ['hzb-seed'],
+      ['hzb-reduce-1'],
+      ['hzb-reduce-2'],
+      ['hzb-reduce-3'],
+    ]);
+    expect(evidence.finalDepth).toBeCloseTo(1, 6);
+  });
+});

package/src/__tests__/render-graph-primitives.unit.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { validateColorDomainConnection } from '../../../render-graph/src/pipeline/color-value-domain';
+
+describe('LDR transparent blend contract', () => {
+  it('keeps source and destination in the linear LDR domain', () => {
+    expect(validateColorDomainConnection('linear-ldr', 'linear-ldr')).toEqual({ ok: true });
+  });
+
+  it('rejects a linear source mixed into an encoded destination', () => {
+    const result = validateColorDomainConnection('linear-ldr', 'display-encoded');
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('expected encoded destination rejection');
+    expect(result.error.code).toBe('color-domain-mismatch');
+  });
+
+  it('requires an explicit encoding conversion after the blend', () => {
+    const result = validateColorDomainConnection('linear-ldr', 'display-encoded', {
+      kind: 'encode-srgb',
+    });
+    expect(result).toEqual({ ok: true });
+  });
+});

package/src/__tests__/render-graph-storage-indirect-gpu.ts

@@ -0,0 +1,162 @@
+import { type CompiledRenderGraphInfo, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const BUFFER_USAGE_INDIRECT = 0x0100;
+
+const STORAGE_TEXTURE_WGSL = /* wgsl */ `
+@group(0) @binding(0) var outputTexture: texture_storage_2d<rgba8unorm, write>;
+
+@compute @workgroup_size(1)
+fn fill(@builtin(global_invocation_id) id: vec3<u32>) {
+  textureStore(outputTexture, vec2<i32>(id.xy), vec4<f32>(0.25, 0.5, 0.75, 1.0));
+}
+`;
+
+export interface StorageIndirectEvidence {
+  readonly caps: {
+    readonly compute: boolean;
+    readonly storageTexture: boolean;
+    readonly indirectDrawing: boolean;
+  };
+  readonly graph: CompiledRenderGraphInfo;
+  readonly pixel: readonly number[];
+}
+
+export async function runStorageIndirectGraph(): Promise<StorageIndirectEvidence> {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  const caps = {
+    compute: device.caps.compute,
+    storageTexture: device.caps.storageTexture,
+    indirectDrawing: device.caps.indirectDrawing,
+  };
+  if (!caps.compute || !caps.storageTexture || !caps.indirectDrawing) {
+    throw new Error(`required graph capabilities unavailable: ${JSON.stringify(caps)}`);
+  }
+
+  const module = (await createShaderModule(device, { code: STORAGE_TEXTURE_WGSL })).unwrap();
+  const layout = device
+    .createBindGroupLayout({
+      entries: [
+        {
+          binding: 0,
+          visibility: 0x4,
+          storageTexture: {
+            access: 'write-only',
+            format: 'rgba8unorm',
+            viewDimension: '2d',
+          },
+        },
+      ],
+    })
+    .unwrap();
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] }).unwrap();
+  const pipeline = device
+    .createComputePipeline({
+      layout: pipelineLayout,
+      compute: { module, entryPoint: 'fill' },
+    })
+    .unwrap();
+  const indirectBuffer = device
+    .createBuffer({
+      size: 12,
+      usage: BUFFER_USAGE_INDIRECT | BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  device.queue.writeBuffer(indirectBuffer, 0, new Uint32Array([1, 1, 1])).unwrap();
+  const readbackBuffer = device
+    .createBuffer({
+      size: 256,
+      usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+
+  const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+  const output = graph
+    .createTexture('storage-output', {
+      format: 'rgba8unorm',
+      size: { width: 1, height: 1 },
+    })
+    .unwrap();
+  const outputView = graph.view(output, { label: 'storage-output.view' }).unwrap();
+  const indirect = graph
+    .importBuffer(
+      'dispatch-args',
+      { size: 12, usage: BUFFER_USAGE_INDIRECT | BUFFER_USAGE_COPY_DST },
+      () => indirectBuffer,
+    )
+    .unwrap();
+  const readback = graph
+    .importBuffer(
+      'readback',
+      { size: 256, usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST },
+      () => readbackBuffer,
+    )
+    .unwrap();
+  graph
+    .addComputePass('storage-write', {
+      accesses: [
+        { resource: outputView, usage: 'storage-write' },
+        { resource: indirect, usage: 'indirect-read' },
+      ],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout,
+            entries: [
+              {
+                binding: 0,
+                resource: {
+                  kind: 'textureView',
+                  value: resources.textureView(outputView).unwrap(),
+                },
+              },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindings);
+        pass.dispatchWorkgroupsIndirect(resources.buffer(indirect).unwrap(), 0);
+      },
+    })
+    .unwrap();
+  graph
+    .addCopyPass('readback', {
+      accesses: [
+        { resource: outputView, usage: 'copy-src' },
+        { resource: readback, usage: 'copy-dst' },
+      ],
+      encode: ({ encoder, resources }) => {
+        encoder.copyTextureToBuffer(
+          { texture: resources.texture(output).unwrap() as unknown as GPUTexture },
+          {
+            buffer: resources.buffer(readback).unwrap() as unknown as GPUBuffer,
+            bytesPerRow: 256,
+            rowsPerImage: 1,
+          },
+          { width: 1, height: 1, depthOrArrayLayers: 1 },
+        );
+      },
+    })
+    .unwrap();
+
+  const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+  const encoder = device.createCommandEncoder({ label: 'storage-indirect-frame' }).unwrap();
+  compiled.execute({ encoder }).unwrap();
+  const command = encoder.finish().unwrap();
+  device.queue.submit([command]).unwrap();
+  await device.queue.onSubmittedWorkDone();
+
+  const mapped = (await readbackBuffer.mapAsync(BUFFER_USAGE_MAP_READ)).unwrap();
+  const range = mapped.getMappedRange().unwrap();
+  const pixel = [...new Uint8Array(range.slice(0, 4))];
+  mapped.unmap();
+  const inspected = compiled.inspect();
+  (await compiled.retire()).unwrap();
+  device.destroyBuffer(indirectBuffer).unwrap();
+  device.destroyBuffer(readbackBuffer).unwrap();
+  return { caps, graph: inspected, pixel };
+}

package/src/__tests__/render-graph-storage-indirect.browser.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { runStorageIndirectGraph } from './render-graph-storage-indirect-gpu';
+
+describe('RenderGraph storage texture and indirect dispatch in Chromium', () => {
+  it('executes storage-write -> copy-readback through browser WebGPU', async () => {
+    const evidence = await runStorageIndirectGraph();
+    expect(evidence.caps).toEqual({
+      compute: true,
+      storageTexture: true,
+      indirectDrawing: true,
+    });
+    expect(evidence.graph.passes.map((pass) => [pass.name, pass.kind])).toEqual([
+      ['storage-write', 'compute'],
+      ['readback', 'copy'],
+    ]);
+    expect(evidence.pixel[0]).toBeCloseTo(64, 0);
+    expect(evidence.pixel[1]).toBeCloseTo(128, 0);
+    expect(evidence.pixel[2]).toBeCloseTo(191, 0);
+    expect(evidence.pixel[3]).toBe(255);
+  });
+});

package/src/__tests__/render-graph-storage-indirect.dawn.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { runStorageIndirectGraph } from './render-graph-storage-indirect-gpu';
+
+describe('RenderGraph storage texture and indirect dispatch on Dawn', () => {
+  it('executes storage-write -> copy-readback through one command encoder', async () => {
+    const evidence = await runStorageIndirectGraph();
+    expect(evidence.caps).toEqual({
+      compute: true,
+      storageTexture: true,
+      indirectDrawing: true,
+    });
+    expect(evidence.graph.passes).toMatchObject([
+      {
+        name: 'storage-write',
+        kind: 'compute',
+        accesses: [
+          { resource: 'storage-output', usage: 'storage-write' },
+          { resource: 'dispatch-args', usage: 'indirect-read' },
+        ],
+      },
+      { name: 'readback', kind: 'copy', dependencies: ['storage-write'] },
+    ]);
+    expect(evidence.pixel[0]).toBeCloseTo(64, 0);
+    expect(evidence.pixel[1]).toBeCloseTo(128, 0);
+    expect(evidence.pixel[2]).toBeCloseTo(191, 0);
+    expect(evidence.pixel[3]).toBe(255);
+  });
+});

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

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const material = {} as MaterialSnapshot;
+
+function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = translationX;
+  return {
+    assetHandle: 1,
+    transform: { world },
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+  };
+}
+
+describe('RenderScene canonical owner', () => {
+  it('coalesces create and transform updates into one stable slot', () => {
+    const projection = new RenderScene();
+    const initial = snapshot(7, 1);
+    const updatedWorld = new Float32Array(initial.transform.world);
+    updatedWorld[12] = 9;
+
+    const result = projection.apply([
+      { kind: 'create', snapshot: initial },
+      { kind: 'update-transform', worldId: 0, entityKey: 7, world: updatedWorld },
+    ]);
+
+    expect(result).toMatchObject({ created: 1, updated: 0, removed: 0, recreated: 0 });
+    expect(projection.inspect().records).toEqual([
+      expect.objectContaining({ slot: 0, generation: 0, worldId: 0, entityKey: 7 }),
+    ]);
+    expect(projection.materialize()[0]?.transform.world[12]).toBe(9);
+  });
+
+  it('cancels a transient create/remove pair without allocating a slot', () => {
+    const projection = new RenderScene();
+
+    const result = projection.apply([
+      { kind: 'create', snapshot: snapshot(3, 1) },
+      { kind: 'remove', worldId: 0, entityKey: 3 },
+    ]);
+
+    expect(result).toMatchObject({ created: 0, updated: 0, removed: 0, recreated: 0 });
+    expect(projection.inspect().records).toEqual([]);
+  });
+
+  it('bumps generation when remove and recreate reuse a slot', () => {
+    const projection = new RenderScene();
+    projection.apply([{ kind: 'create', snapshot: 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 },
+    ]);
+
+    const after = projection.inspect().records[0];
+    expect(result).toMatchObject({ created: 0, updated: 0, removed: 0, recreated: 1 });
+    expect(after?.slot).toBe(before?.slot);
+    expect(after?.generation).toBe((before?.generation ?? -1) + 1);
+    expect(projection.materialize()[0]?.transform.world[12]).toBe(7);
+  });
+
+  it('ignores an update that arrives after removal', () => {
+    const projection = new RenderScene();
+    projection.apply([{ kind: 'create', snapshot: 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 },
+    ]);
+
+    expect(result).toMatchObject({ removed: 1, ignoredLateUpdates: 1 });
+    expect(projection.inspect().records).toEqual([]);
+  });
+
+  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 } },
+    ]);
+
+    expect(projection.materialize().map((record) => record.transform.world[12])).toEqual([3, 8]);
+  });
+});
+
+describe('RenderScene', () => {
+  it('keeps world identity slots stable across a composition reorder', () => {
+    const scene = new RenderScene();
+    const first = snapshot(1, 3);
+    const second = { ...snapshot(1, 8), worldId: 1 };
+
+    scene.reset([first, second]);
+    const before = scene.slot(0, 1);
+    scene.reset([second, first]);
+
+    expect(scene.slotsSnapshot().map((entry) => [entry.worldId, entry.entityKey])).toEqual([
+      [1, 1],
+      [0, 1],
+    ]);
+    expect(scene.slot(0, 1)).toMatchObject({
+      slot: before?.slot,
+      generation: before?.generation,
+    });
+  });
+
+  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 } },
+    ]);
+
+    const before = scene.slot(0, 7);
+    scene.apply([]);
+    const after = scene.slot(0, 7);
+
+    expect(after).toMatchObject({ slot: before?.slot, generation: before?.generation });
+    expect(scene.inspect()).toMatchObject({ noChangeFrames: 1, renderableScans: 0 });
+  });
+
+  it('indexes material and spatial facts from the same scene slots', () => {
+    const scene = new RenderScene();
+    scene.apply([
+      {
+        kind: 'create',
+        snapshot: {
+          ...snapshot(11, 4),
+          localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+          material: { ...material, materialHandle: 42 },
+          materials: [{ ...material, materialHandle: 42 }],
+        },
+      },
+    ]);
+
+    expect(scene.slotsForMaterial(42)).toHaveLength(1);
+    expect(
+      scene.querySpatial({ min: [2, -2, -2], max: [6, 2, 2] }).map((entry) => entry.entityKey),
+    ).toEqual([11]);
+  });
+
+  it('rebuilds from a resync delta after journal overflow', () => {
+    const scene = new RenderScene();
+    scene.apply([{ kind: 'create', snapshot: snapshot(1, 0) }]);
+
+    const result = scene.applyDelta({
+      operations: [],
+      overflowed: true,
+      resync: [snapshot(99, 9)],
+      reason: 'journal-overflow',
+    });
+
+    expect(result.resynced).toBe(1);
+    expect(scene.has(0, 1)).toBe(false);
+    expect(scene.has(0, 99)).toBe(true);
+  });
+});